core-framework 2.3.3__tar.gz → 3.1.0__tar.gz

core_framework-3.1.0/.cursor/rules/constitution.mdc

@@ -0,0 +1,47 @@
+---
+description: Core non-negotiables — behavior, tech stack, layer direction, host scope
+alwaysApply: true
+---
+
+# Constitution
+
+## Behavior
+
+- State assumptions; ask when unclear. Prefer the simplest correct solution.
+- Touch only what the task requires. Match existing style. Remove orphans your edits create.
+- Define verifiable success criteria for non-trivial work.
+- **Inline small single-use helpers** — do not extract a private function used once and only a few lines (identifier quoting, a short SQL fragment, pass-through wrappers). Extract when the logic is **reused**, **~15+ lines / non-obvious branching**, or a scoped rule requires sharing (e.g. normal + `*_strong` repository reads in **`strong-reads.mdc`**). Do not repo-wide refactor unrelated existing helpers.
+
+## Tech stack
+
+- Python 3.14, Pydantic v2, PostgreSQL 18, orjson (not stdlib json).
+- Absolute imports only (`from core_framework....`). Comma-style `except A, B:` is intentional.
+- Prefer newer APIs and **current Python syntax** over older equivalents still legal on 3.14, for example:
+  - `asyncio.TaskGroup` over `asyncio.gather`
+  - PEP 695 type parameters (`def f[T](...)`, `def f[**P, R](...)`) over module-level `TypeVar` / `ParamSpec`
+  - Built-in generics (`list[str]`, `dict[str, int]`) over `typing.List` / `typing.Dict`
+  - `X | Y` over `Optional[X]` / `Union[X, Y]` unless a library API requires the old form
+  - Do **not** add `from __future__ import annotations` — 3.14 deferred annotations are the default (PEP 649)
+
+## Layers
+
+Dependencies point inward: API/worker → application → domain. Never reverse.
+
+- **API/worker** — transport adapters; call application services.
+- **Application** — orchestration shared by API + worker; no FastAPI types.
+- **Domain** — models, repositories (Postgres only), services. No API/worker/application imports except wiring in `dependencies.py`.
+
+Path-scoped rules under `.cursor/rules/` add detail (API, domains, docs, etc.). For FastAPI/Pydantic work in `core_framework/api/`, use the **fastapi** skill (`.agents/skills/fastapi/`).
+
+## Agent skills
+
+- Package skills (for example **fastapi**) are Library Skills-managed symlinks under **`.agents/skills/<name>/`**. Rules and hand-authored skills reference that path, not a copied tree under **`.cursor/skills/`**.
+- **`.cursor/skills/<name>`** may symlink to **`.agents/skills/<name>`** for Cursor; Library Skills repairs **`.agents/skills`** links when packages move. After **`uv sync`** or a dependency upgrade, run **`uvx library-skills --yes`** if symlinks are stale.
+
+## Host applications
+
+Do not edit consuming host repos in the same task as core-framework work unless the user scopes work to a host or asks to sync/upgrade. See the **sync-host-rules** skill.
+
+## Feature implementation
+
+Greenfield features (DB → API → repository → service → **documentation** → tests): use the **implement-feature** skill — one layer per response unless the user says otherwise. A feature is **not done** until documentation is updated.

