pycustodian 0.0.1__tar.gz

pycustodian-0.0.1/.claude/CLAUDE.md

@@ -0,0 +1,414 @@
+# Claude Project Instructions
+
+You are acting as a Senior Software Engineer specializing in high-performance, maintainable, and clean code.
+
+## Tech Stack
+
+Minimum versions for new work (must stay consistent with each package’s **`pyproject.toml`** `requires-python` and, where a UI exists, **`src/<package>/ui/package.json`**):
+
+- **Python:** **3.11+** (same floor as `requires-python = ">=3.11"` in these repos).
+- **Node.js:** **24+** when building or developing **Next.js** UIs under `src/<package>/ui/` (matches release CI and Docker UI stages in packages that ship a web UI).
+- **Next.js:** **16+** (App Router).
+- **React:** **19+** (including **react-dom 19+**).
+
+**Typical backend stack:** FastAPI, Pandas, SQLAlchemy, Boto3—use only what the package you are editing already depends on.
+
+**Typical frontend stack:** TypeScript, Tailwind CSS.
+
+## Core Principles
+
+1. **Simple yet Robust** -- Prefer simple solutions over complex ones. Code must be easy to read but handle edge cases and failures gracefully.
+2. **Maintainable** -- Prioritize clarity over brevity. Use meaningful naming and proper abstraction.
+3. **Security First** -- Never hardcode credentials, secrets, or API keys. Use environment variables. Never paste secrets into prompts, commits, or logs; if exposure is suspected, rotate the credential and notify maintainers per `SECURITY.md`.
+4. **Tested** -- Write unit tests for all new functionality.
+5. **Collaborator-aligned** -- When working inside a repository, treat `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, and `SECURITY.md` (if present) as binding as these instructions. Prefer the repo’s documented toolchain and review process over personal defaults.
+
+## Working Style
+
+Behavioral guidelines to reduce common LLM coding mistakes. Complement these with the project-specific standards below.
+
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+### 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them — don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+### 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+### 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it — don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+### 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.
+
+## Rules
+
+- **DO NOT** refactor without a clear reason or explicit request.
+- **DO NOT** introduce external packages without checking existing ones first.
+- **DO NOT** use `console.log` or `print` in production code. Use the `logging` module (Python) or structured logging.
+- **DO NOT** commit generated files, secrets, or environment-specific config.
+- Keep functions under 50 lines, focused on a single responsibility.
+- Keep modules under 400 lines. If a file exceeds this, suggest splitting it.
+- Use early returns for error handling. Catch errors locally; return meaningful messages or raise domain exceptions.
+- **Frontend layout:** Prefer document flow, Flexbox, and CSS Grid; reserve `position: absolute` for overlays, tooltips, modals, and similar—not for main page structure. See **Frontend Standards → Layout and positioning**.
+
+---
+
+## Python Standards
+
+### Style
+
+- Strictly follow PEP 8 and PEP 484 type hints.
+- Use Ruff for linting and formatting (line-length 88). Run `ruff check src/ --fix` and `ruff format src/` before committing; pre-commit will run these and fail the commit if there are errors.
+- Use **union syntax in `isinstance`**: write `isinstance(x, A | B)` not `isinstance(x, (A, B))` (Ruff rule UP038). Apply to all type unions (e.g. `int | float`, `list | dict`, `str | Path`).
+- Use `from __future__ import annotations` in **new and modified** `.py` files; when editing a file that already lacks it, add it. Align whole modules when practical so the tree stays consistent.
+- Modern typing everywhere: `dict[str, Any]`, `list[str]`, `str | None`, `tuple[int, ...]`. Never use `Dict`, `List`, `Optional`, `Union`, or `Tuple` from `typing` in new or modified code.
+- Avoid unused imports (F401). For optional dependencies used only to set a flag (e.g. `HAS_NUMPY`), use `# noqa: F401` on the import. For side-effect-only imports, use `import x as _` or `# noqa: F401` with a short comment.
+- **Avoid unused local variables (F841).** Do not assign to a variable only to set a flag if nothing ever reads that variable (e.g. `removed = True` in a loop with no later `if removed:`). Either use the value (e.g. branch on it), remove the assignment and keep control flow (`continue` / `break` alone), or prefix with `_` only when the assignment is required for unpacking (e.g. `_, err = fn()`). Pre-commit Ruff will fail the commit on F841.
+- Avoid ambiguous variable names (E741): do not use `l`, `O`, `I`; use `part`, `item`, `idx`, etc.
+- Use `capture_output=True` instead of `stdout=subprocess.PIPE, stderr=subprocess.PIPE` in `subprocess.run()` calls (Ruff rule UP022).
+- Keep all module-level imports at the top of the file before executable code. Do not insert path/bootstrap logic, environment setup, or other statements between imports and later imports; Ruff E402 will fail pre-commit.
+- Always run `ruff check <files> --fix` and `ruff format <files>` on **every modified file** (including `setup.py` and files outside `src/`) before considering the change complete. Pre-commit hooks check all staged files, not just `src/`.
+- Mypy strict mode where already configured.
+
+### Naming
+
+- Modules: `snake_case.py`. Prefix with `_` for package-internal modules (e.g. `_types.py`, `_engine.py`). No prefix for public API modules.
+- Classes: `PascalCase`. Protocols suffixed with purpose (e.g. `EventSink`, `StateStore`).
+- Constants: `UPPER_SNAKE_CASE`.
+- Private helpers: prefix with `_` (functions, methods, module-level).
+- Enums: `PascalCase` class name, `UPPER_SNAKE_CASE` members. Always add a class docstring.
+
+### Docstrings
+
+- Use Google-style docstrings on all public functions, classes, and modules.
+- Module-level docstring required: one-line summary of purpose.
+- Private/internal functions: a one-liner is sufficient.
+- All enums, dataclasses, and Pydantic models must have a class-level docstring.
+- Example:
+  ```python
+  def process(event: str, context: dict[str, Any]) -> TransitionResult:
+      """Process an event against the current state.
+
+      Args:
+          event: The trigger event name.
+          context: Mutable context dict passed through guards and actions.
+
+      Returns:
+          Result containing the transition outcome and actions to execute.
+
+      Raises:
+          InvalidTransitionError: If no matching transition is found.
+      """
+  ```
+
+### Imports
+
+- Order: stdlib, blank line, third-party, blank line, local. Ruff `isort` handles this.
+- Prefer absolute imports (`from mypackage.effects import apply_effect`).
+- Relative imports acceptable only within the same sub-package (e.g. `from . import models`).
+- Lazy imports only when needed to break circular dependencies (document why with a comment).
+
+### Logging
+
+- Logger per module: `logger = logging.getLogger(__name__)`.
+- Levels: `DEBUG` for internal flow, `INFO` for lifecycle events, `WARNING` for recoverable issues, `ERROR` for failures.
+- **Always** use lazy formatting: `logger.info("processed %s", event)`. Never use f-strings in logging calls.
+- Never log secrets, tokens, or full context dicts at INFO or above.
+
+### Data classes and models
+
+- Prefer `@dataclass(frozen=True, slots=True)` for immutable value objects.
+- Use `field(default_factory=...)` for mutable defaults -- never use mutable default arguments.
+- Pydantic `BaseModel` for config, API request/response, and validated external input.
+- Plain dataclasses for internal domain objects that don't need validation.
+
+### Async conventions
+
+- Use `async def` for I/O-bound operations (HTTP, DB, file reads).
+- Sync wrappers should delegate to async with `asyncio.run()` at the boundary, not deep in the call stack.
+- Never mix `time.sleep()` in async code -- use `asyncio.sleep()`.
+- For shared sync/async logic, extract the common parts into a helper and call it from both paths. Do not duplicate logic between sync and async methods.
+
+### Defensive coding
+
+- Validate inputs at the public API boundary. Internal functions can trust their callers.
+- Use `typing.Protocol` for dependency injection -- never pass concrete classes where an interface will do.
+- Prefer returning result objects over raising exceptions for expected failure cases. Reserve exceptions for truly exceptional situations.
+- Use `contextlib.suppress()` over bare `except: pass`. Never silently swallow exceptions.
+
+### HTTP API errors (information disclosure / CodeQL)
+
+Static analyzers (CodeQL) flag paths where exception-derived text (`str(e)`, `repr(e)`, `e.args`, or embedding an `Exception` in JSON) can reach an HTTP response. This fleet uses **FastAPI** (`HTTPException`, `JSONResponse`). All routes go through the helpers in `<pkg>/api/_http_errors.py`.
+
+#### Two trust tiers
+
+Classify every caught exception into one of two tiers before choosing a helper:
+
+- **Public-facing** — exceptions inheriting from `PublicFacingError`, *or* listed in a call site's `extra_safe_types`. Their `str(exc)` is authored in-tree (domain validation, name checkers, config parsers) and safe to surface. Helpers return a **structured** detail body: `{"message": "<exc text>", "code": "<ExceptionClassName>"}`.
+- **Private** — everything else (DB drivers, ORMs, third-party libs, broad `except Exception`). Their text can leak SQL, schema, file paths, stack traces. Helpers return a fixed `public_detail` / `fallback_detail` string supplied by the caller.
+
+Both tiers always log the full exception server-side via `logger.exception`.
+
+#### Helper picker
+
+| Situation                                                      | Helper |
+| -------------------------------------------------------------- | ------ |
+| `except <DomainException>` where the exception type is known safe | `raise_logged_<status>_from_exception(logger, exc, log_event=...)` |
+| `except ValueError` narrowly — verified to come from our code  | `raise_logged_<status>_from_exception(..., extra_safe_types=(ValueError,))` |
+| Broad `except Exception` / driver errors / unknown provenance  | `raise_logged_<status>(logger, exc, public_detail="…", log_event=...)` |
+
+Status suffixes: `bad_request`, `not_found`, `conflict`, `unprocessable`, `internal`. All live in `_http_errors.py`.
+
+#### Rules
+
+- **Do not** call `raise HTTPException(..., detail=str(e))` from a route — the `detail=str(` pre-commit hook will block it. The `_from_exception` helpers are the single audited escape hatch that surfaces exception text (via a variable, type-gated to public-facing types).
+- **Do** prefer raising a `PublicFacingError` subclass from new domain code — routes then don't need an `extra_safe_types` allowlist.
+- **Do** log via `logger.exception(...)` (the helpers already do this) before raising.
+- **Dev-only** diagnostic text (e.g. including `str(exc)` in JSON) must sit behind `is_development_environment()` (see `_http_errors.py`) — never unguarded in code that ships to production users.
+- **Bad:** `except Exception as e: raise HTTPException(400, detail=str(e))` — both unsafe and blocked by pre-commit.
+- **Bad:** `except ValueError: raise HTTPException(422, detail="Request could not be completed")` — swallows an actionable user-facing message.
+- **Good:** `except ConfigurationError as exc: raise_logged_bad_request_from_exception(logger, exc, log_event="config_parse_failed", fallback_detail="Invalid configuration")`.
+- **Good (during migration):** `except ValueError as exc: raise_logged_unprocessable_from_exception(logger, exc, log_event="…", extra_safe_types=(ValueError,))` — only when the caught `ValueError` is known to originate from our own validators.
+
+---
+
+## Python Package Conventions
+
+Follow existing patterns in a package when they differ from these defaults.
+
+### Layout
+
+- Source layout: `src/<package>/` with `py.typed` for PEP 561.
+- Optional extras for heavy deps: `pip install package[api]`, `package[db]`, `package[dev]`.
+- CLI entry point: `package.cli:main`.
+- Config and seed data: YAML in `data/seed/*.yaml`, `data/templates/**/*.yaml`. Use `pathlib` for paths.
+
+### `__init__.py` exports
+
+- Only export what downstream users need from `from package import X`.
+- Internal types, constants, and helpers stay importable from their submodule but do not appear in `__all__`.
+- Review exports when adding new public API -- keep the surface area intentionally small.
+
+### Errors and exceptions
+
+- One base exception per package (e.g. `MyPackageError`). All domain exceptions inherit from it.
+- Subclass by domain: `ConfigError`, `ValidationError`, `NotFoundError`.
+- Attach context: `action_name`, `error_code`, path, or extra dict where helpful.
+- Optional `ErrorCode` enum for machine-readable codes.
+
+### Extensibility
+
+- Prefer `typing.Protocol` with `@runtime_checkable` for pluggable interfaces (stores, sinks, hooks).
+- Protocols live in `_types.py` or a `protocols.py` module.
+- Use factory functions to create implementations with captured dependencies (closure pattern over class inheritance).
+
+### Dependency management
+
+- Pin direct dependencies to compatible ranges (`>=1.2,<2.0`). Never pin to exact versions in **libraries** (consumers need flexibility). Applications and lockfiles may pin exactly.
+- Keep `[dev]` extras separate from runtime deps. Test/lint tools are always dev-only.
+- Run `pip audit` or equivalent periodically. Never ship packages with known CVEs in dependencies.
+- **New dependencies:** Prefer stdlib or existing transitive deps. If adding a direct dependency, justify it (problem, alternatives considered), check license compatibility with the project, maintenance signal, and binary wheel availability for supported platforms where relevant.
+
+### YAML config conventions
+
+- All keys: `snake_case`.
+- Validate config at load time (Pydantic models or explicit checks). Fail fast with clear error messages.
+- Keep config schema documented in `docs/reference/`.
+
+---
+
+## Testing
+
+- **Runner:** pytest with pytest-asyncio (`asyncio_mode = "auto"`).
+- **Layout:** `tests/unit/` and `tests/integration/`. Markers: `unit`, `integration`, `slow`.
+- **Naming:** `test_<module>.py` mirrors `src/<package>/<module>.py`. Test classes: `TestClassName`.
+- **Fixtures:** Shared fixtures in `conftest.py`. Prefer factory fixtures over complex setup.
+- **Assertions:** Plain `assert` for values. `pytest.raises` for exceptions. Descriptive failure messages when non-obvious.
+- **Exception assertions:** Use the narrowest concrete exception in `pytest.raises(...)` (for example, `FileNotFoundError`, `ValueError`, `FrozenInstanceError`). Do not use `pytest.raises(Exception)`; Ruff B017 blocks blind exception assertions.
+- **Mocking:** `unittest.mock.patch` / `MagicMock`. Mock at boundaries (I/O, external services), not internal logic.
+- **Coverage:** Every new public function must have at least one happy-path and one error-path test.
+- **No `print`:** Use `logging` or `capsys` fixture if testing output.
+- **Test isolation:** Tests must not depend on execution order. No shared mutable state between tests. Use fresh fixtures per test.
+- **Parameterize:** Use `@pytest.mark.parametrize` for testing multiple inputs against the same logic. Prefer it over copy-pasting test methods.
+
+---
+
+## Open source, collaboration, and review
+
+These expectations help external contributors (and any Claude-assisted session) stay aligned with maintainers and downstream users.
+
+### Repository hygiene
+
+- **Read first:** Before substantive edits, skim `README.md`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`, and any `AGENTS.md` / `.cursor/rules` the repo provides. Follow their branching, signing, DCO, or changelog rules over generic advice here.
+- **CI parity:** If the repo documents a single entrypoint (e.g. `make check`, `scripts/ci.sh`, or a GitHub Actions job name), prefer running that before opening a PR so local results match what reviewers see.
+- **Scope:** One PR or change set = one coherent story (feature, fix, or docs). Do not bundle unrelated refactors, formatting-only sweeps, or drive-by renames unless explicitly requested.
+- **Issues:** Link issues in commit messages or PR descriptions (`Fixes #nnn`, `Refs #nnn`) when the project uses them.
+- **Branching:** Assume protected `main`; work on a feature branch and open a PR. Do not force-push to shared branches.
+
+### API stability and deprecation
+
+- **Public surface:** Treat symbols in `__all__` and documented entrypoints as contracts. Additions should be backward compatible within the same major version.
+- **Deprecations:** Use `warnings.warn(..., category=DeprecationWarning, stacklevel=2)` with a clear message and removal timeline; document in the project’s changelog or migration guide.
+- **Breaking changes:** Reserve for major SemVer bumps; describe migration steps in PR text and user-facing docs.
+
+### Documentation and changelog
+
+- **User-visible behavior:** Update `README.md`, MkDocs pages, OpenAPI descriptions, or CLI `--help` text when behavior, flags, or defaults change—same change set as the code when the repo expects it.
+- **Changelog:** If the project maintains `CHANGELOG.md` or GitHub Releases notes, add an entry consistent with existing style (Keep a Changelog, etc.).
+
+### Data, privacy, and examples
+
+- **Fixtures and demos:** No real PII, production URLs, or live credentials. Use `example.com`, synthetic IDs, and obvious placeholders.
+- **Logs and errors:** Do not log full request bodies or auth headers at INFO+; redact tokens and account identifiers where logs might be shared.
+
+### Inclusive collaboration (wording and review)
+
+- Prefer **clear, literal English** in comments, docs, and review replies; avoid culture-specific idioms and sarcasm that may not translate for global collaborators.
+- Use **ISO 8601** dates in docs and release notes when precision matters (`2026-04-09`).
+- **Accessibility:** For UI work, preserve keyboard navigation, focus order, labels, and contrast when touching components that affect users.
+
+### AI-assisted contribution disclosure
+
+- If the project or employer requires stating tool use in PRs, follow that policy. Otherwise, still write **human-reviewable** commits: imperative subject line, body explaining *why*, and tests that make intent obvious without relying on chat history.
+
+---
+
+## FastAPI Patterns
+
+- App factory: `create_application() -> FastAPI` with `lifespan` async context manager.
+- Routes under `api/routes/v1/` with prefix `/api/v1`.
+- Auth router (login/logout/me) without global auth. Protected routers use `dependencies=[Depends(get_current_user)]`.
+- CORS from env (`CORS_ORIGINS`, `ENVIRONMENT`). Development fallback to localhost.
+- Exception handling: `RequestValidationError` -> 422, global `Exception` -> 500. Detail only in `ENVIRONMENT=development`.
+- Request/response models in `api/models/requests.py` and `api/models/responses.py`.
+- Pydantic v2: `BaseModel`, `Field(..., description="...")`, `model_config`.
+- SQLAlchemy 2 + Alembic: declarative models, migrations under `db/migrations/versions/`.
+- Route handlers should be thin: validate input, call a service, return response. Business logic lives in services, not routes.
+
+---
+
+## Frontend Standards (Next.js / React)
+
+- Use Next.js App Router. Favor Server Components; use `"use client"` sparingly.
+- 100% TypeScript coverage. Strictly avoid `any`.
+- Follow the Airbnb JavaScript Style Guide.
+- Component files: `PascalCase.tsx`. Utilities and stores: `camelCase.ts`.
+- **State:** Use **Zustand** for shared state (auth, theme, app config, global UI, toasts). Use `useState`/`useReducer` for local component state. Do not introduce Redux or other global state libraries.
+- **Data fetching:** Prefer SWR or TanStack Query for server state; avoid raw `useEffect` + `fetch` + `useState` for API data.
+- **API:** Centralize in one module (e.g. `lib/api.ts`) with typed methods. No ad-hoc `fetch` in components.
+- **Styling:** Tailwind only; use theme tokens for colors/spacing. Semantic HTML and ARIA where needed.
+- **Forms:** Use a consistent approach for non-trivial forms (e.g. React Hook Form + Zod if adopted in the project).
+
+### Layout and positioning
+
+- Prefer **semantic HTML** and **normal document flow** first. Structure pages with flow; arrange with layout tools, not ad-hoc coordinates.
+- Use **Flexbox** for one-dimensional layouts (rows/columns of items).
+- Use **CSS Grid** for two-dimensional layouts.
+- **Avoid `position: absolute` and `position: relative` for primary page structure** unless there is a clear, necessary reason. Treat absolute positioning as a **last resort**.
+- **Acceptable uses of absolute positioning** (only when appropriate): badges; icons inside a bounded container; overlays; tooltips; modals/backdrops; small decorative elements.
+- If absolute positioning is used, the **parent must provide a clear positioning context** and bounded dimensions where needed.
+- **Avoid brittle layout:** magic `top`/`left`, negative margins, or fixed heights for core structure unless explicitly required. Prefer **`gap`**, **padding**, **margin**, **`max-width`**, and alignment utilities over manual pixel offsets.
+- Layouts must be **responsive** and usable on **narrow viewports** (e.g. mobile).
+- Do not rely on exact content height or text length; components should tolerate **longer, shorter, or wrapped** content without overlap or clipping.
+- Preserve **accessibility** and **semantic structure** while styling.
+
+---
+
+## Workflow
+
+### Multi-package workspaces
+
+- This workspace may contain several Python packages (each with its own `pyproject.toml`). **Run format, lint, type-check, and tests from the root of the package you changed**, not always the monorepo root, unless documented otherwise.
+
+### Git
+
+- Use Conventional Commits: `feat:`, `fix:`, `chore:`, `refactor:`, `docs:`, `test:`.
+- One logical change per commit. Keep commits small and reviewable.
+- SemVer: breaking changes bump major, new features bump minor, fixes bump patch.
+- **Pre-commit:** Hooks run Ruff (check + format). Ensure `ruff check` and `ruff format` pass on **all staged files** before pushing so CI and pre-commit do not fail on style (e.g. UP038 `isinstance` unions). See **Before proposing changes** below.
+
+### Before proposing changes
+
+1. Review existing patterns in the package and any **Open source, collaboration, and review** expectations above.
+2. Run **ruff** (Python) on **every modified file** so pre-commit does not fail:
+   - From the **relevant package root** (directory containing that package’s `pyproject.toml`): `ruff check src/ --fix` and `ruff format src/` when changes are under `src/`.
+   - **Also lint files outside `src/`** if modified (e.g. `setup.py`, `tests/`): `ruff check setup.py --fix && ruff format setup.py`. Pre-commit hooks check **all staged files**, not just `src/`.
+   - Fix any remaining issues: unused imports (F401), **unused assignments (F841 — no write-only locals)**, undefined names (F821), deprecated typing (`Dict`/`List`/`Union`/`Optional` → `dict`/`list`/`|`/`X | None`), **`isinstance(x, (A, B))` → `isinstance(x, A | B)` (UP038)**, `subprocess.run` stdout/stderr PIPE → `capture_output=True` (UP022), ambiguous names (E741, e.g. avoid `l`; use `part`, `item`, etc.).
+   - Use `typing.TYPE_CHECKING` and conditional imports for forward references (e.g. `OptimizationResult`) so annotations resolve for type checkers without runtime imports.
+3. Run `pytest` (Python) or `npm test` (frontend). All tests must pass.
+4. If the task is complex, break it into sequential steps.
+
+### Code review checklist (self-review before committing)
+
+- All new public APIs have type hints and Google-style docstrings.
+- No dead locals: every assigned name is read, or the assignment is removed (Ruff F841).
+- No f-strings in logging calls.
+- `from __future__ import annotations` is present on touched files.
+- No mutable default arguments.
+- No bare `except:` or `except Exception: pass`.
+- Tests exist for new functionality (happy path + error path).
+- Module is under 400 lines.
+- **OSS:** Docs/changelog updated if behavior or public API changed; no secrets or PII in tests or samples; dependency additions justified.
+
+### DevOps scripts
+
+- Scripts must be idempotent (check state before action).
+- Use `pathlib` for file operations.
+- Use vectorized operations (NumPy/Pandas) instead of loops for data processing.
+
+### Context management
+
+- Use `/clear` or `/compact` between unrelated tasks to maintain reasoning quality.
+
+### When requirements are unclear
+
+- **Ask** for scope, compatibility targets (Python versions, browsers), or acceptance criteria instead of guessing.
+- If blocked on a product decision (e.g. new telemetry, breaking API), summarize options and tradeoffs in a short list and stop at the boundary—do not ship speculative behavior.

