coding-os 0.3.2__py3-none-any.whl

templates/python/stack.yaml

@@ -0,0 +1,60 @@
+version: 1
+id: python
+language: python
+label: "Python library / CLI / MCP server"
+category: library
+
+structure:
+  root: src
+  tree: |
+    src/<package>/       # src-layout package
+    tests/               # mirrors the package tree
+  notes: "src-layout; packaging SSOT is pyproject.toml (docs/engineering/python-rules.md)"
+primary_skill: null
+skills: []
+
+# Generic Python stack — for libraries, CLI tools, MCP servers, and the
+# coding-os meta-repo itself. No stack-specific skill files; the always-on
+# core skills (clean-code, thinking_os, codebase-explorer, worktree-orchestration)
+# from base.yaml cover Python authoring.
+#
+# When this stack is selected for the coding-os meta-repo, the canonical
+# rules live in CLAUDE.md (rules 0–23). For consumer projects using this
+# stack, see docs/governance/critical-rules.md as the entry point.
+
+substitutions:
+  DOMAIN_ROUTES: "Python module / CLI / MCP tool → `docs/playbooks/python-library.md`"
+  SKILL_ROUTES: "Python → `clean-code` + `testing-strategy` + `shell-scripting` + `sql-authoring` (core skills)"
+  ENGINEERING_RULE_ROUTING: "Python → `docs/engineering/python-rules.md` + `docs/governance/`"
+  TOOL_ROUTING_IMPL: "`pytest` (lint/format opt-in: ruff/mypy not enforced by default)"
+  QUICK_ROUTING: |-
+    - Python module / package task → [Python Library Playbook](./playbooks/python-library.md)
+    - MCP tool / CLI command task → [Python Library Playbook](./playbooks/python-library.md)
+    - Test / fixture task → `tests/` + `pytest`
+  STACK_REF_CODES: |-
+    - `REF:PLAYBOOK-PY` → `./playbooks/python-library.md`
+    - `REF:PY-RULES` → `./engineering/python-rules.md`
+
+ref_codes:
+  - {code: "REF:PLAYBOOK-PY", path: "./playbooks/python-library.md", desc: "Python library/CLI playbook"}
+  - {code: "REF:PY-RULES",    path: "./engineering/python-rules.md", desc: "Python engineering rules"}
+
+routing_entries:
+  - "Python module / CLI / MCP tool task → [Python Library Playbook](./docs/playbooks/python-library.md)"
+
+# No stack-specific rules. CLAUDE.md (or consumer AGENTS.md) carries them.
+rules: []
+
+dimensions:
+  - {name: "Python module / API", read_files: ["docs/playbooks/python-library.md", "docs/engineering/python-rules.md"]}
+  - {name: "CLI command", read_files: ["docs/playbooks/python-library.md"]}
+
+# No skill_enforcement globs. Generic clean-code applies to all Python via
+# the global skill list in base.yaml. Stack-specific globs would either
+# duplicate that or conflict with consumer project layouts.
+skill_enforcement: []
+
+# No stack-specific Makefile targets. The meta-repo's Makefile already
+# defines `make verify`, `make verify-hooks`, etc. Consumer Python libraries
+# can add targets if they need them.
+makefile_targets: []

templates/rails/rules/backend.md

@@ -0,0 +1,10 @@
+# Rails Backend Rules (auto-loaded for src/backend/**/*.rb)
+
+> Controllers thin, ActiveRecord models own logic, ONE `rescue_from` chain shapes
+> every error. Full conventions: [rails-rules.md](../scaffold/docs/engineering/rails-rules.md).
+
+- Route → controller → model; imports flow one way only.
+- Strong parameters on every write action; raw `params` never reaches the model.
+- Validations live on the model (`validates`), not in the action.
+- Only `ApplicationController`'s `rescue_from` chain writes error bodies.
+- Reversible migrations; schema and data migrations stay separate.

templates/rails/scaffold/docs/engineering/rails-rules.md

