feat: caregiver push flow + hexagonal architecture

.claude/commands/fall-guardian/bug-fix.md

@@ -1,8 +1,31 @@
-Fix the bug at the correct layer, not with a local workaround.
-
-Steps:
-- reproduce or understand the failing path
-- trace ownership across Flutter/native/backend if cross-platform
-- implement the smallest durable fix
-- add a regression test when practical
-- verify the narrowest relevant checks, then broader checks if needed
+Fix a Symfony/API Platform bug using a small, repeatable regression-first workflow.
+
+Bug report or scope: `$ARGUMENTS`
+
+Execution order:
+1. Reproduce the bug from the user report, failing test, logs, or current behavior.
+2. Find the narrowest code path that explains the failure.
+3. Identify the root cause before changing code.
+4. Implement the smallest fix that resolves the bug cleanly.
+5. Add or update a regression test in the same session.
+6. Run the relevant repository quality gates before reporting completion.
+
+Default expectations unless the repo clearly differs:
+- Prefer the smallest understandable fix over broad refactoring.
+- Keep the fix easy for a human reviewer to understand.
+- If API Platform already provides the correct behavior directly, use it instead of adding extra layers.
+- If performance and readability conflict and there is no measured bottleneck, choose readability.
+
+Checklist:
+1. State expected behavior versus actual behavior.
+2. Point to the concrete failing path: endpoint, handler, repository, listener, or adapter.
+3. Reuse local patterns instead of introducing a new structure during a bug fix.
+4. Add one regression test for the reproduced scenario.
+5. Add extra coverage only for closely related edge cases.
+6. Verify with the commands exposed by `Makefile`.
+
+Avoid:
+- mixing unrelated cleanup into the fix
+- speculative refactors during an urgent bug fix
+- skipping the regression test unless the repo truly cannot express one
+- introducing extra indirection for a local issue

.claude/commands/fall-guardian/improve-instructions.md

@@ -1,8 +1,42 @@
-Improve repo instructions only when there is durable evidence of drift.
-
-Steps:
-- identify the stable guidance gap
-- propose the change first
-- update the canonical file
-- keep pointer files minimal
-- avoid adding one-off local anecdotes
+Review the repository guidance and propose improvements to instruction files without editing them silently.
+
+Scope or context: `$ARGUMENTS`
+
+Target files:
+- `AGENTS.md`
+- `CLAUDE.md`
+- `.claude/rules/*.md`
+- `.claude/patterns.md`
+- `.claude/commands/fall-guardian/*.md`
+- `.claude/skills/*/SKILL.md`
+
+Workflow:
+1. Inspect the current repository shape, quality gates, and recent workflow expectations.
+2. Look for instruction drift:
+   - repeated corrections in recent work
+   - `Makefile`, `composer.json`, or repo structure changes
+   - architecture or testing conventions no longer reflected in instructions
+   - duplicated or conflicting guidance
+3. Classify each candidate update:
+   - policy
+   - workflow
+   - pattern
+   - project fact
+   - temporary note
+4. Keep only durable, reusable updates. Ignore one-off preferences.
+5. Produce a proposed patch and rationale.
+6. Ask for confirmation before editing any instruction file.
+
+Rules:
+- Never edit instruction files silently.
+- `AGENTS.md` remains the canonical source of repository-specific rules.
+- `CLAUDE.md` must stay a thin pointer.
+- Update `.claude` files only when the improvement is reusable and not just project noise.
+- If commands and skills overlap, keep them aligned with the same underlying rules and patterns.
+
+Output format:
+- `Detected drift`
+- `Proposed updates`
+- `Why each update is useful`
+- `Patch preview`
+- `Confirmation request`

.claude/commands/fall-guardian/new-feature.md