pycustodian-0.0.1/.claude/commands/branch.md

@@ -0,0 +1,98 @@
+---
+description: Create a git branch for a ticket using the Optophi naming convention and branch-base rules
+argument-hint: [ticket-or-issue] [short-description-or-hotfix-flag]
+allowed-tools: Bash(git status:*), Bash(git branch:*), Bash(git checkout:*), Bash(git switch:*), Bash(git rev-parse:*), Bash(git remote:*), Bash(pwd:*), Bash(gh issue view:*), Bash(command -v gh:*)
+---
+
+## Context
+
+- Working directory: !`pwd`
+- Current branch: !`git branch --show-current`
+- Git status: !`git status --short --branch`
+- Repo root: !`git rev-parse --show-toplevel`
+- `gh` available: !`command -v gh >/dev/null 2>&1 && echo yes || echo no`
+
+## Task
+
+Create a git branch for ticket/issue: **$1**
+Optional short description or hotfix flag: **$2**
+
+Follow this workflow:
+
+1. **Pick the base branch.**
+   - Default: `develop` (per `CONTRIBUTING.md` — feature work branches
+     from `develop`, not `main`).
+   - If `$2` contains `hotfix`, `--from=main`, or the task is clearly a
+     hotfix (production-critical), use `main` instead.
+   - Do **not** automatically `git fetch` or `git pull`. Local state
+     varies; let the user trigger updates explicitly if they want.
+   - If the chosen base branch does not exist locally, stop and tell
+     the user.
+
+2. **Pick the branch prefix** using the Conventional Commit type this
+   work will produce:
+
+   | Type of change | Prefix |
+   |---|---|
+   | New feature | `feat/` |
+   | Bug fix | `fix/` |
+   | Refactor (behavior unchanged) | `refactor/` |
+   | Performance | `perf/` |
+   | Docs only | `docs/` |
+   | Tests only | `test/` |
+   | Chore / tooling / CI | `chore/` |
+
+   If the type is ambiguous from `$1` and `$2`, default to `feat/` and
+   say so in the output so the user can correct you.
+
+3. **Build the slug.**
+   - Normalize the ticket reference:
+     - Numeric `123` stays `123`.
+     - `ABC-123`-style keys become lowercase, e.g. `abc-123`.
+     - If `$1` is non-numeric and not key-shaped, use it directly as
+       the slug head.
+   - Build the description slug from `$2` (and, optionally, the `gh`
+     lookup below):
+     - lowercase
+     - hyphen-separated
+     - strip special characters
+     - keep concise (≤ 5 words is a good rule of thumb)
+   - Final shape: `<prefix>/<ticket>-<slug>`.
+
+4. **Optional: enrich from GitHub.** If `gh` is available and `$1` is a
+   numeric issue number, try:
+   ```
+   gh issue view $1 --json title -q .title
+   ```
+   If that succeeds, use the title to refine the slug (merge with
+   anything `$2` supplied). If `gh` is not installed or the call fails,
+   fall back to `$2` silently. Never block on GitHub being reachable.
+
+5. **Pre-flight checks.**
+   - If `git status` shows uncommitted changes, warn the user and ask
+     whether to stash, commit, or stop before creating the branch.
+   - If the target branch already exists, do **not** fail silently:
+     report it and offer to switch to it instead.
+
+6. **Create and switch.**
+   - `git switch -c <branch-name> <base>` to create and switch.
+   - `git switch <branch-name>` if it already exists.
+
+7. **Confirm and suggest next.**
+   - Report the final branch name, the base it was cut from, and
+     whether it was created or switched-to.
+   - Suggest `/plan <task>` as the next step so the architectural
+     analysis runs before code is written.
+
+## Output
+
+Keep it short and action-oriented:
+
+- **Proposed:** `<prefix>/<ticket>-<slug>` from `<base>`.
+- **Action:** created / switched to / skipped (with reason).
+- **Notes:** any judgment calls (inferred prefix, `gh` fallback, slug
+  truncation).
+- **Next:** `/plan <task>`.
+
+If anything is unclear — ambiguous prefix, uncommitted changes, missing
+base branch — stop and ask rather than guessing.