@@ -0,0 +1,33 @@
+<!-- domain:BACKEND | layer:rules | ssot:true | updated:{{DATE}} -->
+# Rails Engineering Rules
+
+Purpose: Non-negotiable conventions for the {{PROJECT_NAME}} Rails backend.
+Read when: Editing anything under `src/backend/`.
+Skip when: Frontend/mobile work.
+Read next: [Rails Service Playbook](../playbooks/rails-service.md)
+
+> Nav: [Master Index](../00-index.md)
+
+## Hard rules
+
+1. **Layering** — route → controller → model. Controllers parse params and
+   render; ActiveRecord models own business logic. Imports flow one way only
+   (the table in the `rails` skill is the SSOT).
+2. **Thin controllers** — an action that runs more than one query or branches on
+   business state is a build-blocking review finding; push the logic to the model.
+3. **One error shaper** — only the `rescue_from` chain in `ApplicationController`
+   writes error bodies; it logs full detail and returns the problem shape with no
+   internals (no backtraces, no SQL).
+4. **Strong parameters fail-closed** — every action whitelists its fields with
+   `params.require(...).permit(...)`; raw `params` never reaches `create`/`update`.
+5. **Validations on the model** — data integrity lives in `validates`, not in the
+   controller; a save that can fail uses `save!`/`create!` so the error chain maps it.
+6. **Reversible migrations** — `change` when auto-reversible, otherwise paired
+   `up`/`down`; schema and data migrations stay separate.
+7. **No floating config** — environment access happens once at boot via
+   `Rails.application.config`; models and controllers never read `ENV` inline.
+
+## Testing bar
+
+Models ≥ unit-spec per public method; controllers ≥ happy + error path via RSpec
+request specs; database-touching code uses transactional fixtures, never a real port.

templates/rails/scaffold/docs/playbooks/rails-service.md

@@ -0,0 +1,42 @@
+<!-- domain:BACKEND | layer:playbook | ssot:true | updated:{{DATE}} -->
+# Rails Service Playbook
+
+Purpose: The end-to-end recipe for adding or changing a Rails endpoint in {{PROJECT_NAME}}.
+Read when: Any task that adds a controller, route, ActiveRecord model, concern, or migration.
+Skip when: Pure infra/devops work — see the deployment docs.
+Read next: [Rails Engineering Rules](../engineering/rails-rules.md), [Error Format](../api-contracts/error-format.md)
+
+> Nav: [Master Index](../00-index.md)
+
+## Add an endpoint (the only sanctioned path)
+
+1. **Route first** — declare the route in `config/routes.rb` (prefer `resources`
+   over hand-rolled paths); the routing table stays the single place URLs live.
+2. **Model** — `app/models/<domain>.rb`: an ActiveRecord class that owns its
+   validations, scopes, and business logic. Persistence stays here, not in the
+   controller.
+3. **Controller** — `app/controllers/<domain>_controller.rb`: thin. Use strong
+   parameters (`params.require(...).permit(...)`), call exactly one model method,
+   then `render`. Raise a typed error on failure — never build an error body here.
+4. **Error mapping** — failures surface as exceptions; the `rescue_from` chain in
+   `ApplicationController` maps each to a status + the shared problem body
+   ([error-format](../api-contracts/error-format.md)).
+5. **Concern** — extract cross-cutting behavior (auth filters, pagination) into a
+   module under `controllers/concerns/` only when three call sites need it.
+6. **Migration** — `bin/rails generate migration` for schema changes; reversible
+   (`change` or paired `up`/`down`). The agent writes it; the user runs `db:migrate`.
+7. **Test** — RSpec request spec per endpoint (happy + error path) + a model spec
+   per public method; never bind a real server port.
+8. **Verify** — `cd src/backend && bundle exec rubocop && bundle exec rspec`.
+
+## Global wiring (set once in `ApplicationController`)
+
+`before_action` filters run auth/loading; the `rescue_from` chain is the single
+error shaper. Every controller inherits both by subclassing `ApplicationController`.
+
+## Anti-patterns
+
+- Error JSON built inside an action — the `rescue_from` chain owns the shape.
+- A fat controller running queries or business logic — that belongs in the model.
+- Mass-assignment without strong parameters — every action permits its fields.
+- Binding a real port in specs — use request specs against the Rack app.

templates/rails/scaffold/src/backend/Gemfile

@@ -0,0 +1,12 @@
+source "https://rubygems.org"
+
+ruby "3.3.0"
+
+gem "rails", "~> 7.1"
+gem "puma", "~> 6.4"
+
+group :development, :test do
+  gem "rspec-rails", "~> 6.1"
+  gem "rubocop", "~> 1.60", require: false
+  gem "rubocop-rails", "~> 2.23", require: false
+end

templates/rails/scaffold/src/backend/app/controllers/application_controller.rb

@@ -0,0 +1,26 @@
+class ApplicationController < ActionController::API
+  # The ONLY place that shapes an error response (RFC 9457 problem shape).
+  # Controllers and models raise typed errors; this chain maps them.
+  rescue_from StandardError, with: :render_internal_error
+  rescue_from ActiveRecord::RecordNotFound, with: :render_not_found
+
+  private
+
+  def render_not_found
+    render_problem(status: :not_found, title: "Not Found")
+  end
+
+  def render_internal_error(exception)
+    # Full detail to the logger only; never a backtrace to the client.
+    logger.error(exception)
+    render_problem(status: :internal_server_error, title: "Internal Server Error")
+  end
+
+  def render_problem(status:, title:)
+    render(
+      json: { type: "about:blank", title: title, status: Rack::Utils.status_code(status) },
+      status: status,
+      content_type: "application/problem+json",
+    )
+  end
+end

templates/rails/scaffold/src/backend/app/controllers/health_controller.rb

@@ -0,0 +1,6 @@
+class HealthController < ApplicationController
+  # Thin: delegates to the model and renders its value.
+  def show
+    render json: Health.status
+  end
+end

templates/rails/scaffold/src/backend/app/models/health.rb

@@ -0,0 +1,6 @@
+# Plain model (no table) — business logic stays out of the controller.
+class Health
+  def self.status
+    { status: "ok" }
+  end
+end

templates/rails/scaffold/src/backend/config/application.rb

@@ -0,0 +1,12 @@
+require_relative "boot"
+
+require "rails"
+require "action_controller/railtie"
+
+# Rails app bootstrap — wires the framework, owns no business logic.
+module Backend
+  class Application < Rails::Application
+    config.load_defaults 7.1
+    config.api_only = true
+  end
+end

templates/rails/scaffold/src/backend/config/boot.rb

@@ -0,0 +1,3 @@
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+require "bundler/setup" # Set up gems listed in the Gemfile.

templates/rails/scaffold/src/backend/config/routes.rb

@@ -0,0 +1,4 @@
+Rails.application.routes.draw do
+  # The routing table — one place every URL lives.
+  get "health", to: "health#show"
+end

templates/rails/scaffold/src/backend/config.ru

@@ -0,0 +1,5 @@
+# This file is used by Rack-based servers to start the application.
+require_relative "config/application"
+
+run Rails.application
+Rails.application.load_server if Rails.application.respond_to?(:load_server)

templates/rails/scaffold/src/backend/spec/rails_helper.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+ENV["RAILS_ENV"] ||= "test"
+
+require_relative "../config/application"
+Backend::Application.initialize! unless Backend::Application.initialized?
+
+require "rspec/rails"
+
+RSpec.configure do |config|
+  config.infer_spec_type_from_file_location!
+  config.expect_with :rspec do |expectations|
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+  config.mock_with :rspec do |mocks|
+    mocks.verify_partial_doubles = true
+  end
+end

templates/rails/scaffold/src/backend/spec/requests/health_spec.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+# Request spec for the existing GET /health endpoint.
+# Drives the Rack app through the request layer (never binds a real port),
+# exercising HealthController#show -> Health.status, plus a direct model
+# assertion on the existing Health.status method.
+RSpec.describe "Health", type: :request do
+  describe "GET /health" do
+    it "returns 200 with the ok status body" do
+      get "/health"
+
+      expect(response).to have_http_status(:ok)
+      expect(response.parsed_body).to eq("status" => "ok")
+    end
+  end
+
+  describe "Health.status" do
+    it "reports ok without touching HTTP" do
+      expect(Health.status).to eq(status: "ok")
+    end
+  end
+end

templates/rails/scaffold-boundary.yaml

@@ -0,0 +1,25 @@
+# Scaffold boundary for the rails stack.
+# Schema: docs/governance/scaffold-boundary-contract.md
+
+version: 1
+stack: rails
+
+roots:
+  - src/backend/
+
+file_patterns:
+  - "src/backend/**/*.rb"
+  - "src/backend/**/*.ru"
+  - "src/backend/Gemfile"
+
+imports_from:
+  - src/shared/
+  - src/shared/contracts/
+
+forbids_writing_in:
+  - src/frontend/
+  - src/mobile/
+
+notes:
+  - "Controllers thin (parse params, call the model, render); ActiveRecord models own business logic."
+  - "One rescue_from chain in ApplicationController is the only error-response shaper."

templates/rails/skills/rails/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: rails
+tier: stack
+domain: [backend]
+description: Use when creating or modifying Ruby files under src/backend/ in a Ruby on Rails service — controllers, ActiveRecord models, routes.rb, concerns, migrations, the rescue_from error chain, and their RSpec specs. Triggers on any .rb change under src/backend/. Covers thin controllers + strong parameters, model-owned business logic and validations, the single ApplicationController rescue_from error shaper, routes-as-table, concerns extraction, and request/model specs. Generic Ruby fundamentals live in clean-code.
+globs: "src/backend/**/*.rb"
+depends_on:
+  - clean-code
+  - backend-fundamentals
+last_reviewed: "2026-06-14"
+---
+
+REQUIRED BACKGROUND: This skill `depends_on: [clean-code, backend-fundamentals]`. `clean-code` gives universal code quality (fail-closed errors, typed exceptions, self-documenting code, error-path tests); `backend-fundamentals` gives stack-agnostic backend patterns (services, idempotency, envelopes, N+1, migrations, auth). This skill adds ONLY Ruby on Rails-specific layering on top.
+
+# rails
+
+## Layer contract (matches `structure.tree`)
+
+| Layer | May import | Never |
+|---|---|---|
+| `config/routes.rb` | route helpers | controller bodies, models |
+| `*_controller.rb` | the domain model, concerns | another controller, raw SQL |
+| `app/models/*.rb` (ActiveRecord) | other models, the DB | controllers, `params`, `render` |
+| `controllers/concerns/` | models (for auth lookups) | a specific controller's privates |
+
+Controllers stay thin and transport-aware; models stay transport-free (no
+`params`, no `render`) so they are unit-testable and the business logic survives
+a transport swap (REST → GraphQL → ActionCable).
+
+## Routes & controllers (thin)
+
+- `config/routes.rb` is the single routing table — prefer `resources`/`resource`
+  over hand-rolled `match`; one URL, one place.
+- An action: strong-parameter the input (`params.require(:x).permit(:a, :b)`) →
+  call ONE model method → `render`. No business branching, no multi-query loops.
+- Subclass `ApplicationController`; never rescue-and-shape inside an action — raise
+  a typed error and let the global chain map it.
+- `before_action` filters load records / enforce auth; keep them in concerns when
+  three controllers share them (rule of three), not copy-pasted.
+
+## Models (ActiveRecord — the only layer that thinks)
+
+- Business logic, scopes, and `validates` live on the model; a controller that
+  validates by hand is a layering violation.
+- Persist with `save!`/`create!`/`update!` so a failure raises and the
+  `rescue_from` chain maps it — silent `save` that returns `false` hides errors.
+- Migrations are reversible (`change`, or paired `up`/`down`); schema and data
+  migrations stay in separate files. The agent writes them; the user runs `db:migrate`.
+
+## Error handling
+
+- ONE `rescue_from` chain in `ApplicationController` shapes every error response
+  (RFC 9457 problem shape per `docs/api-contracts/error-format.md`).
+  Unknown errors → 500 generic body, full detail to `logger` only — never a
+  backtrace or SQL to the client.
+
+## Testing
+
+- Models: unit specs per public method (no HTTP) with transactional fixtures.
+- Controllers: RSpec request specs against the Rack app — one happy + one
+  error-path per endpoint minimum.
+- Never bind a real server port in specs; drive the app through the request layer.

templates/rails/skills/rails/references/anatomy.md

@@ -0,0 +1,71 @@
+<!-- domain:RAILS | layer:reference | ssot:true | updated:2026-06-27 -->
+# Rails Anatomy
+
+> P: Canonical file map + entity recipes for the Rails (thin-controller, fat-model) API stack.
+> R: Adding any `.rb` under `src/backend/`, or routing a backend task.
+> S: Reading frontend / mobile code — wrong stack.
+> N: [SKILL.md](../SKILL.md), [scaffold-boundary.yaml](../../../scaffold-boundary.yaml)
+
+> Nav: [Skill](../SKILL.md)
+
+---
+
+## 1. Boundary
+
+SSOT: `src/templates/rails/scaffold-boundary.yaml`.
+
+## 2. Layout map
+
+| Pattern | Location | Naming | Imports from | Description |
+|---|---|---|---|---|
+| Controller | `app/controllers/<domain>_controller.rb` | `<domain>_controller.rb` | its model | Thin — parse params, call model, render |
+| Model | `app/models/<domain>.rb` | `<domain>.rb` | none | ActiveRecord — logic + validations |
+| Concern | `app/controllers/concerns/<name>.rb` | `<name>.rb` | none | Cross-cutting mixin (auth, pagination) |
+| Routes | `config/routes.rb` | `routes.rb` | controllers | The one routing table |
+| Error shaper | `app/controllers/application_controller.rb` | — | none | `rescue_from` chain — the ONLY error shaper |
+| Migration | `db/migrate/<ts>_<slug>.rb` | `<ts>_<slug>.rb` | none | Schema change, append-only |
+| Test | `test/<type>/<name>_test.rb` | `<name>_test.rb` | source under test | Minitest / RSpec |
+
+## 3. Entity recipes
+
+### Add a new endpoint
+- **Trigger:** "add `POST /<resource>`".
+- **Files emitted:**
+  1. `app/controllers/<domain>_controller.rb`
+  2. route entry in `config/routes.rb`
+- **Steps:**
+  1. Controller parses strong params, calls the model, renders JSON.
+  2. Errors bubble to the `rescue_from` chain in `ApplicationController`.
+
+### Add a new model
+- **Trigger:** "persist `<Entity>`".
+- **Files emitted:**
+  1. `app/models/<domain>.rb`
+  2. `db/migrate/<ts>_create_<table>.rb`
+- **Steps:**
+  1. Validations + business logic on the model; avoid N+1 with `includes`.
+
+### Add a new migration
+- **Trigger:** schema change.
+- **Files emitted:** `db/migrate/<ts>_<slug>.rb`.
+- **Steps:**
+  1. Append-only; reversible `change` or `up`/`down`.
+
+### Add a new test
+- **Trigger:** any new controller / model.
+- **Files emitted:** `test/<type>/<name>_test.rb`.
+- **Steps:**
+  1. Controller test hits the route (happy + error); model test per public method.
+
+## 4. Conventions
+
+#### Naming
+- Files: `snake_case.rb`. Classes: `PascalCase`; methods: `snake_case`.
+
+#### Test colocation
+- Mirrored: `test/models/<name>_test.rb` mirrors `app/models/<name>.rb`.
+
+#### Dependency rules
+- ✓ controller → model; shared behavior via concerns.
+- ✗ no business logic in controllers or routes.
+- ✗ `src/backend/` never imports from `src/frontend/` / `src/mobile/` — share via `src/shared/`.

