fix(workflow): fold v5.1/v5.2 hotfixes + OC-8 exception into v5.0.20260418 - Structured Phascolarctos (#69)

* chore(release): bump version to v5.2.20260418 - Emergent Colugo (hotfix)

* fix(workflow): OC-8 dataclass exception, SELF-DECLARE phase, design-patterns heuristic

Author: nullhack

.opencode/skills/design-patterns/SKILL.md

@@ -393,3 +393,13 @@ class JsonImporter(Importer):
 | Class directly calls B, C, D on state change | Observer |
 | Two functions share the same skeleton, differ in one step | Template Method |
 | Subsystem is complex and callers need a simple entry point | Facade |
+
+---
+
+## Core Heuristic — Procedural vs OOP
+
+> **When procedural code requires modifying existing functions to add new variants, OOP is the fix.**
+
+Procedural code is open to inspection but open to modification too — every new case touches existing logic.
+OOP (via Strategy, State, Observer, etc.) closes existing code to modification and opens it to extension through new types.
+The smell is always the same: **a place in the codebase that must change every time the domain grows.**

.opencode/skills/implementation/SKILL.md

@@ -135,7 +135,7 @@ Only write an ADR if the decision is non-obvious or has meaningful trade-offs. R
 Apply to the stub files just written:
 
 - [ ] No class with >2 responsibilities (SOLID-S)
-- [ ] No class with >2 instance variables (OC-8)
+- [ ] No behavioural class with >2 instance variables (OC-8; dataclasses, Pydantic models, value objects, and TypedDicts are exempt)
 - [ ] All external deps assigned a Protocol (SOLID-D + Hexagonal) — N/A if no external dependencies identified in scope
 - [ ] No noun with different meaning across modules (DDD Bounded Context)
 - [ ] No missing Creational pattern: repeated construction without Factory/Builder
@@ -254,7 +254,7 @@ As a software-engineer I declare:
 * OC-5: one dot per line — AGREE/DISAGREE | file:line
 * OC-6: no abbreviations — AGREE/DISAGREE | file:line
 * OC-7: ≤20 lines per function, ≤50 per class — AGREE/DISAGREE | longest: file:line
-* OC-8: ≤2 instance variables per class — AGREE/DISAGREE | file:line
+* OC-8: ≤2 instance variables per class (behavioural classes only; dataclasses, Pydantic models, value objects, and TypedDicts are exempt) — AGREE/DISAGREE | file:line
 * OC-9: no getters/setters — AGREE/DISAGREE | file:line
 * Patterns: no creational smell — AGREE/DISAGREE | file:line
 * Patterns: no structural smell — AGREE/DISAGREE | file:line

.opencode/skills/refactor/SKILL.md

@@ -291,7 +291,7 @@ Before marking the `@id` complete, verify all of the following. Each failed item
 | OC-5 | One dot per line | `obj.repo.find(id).name` |
 | OC-6 | No abbreviations | `usr`, `mgr`, `cfg`, `val`, `tmp` |
 | OC-7 | Classes ≤ 50 lines, methods ≤ 20 lines | Any method requiring scrolling |
-| OC-8 | ≤ 2 instance variables per class | `__init__` with 3+ `self.x =` assignments |
+| OC-8 | ≤ 2 instance variables per class *(behavioural classes only; dataclasses, Pydantic models, value objects, and TypedDicts are exempt)* | `__init__` with 3+ `self.x =` assignments in a behavioural class |
 | OC-9 | No getters/setters | `def get_name(self)` / `def set_name(self, v)` |
 
 ### SOLID (Martin 2000)

AGENTS.md

@@ -95,7 +95,7 @@ docs/architecture/
 
 tests/
   features/<feature-name>/
-    <rule-slug>_test.py               ← one per Rule: block, software-engineer-written
+    <rule_slug>_test.py               ← one per Rule: block, software-engineer-written
   unit/
     <anything>_test.py                ← software-engineer-authored extras (no @id traceability)
 ```
@@ -109,7 +109,7 @@ Tests in `tests/unit/` are software-engineer-authored extras not covered by any
 ## Test File Layout
 
 ```
-tests/features/<feature-name>/<rule-slug>_test.py
+tests/features/<feature-name>/<rule_slug>_test.py
 ```
 
 ### Function Naming
@@ -177,7 +177,7 @@ uv run task doc-serve
 - **Function length**: ≤ 20 lines
 - **Class length**: ≤ 50 lines
 - **Max nesting**: 2 levels
-- **Instance variables**: ≤ 2 per class
+- **Instance variables**: ≤ 2 per class *(exception: dataclasses, Pydantic models, value objects, and TypedDicts are exempt — they may carry as many fields as the domain requires)*
 - **Semantic alignment**: tests must operate at the same abstraction level as the acceptance criteria they cover
 - **Integration tests**: multi-component features require at least one test in `tests/features/` that exercises the public entry point end-to-end
 

docs/workflow.md

@@ -163,7 +163,9 @@ Each step has a designated agent and a specific deliverable. No step is skipped.
 │                                                                     │
 │  ARCHITECTURE SMELL CHECK — hard gate (fix before commit)           │
 │    [ ] No class with >2 responsibilities (SOLID-S)                 │
-│    [ ] No class with >2 instance variables (OC-8)                  │
+│    [ ] No behavioural class with >2 instance variables (OC-8;      │
+│        dataclasses, Pydantic models, value objects, TypedDicts      │
+│        are exempt)                                                  │
 │    [ ] All external deps assigned a Protocol (SOLID-D + Hexagonal) │
 │        N/A if no external dependencies identified in scope          │
 │    [ ] No noun with different meaning across planned modules        │
@@ -221,6 +223,11 @@ Each step has a designated agent and a specific deliverable. No step is skipped.
 │  │  │    Load skill refactor — follow its protocol          │ │   │
 │  │  │    uv run task test-fast after each individual change │ │   │
 │  │  │    EXIT: test-fast passes; no smells remain           │ │   │
+│  │  ├───────────────────────────────────────────────────────┤ │   │
+│  │  │  SELF-DECLARE                                         │ │   │
+│  │  │    Fill Self-Declaration block in TODO.md             │ │   │
+│  │  │    AGREE/DISAGREE per principle with file:line        │ │   │
+│  │  │    DISAGREE requires inline justification             │ │   │
 │  │  └───────────────────────────────────────────────────────┘ │   │
 │  │                                                             │   │
 │  │  Mark @id completed in TODO.md                             │   │
@@ -259,7 +266,7 @@ Each step has a designated agent and a specific deliverable. No step is skipped.
 │      * OC-5: one dot per line — AGREE/DISAGREE | file:line                │
 │      * OC-6: no abbreviations — AGREE/DISAGREE | file:line                │
 │      * OC-7: ≤20 lines per function — AGREE/DISAGREE | file:line          │
-│      * OC-8: ≤2 instance variables per class — AGREE/DISAGREE | file:line │
+│      * OC-8: ≤2 instance variables per class (behavioural classes only; dataclasses, Pydantic models, value objects, and TypedDicts are exempt) — AGREE/DISAGREE | file:line │
 │      * OC-9: no getters/setters — AGREE/DISAGREE | file:line              │
 │      * Patterns: no creational smell — AGREE/DISAGREE | file:line         │
 │      * Patterns: no structural smell — AGREE/DISAGREE | file:line         │
@@ -471,7 +478,7 @@ Source: docs/features/in-progress/<name>.feature
 
 ## Cycle State
 Test: @id:<hex> — <description>
-Phase: RED | GREEN | REFACTOR
+Phase: RED | GREEN | REFACTOR | SELF-DECLARE
 
 ## Self-Declaration
 As a software-engineer I declare:
@@ -493,7 +500,7 @@ As a software-engineer I declare:
 * OC-5: one dot per line — AGREE/DISAGREE | file:line
 * OC-6: no abbreviations — AGREE/DISAGREE | file:line
 * OC-7: ≤20 lines per function, ≤50 per class — AGREE/DISAGREE | longest: file:line
-* OC-8: ≤2 instance variables per class — AGREE/DISAGREE | file:line
+* OC-8: ≤2 instance variables per class (behavioural classes only; dataclasses, Pydantic models, value objects, and TypedDicts are exempt) — AGREE/DISAGREE | file:line
 * OC-9: no getters/setters — AGREE/DISAGREE | file:line
 * Patterns: no creational smell — AGREE/DISAGREE | file:line
 * Patterns: no structural smell — AGREE/DISAGREE | file:line
@@ -534,7 +541,7 @@ As a software-engineer I declare:
 | Function length | ≤ 20 lines |
 | Class length | ≤ 50 lines |
 | Max nesting | 2 levels |
-| Instance variables per class | ≤ 2 |
+| Instance variables per class | ≤ 2 (behavioural classes only; dataclasses, Pydantic models, value objects, TypedDicts are exempt) |
 | `noqa` comments | 0 |
 | `type: ignore` comments | 0 |
 | Orphaned tests | 0 |

tests/unit/app_test.py

@@ -7,7 +7,6 @@
 from app.__main__ import main
 
 
-@pytest.mark.unit
 @given(verbosity=st.sampled_from(["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]))
 @example(verbosity="INFO")
 def test_app_main_runs_with_valid_verbosity(verbosity: str) -> None: