@softspark/ai-toolkit 2.10.1 → 2.11.0

package/CHANGELOG.md

@@ -7,6 +7,20 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v2.11.0 — JSON Wire Format Rules (2026-04-21)
+
+### Added
+- **`app/rules/common/coding-style.md` v1.2.0 — JSON Wire Format Conventions section** — `camelCase` for field names (JSON:API, Google JSON Style, Symfony Serializer + `json_serializable` defaults), `UPPER_SNAKE_CASE` for enum/status/permission values (Protocol Buffers style guide, Google AIP-126 / api-linter, Zalando Rule #240, Java/Kotlin/C++/Python consensus). Explicit call-out that `camelCase` for enum VALUES is an anti-pattern with no major public API precedent.
+- **`app/rules/php/frameworks.md` v1.1.0 — Symfony Serializer section** — documents the `property-names-used-as-is` default, the global-override side effect of `api_platform.name_converter` ([api-platform/core #6101](https://github.com/api-platform/core/issues/6101)), pragmatic `#[SerializedName]` usage (only when justified), and the Symfony 7.3.5+ `ObjectNormalizer` `isXxx` behavior change ([symfony/symfony #62353](https://github.com/symfony/symfony/issues/62353)) that makes pre-7.3.5 `SerializedName` aliases redundant. API Platform section extended with `operation_name` metadata note.
+- **`app/rules/dart/frameworks.md` v1.1.0 — JSON Serialization section** — `json_serializable` `FieldRename.none` default + Effective Dart `lowerCamelCase` = `camelCase` JSON keys without configuration; community recommendation to prefer class-level `fieldRename` over per-field `@JsonKey(name:)`; enum value strategy (`UPPER_SNAKE_CASE` on wire, Dart case names stay `lowerCamelCase`).
+- **`tests/test_rules_content.bats` (3 bats cases)** — smoke tests guarding the three new rule sections (`JSON Wire Format Conventions`, `Symfony Serializer`, `JSON Serialization`). Heading-only checks, intentionally non-brittle. Test count: 666 → 669.
+
+### Notes
+- Changes are additive — no existing rule text removed or reworded. Projects that ran `ai-toolkit install --local` before v2.11.0 will pick up the new sections on next re-run (install is idempotent — existing TOOLKIT markers get replaced, not duplicated).
+- Rules codify documented facts + widely-cited community consensus, not project-specific enforcement. Project-level SOPs (grep gates, migration workflows, whitelists) remain in each project's `kb/procedures/`.
+
+---
+
 ## v2.10.1 — Art. VI Enforcement Drift Repair (2026-04-21)
 
 ### Fixed

package/README.md

@@ -6,16 +6,20 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-99-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-666%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-669%20passing-success)](tests/)
 
 ---
 
-## What's New in v2.10.1
+## What's New in v2.11.0
 
-- **Art. VI enforcement drift repaired** — `IMMUTABLE_ARTICLES` in `config_merger.py` and `config_validator.py` extended to include Article 6, so downstream `extends:` configs can no longer override Repair Discipline. Enterprise config schema, CLI diff label, and doc surfaces updated to match.
-- **Generator emits Article VI** — `scripts/emission.py::generate_quality_standards()` now includes Article VI's four clauses; `AGENTS.md`, `GEMINI.md`, `llms-full.txt`, and editor rule files (`.clinerules`, `.roo`, `.windsurf`, `.augment`, `.agents`, `.github/copilot-instructions.md`) all regenerated.
-- **Constitution self-consistency** — Article I.3 "Max 3" aligned to Section 4's "maximum 5 iterations". `validate.py --strict` now fails on article-count drift between `app/constitution.md` and downstream catalogs; the lint parses `## Article <roman>:` headings and fails on stale count or roman-range literals elsewhere.
-- **SKILL.md improvements from #8** (merged from @rohan-tessl) — `biz-scan`, `evolve`, `plan`, `predict`, and `teams` got richer descriptions, executable protocol steps, and structured report templates; team preset details moved to `teams/reference/presets.md` for progressive disclosure. 5 skills total, totals unchanged: 44 agents, 99 skills, 666 tests.
+- **JSON wire format rules added to `common/coding-style.md`** — `camelCase` for field names (aligned with JSON:API, Google JSON Style, Symfony Serializer + `json_serializable` defaults), `UPPER_SNAKE_CASE` for enum values (Protocol Buffers, Google AIP-126 / api-linter, Zalando Rule #240, Java/Kotlin/Python consensus). Anti-pattern call-out against `camelCase` for enum values (no major public API uses it).
+- **`php/frameworks.md` — Symfony Serializer section** — documents the property-names-as-is default, the global-override side effect of `api_platform.name_converter` ([api-platform/core #6101](https://github.com/api-platform/core/issues/6101)), pragmatic `#[SerializedName]` usage, and Symfony 7.3.5+ `ObjectNormalizer` `isXxx` behavior change ([#62353](https://github.com/symfony/symfony/issues/62353)) that retires pre-7.3.5 boolean-getter aliases.
+- **`dart/frameworks.md` — JSON Serialization section** — `json_serializable` `FieldRename.none` default + Effective Dart `lowerCamelCase` = `camelCase` output with zero config; community recommendation to prefer class-level `fieldRename` over per-field `@JsonKey(name:)`; enum value wire strategy (`UPPER_SNAKE_CASE`) while keeping Dart enum case names `lowerCamelCase`.
+
+### Previous: v2.10.1 — Art. VI Enforcement Drift Repair
+
+- Art. VI enforcement drift repaired (`IMMUTABLE_ARTICLES` extended to include Article 6; generator emits Article VI text; article-count drift lint added).
+- Constitution self-consistency fixes (Article I.3 aligned with Section 4) and SKILL.md improvements from #8 (merged from @rohan-tessl). Totals unchanged: 44 agents, 99 skills, 666 tests.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -143,7 +147,7 @@ ai-toolkit/
 │   └── ARCHITECTURE.md  # Full system design
 ├── kb/                  # Reference docs, procedures, plans
 ├── scripts/             # Validation, install, evaluation scripts
-├── tests/               # Bats test suite (666 tests)
+├── tests/               # Bats test suite (669 tests)
 └── CHANGELOG.md
 ```
 

package/app/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ai-toolkit",
   "description": "Professional-grade Claude Code toolkit with persona presets, skill security auditor, expanded lifecycle hooks, experimental opt-in plugin packs, benchmark harvesting, and multi-tool support.",
-  "version": "2.10.1",
+  "version": "2.11.0",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/rules/common/coding-style.md

@@ -1,7 +1,7 @@
 ---
 language: common
 category: coding-style
-version: "1.1.0"
+version: "1.2.0"
 ---
 
 # Universal Coding Style
@@ -69,6 +69,13 @@ version: "1.1.0"
   `1. [Step] → verify: [check]`
 - Strong success criteria enable independent looping. Weak criteria ("make it work") require clarification — ask first.
 
+## JSON Wire Format Conventions
+- Field names (keys): `camelCase`. Aligns with JSON:API spec, Google JSON Style Guide, and framework defaults (Symfony Serializer, Spring Jackson, `json_serializable` for Dart). No public major API uses `snake_case` keys in modern designs except ecosystem-bound cases (Rails/Django APIs defaulting to ecosystem convention).
+- Enum / status / permission / domain values: `UPPER_SNAKE_CASE`. Community consensus: [Protocol Buffers style guide](https://protobuf.dev/programming-guides/style/) (mandatory), [Google AIP-126 / api-linter](https://linter.aip.dev/126/upper-snake-values) (enforced), [Zalando Rule #240](https://opensource.zalando.com/restful-api-guidelines/), Java/Kotlin/C++/Python enum convention. `lowercase snake_case` (Stripe-style) is a legitimate outlier but not consensus.
+- Avoid `camelCase` for enum values — no major public API uses it, loses visual distinction between keys and values.
+- Pick one convention per project and enforce it with a CI grep gate. Mixing conventions inside a single API surface is the worst outcome.
+- External contracts (Stripe, GitHub, webhooks you receive) follow their own convention — map to your project convention at the adapter boundary, do not leak their keys past it.
+
 ## Anti-Patterns to Avoid
 - God classes/modules with 500+ lines and multiple responsibilities.
 - Deep nesting (>3 levels): use early returns and extract functions.

package/app/rules/dart/frameworks.md

@@ -1,7 +1,7 @@
 ---
 language: dart
 category: frameworks
-version: "1.0.0"
+version: "1.1.0"
 ---
 
 # Dart Frameworks
@@ -27,6 +27,14 @@ version: "1.0.0"
 - Set timeouts on every request: `connectTimeout`, `receiveTimeout`.
 - Use `CancelToken` for cancelling in-flight requests on navigation.
 
+## JSON Serialization
+- Use `json_serializable` (+ `build_runner`) for generated `fromJson`/`toJson`. Default `fieldRename: FieldRename.none` uses Dart property names as-is — combined with Effective Dart `lowerCamelCase`, this produces `camelCase` JSON keys with zero configuration.
+- Flutter docs recommend: *"best if both server and client follow the same naming strategy"* ([Flutter — JSON and serialization](https://docs.flutter.dev/data-and-backend/serialization/json)). When they do, no mapping is needed.
+- When server uses a different convention, prefer `@JsonSerializable(fieldRename: FieldRename.snake)` at the class level (or globally in `build.yaml`) over sprinkling `@JsonKey(name:)` on every field. Community recommendation from the `json_serializable` docs and pub.dev guides.
+- Use individual `@JsonKey(name: '...')` only for exceptional cases: external API with mixed conventions, reserved Dart keyword collision (`class`, `is`, `new`), or legacy field rename during deprecation window. Document the reason in a comment.
+- For enum / status / permission values on the wire: `UPPER_SNAKE_CASE` is the cross-language community consensus (see `common/coding-style.md` — JSON Wire Format Conventions). Dart enum case names themselves stay `lowerCamelCase` per Effective Dart; map them to uppercase strings in `fromJson`/`toJson` (`value.toUpperCase()` + `switch`).
+- Write unit tests asserting both directions (`fromJson` + `toJson`) with explicit expected keys. Catches contract drift at CI time.
+
 ## Local Storage
 - Use `shared_preferences` for simple key-value persistence.
 - Use `drift` (formerly Moor) for type-safe SQLite with reactive queries.

package/app/rules/php/frameworks.md

@@ -1,7 +1,7 @@
 ---
 language: php
 category: frameworks
-version: "1.0.0"
+version: "1.1.0"
 ---
 
 # PHP Frameworks
@@ -36,12 +36,21 @@ version: "1.0.0"
 - Use migrations: `bin/console doctrine:migrations:diff` and `migrate`.
 - Use lifecycle callbacks (`@PrePersist`, `@PostUpdate`) for entity events.
 
+## Symfony Serializer
+- Default behavior uses property names as-is. Combined with PSR-12 `camelCase` property names, JSON output is `camelCase` with zero configuration.
+- Avoid adding `api_platform.name_converter: CamelCaseToSnakeCaseNameConverter` globally. Known side-effect ([api-platform/core #6101](https://github.com/api-platform/core/issues/6101)): overrides the project-wide `MetadataAwareNameConverter`, affecting Messenger serializers, custom normalizers, and CLI JSON output — not just the HTTP API.
+- Use `#[SerializedName]` only when justified: legacy field alias during rename, external contract mapping, ObjectNormalizer cross-version stabilization. Community practice ([Symfony docs](https://symfony.com/doc/current/serializer.html), Sylius, SymfonyCasts): prefer clean property/getter naming over aliases. When using, document the reason next to the attribute.
+- Symfony 7.3.5+ `ObjectNormalizer` produces `isActive` natively for a `isActive(): bool` getter ([symfony/symfony #62353](https://github.com/symfony/symfony/issues/62353)). Older `#[SerializedName('isActive')]` aliases added for pre-7.3.5 `ObjectNormalizer` (which produced `active`) are redundant after upgrade — remove them.
+- Avoid duplicate getters like `isActive()` + `getIsActive()` on the same property — `ObjectNormalizer` treats them as two fields and serializes ambiguously. Keep one (`isXxx()` for booleans, `getXxx()` otherwise).
+
 ## API Platform
 - Use API Platform for rapid REST/GraphQL API generation from entities.
 - Use `#[ApiResource]` attribute for automatic CRUD endpoint generation.
 - Use custom state providers and processors for business logic.
 - Use serialization groups for controlling response shape.
 - Use filters for query parameter support: pagination, search, ordering.
+- Property names on `ApiResource` DTOs drive JSON keys directly (see Symfony Serializer above). Write them in `camelCase` — that is both the Symfony default and the dominant JSON API convention.
+- Use `operation_name` in `extraProperties` for dispatch metadata (e.g., `extraProperties: ['operation_name' => 'club_activate']`). The key `operation_name` and its `snake_case` values are framework metadata, not JSON wire keys — keeping them `snake_case` is expected.
 
 ## Livewire (Laravel)
 - Use Livewire components for reactive UI without JavaScript.

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.10.1",
+  "version": "2.11.0",
   "components": {
     "agents": {
       "description": "44 specialized agents (orchestrator, backend, frontend, security, devops, etc.)",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "2.10.1",
+  "version": "2.11.0",
   "description": "AI coding toolkit: 99 skills, 44 agents, 12-editor write-through (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo, Aider, Augment, Antigravity, Codex, opencode), machine-enforced safety constitution, SARIF audit, signed npm provenance.",
   "keywords": [
     "claude",