templates/rails/stack.yaml

@@ -0,0 +1,72 @@
+version: 1
+id: rails
+language: ruby
+label: "Ruby on Rails"
+category: backend
+
+structure:
+  root: src/backend
+  tree: |
+    src/backend/
+    ├── Gemfile
+    ├── config.ru
+    ├── config/
+    │   ├── application.rb     # Rails app bootstrap (no logic)
+    │   └── routes.rb          # the routing table — one place
+    └── app/
+        ├── controllers/
+        │   ├── application_controller.rb   # rescue_from lives here — the ONLY error shaper
+        │   └── <domain>_controller.rb      # thin — parse params, call the model, render
+        ├── models/<domain>.rb              # ActiveRecord — business logic + validations
+        └── controllers/concerns/           # cross-cutting mixins (auth, pagination)
+  notes: "controllers thin (parse → call model → render); ActiveRecord models own logic + validations; ONE rescue_from chain in ApplicationController shapes every error; shared behavior in concerns"
+primary_skill: rails
+skills: [rails]
+
+# These substitution keys are joined across stacks by the aggregator via
+# _derive_substitutions (joined on " | "). VERIFY_BACKEND_* override the
+# "(none)" defaults from base.yaml.
+substitutions:
+  DOMAIN_ROUTES: "Backend→`docs/playbooks/rails-service.md`"
+  SKILL_ROUTES: "Backend→`rails`"
+  ENGINEERING_RULE_ROUTING: "Backend→`docs/engineering/rails-rules.md`, Error format→`docs/api-contracts/error-format.md`"
+  TOOL_ROUTING_IMPL: "`lint-backend`, `test-backend`"
+  VERIFY_BACKEND_GLOB: "`src/backend/`"
+  VERIFY_BACKEND_SUITES: "lint-backend + test-backend"
+  VERIFY_BACKEND: "`cd src/backend && bundle exec rubocop && bundle exec rspec`"
+  QUICK_ROUTING: |-
+    - Rails controller / route task → [Rails Service Playbook](./playbooks/rails-service.md)
+    - ActiveRecord model / migration → [Rails Service Playbook](./playbooks/rails-service.md)
+  STACK_REF_CODES: |-
+    - `REF:PLAYBOOK-RAILS` → `./playbooks/rails-service.md`
+    - `REF:RAILS-RULES` → `./engineering/rails-rules.md`
+
+ref_codes:
+  - {code: "REF:PLAYBOOK-RAILS", path: "./playbooks/rails-service.md", desc: "Rails service playbook"}
+  - {code: "REF:RAILS-RULES",    path: "./engineering/rails-rules.md", desc: "Rails engineering rules"}
+
+routing_entries:
+  - "Rails controller / route task → [Rails Service Playbook](./playbooks/rails-service.md)"
+
+rules:
+  - {file: rules/backend.md, globs: ["src/backend/**/*.rb"]}
+
+makefile_targets:
+  - {name: lint-backend, cmd: "cd src/backend && bundle exec rubocop"}
+  - {name: test-backend, cmd: "cd src/backend && bundle exec rspec"}
+
+verify:
+  - {glob: "src/backend/**/*.rb", suites: "lint-backend + test-backend", cmd: "cd src/backend && bundle exec rubocop && bundle exec rspec"}
+
+dimensions:
+  - {name: "Rails controller",        read_files: ["docs/playbooks/rails-service.md", "docs/engineering/rails-rules.md"]}
+  - {name: "ActiveRecord model",      read_files: ["docs/engineering/rails-rules.md"]}
+  - {name: "Route / routes.rb",       read_files: ["docs/engineering/rails-rules.md"]}
+  - {name: "Concern / mixin",         read_files: ["docs/engineering/rails-rules.md"]}
+  - {name: "Migration / schema",      read_files: ["docs/engineering/rails-rules.md", "docs/api-contracts/error-format.md"]}
+  - {name: "Auth / rescue_from",      read_files: ["docs/engineering/rails-rules.md"]}
+
+skill_enforcement:
+  - {globs: ["src/backend/**/*.rb"], primary: rails, secondary: [clean-code, backend-fundamentals, api-design, auth-patterns, security-web, testing-strategy, observability]}
+  - {globs: ["src/backend/**/models/**/*.rb", "src/backend/**/migrate/**/*.rb"], primary: rails, secondary: [clean-code, db-design, backend-fundamentals]}
+  - {globs: ["src/backend/**/controllers/concerns/auth*.rb", "src/backend/**/models/concerns/auth*.rb"], primary: rails, secondary: [auth-patterns, security-web, clean-code]}

