@softspark/ai-toolkit 4.32.3 → 4.33.0

package/CHANGELOG.md

@@ -7,6 +7,67 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v4.33.0 - DSH refresh and maintenance contracts (2026-09-06)
+
+### Changed
+
+- Explicit DSH profile lifecycle targets runtime `0.1.2-rc.1` and exact packages
+  `@softspark/dsh-codex@1.5.0` and `@softspark/dsh-orchestrator@2.0.0`.
+  Upgrade the DSH runtime before updating the managed profile packages.
+- Refresh the ecosystem source references and retain the pnpm 11 support range
+  declared by the reviewed upstream release.
+
+### Fixed
+
+- Automatically select Claude Agent SDK `0.3.263` for the DSH Claude provider,
+  replacing the bundled CLI rejected by current models. Preserve unrelated
+  profile settings and restore prior configuration after failed installation
+  or update; concurrent file replacements remain preserved for recovery.
+- Align the security support table with the current 4.x release line and describe
+  the actual scope of hooks, network-aware commands, and managed installation files.
+- Require documentation, generated surfaces, and counts to change in the same
+  pull request as the corresponding behavior.
+- Cover migration from the previously shipped DSH package pair and retain
+  rollback tests that restore the exact recorded package versions.
+- Canonicalize temporary test roots on macOS so recovery assertions compare
+  the same paths reported by the lifecycle without weakening the assertions.
+
+## v4.32.4 - Validation parity and API error contracts (2026-09-06)
+
+### Changed
+
+- **Validation contracts:** Add practical guidance to `/api-patterns`,
+  `/security-patterns`, `/review` and `/testing-patterns` for a shared backend
+  and frontend rule source, operation-specific DTO groups/defaults, finite
+  collection bounds, Unicode units, explicit server-only checks and parity
+  fixtures. Local validation failures remain distinct from HTTP responses.
+  Cross-skill references resolve through the installed catalog so namespaced
+  adapters, including GitHub Copilot, can find the same guidance.
+- **API error contracts:** Preserve the host's error representation and
+  distinguish domain refusals from technical failures. Cover actionable
+  messages, JSON types, background-job failures, unknown outcomes and safe
+  retries. Common security/testing rules retain shared-database test isolation.
+
+### Fixed
+
+- **Schema guidance:** Correct JSON Schema conditional requirements and Ajv
+  strict-mode semantics, retain domain checks alongside boundary validation,
+  and import `Field` in the Pydantic example. The FastAPI example catches a
+  specific request refusal while preserving its exception cause.
+- **Release verification:** Compare inventories with the current artifact,
+  run installation smoke in a disposable environment, and fail when an
+  expected generated JSON file is missing. Preserve the operator's install
+  and authentication state during candidate and published-package checks.
+- **Package metadata:** Refresh skill and hook inventory descriptions.
+
+### Release checks
+
+- **Ecosystem:** Refresh documentation hashes and local CLI version probes;
+  the review found no heading or capability-marker changes and changes no
+  generators, runtime integration paths or permission declarations.
+- **Skill body budget:** Keep the existing 18,000-byte warning threshold;
+  the largest body remains 17,197 bytes, so the ratchet cannot tighten yet.
+
 ## v4.32.3 — Search-first stops firing on things nobody asked (2026-09-04)
 
 ### Fixed

package/README.md