core_framework-3.1.0/.cursor/skills/code-review/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: code-review
+description: Review code for quality, architecture compliance, and best practices. Use when the user asks for a code review, audit, or review.
+---
+
+# Code Review
+
+## Output format (required)
+
+**Actionable findings only:**
+
+- Bugs, wrong behavior, improvements, optimizations, doc/code contradictions, parallel implementation drift (sibling flows that diverge without documented reason).
+- Prioritize by severity with file context and fix direction.
+- **Do not** praise, summarize strengths, or pad with checklist pass narratives.
+- One-line scope is fine. If nothing is wrong, say so in one sentence.
+
+Do **not** flag documented accepted trade-offs in **`docs/platform/architecture-decisions.md`** unless the implementation violates them.
+
+## Workflow
+
+1. Read **`docs/platform/layers-and-boundaries.md`**, **`conventions.md`**, and **`architecture-decisions.md`** for the reviewed scope.
+1. Apply **scoped rules** (`.cursor/rules/*.mdc`) matching files under review — especially **`error-boundary`**, **`domain-imports`**, **`api-layer`**, **`application-layer`**, **`strong-reads`**.
+1. Report findings only — no filler.
+
+## Quick checks
+
+- Application services: no HTTP types, no domain exceptions, no Pydantic return types, one-line docstrings.
+- API: thin routers, validation in schemas, orchestration in application — **fastapi** skill (`.agents/skills/fastapi/`) + **`api-layer`** / **`api-validation`** / **`error-boundary`** rules.
+- Domain: imports only via **`__init__.py`** / **`dependencies`** from outer layers; no caller-context names (**`domain-caller-context`**).
+- Read-after-write refetches use **`*_strong`** where applicable.
+- **Python modernity (constitution):** prefer current 3.14 syntax in reviewed code — PEP 695 type params over module-level `TypeVar`/`ParamSpec`; no unnecessary `from __future__ import annotations`; builtins / `X | Y` over legacy `typing` aliases; `asyncio.TaskGroup` over `gather`.
+
+## Parallel drift
+
+Flag sibling modules with the same job but different structure (async layout, cleanup order, error/idempotency contracts) when docs do not explain the difference.

core_framework-3.1.0/.cursor/skills/sync-host-rules/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: sync-host-rules
+description: Sync core-framework rules, skills, and platform docs to consuming host applications. Use when the user asks to sync rules to a host, bump core-framework in a host, upgrade a host dependency, or port shared cursor/docs content.
+---
+
+# Sync Host Rules and Docs
+
+Consuming applications embed **core-framework** as a dependency.
+
+## Default (core-framework work)
+
+When changing **core-framework** code, migrations, tests, or **`docs/`**:
+
+- **Do not** edit host repos in the same task.
+- **Do not** port **`docs/platform/`**, **`docs/design/`**, **`docs/deployments/`**, **`.cursor/rules/`**, or **`.cursor/skills/`** to hosts proactively.
+- Mention that host sync is **deferred until the host bumps its core-framework version** (unless the user asked otherwise).
+
+## When host changes are allowed
+
+1. User explicitly scopes work to a host repo.
+1. User explicitly asks to sync or upgrade the core dependency in a host.
+1. You are editing a host repo directly — follow that repo's rules.
+
+## Sync procedure
+
+Diff by **basename** against the host's **`.cursor/`** and applicable **`docs/`** paths. Port shared content and **adapt**:
+
+- globs: **`core_framework/**`** → host source tree where applicable
+- imports: **`core_framework....`** → host package prefix
+- strong reads: **`strong-reads`** → host equivalent rule if present
+
+**Do not overwrite** host-only rules, skills, or product docs.
+
+### `docs/deployments/guides/` layout
+
+Core walkthroughs live under **`docs/deployments/guides/setup/`** (one-time install) and **`docs/deployments/guides/playbook/`** (ops / incident runbooks) — not a flat **`guides/`** directory.
+
+When syncing **`docs/deployments/`** to a host:
+
+1. **Match the directory layout** — create **`guides/setup/`** and **`guides/playbook/`** on the host; move or rewrite files into those paths. Do **not** leave stale flat **`guides/*.md`** copies beside the new tree.
+1. **Basename alone is not enough** — a host may still have **`guides/ubuntu-server-setup.md`** while core has **`guides/setup/ubuntu-server-setup.md`**. Diff by relative path under **`docs/deployments/`**, then port.
+1. **Renames** — e.g. **`postgres-backup-ops.md`** → **`guides/playbook/postgres-backup-playbook.md`**. Delete the old host path after porting.
+1. **Adapt host paths** in playbooks (Compose project dir, image names, **`app_configs/<host>/`**) — keep Henry-specific notes in host **`deploy-playbook.md`** / **`release-playbook.md`**.
+
+## Docs boundaries
+
+**Core `docs/` must stay host-agnostic** — no references to specific consuming applications.
+
+| Core path                                                         | Host behavior                                                 |
+| ----------------------------------------------------------------- | ------------------------------------------------------------- |
+| **`docs/platform/`**, **`docs/design/`**, **`docs/deployments/`** | Sync on dependency upgrade or explicit sync request           |
+| **`docs/domains/`**, **`docs/library/`**                          | Canonical in core only — do not mirror product trees to hosts |