feat: add governed State Management domain

.github/CODEOWNERS

@@ -14,6 +14,7 @@
 /design-engineering/reference-profiles/ @changeroa
 /game-ui/ @changeroa
 /platform-guides/ @changeroa
+/state-management/ @changeroa
 /consumer-reference/ @changeroa
 /consumer-reference/adapters/ @changeroa
 /consumer-reference/generated/ @changeroa

AGENTS.md

@@ -6,7 +6,7 @@ description: Rules coding agents must follow when editing this governed multi-do
 
 # Agent Instructions
 
-This repository is StyleGallery: a governed gallery with Layout, Motion, Design Engineering, Game UI, and Platform Guides domains. Read [StyleGallery Domains](DOMAINS.md) before adding a domain, changing a domain boundary, or adapting an external source.
+This repository is StyleGallery: a governed gallery with Layout, Motion, Design Engineering, Game UI, Platform Guides, and State Management domains. Read [StyleGallery Domains](DOMAINS.md) before adding a domain, changing a domain boundary, or adapting an external source.
 
 Before editing generated artifacts, validators, lifecycle state, or ownership policy, read [Governance, Lifecycle, And Docs-As-Code](GOVERNANCE.md).
 
@@ -23,6 +23,8 @@ Before editing generated artifacts, validators, lifecycle state, or ownership po
 - Treat `consumer-reference/policies/lifecycle-dispositions.json` as the lifecycle index. Preserve named owners, caller status `unknown`, deadlines, extension dispositions, and immutable archive bindings until their machine gate authorizes a transition.
 - Treat `patterns/**`, `recipes/**`, `GUIDE.md`, and `CATALOG.md` as the Layout corpus at their existing paths.
 - Treat the Layout domain as a layout pattern library, not a visual design system.
+- Treat `state-management/**` as the State Management corpus. Keep its canonical guidance framework-neutral, domain-local, and separate from Layout pattern generation and consumer implementation state.
+- Keep logical application-state transitions in State Management, transition animation in Motion, spatial consequences in Layout, and product-level visual or interaction-state decisions in Design Engineering.
 - Start with semantic HTML before adding layout classes.
 - Keep DOM order, reading order, and focus order logical.
 - Keep each pattern focused on one primary spatial problem.
@@ -41,6 +43,16 @@ Before editing generated artifacts, validators, lifecycle state, or ownership po
 
 The remaining pattern, CSS, naming, token, checklist, and verification rules apply to the Layout domain. Non-Layout domain documents may discuss product-layer behavior, but they do not authorize decorative or motion properties in reusable Layout pattern CSS.
 
+## State Management Boundary Gate
+
+Before adding a State Management pattern or recipe, check [State Management Decision Tree](state-management/guides/decision-tree.md) and [State Brief](state-management/guides/state-brief.md).
+
+- Name one authoritative owner, lifetime, reset boundary, readers, writers, accepted events, and failure behavior.
+- Derive values when existing authority determines them; do not create a mirrored writable copy without a synchronization contract.
+- For asynchronous work, declare cancellation, ordering, stale-result, conflict, and recovery behavior where applicable.
+- Add a pattern only when an existing State Management pattern or recipe does not already cover the responsibility.
+- Keep library-specific APIs as bounded examples rather than canonical contracts.
+
 ## Pattern Boundary Gate
 
 Before adding a new pattern or changing reusable pattern CSS, check [Layout Decision Tree](guides/decision-tree.md) and [Layout Brief Template](guides/layout-brief.md).

DOMAINS.md

@@ -19,6 +19,7 @@ This manifest is the source of truth for top-level StyleGallery domains. A domai
 | Design Engineering | [Design Engineering](design-engineering/index.md) | `experimental` | Product-layer craft questions and evidence-bearing decisions. | A second shared principle system or taste as proof. | Design Engineering domain owner |
 | Game UI | [Game UI](game-ui/index.md) | `experimental` | Game-interface classification, hierarchy, reference records, and implementation guides nested by engine. | Reusable Layout CSS or claims that one engine structure is universal. | Game UI domain owner |
 | Platform Guides | [Platform Guides](platform-guides/index.md) | `experimental` | Comparative references for a named platform and version context. | Affiliation, brand imitation, or authority over web standards. | Platform Guides domain owner |