templates/react-native/rules/mobile.md

@@ -0,0 +1,26 @@
+<!-- domain:REACTNATIVE | layer:policy | ssot:true | updated:2026-04-29 -->
+# React Native — stack rules
+
+> P: Compact rule list applied to every `src/mobile/**/*.{ts,tsx}` file in addition to clean-code, frontend-fundamentals, and a11y.
+> R: Reviewing or writing any mobile code.
+> S: Touching the web frontend or backend.
+> N: [skills/react-native-mobile/SKILL.md](../skills/react-native-mobile/SKILL.md), [skills/react-native-mobile/references/anatomy.md](../skills/react-native-mobile/references/anatomy.md)
+
+## Hard rules
+
+1. **Three-state UI.** Every data-fetching screen handles loading / error / empty / content explicitly.
+2. **Worklets are pure.** Functions marked `'worklet'` MUST NOT call JS-thread APIs.
+3. **No raw AsyncStorage.** Use `src/mobile/lib/storage.ts` so storage adapters can swap in tests.
+4. **No hard-coded design tokens.** Read from `src/shared/contracts/design-tokens.ts`.
+5. **a11y on every interactive element.** `accessibilityRole` + `accessibilityLabel` mandatory.
+6. **Offline mutations queue.** User-mutating actions go through `src/mobile/sync/queue.ts` — never direct API calls during a write.
+7. **Native bridges require an ADR.** No fork to Swift / Kotlin without `docs/architecture/adr/ADR-NNN-*.md`.
+8. **Boundary.** May import from `src/shared/`. Never from `src/frontend/`, `src/backend/`, `src/ai-service/`.
+
+## Pre-commit checklist
+
+- [ ] Three-state branches present.
+- [ ] No JS-thread call inside a `'worklet'` function.
+- [ ] `accessibilityRole` set on every Pressable / Touchable.
+- [ ] Imports respect `src/templates/react-native/scaffold-boundary.yaml`.
+- [ ] Tests colocated and Given/When/Then.

templates/react-native/scaffold/docs/engineering/accessibility-mobile.md

