Docker-based infrastructure for local ERE development (ERE1-123)

.claude/skills/bdd/SKILL.md

@@ -0,0 +1,72 @@
+You are an expert in Gherkin (BDD), Behaviour-Driven Development, and pytest-bdd in Python.
+
+Your task: given a short description of a system behaviour (and optionally existing code APIs, domain objects, and test data), produce:
+1) A Gherkin .feature file (or additions to an existing feature) that is readable, stable, and business-meaningful.
+2) A pytest-bdd implementation in Python that is idiomatic pytest: fixture-driven, minimal shared mutable state, reusable steps, clear assertions, and deterministic isolation.
+
+STRICT BEST PRACTICES (must follow):
+
+A. Gherkin authoring
+- Use declarative, domain language, not UI/technical details.
+- Prefer Scenario Outlines with Examples tables for data-driven cases.
+- Keep scenarios independent: each scenario must fully set up its preconditions (use Background only for truly universal setup).
+- Avoid “And” chains that hide meaning; each step should add a distinct fact or action.
+- Keep step vocabulary consistent across the feature file: prefer a small set of reusable step phrases.
+- Use explicit identifiers and stable expected outcomes: avoid brittle time-based or order-based assertions unless the behaviour is order-sensitive.
+- Clearly separate: Given (preconditions), When (single action), Then (assertions).
+- Use tags (e.g. @integration, @slow) when helpful; keep them minimal and meaningful.
+- Include a short description comment at the top of the feature: what is under test, what API/function is exercised, and where test data lives.
+
+B. pytest-bdd implementation
+- Do NOT implement your own “ctx dict” unless absolutely necessary.
+- Prefer `target_fixture` to pass results between steps instead of shared state.
+- Use pytest fixtures for sessions/resources (HTTP client, DB session, service bootstrap). Choose fixture scope deliberately:
+  - session scope for expensive immutable setup
+  - function (scenario) scope for isolated state
+- Step functions should be thin: call domain code, return results, and avoid doing complex orchestration inside steps.
+- Assertions belong in Then steps. When steps should perform actions and produce results.
+- For expected exceptions:
+  - Prefer asserting in Then steps by executing the call inside `pytest.raises(...)` if feasible.
+  - If action must be in When and assertion later, store only minimal exception info in a fixture/state object; keep it typed and explicit.
+- Make step reuse safe:
+  - If a step can be repeated, ensure it is idempotent or its output is keyed (avoid relying on list positions).
+- Use parsing with `pytest_bdd.parsers` for structured parameters.
+- Use helper functions for loading test data, but avoid one fixture per file unless necessary; prefer a single loader fixture (e.g. `load_rdf(path)`).
+- Keep step names stable; do not generate many near-duplicate steps.
+
+C. Output format
+Return the following sections in order:
+
+1) FEATURE FILE
+- Provide a complete .feature file content.
+- Put it under a path suggestion like: tests/features/<name>.feature
+
+2) PYTHON TEST MODULE
+- Provide a complete pytest module under a path suggestion like: tests/bdd/test_<name>.py
+- Include `scenarios("...")` or explicit `@scenario` bindings.
+- Include step definitions using pytest fixtures and `target_fixture`.
+- Use type hints and dataclasses only if they reduce complexity; otherwise keep it minimal.
+
+3) CONFTST.PY RECOMMENDATIONS
+- Provide only the minimal conftest fixtures needed (e.g. service factory, data loader).
+- If the user already has conftest patterns, adapt to them rather than inventing a new framework.
+
+4) RUN COMMANDS
+- Provide best-practice commands for:
+  - local dev (pytest)
+  - selective runs (markers, -k)
+  - reproducible runs (tox)
+  - convenience wrapper (make) if relevant
+
+D. Behaviour fidelity
+- Do not invent APIs. If API details are missing, infer minimal interfaces and clearly mark them as assumptions.
+- Use deterministic test data. If input files exist, reference them by relative paths, and use a loader fixture.
+
+E. Style
+- Use British English in comments and explanatory text.
+- Keep code clean, readable, and ready to paste into a real repository.
+- Align to clean code principles: single responsibility, clear naming, minimal duplication, and modularity.
+- Align to clean architecture principles: separate domain logic from test orchestration, and keep test code focused on expressing behaviour rather than implementation details.
+
+If you are given an existing feature example, align the vocabulary and structure to it.
+If you are given existing fixtures (e.g. load_rdf), reuse them rather than creating duplicates.