+| State Management | [State Management](state-management/index.md) | `experimental` | Framework-neutral application-state ownership, lifetime, derivation, logical transitions, synchronization, recovery, and verification. | Spatial Layout, transition animation, visual component states, backend consistency, product business rules, or universal library prescriptions. | State Management domain owner |
 
 ## Page Manifest
 
@@ -29,14 +30,15 @@ This manifest is the source of truth for top-level StyleGallery domains. A domai
 | Design Engineering | `design-engineering/index.md` | `design-engineering/interface-craft.md`, `design-engineering/consumer-migration-readiness.md`, `design-engineering/reference-profiles/index.md`, `design-engineering/reference-profiles/governed-local/index.md`, `design-engineering/reference-profiles/external-adaptation/index.md` |
 | Game UI | `game-ui/index.md` | `game-ui/classification.md`, `game-ui/screen-hierarchy.md`, `game-ui/reference-record.md`, `game-ui/unity/architecture.md`, `game-ui/unity/ui-systems.md`, `game-ui/unity/cli-loop.md`, `game-ui/unity/repository-map.md`, `game-ui/unity/org-wiki.md` |
 | Platform Guides | `platform-guides/index.md` | `platform-guides/apple-interaction.md` |
+| State Management | `state-management/index.md` | `state-management/catalog.md`, `state-management/guides/planning-workflow.md`, `state-management/guides/decision-tree.md`, `state-management/guides/state-brief.md`, `state-management/guides/verification-matrix.md`, `state-management/patterns/index.md`, `state-management/patterns/ownership/local-draft-state.md`, `state-management/patterns/ownership/url-owned-state.md`, `state-management/patterns/ownership/server-state-cache.md`, `state-management/patterns/derivation/derived-state.md`, `state-management/patterns/transitions/explicit-transition-model.md`, `state-management/patterns/synchronization/optimistic-mutation.md`, `state-management/recipes/index.md`, `state-management/recipes/pattern-to-recipe-matrix.md`, `state-management/recipes/search-and-filter.md`, `state-management/recipes/editable-form.md`, `state-management/recipes/optimistic-list.md` |
 
 ## Shared Non-Domain Infrastructure
 
-[Consumer Reference](consumer-reference/index.md) is shared schema, provenance, routing, evidence, lifecycle, and machine-retrieval infrastructure outside the five-domain contract. Its source-bound material v2 index classifies admitted pages by these five domains but does not own their prose. It owns no profile implementation, visual values, or product CSS and cannot add a sixth domain row. Consumer or profile records may depend on Layout; Layout and its generated corpus cannot import consumer-reference, profile, material-registry, or transport records.
+[Consumer Reference](consumer-reference/index.md) is shared schema, provenance, routing, evidence, lifecycle, and machine-retrieval infrastructure outside the six-domain contract. Its source-bound material v2 index classifies admitted pages by these six domains but does not own their prose. It owns no profile implementation, visual values, application-state behavior, or product CSS and cannot add another domain row. Consumer or profile records may depend on Layout; Layout and its generated corpus cannot import consumer-reference, profile, material-registry, or transport records.
 
 ## External Adaptation Contract
 