@@ -0,0 +1,95 @@
+<!-- domain:MOBILE | layer:reference | ssot:true | updated:2026-04-29 -->
+# Mobile Accessibility (a11y) Checklist — WCAG 2.2 AA
+
+> P: Per-screen / per-component a11y bar for every `src/mobile/**/*.{ts,tsx}` change. Tests with VoiceOver (iOS) AND TalkBack (Android).
+> R: Reviewing or writing any interactive RN component.
+> S: Touching pure backend / sync code with no UI surface.
+> N: [mobile-rules.md](mobile-rules.md), [offline-first.md](offline-first.md), [../playbooks/mobile-app.md](../playbooks/mobile-app.md)
+
+> Nav: [Docs Index](../00-index.md) | [Mobile Rules](./mobile-rules.md)
+
+---
+
+## 1. Interactive elements
+
+- Every `Pressable` / `TouchableOpacity` / `Button` / icon-only tap target MUST set:
+  - `accessibilityRole` (`button` | `link` | `tab` | `header` | …)
+  - `accessibilityLabel` describing the action (no emoji-only labels)
+  - `accessibilityState` for stateful elements (`{ disabled, selected, checked, expanded }`)
+- Tap targets MUST be ≥ 44×44 pt (iOS) / 48×48 dp (Android). Smaller surfaces wrap a larger `hitSlop`.
+- Form fields MUST set `accessibilityLabel` when no visible label is present.
+
+## 2. Dynamic announcements
+
+- Use `AccessibilityInfo.announceForAccessibility(message)` for:
+  - Toast / banner-style state changes that have no visible focus.
+  - Async result toasts (sync queue success / failure).
+- Live-region updates use `accessibilityLiveRegion="polite"` (Android) plus an explicit announce on iOS.
+- Never auto-focus an element on screen mount unless it materially helps a screen-reader user.
+
+## 3. Navigation + focus
+
+- Use `accessibilityFocus()` on screen change ONLY when the user benefits — e.g. error recovery, modal open.
+- Tab order follows visual reading order; never reorder via `accessibilityElementsHidden` for layout reasons.
+- Modal-equivalent surfaces (`Modal`, bottom sheets) MUST set `accessibilityViewIsModal` (iOS) and trap focus.
+- Provide a clear close affordance with `accessibilityLabel="Close"`.
+
+## 4. Color + contrast
+
+- Normal text (< 18 sp): contrast ratio ≥ 4.5:1.
+- Large text (≥ 18 sp bold or ≥ 24 sp): ≥ 3:1.
+- Interactive elements vs adjacent surfaces: ≥ 3:1.
+- Focus / selection indicators: ≥ 3:1 against background.
+- Theme-tested in both light AND dark modes.
+
+## 5. Motion + animation
+
+- Respect `useReduceMotion()` from `react-native-reanimated`. Disable parallax / hero animations when on.
+- Auto-playing motion ≤ 5 s OR provide a pause control.
+- Avoid flashing content > 3 Hz (seizure trigger).
+
+## 6. Text + scaling
+
+- Read user's font scale via `Appearance` / `PixelRatio.getFontScale()`. Layouts MUST tolerate up to 200%.
+- Never set fixed heights on rows containing text — use min-height plus content-driven growth.
+- Avoid `numberOfLines` clipping on critical info; prefer expandable sections.
+
+## 7. Images + media
+
+- All images carry `accessibilityLabel` OR `accessibilityRole="image"` with descriptive `alt`-equivalent.
+- Decorative-only images: `accessible={false}` AND `importantForAccessibility="no"`.
+- Video content carries captions OR a textual alternative.
+
+## 8. Forms
+
+- Labels associated to inputs via `accessibilityLabelledBy` (Android) / `accessibilityLabel` fallback.
+- Error messages use `accessibilityLiveRegion="assertive"` (Android) + announceForAccessibility (iOS).
+- Required fields announce required state.
+
+## 9. Test discipline
+
+- Manual: run every changed screen through VoiceOver AND TalkBack before merge.
+- Automated: `axe-core/react-native` in unit tests for component-level a11y.
+- E2E: Maestro flow uses `accessibilityLabel` selectors so a broken label fails the flow loudly.
+
+## 10. Reference table
+
+| Concern | iOS prop | Android prop |
+|---|---|---|
+| Role | `accessibilityRole` | `accessibilityRole` |
+| Label | `accessibilityLabel` | `accessibilityLabel` |
+| State | `accessibilityState` | `accessibilityState` |
+| Hint | `accessibilityHint` | `accessibilityHint` |
+| Live region | `accessibilityLiveRegion` (no-op) | `accessibilityLiveRegion` |
+| Modal | `accessibilityViewIsModal` | (focus trap manual) |
+| Hide from reader | `accessibilityElementsHidden` | `importantForAccessibility="no"` |
+
+## 11. Pre-merge checklist
+
+- [ ] Every interactive element has role + label + state where applicable.
+- [ ] Tap target ≥ 44×44 pt / 48×48 dp.
+- [ ] Color contrast verified (light + dark).
+- [ ] Reduce-motion respected.
+- [ ] VoiceOver smoke pass.
+- [ ] TalkBack smoke pass.
+- [ ] axe-core tests green.