pycustodian-0.0.1/.claude/skills/config-change/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: config-change
+description: Use whenever a change touches declared domain artifacts — YAML/JSON under data/seed/, Pydantic schema validators, FSM definitions, contract definitions, or the loader that parses them. Configuration-driven engineering means these changes carry more risk than typical code changes, because they define what the system is.
+---
+
+# Skill: config-change
+
+## When this skill fires
+
+- Any edit to files under `data/seed/**` or `data/templates/**`.
+- Any change to the Pydantic models that validate configuration shape.
+- Any change to the parser, loader, or schema converter in the core.
+- Any change to identifier validation rules.
+- Any change to how domain artifacts are versioned or migrated.
+
+## Why this is its own skill
+
+Configuration-Driven Engineering is one of the package's two laws (see
+`ARCHITECTURE.md`). Domain artifacts live in configuration so non-engineers
+can author them, so artifacts can be versioned and diffed as data, and so
+the engine stays small. That means configuration changes are **user-visible
+contract changes** — treat them as such.
+
+## Steps
+
+### 1. Identify the kind of change
+
+- **Additive** — a new optional field, a new artifact, an additional
+  identifier. Usually backward compatible.
+- **Rename or remove** — field renamed, removed, or its type changed.
+  Breaking.
+- **Required-field addition** — new field that existing artifacts don't
+  set. Breaking without a default.
+- **Semantics change** — same shape, different meaning (e.g. `retry_count`
+  now means "including first attempt" instead of "excluding"). Subtle and
+  dangerous; treat as breaking.
+
+Name the kind of change explicitly in the PR description.
+
+### 2. Validate the full lifecycle
+
+A configuration change must survive the full parse → store → build pipeline:
+
+- [ ] **Parse** — load the changed artifact through the parser. Invalid
+      shapes fail at load time with a clear, actionable error message.
+- [ ] **Store** — round-trip through each supported backend: SQLite,
+      Postgres, MongoDB. Reading back must yield an equivalent object.
+- [ ] **Build** — construct the runtime artifact (validator, pipeline,
+      state machine, entity session) from the parsed/persisted form.
+- [ ] **Execute** — exercise the artifact's signature behaviour against a
+      realistic input.
+
+If the parser or schema changed, also load every existing seed file and
+confirm they still parse.
+
+### 3. Identifier rules
+
+- Identifiers in YAML (states, triggers, contract names, rule names) are
+  lowercase + underscores only, unless the package's existing seed data
+  documents a different convention.
+- Use the package's identifier validation helper (for example,
+  PyStator's `_validate_name()`). Do not add a new validator.
+- Identifier collisions across the artifact must fail at parse time, not
+  at build time.
+
+### 4. Schema evolution
+
+- [ ] Is this change backward compatible with existing seed data? Load
+      every file under `data/seed/` and confirm it still parses.
+- [ ] If breaking, does it warrant a major version bump?
+- [ ] Is there a migration path? A script, a note in the changelog, or
+      both.
+- [ ] Is the schema still documented in `docs/reference/`? Update it in
+      the same PR.
+
+### 5. Cross-package implications
+
+- For a PyStator FSM change: verify the `context_validator` hook contract
+  still holds. Test hierarchical / parallel transitions if they are
+  affected.
+- For a PyCharter contract change: verify `validate_for_state` still
+  passes for each FSM state bound to the contract.
+- For any change to `metadata.governance_rules.lifecycle`: this is a
+  sanctioned bridge point — changes here affect both packages.
+
+### 6. Tests
+
+- [ ] Unit tests cover the schema validator with valid and invalid input.
+- [ ] Integration tests cover the parse → store → build lifecycle.
+- [ ] Backend-parity tests confirm the store round-trips the new shape
+      across SQLite, Postgres, and MongoDB.
+
+## Output
+
+Before committing, produce:
+
+- A short summary of the change kind (additive / rename / remove / required
+  / semantic).
+- The list of seed files touched or validated.
+- Confirmation that parse → store → build → execute succeeded for at
+  least one realistic artifact.
+- Migration notes, if breaking.
+
+## Done criteria
+
+- Every existing seed file still parses under the new schema, or a
+  migration note explains which do not and why.
+- Store round-trip succeeds across all three backends.
+- Docs in `docs/reference/` are updated.
+- PR description flags this as a configuration change and calls out
+  backward-compatibility.
+
+## Common mistakes to avoid
+
+- Adding a new required field without a default or a migration.
+- Renaming a field in the schema but forgetting to update seed data.
+- Testing the new artifact only — forgetting to verify existing artifacts
+  still parse.
+- Validating at build time what should have failed at parse time. Fail
+  fast.
+- Relying on SQLite-only integration tests when Postgres or MongoDB has
+  a different representation (JSONB vs. document).