@@ -6,30 +6,21 @@
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-114-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-1978%20passing-success)](tests/)
-
-## What's New in v4.32.3
-
-**v4.32.3** stops search-first enforcement firing on things nobody asked:
-
-- **A background task finishing no longer blocks `Stop`.** The search-required
-  flag was set on any stdin over 30 characters, and the harness delivers
-  background-task notifications, CI events and replayed slash-command output
-  on the same channel as a prompt. Event envelopes no longer set it.
-- **A pasted credential no longer becomes a search query.** A 43-character API
-  key on its own line cleared the length gate, and the block message names the
-  prompt as the thing to search for — so the enforcement path asked for a live
-  secret to be sent to a retrieval service. Single-token prompts no longer set
-  the flag.
-- Nothing that was enforced before stops being enforced: a genuine one-word
-  prompt is under the length gate anyway, and prose that merely mentions a task
-  notification still sets the flag. That case is now a test.
-- Still in this train: exports land in the directory you ran the command in
-  (v4.32.2); `plugin remove` leaves nothing behind, every skill script answers
-  `--help` (v4.32.1); path-scoped common rules, project-scoped language skills,
-  `doctor` context-budget and permission checks, one strict frontmatter parser,
-  `git-team` for `--profile strict` (v4.32.0). Test count: 1974 -> 1978 bats +
-  348 pytest.
+[![Tests](https://img.shields.io/badge/tests-1989%20passing-success)](tests/)
+
+## What's New in v4.33.0
+
+**v4.33.0** refreshes the explicit DSH lifecycle and public maintenance policies:
+
+- **Current DSH package pins.** Explicit profile installation and updates target
+  DSH `0.1.2-rc.1`, `dsh-codex 1.5.0`, and `dsh-orchestrator 2.0.0`.
+- **Existing profile ownership survives the update.** Regression tests cover
+  refreshing the previously shipped package pair and restoring the recorded
+  versions when an update fails.
+- **Accurate security scope.** The support table follows the current release
+  line, and the policy describes the actual installation and network boundaries.
+- **Documentation travels with code.** Contributions update affected KB pages,
+  manifests, counts, and generated instructions in the same pull request.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -102,7 +93,7 @@ ai-toolkit dsh doctor --profile web
 ai-toolkit dsh uninstall --profile web --yes
 ```
 
-DSH is excluded from `--editors all`, auto-detection, and defaults. Its only DSH-specific project output is `.agents/skills`; the normal `--local` Claude files, detected language rules, and other generic project outputs still apply. Project and profile `--dry-run` commands are read-only. The reviewed pins are DSH `0.1.1-rc.2`, `@softspark/dsh-codex@1.0.0`, and `@softspark/dsh-orchestrator@1.0.1`. Codex, Claude Code, and GitHub Copilot own their logins. ai-toolkit accepts no provider API keys, and GitHub AI credits apply to the Copilot Gemini route. Isolated pre-tag and exact-registry post-release qualification completed both Claude Code and Copilot Gemini marker roundtrips through the Codex parent. See [DSH Compatibility](kb/reference/dsh-compatibility.md).
+DSH is excluded from `--editors all`, auto-detection, and defaults. Its only DSH-specific project output is `.agents/skills`; the normal `--local` Claude files, detected language rules, and other generic project outputs still apply. Project and profile `--dry-run` commands are read-only. The lifecycle targets DSH `0.1.2-rc.1`, `@softspark/dsh-codex@1.5.0`, and `@softspark/dsh-orchestrator@2.0.0`. Update the DSH runtime before updating this profile integration. Codex, Claude Code, and GitHub Copilot own their logins. ai-toolkit accepts no provider API keys, and GitHub AI credits apply to the Copilot Gemini route. See [DSH Compatibility](kb/reference/dsh-compatibility.md) for the exact contract and version-specific qualification evidence.
 
 ### Plugin Management
 
@@ -211,7 +202,7 @@ ai-toolkit/
 │   ├── agents/          # 44 agent definitions
 │   ├── skills/          # 114 skills (task / hybrid / knowledge)
 │   ├── rules/           # Source rules synced into Claude/editor rule files
-│   ├── hooks/           # Hook scripts (29 entries, 14 lifecycle events)
+│   ├── hooks/           # Hook scripts (28 entries, 14 lifecycle events)
 │   ├── claude-app/      # Generated Chat/Cowork plugin rules, hooks, instructions
 │   ├── plugins/         # 2 experimental plugin packs (opt-in)
 │   ├── output-styles/   # System prompt output style overrides

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

@@ -3,7 +3,7 @@
   "name": "ai-toolkit",
   "displayName": "AI Toolkit",
   "description": "Professional-grade engineering skills, agents, rules, and lifecycle guardrails for Claude Code, Claude Chat, and Cowork.",
-  "version": "4.32.3",
+  "version": "4.33.0",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/ARCHITECTURE.md

@@ -8,7 +8,7 @@ Universal multi-agent system for software development. Works across all reposito
 |-----------|-------|
 | Agents | See agents catalog |
 | Skills | See skills catalog |
-| Hooks | 14 events / 29 entries (SessionStart ×2, Notification ×1, PreToolUse ×5, UserPromptSubmit ×2, PostToolUse ×6, Stop ×4, TaskCompleted ×1, TeammateIdle ×1, SubagentStart ×1, SubagentStop ×1, PreCompact ×2, SessionEnd ×1, InstructionsLoaded ×1, ConfigChange ×1) plus statusLine |
+| Hooks | 14 events / 28 entries (SessionStart ×2, Notification ×1, PreToolUse ×5, UserPromptSubmit ×2, PostToolUse ×5, Stop ×4, TaskCompleted ×1, TeammateIdle ×1, SubagentStart ×1, SubagentStop ×1, PreCompact ×2, SessionEnd ×1, InstructionsLoaded ×1, ConfigChange ×1) plus statusLine |
 
 ---
 

package/app/claude-app/skills/ai-toolkit-rules/SKILL.md

@@ -352,7 +352,8 @@ Solo-safe core: everything here holds whether one person or twenty merge into
 - Use HTTPS everywhere. No exceptions.
 - Implement rate limiting and request throttling.
 - Set CORS headers explicitly. Never use `*` in production.
-- Return generic error messages to clients. Log details server-side.
+- Return safe, actionable messages for known failures; use a neutral fallback when the cause is unknown or disclosure would reveal protected information.
+- Keep SQL, stack traces and provider internals out of ordinary client responses, including 4xx and background-job error fields. Preserve original causes in access-controlled, redacted diagnostics.
 - Use security headers: HSTS, X-Content-Type-Options, X-Frame-Options.
 
 ## Dependencies
@@ -403,6 +404,12 @@ Solo-safe core: everything here holds whether one person or twenty merge into
 - Tests must be fast: unit tests <100ms each, test suite <60s.
 - Avoid `sleep` in tests: use polling, events, or test clocks.
 - Do not test implementation details (private methods, internal state).
+- Run integration suites serially when they share or reset a database. Parallel runners need isolated databases/stores; a filtered test must not invalidate an in-progress full suite.
+
+## API Error Paths
+- For changed error handling, assert the actual status, public code/message, field paths, locale and recovery headers through the API boundary.
+- Preserve JSON object/list types, including empty nested `{}` and `[]`, when testing response filters.
+- Exercise real database constraints, idempotent replay and known versus uncertain write outcomes; schema-generated fixtures may omit migration-only indexes.
 
 ## Coverage
 - Measure coverage but do not chase 100%: focus on critical paths.

package/app/rules/common/security.md

@@ -45,7 +45,8 @@ version: "1.0.0"
 - Use HTTPS everywhere. No exceptions.
 - Implement rate limiting and request throttling.
 - Set CORS headers explicitly. Never use `*` in production.
-- Return generic error messages to clients. Log details server-side.
+- Return safe, actionable messages for known failures; use a neutral fallback when the cause is unknown or disclosure would reveal protected information.
+- Keep SQL, stack traces and provider internals out of ordinary client responses, including 4xx and background-job error fields. Preserve original causes in access-controlled, redacted diagnostics.
 - Use security headers: HSTS, X-Content-Type-Options, X-Frame-Options.
 
 ## Dependencies

package/app/rules/common/testing.md

@@ -46,6 +46,12 @@ paths:
 - Tests must be fast: unit tests <100ms each, test suite <60s.
 - Avoid `sleep` in tests: use polling, events, or test clocks.
 - Do not test implementation details (private methods, internal state).
+- Run integration suites serially when they share or reset a database. Parallel runners need isolated databases/stores; a filtered test must not invalidate an in-progress full suite.
+
+## API Error Paths
+- For changed error handling, assert the actual status, public code/message, field paths, locale and recovery headers through the API boundary.
+- Preserve JSON object/list types, including empty nested `{}` and `[]`, when testing response filters.
+- Exercise real database constraints, idempotent replay and known versus uncertain write outcomes; schema-generated fixtures may omit migration-only indexes.
 
 ## Coverage
 - Measure coverage but do not chase 100%: focus on critical paths.

package/app/skills/api-patterns/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: api-patterns
-description: "REST/GraphQL API design: naming, versioning, pagination, idempotency, OpenAPI. Triggers: API design, REST, GraphQL, OpenAPI, Swagger, idempotency, rate limit."
+description: "API design: naming, versioning, pagination, idempotency, OpenAPI, error contracts and safe retries. Triggers: API design, REST, GraphQL, OpenAPI, Swagger, error response, HTTP status, rate limit."
 effort: medium
 user-invocable: false
 allowed-tools: Read
@@ -34,17 +34,24 @@ GET    /api/v1/users/{id}/documents  # User's documents
 | 200 | OK | Successful GET/PUT/PATCH |
 | 201 | Created | Successful POST |
 | 204 | No Content | Successful DELETE |
-| 400 | Bad Request | Invalid input |
+| 400 | Bad Request | Malformed request or an established domain refusal |
 | 401 | Unauthorized | Missing/invalid auth |
 | 403 | Forbidden | No permission |
 | 404 | Not Found | Resource doesn't exist |
-| 409 | Conflict | Duplicate resource |
+| 405 | Method Not Allowed | Unsupported method; preserve Allow |
+| 409 | Conflict | Duplicate resource or current-state conflict |
+| 412 | Precondition Failed | Supplied concurrency version is stale |
 | 422 | Unprocessable | Validation error |
+| 428 | Precondition Required | Required concurrency precondition is missing |
 | 429 | Too Many Requests | Rate limited |
 | 500 | Internal Error | Server error |
+| 503 | Service Unavailable | Dependency temporarily unavailable |
 
 ### Response Format
 
+Follow the host's existing resource and collection contract. This envelope is
+illustrative; do not impose it on a framework that already defines another shape.
+
 ```json
 {
   "data": {
@@ -65,6 +72,9 @@ GET    /api/v1/users/{id}/documents  # User's documents
 
 ### Error Response
 
+Use the established error representation, which may be problem details,
+framework validation errors, or a domain-specific envelope like this example:
+
 ```json
 {
   "error": {
@@ -78,6 +88,17 @@ GET    /api/v1/users/{id}/documents  # User's documents
 }
 ```
 
+When implementing or reviewing failure paths, read
+[Error contracts and safe retries](reference/error-contracts.md). Classify from
+the original cause, preserve public codes and JSON types, and distinguish an
+unknown operation outcome from a confirmed refusal. Do not turn arbitrary
+server failures into invalid-input responses.
+
+When adding client-side validation, read `reference/input-validation.md` from
+the installed `security-patterns` skill. Resolve that skill through the current
+client's catalog, since adapters may namespace skill directory names.
+Use one authoritative rule source and prove parity at the request boundary.
+
 ---
 
 ## FastAPI Implementation
@@ -88,6 +109,9 @@ from pydantic import BaseModel, Field
 
 app = FastAPI(title="RAG-MCP API", version="1.0.0")
 
+class InvalidSearchQuery(Exception):
+    """Known request-level refusal from the application-owned search adapter."""
+
 class SearchRequest(BaseModel):
     query: str = Field(..., min_length=1, description="Search query")
     limit: int = Field(10, ge=1, le=100, description="Max results")
@@ -115,8 +139,11 @@ async def search(request: SearchRequest):
     try:
         results = await perform_search(request.query, request.limit)
         return SearchResponse(results=results, total=len(results))
-    except ValueError as e:
-        raise HTTPException(status_code=400, detail=str(e))
+    except InvalidSearchQuery as exc:
+        raise HTTPException(
+            status_code=400,
+            detail="The search query is not supported. Check its syntax.",
+        ) from exc
 ```
 
 ---
@@ -146,7 +173,7 @@ In OpenAPI, pair `enum` with the value meanings in the description (or `x-enum-d
 
 ### Encode cross-field dependencies in the description
 
-If a field is only valid given another, say so where the dependent field is defined — schemas cannot express "required when":
+Document cross-field requirements where the dependent field is defined and encode them in the supported schema dialect. JSON Schema supports conditional requirements with `dependentRequired` or `if`/`then`; application state and opaque-token provenance still require prose and runtime checks. See [conditional schema validation](https://json-schema.org/understanding-json-schema/reference/conditionals).
 
 ```python
 cursor: str | None = Field(
@@ -372,10 +399,10 @@ Accept: application/vnd.myapi.v1+json
 ## Hard Rules
 
 - **MUST** version the API from day one (URL path or Accept header) — unversioned APIs break clients on every change
-- **MUST** validate every input at the API boundary, not inside business logic
+- **MUST** validate input type, format and size at the API boundary; enforce state-dependent domain invariants in business logic as well
 - **MUST** use PUT for full replacement and PATCH for partial update — confusing the two causes silent data loss
 - **NEVER** return unbounded list responses — pagination (offset or cursor) is mandatory
-- **NEVER** expose stack traces or internal error details in 5xx responses — clients get a `code`, `message`, and optional `details[]`
+- **NEVER** expose private implementation details in ordinary API errors, including 4xx and background-job error fields; preserve the host's public error representation
 - **CRITICAL**: idempotency on POST/PUT/PATCH is non-negotiable when retries are possible — accept an `Idempotency-Key` header or design the endpoint to be naturally idempotent
 - **CRITICAL**: rate limits exist from the first deploy, not "later" — unprotected endpoints get abused within hours
 
@@ -395,10 +422,10 @@ Accept: application/vnd.myapi.v1+json
 ## Gotchas
 
 - CDN and load-balancer caches key on the full URL by default. If you version via both URL path and `Accept` header (e.g., `/api/v1/...` + `Accept: application/vnd.myapi.v2+json`), the edge returns the wrong payload for non-path versioning. Pick one versioning axis and stick to it.
-- OpenAPI `additionalProperties: false` is **not** enforced by most JSON Schema validators unless you explicitly enable strict mode (`ajv({strict: true})`, Pydantic `Config.extra = "forbid"`). An API marked "strict" in the spec silently accepts unknown fields.
+- A published OpenAPI schema does not prove request enforcement. Ajv enforces `additionalProperties: false` when that schema is executed; its strict mode checks schema correctness and does not change validation results. Verify that the request boundary runs the intended schema and test unknown fields. See [Ajv strict mode](https://ajv.js.org/strict-mode.html) and [additionalProperties](https://ajv.js.org/json-schema.html#additionalproperties).
 - `Idempotency-Key` only works if the server persists the mapping from key to response — purely in-memory implementations forget it on restart. Back it with Redis or the primary DB.
 - HTTP methods are **case-sensitive** per RFC 7230 (all uppercase); some clients and proxies normalize, some don't. A `post` method reaches the server as-is through some edge proxies and hits a 405 instead of the POST route.
-- `429 Too Many Requests` without a `Retry-After` header leaves clients guessing — most libraries back off exponentially from zero and hammer the server. Always include `Retry-After` on 429 and 503.
+- Give rate-limited callers a meaningful `Retry-After`. For 503, include it when the server can provide a credible retry window; do not invent an outage duration. A retry header does not prove that repeating a write is safe.
 
 ## When NOT to Load
 
@@ -407,4 +434,3 @@ Accept: application/vnd.myapi.v1+json
 - For **language-specific idioms** (Fastify middleware chains, ASP.NET minimal APIs, etc.) — pair this skill with `/typescript-patterns`, `/csharp-patterns`, etc.
 - For **OpenAPI schema authoring** as the primary task — use `/docs` with OpenAPI output; this skill is design-only
 - For **authentication deep-dives** beyond the starter API-key and JWT snippets — use `/security-patterns`
-

package/app/skills/api-patterns/reference/error-contracts.md

@@ -0,0 +1,88 @@
+# Error Contracts and Safe Retries
+
+Use this reference for API failure paths. Apply the host's current contract and
+keep unrelated endpoints, schemas and workflows outside the requested change.
+
+## Classify before wording
+
+- Trace the original exception and persisted/provider state. A truncated message
+  or a generic unique-constraint error does not identify the affected entity.
+- Prefer typed domain exceptions and structured database/provider codes. If a
+  constraint name is available only in text, read its diagnostic header rather
+  than matching a submitted value in the detail section.
+- Distinguish malformed input, authorization, current-state conflict and a
+  dependency failure. Preserve deliberate domain-specific status conventions;
+  do not mechanically rewrite every existing 400.
+- Catch known domain failures narrowly and preserve the exception cause. A
+  catch-all that copies arbitrary exception text into a 4xx response both leaks
+  internals and blames the caller for server failures.
+
+## Give a supported explanation and a safe action
+
+A useful message identifies the affected operation/resource, the cause that is
+actually known, and the next safe action. Use a neutral fallback when the cause
+is unknown or disclosing it would reveal protected information.
+
+| Observation | Response direction |
+|---|---|
+| A resource already has an open session | Explain the existing-session conflict |
+| A provider request received no response | Explain the missing response, not a supposed provider rejection |
+| The date parser rejected a timestamp | Identify the date/time problem, not an unrelated score or amount |
+| An internal persistence invariant failed | Report a server failure, not a missing client field |
+| A refund may have been accepted remotely | Require reconciliation before another refund |
+
+Keep SQL, traces, internal paths and provider internals out of ordinary failure
+text. Preserve original causes in access-controlled, redacted diagnostics.
+Sanitized administrator connection tests and expected row-level validation may
+legitimately provide more detail; do not erase useful authorized diagnostics.
+
+## Preserve the wire contract
+
+- Keep existing envelopes, machine codes, field paths and supported media types.
+  A client-owned error code must not silently become localized server prose.
+- Preserve JSON object/list types, including empty nested `{}` and `[]`.
+  Test the round trip when adding a response filter or normalizer.
+- Keep recovery headers such as `Allow`, `Retry-After`, authentication challenges
+  and concurrency preconditions.
+- Verify the host's actual locale selection and fallback. Do not invent a
+  profile/tenant/header precedence or assume every existing literal is translated.
+- Cover router/firewall errors outside the main API framework and account for
+  cloned requests or error subrequests before relying on request attributes.
+- Inspect error fields returned with HTTP 200 by background-job status APIs and
+  downloadable failure reports. Retain domain validation; sanitize unexpected
+  worker failures without changing retry/accounting behavior.
+
+## Do not infer rollback from the response
+
+A transaction can commit before serialization or response delivery fails. A
+remote service can accept an operation before its reply is lost. An HTTP error,
+including a 5xx, therefore does not prove that nothing happened.
+
+Use the operation's existing idempotency/reconciliation contract. Confirm state
+before creating another write. Do not recommend blind replay of an uncertain
+payment, refund or other external mutation, and do not remove a database
+invariant merely to make its error disappear.
+
+## Verify behavior at the boundary
+
+Choose tests for the paths actually changed:
+
+- real constraints, including migration-only indexes omitted by test schemas;
+- expected refusals versus unexpected runtime/provider failures;
+- idempotent replay, conflicts and recovery after the conflict is resolved;
+- HTTP status, public text/code, field paths, locale and recovery headers;
+- supported response formats and empty object/list preservation;
+- known versus uncertain write outcomes and background-job error fields;
+- diagnostic retention without public technical details.
+
+Test actual rate-limit exhaustion and recovery. A non-consuming peek may report
+that the peek was accepted even when no request budget remains; the configured
+limiter's behavior determines the guard.
+
+Run tests serially when they share or reset a database. Parallel test runners
+need isolated databases/stores; a filtered test must not reset the fixtures of
+an in-progress full suite.
+
+For additional project evidence, when RAG-MCP is available, retrieve
+`shared/rag-mcp/best-practices/api-error-contracts.md`. The guidance above is
+self-contained and does not require that integration.

package/app/skills/review/SKILL.md

@@ -125,7 +125,12 @@ After all reviewers complete:
 - [ ] Backward compatibility preserved (no silent breaking changes)
 - [ ] API versioning updated if contract changed
 - [ ] Schema validation on request/response
+- [ ] Client validation uses the authoritative input contract, including operation groups/defaults, finite bounds, nested paths and documented Unicode units; read `reference/input-validation.md` from the `security-patterns` skill located through the current client's installed catalog
+- [ ] Shared backend/client fixtures and generation drift checks cover changed rules; unsupported/server-only checks are explicit, and local refusals do not masquerade as HTTP responses
 - [ ] Error responses follow project convention
+- [ ] Statuses and messages distinguish input/state refusals from infrastructure failures; original causes remain available in authorized diagnostics
+- [ ] Error filtering preserves machine codes, field paths, JSON object/list types, locale and recovery headers; background-job error fields are covered too
+- [ ] Retry advice reflects known persisted/provider state and does not invite blind replay of an uncertain mutation
 - [ ] Wire-level contracts checked, not just code signatures: HTTP routes, webhook payloads, event/queue schemas
 
 ### Concurrency / Async

package/app/skills/security-patterns/SKILL.md

@@ -129,13 +129,13 @@ For authentication patterns (JWT, passwords, token strategy), see [reference/aut
 
 For authorization patterns (RBAC, ABAC), see [reference/authorization.md](reference/authorization.md).
 
-For input validation patterns (SQL injection, XSS, Pydantic), see [reference/input-validation.md](reference/input-validation.md).
+For input validation, client/backend contract parity, finite bounds and Unicode gotchas, see [reference/input-validation.md](reference/input-validation.md).
 
 For OAuth2 flows, CSRF protection, and audit logging, see [reference/oauth-csrf-audit.md](reference/oauth-csrf-audit.md).
 
 ## Rules
 
-- **MUST** validate all input at the trust boundary, not inside business logic — deep validation allows bad data to spread before rejection
+- **MUST** validate input type, format and size at the trust boundary; domain logic must also enforce state-dependent invariants before side effects
 - **MUST** use parameterized queries (prepared statements) for every SQL interaction — string concatenation is SQL injection
 - **NEVER** store secrets (API keys, tokens, passwords) in code, config files, or git history — use the platform's secret manager
 - **NEVER** log passwords, tokens, PII, or PHI — even at debug level. Logs reach aggregation systems, backups, and disk snapshots.

package/app/skills/security-patterns/reference/input-validation.md

@@ -2,7 +2,7 @@
 
 ## Validation Rules
 ```python
-from pydantic import BaseModel, EmailStr, constr
+from pydantic import BaseModel, EmailStr, Field, constr
 
 class UserInput(BaseModel):
     email: EmailStr
@@ -10,6 +10,74 @@ class UserInput(BaseModel):
     age: int = Field(ge=0, le=150)
 ```
 
+## Validation contract gotchas
+
+These traps came from repeated corrections during a DTO-to-client validation
+rollout. Apply them when a client mirrors server rules; they do not require a
+new generator for every small form.
+
+- **Two validators can still be two conflicting policies.** Derive portable
+  client checks from the server's authoritative schema or resolved metadata.
+  A shared schema is also valid when the backend actually enforces it. Bind
+  field feedback and serialized-payload preflight to that same contract.
+  Backend enforcement remains mandatory, including when client code is bypassed.
+- **The entity may never be validated.** Trace the operation's real input object.
+  In API Platform, an input DTO can be validated before mapping to an entity.
+  Validation groups select constraints; denormalization groups select writable
+  fields. Output-only constraints add no protection to the request path.
+- **PATCH does not make every property optional.** An update hydrated from
+  existing state and a newly constructed input DTO have different missing-field
+  semantics. Preserve actual defaults and distinguish omitted keys, null and
+  empty values. Resolve this per operation, not from the HTTP method alone.
+- **A constraint name is not a finite bound.** Length(min), Count(min),
+  All(Email) and an unbounded regex do not cap input size. Check actual maximum
+  values, collection size, item shape/type and nested validation separately.
+  In Symfony, retain All/Collection/Valid and sequential evaluation semantics.
+  Bound body size and violation output too; stop expensive item validation
+  after an oversized list is refused.
+- **A field name does not identify its storage or wire format.** Read the
+  mapper/processor and owning storage before choosing limits. An Id field can
+  accept an IRI; a timestamp ceiling does not validate a real date. Feature
+  limits and established domain error codes can be stricter or more specific
+  than a generic ceiling. Do not replace them accidentally in a bulk pass.
+- **Unicode length has several units.** Specify bytes, code units, codepoints
+  or grapheme clusters and the normalization order. Test decomposed accents,
+  non-BMP characters, joined emoji and IME composition. A client must not
+  silently truncate a value the server accepts; preserve input when showing an
+  error. Do not normalize passwords or apply identifier alphabet rules to
+  names without a documented product policy.
+- **Rule names hide runtime options.** Email modes, URL schemes, numeric
+  coercion, regex dialects and conditional validation can differ across
+  languages. Export supported options explicitly. Conditional rules are
+  audited data, never arbitrary server expressions evaluated in the client.
+- **Some checks depend on server state or libraries.** Keep authorization,
+  availability, uniqueness and domain invariants on the server. If a portable
+  equivalent is unavailable, record the exact operation/field/rule and reason
+  in reviewed policy. Newly unsupported rules must surface as a failed
+  generation/check step, not become an always-valid adapter. Bodyless routes
+  and exclusions are separate measurements, not evidence of client coverage.
+- **A local refusal is not an HTTP response.** Use a distinct local error type,
+  preserve field paths and rule codes, and show localized field feedback.
+  Do not invent an HTTP status or trigger token refresh/network retry for a
+  request that was never sent. Server refusals remain authoritative; keep
+  local/server error state distinguishable and test correction/resubmission.
+- **Generation proves synchronization, not semantic equivalence.** Run shared
+  accepted/rejected fixtures through the real backend validator and client
+  evaluator, including both conditional branches and nested error paths.
+  Check deterministic generation and reviewed exclusions in CI. A snapshot
+  of the exporter tested against itself does not prove parity. HTTP tests
+  must also exercise deserialization and rejected-write persistence behavior.
+
+Input validation does not replace parameterized queries or context-appropriate
+output encoding. The backend may still reject a client-valid request because
+state changed after local validation.
+
+For regression selection, use the "Validation contract regressions" section
+of the installed `testing-patterns` skill. For HTTP failure semantics, read
+`reference/error-contracts.md` from the installed `api-patterns` skill.
+Locate these skills through the current client's catalog because adapters may
+namespace their directory names.
+
 ## SQL Injection Prevention
 ```python
 # Bad

package/app/skills/testing-patterns/SKILL.md

@@ -53,6 +53,25 @@ tests/
 
 ---
 
+## Validation contract regressions
+
+Mirrored validators can agree on a generated snapshot while disagreeing on real
+inputs. Execute the same accepted/rejected fixtures against the real backend
+validator and the client evaluator. Include N/N+1 boundaries, collection/item
+limits, omitted/null/empty/default values, nested paths, conditional branches,
+hydrated updates versus fresh DTOs, Unicode units and previously valid inputs.
+
+Test the actual HTTP path for malformed input and unchanged persisted state
+after a pre-write refusal. Test zero transport calls for a local refusal,
+normal transport for a valid payload, and field correction/resubmission.
+Run deterministic-generation and reviewed-exclusion checks separately from
+behavioral parity. A schema/rule count is inventory, not assertion coverage.
+
+For operation semantics and runtime mismatches, read
+`reference/input-validation.md` from the installed `security-patterns` skill.
+Resolve the skill through the current client's catalog; directory names may
+carry an adapter-specific prefix.
+
 ## Language-Specific References
 
 | Language | Reference | Key Topics |