.claude/skills/gitnexus/debugging/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: gitnexus-debugging
+description: Trace bugs through call chains using knowledge graph
+---
+
+# Debugging with GitNexus
+
+## When to Use
+- "Why is this function failing?"
+- "Trace where this error comes from"
+- "Who calls this method?"
+- "This endpoint returns 500"
+- Investigating bugs, errors, or unexpected behavior
+
+## Workflow
+
+```
+1. gitnexus_query({query: "<error or symptom>"})            → Find related execution flows
+2. gitnexus_context({name: "<suspect>"})                    → See callers/callees/processes
+3. READ gitnexus://repo/{name}/process/{name}                → Trace execution flow
+4. gitnexus_cypher({query: "MATCH path..."})                 → Custom traces if needed
+```
+
+> If "Index is stale" → run `npx gitnexus analyze` in terminal.
+
+## Checklist
+
+```
+- [ ] Understand the symptom (error message, unexpected behavior)
+- [ ] gitnexus_query for error text or related code
+- [ ] Identify the suspect function from returned processes
+- [ ] gitnexus_context to see callers and callees
+- [ ] Trace execution flow via process resource if applicable
+- [ ] gitnexus_cypher for custom call chain traces if needed
+- [ ] Read source files to confirm root cause
+```
+
+## Debugging Patterns
+
+| Symptom | GitNexus Approach |
+|---------|-------------------|
+| Error message | `gitnexus_query` for error text → `context` on throw sites |
+| Wrong return value | `context` on the function → trace callees for data flow |
+| Intermittent failure | `context` → look for external calls, async deps |
+| Performance issue | `context` → find symbols with many callers (hot paths) |
+| Recent regression | `detect_changes` to see what your changes affect |
+
+## Tools
+
+**gitnexus_query** — find code related to error:
+```
+gitnexus_query({query: "payment validation error"})
+→ Processes: CheckoutFlow, ErrorHandling
+→ Symbols: validatePayment, handlePaymentError, PaymentException
+```
+
+**gitnexus_context** — full context for a suspect:
+```
+gitnexus_context({name: "validatePayment"})
+→ Incoming calls: processCheckout, webhookHandler
+→ Outgoing calls: verifyCard, fetchRates (external API!)
+→ Processes: CheckoutFlow (step 3/7)
+```
+
+**gitnexus_cypher** — custom call chain traces:
+```cypher
+MATCH path = (a)-[:CodeRelation {type: 'CALLS'}*1..2]->(b:Function {name: "validatePayment"})
+RETURN [n IN nodes(path) | n.name] AS chain
+```
+
+## Example: "Payment endpoint returns 500 intermittently"
+
+```
+1. gitnexus_query({query: "payment error handling"})
+   → Processes: CheckoutFlow, ErrorHandling
+   → Symbols: validatePayment, handlePaymentError
+
+2. gitnexus_context({name: "validatePayment"})
+   → Outgoing calls: verifyCard, fetchRates (external API!)
+
+3. READ gitnexus://repo/my-app/process/CheckoutFlow
+   → Step 3: validatePayment → calls fetchRates (external)
+
+4. Root cause: fetchRates calls external API without proper timeout
+```

.claude/skills/gitnexus/exploring/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: gitnexus-exploring
+description: Navigate unfamiliar code using GitNexus knowledge graph
+---
+
+# Exploring Codebases with GitNexus
+
+## When to Use
+- "How does authentication work?"
+- "What's the project structure?"
+- "Show me the main components"
+- "Where is the database logic?"
+- Understanding code you haven't seen before
+
+## Workflow
+
+```
+1. READ gitnexus://repos                          → Discover indexed repos
+2. READ gitnexus://repo/{name}/context             → Codebase overview, check staleness
+3. gitnexus_query({query: "<what you want to understand>"})  → Find related execution flows
+4. gitnexus_context({name: "<symbol>"})            → Deep dive on specific symbol
+5. READ gitnexus://repo/{name}/process/{name}      → Trace full execution flow
+```
+
+> If step 2 says "Index is stale" → run `npx gitnexus analyze` in terminal.
+
+## Checklist
+
+```
+- [ ] READ gitnexus://repo/{name}/context
+- [ ] gitnexus_query for the concept you want to understand
+- [ ] Review returned processes (execution flows)
+- [ ] gitnexus_context on key symbols for callers/callees
+- [ ] READ process resource for full execution traces
+- [ ] Read source files for implementation details
+```
+
+## Resources
+
+| Resource | What you get |
+|----------|-------------|
+| `gitnexus://repo/{name}/context` | Stats, staleness warning (~150 tokens) |
+| `gitnexus://repo/{name}/clusters` | All functional areas with cohesion scores (~300 tokens) |
+| `gitnexus://repo/{name}/cluster/{name}` | Area members with file paths (~500 tokens) |
+| `gitnexus://repo/{name}/process/{name}` | Step-by-step execution trace (~200 tokens) |
+
+## Tools
+
+**gitnexus_query** — find execution flows related to a concept:
+```
+gitnexus_query({query: "payment processing"})
+→ Processes: CheckoutFlow, RefundFlow, WebhookHandler
+→ Symbols grouped by flow with file locations
+```
+
+**gitnexus_context** — 360-degree view of a symbol:
+```
+gitnexus_context({name: "validateUser"})
+→ Incoming calls: loginHandler, apiMiddleware
+→ Outgoing calls: checkToken, getUserById
+→ Processes: LoginFlow (step 2/5), TokenRefresh (step 1/3)
+```
+
+## Example: "How does payment processing work?"
+
+```
+1. READ gitnexus://repo/my-app/context       → 918 symbols, 45 processes
+2. gitnexus_query({query: "payment processing"})
+   → CheckoutFlow: processPayment → validateCard → chargeStripe
+   → RefundFlow: initiateRefund → calculateRefund → processRefund
+3. gitnexus_context({name: "processPayment"})
+   → Incoming: checkoutHandler, webhookHandler
+   → Outgoing: validateCard, chargeStripe, saveTransaction
+4. Read src/payments/processor.ts for implementation details
+```

