busya/ss-tools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(agents): inject CONTRACT MANDATE into all coder agent prompts

Browse Source 
Why: agents kept forgetting #region contracts because the rationale
was hidden in loadable skills, not active in their system prompt.

Changed agent prompts (+RATIONALE-first):
- python-coder: +55 lines — 4 failure modes + operational rules
- fullstack-coder: +40 lines — same, with cross-stack emphasis
- svelte-coder: replaced PHYSICS OF ATTENTION with unified mandate
- qa-tester: +15 lines — QA-specific contract mandate

Compressed skills (reference-only):
- semantics-core: 174→110 lines (-37%) — rationale removed, syntax+tables kept
- semantics-contracts: 103→79 lines (-23%) — duplicates removed, methodology kept

Verification: 320 tests pass, 0 parse warnings, 0 semantic audit warnings
This commit is contained in:
busya
2026-05-20 15:02:29 +03:00
parent 904631efe9
commit 07cfaadee1
6 changed files with 276 additions and 222 deletions
Download Patch File Download Diff File Expand all files Collapse all files

126
.opencode/skills/semantics-contracts/SKILL.md
View File

@@ -1,103 +1,79 @@
---
name: semantics-contracts
description: Core extension protocol for Design by Contract, Fractal Decision Memory (ADR), and Long-Horizon Agentic Engineering across Python and Svelte codebases.
description: Methodology reference: Design by Contract enforcement, Fractal Decision Memory (ADR), Zero-Erosion rules, Verifiable Edit Loop, and Search Discipline. Load when implementing C4+ contracts or when your agent prompt says "READ → REASON → ACT → REFLECT → UPDATE" and you need the detailed version.
---
#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.
#region Std.Semantics.Contracts [C:5] [TYPE Skill] [SEMANTICS methodology,contracts,adr,decision-memory,anti-erosion]
@BRIEF HOW to enforce PRE/POST, write ADRs, prevent structural erosion, and execute verifiable edit loops across Python + Svelte.
@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.
@STATUS ACTIVE
## 0. AGENTIC ENGINEERING & PRESERVED THINKING (GLM-5 PARADIGM)
## I. DECISION MEMORY (ADR PROTOCOL)
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.
Decision memory prevents architectural drift. It records the *Decision Space* — why we chose a path, and what we abandoned.
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 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.
- **`@RATIONALE`** — The reasoning behind the chosen implementation.
- **`@REJECTED`** — The alternative path that was considered but FORBIDDEN, and the exact risk/disqualification.
## I. CORE SEMANTIC CONTRACTS (C4-C5 REQUIREMENTS)
**Three layers of decision memory:**
1. **Global ADR** — Standalone nodes defining repo-shaping decisions (e.g., "Use lingua, not fasttext"). Cannot be overridden locally.
2. **Task Guardrails** — Preventive `@REJECTED` tags injected by the Orchestrator to keep agents away from known LLM pitfalls.
3. **Reactive Micro-ADR** — If you encounter a runtime failure and invent a valid workaround, document it via `@RATIONALE` + `@REJECTED` BEFORE closing the task. This prevents regression loops.
Before implementing or modifying any logic inside a contract anchor, you MUST define or respect its contract metadata:
**Resurrection Ban:** Silently reintroducing a pattern or library marked as `@REJECTED` is a fatal regression. If the rejected path must be revived, emit `<ESCALATION>`.
- `@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`).
**`@RATIONALE`/`@REJECTED` are universally allowed at ALL tiers (C1-C5).** They prevent regression loops regardless of complexity.
## II. FRACTAL DECISION MEMORY & ADRs (ADMentor PROTOCOL)
## II. CORE CONTRACT ENFORCEMENT (C4-C5)
Decision memory prevents architectural drift. It records the *Decision Space* (Why we do it, and What we abandoned).
- **`@PRE`** — Execution prerequisites. Enforce via explicit `if/raise` guards. NEVER use `assert`.
- **`@POST`** — Strict output guarantees. **Cascading Protection:** You CANNOT alter a `@POST` without verifying upstream `@RELATION CALLS` consumers won't break.
- **`@SIDE_EFFECT`** — Explicit declaration of state mutations, I/O, DB writes, network calls.
- **`@DATA_CONTRACT`** — DTO mappings (e.g., `Input: UserCreateDTO → Output: UserResponseDTO`).
- `@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.
## III. ZERO-EROSION & ANTI-VERBOSITY
**The 3 Layers of Decision Memory:**
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.
Long-horizon AI coding accumulates "slop":
1. **Structural Erosion:** If modifications push a contract's CC above 10, decompose into smaller helpers linked via `@RELATION CALLS`.
2. **Verbosity:** Don't write identity-wrappers, useless intermediate variables, or defensive checks for impossible states if `@PRE` already guarantees validity. Trust the contract.
**`@RATIONALE`/`@REJECTED` are UNIVERSALLY OPTIONAL (C1–C5).** Decision Memory tags are allowed — and encouraged — at ALL complexity tiers. They document the *why* behind any architectural choice, preventing regression loops when another agent (or your future self) revisits the contract. The complexity tier determines which structural tags are REQUIRED, not which explanatory tags are forbidden.
## IV. VERIFIABLE EDIT LOOP
**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.
1. **Define verifier first.** What pytest or browser check proves the `@POST`?
2. **Build bounded working packet** from semantic context, impact analysis, and related tests.
3. **Preview-first mutation.** Prefer `simulate`/`guarded_preview` before `apply`.
4. **Run the smallest falsifiable verifier** against the intended `@POST`.
5. **Apply only after preview + verifier agree.**
6. **Re-run verification after apply.** Record the result.
## III. ZERO-EROSION & ANTI-VERBOSITY RULES (SlopCodeBench PROTOCOL)
**Shortcut Ban:** A patch that "looks right" without an executable verifier is incomplete.
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 contract node's Cyclomatic Complexity (CC) above 10, 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.
## V. SEARCH DISCIPLINE
## IV. EXECUTION LOOP (INTERLEAVED PROTOCOL)
- Default to ONE primary hypothesis + explicit verification.
- Use multiple branches only for ambiguous high-impact changes where the verifier can't discriminate.
- Don't spend additional search budget on low-impact edits once the verifier passes.
- Overthinking is also a bug: avoid Best-of-N patch churn when one verified path suffices.
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 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.
## VI. RUBRIC REFINEMENT
## V. VERIFIABLE EDIT LOOP (EXECUTABLE ENVIRONMENT PROTOCOL)
- Convert repeated failures into explicit rule updates: which invariant was missed, which verifier was weak.
- Treat failed previews, blocked mutations, and failing test outputs as early experience.
- If the same failure repeats, improve the rubric or verifier BEFORE editing again.
- When unblock requires a higher-level change, escalate with the refined rubric.
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.
## VII. LANGUAGE-SPECIFIC VERIFICATION
**Shortcut Ban:** A patch that "looks right" but is not tied to an executable verifier is incomplete.
```bash
# Python
cd backend && source .venv/bin/activate && python -m pytest -v
**Anchor Safety Ban:** A patch that adds, removes, or moves ANY `#region`/`#endregion` line without verifying ALL pairs remain intact via `read_outline` is forbidden. NEVER:
- Add `@COMPLEXITY N` or `@C N` — complexity is `[C:N]` in the anchor
- Insert code between a `#endregion` and the next `#region` (creates orphan code)
- Start a new `#region` before closing the previous one
- Duplicate `#endregion` markers
# Svelte
cd frontend && npm run test
## 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.
## 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).
# Linting
python -m ruff check . # Python
npm run lint # Frontend
```
#endregion Std.Semantics.Contracts