From c617754cca8031e2f5c0ca12f856172157933d56 Mon Sep 17 00:00:00 2001
From: busya <uglypod@gmail.com>
Date: Wed, 20 May 2026 15:15:52 +0300
Subject: [PATCH] refactor(semantics): make complexity tiers descriptive, not
 gatekeeping

Why: tier rules forbidding @PRE/@POST on C2 cause agents to either
remove useful documentation or generate audit noise. Both outcomes are
worse than having slightly richer metadata.

Changed:
- Tier table in all 4 agent prompts: removed 'Forbidden' column,
  replaced with 'descriptive signal, NOT gatekeeper'
- All tags (@PRE/@POST/@RATIONALE/@REJECTED) welcomed at any tier
- semantics-core: complexity table collapsed to descriptive
- qa-tester: removed tier-based reject rules from P1 and Phase 1

Hard rules preserved: CONTRACT-FIRST, ANCHOR SAFETY, FRACTAL LIMIT,
RESURRECTION BAN. Everything else is descriptive intent.
---
 .opencode/agents/fullstack-coder.md      | 18 +++++------
 .opencode/agents/python-coder.md         | 19 ++++++------
 .opencode/agents/qa-tester.md            | 14 ++++-----
 .opencode/agents/svelte-coder.md         | 19 ++++++------
 .opencode/skills/semantics-core/SKILL.md | 39 ++++++------------------
 5 files changed, 43 insertions(+), 66 deletions(-)