@@ -1,9 +1,43 @@
-Implement a new feature in the smallest clean slice.
-
-Steps:
-- scan the relevant architecture first
-- choose the right layer for each change
-- preserve coordinator/service ownership
-- add or update tests
-- update docs if runtime behavior changes
-- verify the relevant checks before finishing
+Implement a new Symfony/API Platform feature by mirroring the local repository patterns.
+
+User request: `$ARGUMENTS`
+
+Execution order:
+1. Run the equivalent of `/fall-guardian:scan-project` if context is incomplete.
+2. Find one nearby example in the same area and mirror its structure.
+3. Implement the smallest coherent slice that satisfies the request.
+4. Write tests in the same session.
+5. Run the repository quality gates before reporting completion.
+
+Default expectations unless the repo clearly differs:
+- Follow SOLID principles.
+- Prefer clean architecture and hexagonal boundaries when the project already uses them.
+- If API Platform already provides a direct, readable solution for the requested behavior, use the API Platform feature instead of adding extra layers.
+- Symfony entrypoints stay thin.
+- Input validation happens at the DTO or request boundary.
+- Business logic lives in handlers, use-cases, or domain services.
+- Repositories handle persistence only.
+- Output shaping is explicit through DTOs, resources, or entity serialization.
+- Prefer simple, readable code over clever or highly optimized code.
+- If performance and readability conflict and there is no measured bottleneck, choose readability.
+- Keep the result easy for a human reviewer to follow.
+
+Checklist:
+1. Confirm the target flow: API Platform native, layered write side, or both.
+2. Reuse existing naming and file placement conventions.
+3. Keep `declare(strict_types=1);` and modern PHP syntax.
+4. Add or update validation at the input boundary.
+5. Keep exceptions and HTTP error mapping aligned with the existing project.
+6. Add the right tests:
+   - unit tests for behavior and orchestration
+   - integration tests when persistence behavior changes
+   - API tests when endpoint behavior changes
+7. Verify with the commands exposed by `Makefile`.
+
+Avoid:
+- business logic in controllers or framework entrypoints
+- new dependencies without explicit approval
+- schema changes without explicit approval
+- adding hexagonal or CQRS indirection when API Platform can solve the case directly and cleanly
+- premature optimization or indirection that hurts readability
+- project reshaping when the request only needs a local change

.claude/commands/fall-guardian/prepare-commit.md

@@ -1,6 +1,37 @@
-Before preparing a commit:
-- confirm the worktree only contains intended changes
-- group commits logically
-- use Conventional Commits
-- summarize remaining risks or limitations
-- do not commit or push without explicit confirmation in the current conversation
+Prepare a commit for the current changes using Conventional Commits and repo-aware verification notes.
+
+Scope or context: `$ARGUMENTS`
+
+Workflow:
+1. Inspect `git status`, the current branch, and the current diff.
+2. Stage the intended files with `git add`.
+3. Run the repository quality checks relevant to the current change, using the real project gates from `Makefile`.
+4. Review the change for correctness, architecture, validation, regressions, and test completeness.
+5. Review the change with a security lens: auth/authz, input validation, secrets, external calls, and data exposure.
+6. If the current branch is `main`, `master`, `develop`, or another protected/shared branch, create a dedicated branch before committing.
+7. Build a Conventional Commit message that matches the actual change scope.
+8. Prepare PR-ready notes that explain:
+   - what changed
+   - why it changed
+   - how it was implemented
+   - what was verified
+   - remaining risks or follow-up points
+9. Prepare a verification checklist based on the real project gates from `Makefile`.
+10. If the user explicitly asks to commit, ask for confirmation before running `git commit`.
+11. If the user explicitly asks to push, ask for confirmation before running `git push`.
+
+Rules:
+- Never commit or push silently.
+- Treat `git commit` and `git push` as confirmation-required actions even when the user previously asked for preparation work.
+- Stage only the files that belong to the intended change.
+- Prefer a short, accurate Conventional Commit title over a clever one.
+- Do not invent verification steps that do not exist in the repository.
+- If quality, review, or security checks reveal blockers, surface them before proposing the final commit.
+
+Output format:
+- `Pre-commit checks`
+- `Suggested branch`
+- `Suggested commit title`
+- `Suggested commit body`
+- `PR notes`
+- `Verification checklist`

.claude/commands/fall-guardian/review-change.md

@@ -1,8 +1,29 @@
-Review the changed files for:
-- correctness
-- regressions
-- lifecycle safety
-- platform parity
-- missing tests
-
-Findings first. Keep summaries brief.
+Perform a structured code review for a Symfony/API Platform change.
+
+Review scope: `$ARGUMENTS`
+
+If the scope is omitted, inspect the current git diff.
+
+Review checklist:
+1. Confirm the change respects the repository architecture and `AGENTS.md`.
+2. Check that entrypoints remain orchestration-only.
+3. Check that business rules stay in handlers, use-cases, or domain services.
+4. Check validation at the input boundary.
+5. Check persistence code for leaked business logic.
+6. Check error handling and API behavior consistency.
+7. Check test completeness for the changed behavior.
+8. Check that the change can pass the repo quality gates.
+
+Prioritize findings:
+- correctness bugs
+- security regressions
+- architectural regressions
+- missing validation or tests
+- maintainability issues
+
+Response format:
+- findings first, ordered by severity
+- then open questions or assumptions
+- then a short summary only if useful
+
+Do not focus on style nits already covered by formatters or static analysis unless they expose real risk.

.claude/commands/fall-guardian/scan-project.md