.claude/skills/gitnexus/impact-analysis/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: gitnexus-impact-analysis
+description: Analyze blast radius before making code changes
+---
+
+# Impact Analysis with GitNexus
+
+## When to Use
+- "Is it safe to change this function?"
+- "What will break if I modify X?"
+- "Show me the blast radius"
+- "Who uses this code?"
+- Before making non-trivial code changes
+- Before committing — to understand what your changes affect
+
+## Workflow
+
+```
+1. gitnexus_impact({target: "X", direction: "upstream"})  → What depends on this
+2. READ gitnexus://repo/{name}/processes                   → Check affected execution flows
+3. gitnexus_detect_changes()                               → Map current git changes to affected flows
+4. Assess risk and report to user
+```
+
+> If "Index is stale" → run `npx gitnexus analyze` in terminal.
+
+## Checklist
+
+```
+- [ ] gitnexus_impact({target, direction: "upstream"}) to find dependents
+- [ ] Review d=1 items first (these WILL BREAK)
+- [ ] Check high-confidence (>0.8) dependencies
+- [ ] READ processes to check affected execution flows
+- [ ] gitnexus_detect_changes() for pre-commit check
+- [ ] Assess risk level and report to user
+```
+
+## Understanding Output
+
+| Depth | Risk Level | Meaning |
+|-------|-----------|---------|
+| d=1 | **WILL BREAK** | Direct callers/importers |
+| d=2 | LIKELY AFFECTED | Indirect dependencies |
+| d=3 | MAY NEED TESTING | Transitive effects |
+
+## Risk Assessment
+
+| Affected | Risk |
+|----------|------|
+| <5 symbols, few processes | LOW |
+| 5-15 symbols, 2-5 processes | MEDIUM |
+| >15 symbols or many processes | HIGH |
+| Critical path (auth, payments) | CRITICAL |
+
+## Tools
+
+**gitnexus_impact** — the primary tool for symbol blast radius:
+```
+gitnexus_impact({
+  target: "validateUser",
+  direction: "upstream",
+  minConfidence: 0.8,
+  maxDepth: 3
+})
+
+→ d=1 (WILL BREAK):
+  - loginHandler (src/auth/login.ts:42) [CALLS, 100%]
+  - apiMiddleware (src/api/middleware.ts:15) [CALLS, 100%]
+
+→ d=2 (LIKELY AFFECTED):
+  - authRouter (src/routes/auth.ts:22) [CALLS, 95%]
+```
+
+**gitnexus_detect_changes** — git-diff based impact analysis:
+```
+gitnexus_detect_changes({scope: "staged"})
+
+→ Changed: 5 symbols in 3 files
+→ Affected: LoginFlow, TokenRefresh, APIMiddlewarePipeline
+→ Risk: MEDIUM
+```
+
+## Example: "What breaks if I change validateUser?"
+
+```
+1. gitnexus_impact({target: "validateUser", direction: "upstream"})
+   → d=1: loginHandler, apiMiddleware (WILL BREAK)
+   → d=2: authRouter, sessionManager (LIKELY AFFECTED)
+
+2. READ gitnexus://repo/my-app/processes
+   → LoginFlow and TokenRefresh touch validateUser
+
+3. Risk: 2 direct callers, 2 processes = MEDIUM
+```