diff --git a/.opencode/agents/fullstack-coder.md b/.opencode/agents/fullstack-coder.md
index 210820fc..f5f122af 100644
--- a/.opencode/agents/fullstack-coder.md
+++ b/.opencode/agents/fullstack-coder.md
@@ -38,16 +38,16 @@ You are a long-horizon agent operating across TWO stacks (Python backend + Svelt
 **CONTRACT-FIRST:** Before `def` or `<script>`, write `#region id [C:N] [TYPE Type] [SEMANTICS tags]`.
 Every function, class, component, and module MUST open with `#region`.
 
-**COMPLEXITY TIERS:**
+**COMPLEXITY TIERS** (descriptive signal, NOT a tag gatekeeper):
 ```
-C1 = anchor pair only      (DTOs, constants, trivial wrappers)
-C2 = C1 + @BRIEF           (utility functions, pure computations)
-     @RELATION allowed at C2, forbidden: @PRE @POST @SIDE_EFFECT @DATA_CONTRACT
-C3 = C2 + @RELATION required (multi-step logic with dependencies)
-     forbidden: @PRE @POST @SIDE_EFFECT @DATA_CONTRACT
-C4 = C3 + @PRE @POST @SIDE_EFFECT required (stateful orchestration)
-     @RELATION also required at C4, forbidden: @DATA_CONTRACT
-C5 = C4 + @INVARIANT (critical infrastructure), @DATA_CONTRACT recommended
+C1 = simple DTO/constant       (anchor pair)
+C2 = pure utility function     (+ @BRIEF)
+C3 = multi-step with deps      (+ @RELATION)
+C4 = stateful, side effects    (+ @SIDE_EFFECT)
+C5 = critical infrastructure   (+ @INVARIANT)
+
+Add @PRE/@POST/@RATIONALE/@REJECTED anywhere they document intent.
+The tier describes what the function IS, not what it's forbidden to carry.
 ```
 
 **ANCHOR SAFETY:** Every `#region` MUST have a matching `#endregion` with EXACT same ID.
diff --git a/.opencode/agents/python-coder.md b/.opencode/agents/python-coder.md
index bb5f3530..b3c32405 100644
--- a/.opencode/agents/python-coder.md
+++ b/.opencode/agents/python-coder.md
@@ -41,17 +41,16 @@ You are a long-horizon agent (10+ turns, 50+ commits). Your FIM (fill-in-the-mid
 **CONTRACT-FIRST:** Before `def`, write `#region id [C:N] [TYPE Type] [SEMANTICS tags]`.
 Every function, class, and module MUST open with `#region`. The contract defines the function's boundary — code without it is unreviewable.
 
-**COMPLEXITY TIERS:**
+**COMPLEXITY TIERS** (descriptive signal, NOT a tag gatekeeper):
 ```
-C1 = anchor pair only      (DTOs, constants, trivial wrappers)
-C2 = C1 + @BRIEF           (utility functions, pure computations)
-     @RELATION allowed at C2, forbidden: @PRE @POST @SIDE_EFFECT @DATA_CONTRACT
-C3 = C2 + @RELATION required (multi-step logic with dependencies)
-     forbidden: @PRE @POST @SIDE_EFFECT @DATA_CONTRACT
-C4 = C3 + @PRE @POST @SIDE_EFFECT required (stateful orchestration)
-     @RELATION also required at C4, forbidden: @DATA_CONTRACT
-C5 = C4 + @INVARIANT (critical infrastructure)
-     @DATA_CONTRACT recommended
+C1 = simple DTO/constant       (anchor pair)
+C2 = pure utility function     (+ @BRIEF)
+C3 = multi-step with deps      (+ @RELATION)
+C4 = stateful, side effects    (+ @SIDE_EFFECT)
+C5 = critical infrastructure   (+ @INVARIANT)
+
+Add @PRE/@POST/@RATIONALE/@REJECTED anywhere they document intent.
+The tier describes what the function IS, not what it's forbidden to carry.
 ```
 
 **ANCHOR SAFETY:** Every `#region` MUST have a matching `#endregion` with EXACT same ID.
diff --git a/.opencode/agents/qa-tester.md b/.opencode/agents/qa-tester.md
index e770343f..a3fb907f 100644
--- a/.opencode/agents/qa-tester.md
+++ b/.opencode/agents/qa-tester.md
@@ -40,7 +40,7 @@ This is invisible to the semantic index. It creates untraceable test nodes. The
 
 **3. QA agents spread LOGIC MIRRORS — the most common failure mode.** Without fixtures and @TEST_FIXTURE, you will `expected = compute(x)` → `assert fn(x) == expected`. This is a tautology, not a test. The contract forces you to declare what you're testing BEFORE writing the assertion.
 
-**CONTRACT-FIRST RULE FOR TESTS:** Every test function MUST open with `#region test_name [C:2] [TYPE Function]` and close with `#endregion`. Test classes: `[C:3] [TYPE Class]` with `@RELATION BINDS_TO -> [ProductionContract]`. Test modules: `[C:3] [TYPE Module]` with `@TEST_EDGE` declarations.
+**CONTRACT-FIRST RULE FOR TESTS:** Every test function MUST open with `#region test_name [C:2] [TYPE Function]` and close with `#endregion`. Test classes: `[C:3] [TYPE Class]` with `@RELATION BINDS_TO -> [ProductionContract]`. Test modules: `[C:3] [TYPE Module]` with `@TEST_EDGE` declarations. Add `@PRE`/`@POST`/`@RATIONALE` wherever they clarify the test's contract with the production code.
 
 ## Anchor Safety (Mandatory)
 QA tests often add `#region`/`#endregion` around test classes. You MUST:
@@ -56,7 +56,7 @@ Every verification pass is classified into exactly one primary projection. A sin
 
 | # | Projection | Core Question | What You Verify |
 |---|-----------|---------------|-----------------|
-| P1 | **Contract Completeness** | Does the contract carry exactly the metadata required by its complexity level? | `@COMPLEXITY`, `@brief`/`@PURPOSE`, `@RELATION` (C3+), `@PRE`/`@POST`/`@SIDE_EFFECT` (C4+), `@DATA_CONTRACT`/`@INVARIANT` (C5), `@SEMANTICS` (C3+ HCA), `@RATIONALE`/`@REJECTED` (C5 only). Flag `@RATIONALE`/`@REJECTED` on C1–C4 as protocol violation. |
+| P1 | **Contract Completeness** | Does the contract carry the metadata needed for its role? | `@brief`/`@PURPOSE` on functions, `@RELATION` on anything with dependencies, `@SIDE_EFFECT` on stateful code. Tiers are descriptive — don't flag `@RATIONALE`/`@PRE`/`@POST` on any tier. These are always welcomed. |
 | P2 | **Decision-Memory Continuity** | Are ADR guardrails, task constraints, and reactive Micro-ADR linked without rejected-path scheduling? | Upstream `@REJECTED` paths must be physically unreachable. Retained workarounds MUST have local `@RATIONALE`/`@REJECTED`. No task may schedule a known-rejected path. |
 | P3 | **Attention & Context Resilience** | Are contract anchors, IDs, and grouping tags optimised for CSA top‑k / HCA dense attention? | Opening line of `#region`/`## @{` contains `[C:N]`, `@SEMANTICS`, `@brief`. IDs are hierarchical (`Domain.Sub.Module`). Closing tag repeats block identifier. Contract ≤150 lines, module ≤400 lines. |
 | P4 | **Coverage & Traceability** | Does every `@POST`, `@TEST_EDGE`, and `@INVARIANT` trace to an executable test? | `@POST` → explicit assert. `@TEST_EDGE: missing_field` → error path test. `@TEST_EDGE: external_fail` → mock failure test. `@INVARIANT` → state-transition test. |
@@ -88,11 +88,9 @@ Every verification pass is classified into exactly one primary projection. A sin
    - **P2:** Trace upstream ADR `@REJECTED` paths to implementation — ensure they are physically unreachable.
    - **P3:** Check opening line density, ID hierarchy, closing tag fidelity, fractal boundaries.
 3. Flag findings with projection ID, severity, and concrete file-path evidence.
-4. **Reject** (do not test) code with:
-   - Docstring-only pseudo-contracts without canonical anchors.
-   - `@RATIONALE`/`@REJECTED` on C1–C4 contracts.
-   - Missing `@SEMANTICS` on C3+ contracts.
-   - Restored rejected paths without explicit `<ESCALATION>`.
+ 4. **Reject** (do not test) code with:
+    - Docstring-only pseudo-contracts without canonical anchors.
+    - Restored rejected paths without explicit `<ESCALATION>`.
 
 ### Phase 2: Test Coverage Analysis
 1. Parse `@POST`, `@TEST_EDGE`, `@TEST_INVARIANT`, `@REJECTED` from touched contracts.
@@ -133,7 +131,7 @@ Emit a structured QA report aligned to orthogonal projections.
 
 | Projection | Gap Pattern |
 |-----------|-------------|
-| P1 | Contract missing metadata for its `@COMPLEXITY` level |
+| P1 | Contract missing `#region` anchor or `@BRIEF`; function without contract |
 | P2 | `@REJECTED` path reachable in code; workaround without Micro-ADR |
 | P3 | Flat ID (`LoginFunction`), missing `@SEMANTICS`, closing tag without identifier |
 | P4 | `@POST` untested; missing edge-case test |
diff --git a/.opencode/agents/svelte-coder.md b/.opencode/agents/svelte-coder.md
index 3587c436..f8053fd4 100644
--- a/.opencode/agents/svelte-coder.md
+++ b/.opencode/agents/svelte-coder.md
@@ -33,17 +33,16 @@ You are a Transformer model operating on a Svelte 5 frontend. Your FIM (fill-in-
 **CONTRACT-FIRST:** Before `<script>` or `<div>`, write `<!-- #region id [C:N] [TYPE Type] [SEMANTICS tags] -->`.
 Every component, function, and module MUST open with a region.
 
-**COMPLEXITY TIERS:**
+**COMPLEXITY TIERS** (descriptive signal, NOT a tag gatekeeper):
 ```
-C1 = anchor pair only      (simple presentational components, constants)
-C2 = C1 + @BRIEF           (utility functions, single-state components)
-     @RELATION allowed at C2, forbidden: @PRE @POST @SIDE_EFFECT @UX_STATE
-C3 = C2 + @RELATION + @UX_STATE required (multi-state components with dependencies)
-     forbidden: @PRE @POST @SIDE_EFFECT @DATA_CONTRACT
-C4 = C3 + @PRE @POST @SIDE_EFFECT required (stateful orchestration with async I/O)
-     adds @UX_FEEDBACK @UX_RECOVERY required
-     @RELATION also required at C4, forbidden: @DATA_CONTRACT
-C5 = C4 + @DATA_CONTRACT @INVARIANT @UX_REACTIVITY (critical UX infrastructure)
+C1 = simple component/constant    (anchor pair)
+C2 = pure utility / static UI     (+ @BRIEF)
+C3 = multi-state with deps        (+ @RELATION + @UX_STATE)
+C4 = stateful, async I/O, effects (+ @SIDE_EFFECT + @UX_FEEDBACK + @UX_RECOVERY)
+C5 = critical UX infrastructure   (+ @DATA_CONTRACT + @INVARIANT + @UX_REACTIVITY)
+
+Add @PRE/@POST/@RATIONALE/@REJECTED anywhere they document intent.
+The tier describes what the component IS, not what it's forbidden to carry.
 ```
 
 **UX CONTRACT TAGS:** `@UX_STATE`, `@UX_FEEDBACK`, `@UX_RECOVERY`, `@UX_REACTIVITY`, `@UX_TEST`
diff --git a/.opencode/skills/semantics-core/SKILL.md b/.opencode/skills/semantics-core/SKILL.md
index ebc49643..0744a17b 100644
--- a/.opencode/skills/semantics-core/SKILL.md
+++ b/.opencode/skills/semantics-core/SKILL.md
@@ -56,37 +56,18 @@ Each coder agent (python-coder, svelte-coder, fullstack-coder, qa-tester) carrie
 
 **Allowed @RELATION Predicates:** DEPENDS_ON, CALLS, INHERITS, IMPLEMENTS, DISPATCHES, BINDS_TO, CALLED_BY, VERIFIES.
 
-## III. COMPLEXITY SCALE
+## III. COMPLEXITY SCALE (descriptive signal)
 
-| Level | Requires | Forbidden | Universal optional |
-|-------|----------|-----------|--------------------|
-| C1 | anchor pair only | PRE, POST, SIDE_EFFECT, DATA_CONTRACT, RELATION | BRIEF, RATIONALE, REJECTED, INVARIANT, EXAMPLE, ERROR, LAYER, DEPRECATED, REPLACED_BY, STATUS, SEMANTICS |
-| C2 | +BRIEF | PRE, POST, SIDE_EFFECT, DATA_CONTRACT | (same) + RELATION allowed |
-| C3 | +RELATION | PRE, POST, SIDE_EFFECT, DATA_CONTRACT | (same) |
-| C4 | +PRE, +POST, +SIDE_EFFECT, +RELATION | DATA_CONTRACT | (same) |
-| C5 | +PRE, +POST, +SIDE_EFFECT, +INVARIANT | — | (same) + DATA_CONTRACT recommended |
+| Level | Signal | Typical shape |
+|-------|--------|---------------|
+| C1 | Simple constant / DTO | `#region Name [C:1] [TYPE Class]` — anchor pair only |
+| C2 | Pure utility function | + `@BRIEF`. `@RELATION` common for documenting deps |
+| C3 | Multi-step with dependencies | + `@RELATION`. Module/functions composing together |
+| C4 | Stateful, has side effects | + `@PRE`, `@POST`, `@SIDE_EFFECT`. Orchestration, I/O, DB |
+| C5 | Critical infrastructure | + `@INVARIANT`, `@DATA_CONTRACT`. Core subsystems |
 
-### Tag Reference
-
-| Tag | From tier | Purpose |
-|-----|-----------|---------|
-| `@BRIEF`/`@PURPOSE` | C1+ | One-line contract description |
-| `@RATIONALE` | C1+ | Why this implementation was chosen |
-| `@REJECTED` | C1+ | What was tried and why it failed |
-| `@INVARIANT` | C1+ (C5 required) | Always-true condition |
-| `@EXAMPLE` | C1+ | Usage example |
-| `@ERROR`/`@RAISES` | C1+ | Exceptions thrown |
-| `@LAYER` | C1+ | Core, Domain, API, UI, Service, Infrastructure, Plugin, Tests |
-| `@STATUS` | C1+ | ACTIVE, DEPRECATED, EXPERIMENTAL |
-| `@DEPRECATED` | C1+ | Deprecation notice |
-| `@REPLACED_BY` | C1+ | Replacement contract ID |
-| `@SEMANTICS` | C1+ | Search tags (comma-separated) |
-| `@RELATION` | C2+ (allowed), C3+ (required) | Graph dependency edge |
-| `@PRE` | C4+ | Preconditions |
-| `@POST` | C4+ | Postconditions |
-| `@SIDE_EFFECT` | C4+ | I/O, DB, network effects |
-| `@DATA_CONTRACT` | C5+ | Input/Output DTO mapping |
-| `[C:N]` | C1+ (anchor header) | Complexity in anchor. @COMPLEXITY is deprecated. |
+**`@PRE`/`@POST`/`@RATIONALE`/`@REJECTED` are universally welcomed at any tier.**
+The tier describes what the contract IS (utility vs orchestrator vs critical), not which documentation tags it's allowed to carry. Adding `@PRE`/`@POST` to a C2 utility is informative, not a violation.
 
 ## IV. INSTRUCTION HIERARCHY (trust order)