@@ -1,12 +1,32 @@
-Scan the repository before proposing changes.
-
-Read:
-- `AGENTS.md`
-- `PROJECT_CONTEXT.md`
-- `WORKFLOW.md`
-- `CURRENT_STATUS.md`
-
-Then inspect only the code paths relevant to the request and summarize:
-- current architecture touchpoints
-- likely risk areas
-- verification needed
+Review this Symfony/API Platform repository and produce an implementation-ready map.
+
+User request: `$ARGUMENTS`
+
+Workflow:
+1. Read `AGENTS.md`, `CLAUDE.md`, `README.md`, `composer.json`, and `Makefile`.
+2. Inspect the project layout before proposing any change:
+   - `src/`
+   - `config/`
+   - `tests/`
+   - `features/`
+   - `migrations/`
+3. Detect the active conventions:
+   - Symfony and PHP versions
+   - API Platform usage style
+   - Docker/FrankenPHP setup
+   - layered, CQRS, or API Platform native flows
+   - test stack and quality gates
+4. Identify the nearest existing pattern for the requested area.
+5. Call out project-specific constraints that matter before coding.
+
+Output format:
+- `Context`: 4-8 bullets with relevant architecture and tooling facts
+- `Existing patterns`: file paths worth mirroring
+- `Files likely to change`: exact paths or tight glob patterns
+- `Risks`: regressions, hidden coupling, or prerequisites
+- `Implementation plan`: short numbered list
+
+Rules:
+- Prefer local project patterns over Symfony defaults.
+- Do not invent new folders or layers when the repo already has a clear shape.
+- Surface any policy in `AGENTS.md` that requires explicit confirmation before changes.

.claude/commands/fall-guardian/security-review.md

@@ -1,9 +1,41 @@
-Review the relevant change for:
-- secrets exposure
-- unsafe input handling
-- insecure persistence
-- backend authorization gaps
-- unsafe outbound communication
-- cross-device trust assumptions
-
-Call out concrete risks before general advice.
+Perform a focused security review for a Symfony/API Platform change.
+
+Review scope: `$ARGUMENTS`
+
+If the scope is omitted, inspect the current git diff.
+
+Security checklist:
+1. Authentication:
+   - protected routes are explicit
+   - anonymous access is intentional
+2. Authorization:
+   - server-side access checks exist where needed
+   - object ownership or tenant boundaries are enforced
+3. Input handling:
+   - request DTOs or input boundaries validate user input
+   - identifiers, enums, URLs, and uploaded data are constrained
+4. External interactions:
+   - secrets come from configuration, not code
+   - outbound calls are bounded and validated
+   - user-provided URLs or remote targets are handled safely
+5. Data exposure:
+   - only intended fields are returned
+   - stack traces, tokens, and internal details are not leaked
+6. Side effects:
+   - unsafe actions use the correct HTTP semantics
+   - validation happens before persistence or outbound calls
+7. Tests:
+   - negative tests exist for forbidden or invalid paths when relevant
+
+Prioritize findings:
+- auth or authz bypass
+- sensitive data leaks
+- unsafe input or external call handling
+- missing negative tests on protected behavior
+
+Response format:
+- findings first, ordered by severity
+- then open questions or assumptions
+- then a short hardening summary
+
+Tie every finding to concrete code paths and missing or incorrect enforcement.

.claude/commands/fall-guardian/verify-quality.md

@@ -1,8 +1,35 @@
-Run the narrowest relevant verification first, then broaden if needed.
-
-Typical checks:
-- `make check`
-- Flutter targeted tests
-- backend PHPStan
-- backend PHPUnit
-- platform-specific build or manual verification when native code changed
+Verify a Symfony/API Platform change using the repository's real quality gates.
+
+Verification scope: `$ARGUMENTS`
+
+Workflow:
+1. Read `Makefile`, `composer.json`, and `AGENTS.md`.
+2. Identify the canonical commands exposed by the repo.
+3. Prefer the project wrappers over raw vendor commands.
+4. Run the narrowest relevant tests first, then the broader required checks.
+5. Report failures with the command, impacted files, and minimal fix direction.
+
+Typical order:
+1. `make quality` (runs lint, analyse, rector together)
+2. `make tests-unit`
+3. `make tests-integration`
+4. `make tests`
+5. `make tests-api`
+6. `make security`
+
+For targeted runs only (skip if running `make quality`):
+- `make lint`
+- `make analyse`
+- `make rector`
+
+Output format:
+- `Commands run`
+- `Pass/fail summary`
+- `Remaining gaps`
+
+Rules:
+- If a command is unavailable, say so instead of inventing a substitute.
+- If Docker is required, use the project commands or wrappers already defined.
+- If a change affects endpoint behavior, do not stop at unit tests only.
+- When fixing PHPStan issues, prefer correcting the code, types, or annotations instead of changing `phpstan.neon`.
+- Treat edits to `phpstan.neon` as exceptional and ask first unless the user explicitly requested a PHPStan configuration change.