-The initial five domain leaves are independent method rewrites inspired by [emilkowalski/skills](https://github.com/emilkowalski/skills) at snapshot `220e8607c90b17337d210125777b7b695f26c221`. Other adapted leaves record their own repositories and revisions in page metadata.
+The externally adapted leaves in the initial five-domain snapshot are independent method rewrites inspired by [emilkowalski/skills](https://github.com/emilkowalski/skills) at snapshot `220e8607c90b17337d210125777b7b695f26c221`. Other adapted leaves record their own repositories and revisions in page metadata. State Management leaves are locally authored StyleGallery methods with `provenance_kind: local` and no upstream source fields.
 
 - Each externally adapted leaf records `source_repository`, exact `source_path`, and the full `source_revision`. Locally authored synthesis leaves state that boundary in their attribution section and omit upstream metadata.
 - A full SHA identifies source content; it does not prove publisher authenticity or local quality.

GOVERNANCE.md

@@ -42,6 +42,7 @@ Use this file before editing repository documentation. It names which file is au
 | Design Engineering domain guidance | `design-engineering/*.md` | Manual | None | `experimental` | Upstream revision, evidence boundary, or guidance changes. | `scripts/validate-domains.mjs` | Design Engineering domain owner |
 | Game UI domain guidance | `game-ui/**/*.md` | Manual | None | `experimental` | Classification, hierarchy, engine implementation, evidence boundary, or route changes. | `scripts/validate-domains.mjs` | Game UI domain owner |
 | Platform Guides domain guidance | `platform-guides/*.md` | Manual | None | `experimental` | Platform version, upstream revision, evidence boundary, or guidance changes. | `scripts/validate-domains.mjs` | Platform Guides domain owner |
+| State Management domain guidance | `state-management/**/*.md` | Manual | None | `experimental` | Authority, lifetime, transition, synchronization, recovery, pattern composition, evidence boundary, or route changes. | `scripts/validate-domains.mjs`, `scripts/validate-ia.mjs` | State Management domain owner |
 | Pattern data and examples | `scripts/pattern-data.mjs` | Manual data source | `patterns/**/*.md`, `patterns/**/index.md`, `patterns/index.md`, `CATALOG.md` | `generated` output from `stable` source | Source-lineage URL changes, generated drift, category changes, or pattern count changes. | `scripts/validate-patterns.mjs`, `scripts/validate-catalog.mjs`, `scripts/validate-governance.mjs` | Pattern-data owner |
 | Pattern generator | `scripts/generate-patterns.mjs` | Manual code source | `patterns/**/*.md`, `patterns/**/index.md`, `patterns/index.md`, `CATALOG.md` | `stable` generator, `generated` output | Generated structure changes, generated-warning changes, or generated metadata changes. | `node -c scripts/generate-patterns.mjs`, generated drift check, `scripts/validate-governance.mjs` | Pattern-data owner |
 | Validation scripts | `scripts/validate-*.mjs`, `scripts/test-validate-*.mjs` | Manual code source | CI validation output | `stable` | Validator scope changes, fixture changes, or CI parity changes. | `node -c`, matching fixture tests, `.github/workflows/validate.yml` | Validation owner |
@@ -98,7 +99,7 @@ Use these states in reviews and governance notes. Do not invent new lifecycle la
 Default lifecycle:
 
 - Root docs, guides, recipes, quality docs, validators, and CI are `stable` unless a page explicitly says otherwise.
-- `DOMAINS.md`, the scope decision, and `layout/index.md` are `stable`; domain leaves under `motion/`, `design-engineering/`, `game-ui/`, and `platform-guides/` begin `experimental`.
+- `DOMAINS.md`, the scope decision, and `layout/index.md` are `stable`; domain leaves under `motion/`, `design-engineering/`, `game-ui/`, `platform-guides/`, and `state-management/` begin `experimental`.
 - Generated pattern docs, generated pattern indexes, and `CATALOG.md` are `generated`.
 - Draft research artifacts under `.omo/` are `draft` or `experimental` and are not contributor-facing source of truth.
 
@@ -125,6 +126,7 @@ Consumer-reference ownership records the current truth as `owner.enforcement: "p
 | `tests/**`, `playwright.config.mjs`, `consumer-reference/baselines/**`, `scripts/*baseline*.mjs`, `scripts/*sentinel*.mjs`, `scripts/*renderer-purity.mjs` | Repository governance owner with Validation owner | Pure rendering, computed semantics before screenshots, immutable browser pins, required consumer-conformance semantics, optional raster capture, calibration cardinality, and pending owner approval. |
 | `game-ui/**` | Game UI domain owner | Player-task classification, hierarchy responsibility, reference records, engine-specific subtrees, and cross-engine boundaries. |
 | `platform-guides/**` | Platform Guides domain owner | Platform/source/version limits, comparison boundaries, and stale review. |
+| `state-management/**` | State Management domain owner | Application-state authority, lifetime, derivation, logical transitions, synchronization, recovery, framework neutrality, and verification boundaries. |
 | `scripts/validate-*.mjs`, `scripts/test-validate-*.mjs`, `.github/workflows/validate.yml`, `.github/workflows/evidence-freshness.yml` | Validation owner | Validator scope, negative fixtures, blocking/advisory boundaries, CI parity. |
 
 ## Shared Promotion Governance