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.
This commit is contained in:
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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 |
|
||||
|
||||
@@ -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`
|
||||
|
||||
@@ -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)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user