@heyai-rules/pilo-masterkit 1.2.2 → 2.1.0

package/.agent/skills/healthcare-eval-harness/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: healthcare-eval-harness
+description: Patient safety evaluation harness for healthcare application deployments. Automated test suites for CDSS accuracy, PHI exposure, clinical workflow integrity, and integration compliance. Blocks deployments on safety failures.
+origin: Health1 Super Speciality Hospitals — contributed by Dr. Keyur Patel
+version: "1.0.0"
+---
+
+# Healthcare Eval Harness — Patient Safety Verification
+
+Automated verification system for healthcare application deployments. A single CRITICAL failure blocks deployment. Patient safety is non-negotiable.
+
+> **Note:** Examples use Jest as the reference test runner. Adapt commands for your framework (Vitest, pytest, PHPUnit, etc.) — the test categories and pass thresholds are framework-agnostic.
+
+## When to Use
+
+- Before any deployment of EMR/EHR applications
+- After modifying CDSS logic (drug interactions, dose validation, scoring)
+- After changing database schemas that touch patient data
+- After modifying authentication or access control
+- During CI/CD pipeline configuration for healthcare apps
+- After resolving merge conflicts in clinical modules
+
+## How It Works
+
+The eval harness runs five test categories in order. The first three (CDSS Accuracy, PHI Exposure, Data Integrity) are CRITICAL gates requiring 100% pass rate — a single failure blocks deployment. The remaining two (Clinical Workflow, Integration) are HIGH gates requiring 95%+ pass rate.
+
+Each category maps to a Jest test path pattern. The CI pipeline runs CRITICAL gates with `--bail` (stop on first failure) and enforces coverage thresholds with `--coverage --coverageThreshold`.
+
+### Eval Categories
+
+**1. CDSS Accuracy (CRITICAL — 100% required)**
+
+Tests all clinical decision support logic: drug interaction pairs (both directions), dose validation rules, clinical scoring vs published specs, no false negatives, no silent failures.
+
+```bash
+npx jest --testPathPattern='tests/cdss' --bail --ci --coverage
+```
+
+**2. PHI Exposure (CRITICAL — 100% required)**
+
+Tests for protected health information leaks: API error responses, console output, URL parameters, browser storage, cross-facility isolation, unauthenticated access, service role key absence.
+
+```bash
+npx jest --testPathPattern='tests/security/phi' --bail --ci
+```
+
+**3. Data Integrity (CRITICAL — 100% required)**
+
+Tests clinical data safety: locked encounters, audit trail entries, cascade delete protection, concurrent edit handling, no orphaned records.
+
+```bash
+npx jest --testPathPattern='tests/data-integrity' --bail --ci
+```
+
+**4. Clinical Workflow (HIGH — 95%+ required)**
+
+Tests end-to-end flows: encounter lifecycle, template rendering, medication sets, drug/diagnosis search, prescription PDF, red flag alerts.
+
+```bash
+tmp_json=$(mktemp)
+npx jest --testPathPattern='tests/clinical' --ci --json --outputFile="$tmp_json" || true
+total=$(jq '.numTotalTests // 0' "$tmp_json")
+passed=$(jq '.numPassedTests // 0' "$tmp_json")
+if [ "$total" -eq 0 ]; then
+  echo "No clinical tests found" >&2
+  exit 1
+fi
+rate=$(echo "scale=2; $passed * 100 / $total" | bc)
+echo "Clinical pass rate: ${rate}% ($passed/$total)"
+```
+
+**5. Integration Compliance (HIGH — 95%+ required)**
+
+Tests external systems: HL7 message parsing (v2.x), FHIR validation, lab result mapping, malformed message handling.
+
+```bash
+tmp_json=$(mktemp)
+npx jest --testPathPattern='tests/integration' --ci --json --outputFile="$tmp_json" || true
+total=$(jq '.numTotalTests // 0' "$tmp_json")
+passed=$(jq '.numPassedTests // 0' "$tmp_json")
+if [ "$total" -eq 0 ]; then
+  echo "No integration tests found" >&2
+  exit 1
+fi
+rate=$(echo "scale=2; $passed * 100 / $total" | bc)
+echo "Integration pass rate: ${rate}% ($passed/$total)"
+```
+
+### Pass/Fail Matrix
+
+| Category | Threshold | On Failure |
+|----------|-----------|------------|
+| CDSS Accuracy | 100% | **BLOCK deployment** |
+| PHI Exposure | 100% | **BLOCK deployment** |
+| Data Integrity | 100% | **BLOCK deployment** |
+| Clinical Workflow | 95%+ | WARN, allow with review |
+| Integration | 95%+ | WARN, allow with review |
+
+### CI/CD Integration
+
+```yaml
+name: Healthcare Safety Gate
+on: [push, pull_request]
+
+jobs:
+  safety-gate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm ci
+
+      # CRITICAL gates — 100% required, bail on first failure
+      - name: CDSS Accuracy
+        run: npx jest --testPathPattern='tests/cdss' --bail --ci --coverage --coverageThreshold='{"global":{"branches":80,"functions":80,"lines":80}}'
+
+      - name: PHI Exposure Check
+        run: npx jest --testPathPattern='tests/security/phi' --bail --ci
+
+      - name: Data Integrity
+        run: npx jest --testPathPattern='tests/data-integrity' --bail --ci
+
+      # HIGH gates — 95%+ required, custom threshold check
+      # HIGH gates — 95%+ required
+      - name: Clinical Workflows
+        run: |
+          TMP_JSON=$(mktemp)
+          npx jest --testPathPattern='tests/clinical' --ci --json --outputFile="$TMP_JSON" || true
+          TOTAL=$(jq '.numTotalTests // 0' "$TMP_JSON")
+          PASSED=$(jq '.numPassedTests // 0' "$TMP_JSON")
+          if [ "$TOTAL" -eq 0 ]; then
+            echo "::error::No clinical tests found"; exit 1
+          fi
+          RATE=$(echo "scale=2; $PASSED * 100 / $TOTAL" | bc)
+          echo "Pass rate: ${RATE}% ($PASSED/$TOTAL)"
+          if (( $(echo "$RATE < 95" | bc -l) )); then
+            echo "::warning::Clinical pass rate ${RATE}% below 95%"
+          fi
+
+      - name: Integration Compliance
+        run: |
+          TMP_JSON=$(mktemp)
+          npx jest --testPathPattern='tests/integration' --ci --json --outputFile="$TMP_JSON" || true
+          TOTAL=$(jq '.numTotalTests // 0' "$TMP_JSON")
+          PASSED=$(jq '.numPassedTests // 0' "$TMP_JSON")
+          if [ "$TOTAL" -eq 0 ]; then
+            echo "::error::No integration tests found"; exit 1
+          fi
+          RATE=$(echo "scale=2; $PASSED * 100 / $TOTAL" | bc)
+          echo "Pass rate: ${RATE}% ($PASSED/$TOTAL)"
+          if (( $(echo "$RATE < 95" | bc -l) )); then
+            echo "::warning::Integration pass rate ${RATE}% below 95%"
+          fi
+```
+
+### Anti-Patterns
+
+- Skipping CDSS tests "because they passed last time"
+- Setting CRITICAL thresholds below 100%
+- Using `--no-bail` on CRITICAL test suites
+- Mocking the CDSS engine in integration tests (must test real logic)
+- Allowing deployments when safety gate is red
+- Running tests without `--coverage` on CDSS suites
+
+## Examples
+
+### Example 1: Run All Critical Gates Locally
+
+```bash
+npx jest --testPathPattern='tests/cdss' --bail --ci --coverage && \
+npx jest --testPathPattern='tests/security/phi' --bail --ci && \
+npx jest --testPathPattern='tests/data-integrity' --bail --ci
+```
+
+### Example 2: Check HIGH Gate Pass Rate
+
+```bash
+tmp_json=$(mktemp)
+npx jest --testPathPattern='tests/clinical' --ci --json --outputFile="$tmp_json" || true
+jq '{
+  passed: (.numPassedTests // 0),
+  total: (.numTotalTests // 0),
+  rate: (if (.numTotalTests // 0) == 0 then 0 else ((.numPassedTests // 0) / (.numTotalTests // 1) * 100) end)
+}' "$tmp_json"
+# Expected: { "passed": 21, "total": 22, "rate": 95.45 }
+```
+
+### Example 3: Eval Report
+
+```
+## Healthcare Eval: 2026-03-27 [commit abc1234]
+
+### Patient Safety: PASS
+
+| Category | Tests | Pass | Fail | Status |
+|----------|-------|------|------|--------|
+| CDSS Accuracy | 39 | 39 | 0 | PASS |
+| PHI Exposure | 8 | 8 | 0 | PASS |
+| Data Integrity | 12 | 12 | 0 | PASS |
+| Clinical Workflow | 22 | 21 | 1 | 95.5% PASS |
+| Integration | 6 | 6 | 0 | PASS |
+
+### Coverage: 84% (target: 80%+)
+### Verdict: SAFE TO DEPLOY
+```

package/.agent/skills/healthcare-phi-compliance/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: healthcare-phi-compliance
+description: Protected Health Information (PHI) and Personally Identifiable Information (PII) compliance patterns for healthcare applications. Covers data classification, access control, audit trails, encryption, and common leak vectors.
+origin: Health1 Super Speciality Hospitals — contributed by Dr. Keyur Patel
+version: "1.0.0"
+---
+
+# Healthcare PHI/PII Compliance Patterns
+
+Patterns for protecting patient data, clinician data, and financial data in healthcare applications. Applicable to HIPAA (US), DISHA (India), GDPR (EU), and general healthcare data protection.
+
+## When to Use
+
+- Building any feature that touches patient records
+- Implementing access control or authentication for clinical systems
+- Designing database schemas for healthcare data
+- Building APIs that return patient or clinician data
+- Implementing audit trails or logging
+- Reviewing code for data exposure vulnerabilities
+- Setting up Row-Level Security (RLS) for multi-tenant healthcare systems
+
+## How It Works
+
+Healthcare data protection operates on three layers: **classification** (what is sensitive), **access control** (who can see it), and **audit** (who did see it).
+
+### Data Classification
+
+**PHI (Protected Health Information)** — any data that can identify a patient AND relates to their health: patient name, date of birth, address, phone, email, national ID numbers (SSN, Aadhaar, NHS number), medical record numbers, diagnoses, medications, lab results, imaging, insurance policy and claim details, appointment and admission records, or any combination of the above.
+
+**PII (Non-patient-sensitive data)** in healthcare systems: clinician/staff personal details, doctor fee structures and payout amounts, employee salary and bank details, vendor payment information.
+
+### Access Control: Row-Level Security
+
+```sql
+ALTER TABLE patients ENABLE ROW LEVEL SECURITY;
+
+-- Scope access by facility
+CREATE POLICY "staff_read_own_facility"
+  ON patients FOR SELECT TO authenticated
+  USING (facility_id IN (
+    SELECT facility_id FROM staff_assignments
+    WHERE user_id = auth.uid() AND role IN ('doctor','nurse','lab_tech','admin')
+  ));
+
+-- Audit log: insert-only (tamper-proof)
+CREATE POLICY "audit_insert_only" ON audit_log FOR INSERT
+  TO authenticated WITH CHECK (user_id = auth.uid());
+CREATE POLICY "audit_no_modify" ON audit_log FOR UPDATE USING (false);
+CREATE POLICY "audit_no_delete" ON audit_log FOR DELETE USING (false);
+```
+
+### Audit Trail
+
+Every PHI access or modification must be logged:
+
+```typescript
+interface AuditEntry {
+  timestamp: string;
+  user_id: string;
+  patient_id: string;
+  action: 'create' | 'read' | 'update' | 'delete' | 'print' | 'export';
+  resource_type: string;
+  resource_id: string;
+  changes?: { before: object; after: object };
+  ip_address: string;
+  session_id: string;
+}
+```
+
+### Common Leak Vectors
+
+**Error messages:** Never include patient-identifying data in error messages thrown to the client. Log details server-side only.
+
+**Console output:** Never log full patient objects. Use opaque internal record IDs (UUIDs) — not medical record numbers, national IDs, or names.
+
+**URL parameters:** Never put patient-identifying data in query strings or path segments that could appear in logs or browser history. Use opaque UUIDs only.
+
+**Browser storage:** Never store PHI in localStorage or sessionStorage. Keep PHI in memory only, fetch on demand.
+
+**Service role keys:** Never use the service_role key in client-side code. Always use the anon/publishable key and let RLS enforce access.
+
+**Logs and monitoring:** Never log full patient records. Use opaque record IDs only (not medical record numbers). Sanitize stack traces before sending to error tracking services.
+
+### Database Schema Tagging
+
+Mark PHI/PII columns at the schema level:
+
+```sql
+COMMENT ON COLUMN patients.name IS 'PHI: patient_name';
+COMMENT ON COLUMN patients.dob IS 'PHI: date_of_birth';
+COMMENT ON COLUMN patients.aadhaar IS 'PHI: national_id';
+COMMENT ON COLUMN doctor_payouts.amount IS 'PII: financial';
+```
+
+### Deployment Checklist
+
+Before every deployment:
+- No PHI in error messages or stack traces
+- No PHI in console.log/console.error
+- No PHI in URL parameters
+- No PHI in browser storage
+- No service_role key in client code
+- RLS enabled on all PHI/PII tables
+- Audit trail for all data modifications
+- Session timeout configured
+- API authentication on all PHI endpoints
+- Cross-facility data isolation verified
+
+## Examples
+
+### Example 1: Safe vs Unsafe Error Handling
+
+```typescript
+// BAD — leaks PHI in error
+throw new Error(`Patient ${patient.name} not found in ${patient.facility}`);
+
+// GOOD — generic error, details logged server-side with opaque IDs only
+logger.error('Patient lookup failed', { recordId: patient.id, facilityId });
+throw new Error('Record not found');
+```
+
+### Example 2: RLS Policy for Multi-Facility Isolation
+
+```sql
+-- Doctor at Facility A cannot see Facility B patients
+CREATE POLICY "facility_isolation"
+  ON patients FOR SELECT TO authenticated
+  USING (facility_id IN (
+    SELECT facility_id FROM staff_assignments WHERE user_id = auth.uid()
+  ));
+
+-- Test: login as doctor-facility-a, query facility-b patients
+-- Expected: 0 rows returned
+```
+
+### Example 3: Safe Logging
+
+```typescript
+// BAD — logs identifiable patient data
+console.log('Processing patient:', patient);
+
+// GOOD — logs only opaque internal record ID
+console.log('Processing record:', patient.id);
+// Note: even patient.id should be an opaque UUID, not a medical record number
+```

package/.agent/skills/hexagonal-architecture/SKILL.md

@@ -0,0 +1,276 @@
+---
+name: hexagonal-architecture
+description: Design, implement, and refactor Ports & Adapters systems with clear domain boundaries, dependency inversion, and testable use-case orchestration across TypeScript, Java, Kotlin, and Go services.
+origin: ECC
+---
+
+# Hexagonal Architecture
+
+Hexagonal architecture (Ports and Adapters) keeps business logic independent from frameworks, transport, and persistence details. The core app depends on abstract ports, and adapters implement those ports at the edges.
+
+## When to Use
+
+- Building new features where long-term maintainability and testability matter.
+- Refactoring layered or framework-heavy code where domain logic is mixed with I/O concerns.
+- Supporting multiple interfaces for the same use case (HTTP, CLI, queue workers, cron jobs).
+- Replacing infrastructure (database, external APIs, message bus) without rewriting business rules.
+
+Use this skill when the request involves boundaries, domain-centric design, refactoring tightly coupled services, or decoupling application logic from specific libraries.
+
+## Core Concepts
+
+- **Domain model**: Business rules and entities/value objects. No framework imports.
+- **Use cases (application layer)**: Orchestrate domain behavior and workflow steps.
+- **Inbound ports**: Contracts describing what the application can do (commands/queries/use-case interfaces).
+- **Outbound ports**: Contracts for dependencies the application needs (repositories, gateways, event publishers, clock, UUID, etc.).
+- **Adapters**: Infrastructure and delivery implementations of ports (HTTP controllers, DB repositories, queue consumers, SDK wrappers).
+- **Composition root**: Single wiring location where concrete adapters are bound to use cases.
+
+Outbound port interfaces usually live in the application layer (or in domain only when the abstraction is truly domain-level), while infrastructure adapters implement them.
+
+Dependency direction is always inward:
+
+- Adapters -> application/domain
+- Application -> port interfaces (inbound/outbound contracts)
+- Domain -> domain-only abstractions (no framework or infrastructure dependencies)
+- Domain -> nothing external
+
+## How It Works
+
+### Step 1: Model a use case boundary
+
+Define a single use case with a clear input and output DTO. Keep transport details (Express `req`, GraphQL `context`, job payload wrappers) outside this boundary.
+
+### Step 2: Define outbound ports first
+
+Identify every side effect as a port:
+
+- persistence (`UserRepositoryPort`)
+- external calls (`BillingGatewayPort`)
+- cross-cutting (`LoggerPort`, `ClockPort`)
+
+Ports should model capabilities, not technologies.
+
+### Step 3: Implement the use case with pure orchestration
+
+Use case class/function receives ports via constructor/arguments. It validates application-level invariants, coordinates domain rules, and returns plain data structures.
+
+### Step 4: Build adapters at the edge
+
+- Inbound adapter converts protocol input to use-case input.
+- Outbound adapter maps app contracts to concrete APIs/ORM/query builders.
+- Mapping stays in adapters, not inside use cases.
+
+### Step 5: Wire everything in a composition root
+
+Instantiate adapters, then inject them into use cases. Keep this wiring centralized to avoid hidden service-locator behavior.
+
+### Step 6: Test per boundary
+
+- Unit test use cases with fake ports.
+- Integration test adapters with real infra dependencies.
+- E2E test user-facing flows through inbound adapters.
+
+## Architecture Diagram
+
+```mermaid
+flowchart LR
+  Client["Client (HTTP/CLI/Worker)"] --> InboundAdapter["Inbound Adapter"]
+  InboundAdapter -->|"calls"| UseCase["UseCase (Application Layer)"]
+  UseCase -->|"uses"| OutboundPort["OutboundPort (Interface)"]
+  OutboundAdapter["Outbound Adapter"] -->|"implements"| OutboundPort
+  OutboundAdapter --> ExternalSystem["DB/API/Queue"]
+  UseCase --> DomainModel["DomainModel"]
+```
+
+## Suggested Module Layout
+
+Use feature-first organization with explicit boundaries:
+
+```text
+src/
+  features/
+    orders/
+      domain/
+        Order.ts
+        OrderPolicy.ts
+      application/
+        ports/
+          inbound/
+            CreateOrder.ts
+          outbound/
+            OrderRepositoryPort.ts
+            PaymentGatewayPort.ts
+        use-cases/
+          CreateOrderUseCase.ts
+      adapters/
+        inbound/
+          http/
+            createOrderRoute.ts
+        outbound/
+          postgres/
+            PostgresOrderRepository.ts
+          stripe/
+            StripePaymentGateway.ts
+      composition/
+        ordersContainer.ts
+```
+
+## TypeScript Example
+
+### Port definitions
+
+```typescript
+export interface OrderRepositoryPort {
+  save(order: Order): Promise<void>;
+  findById(orderId: string): Promise<Order | null>;
+}
+
+export interface PaymentGatewayPort {
+  authorize(input: { orderId: string; amountCents: number }): Promise<{ authorizationId: string }>;
+}
+```
+
+### Use case
+
+```typescript
+type CreateOrderInput = {
+  orderId: string;
+  amountCents: number;
+};
+
+type CreateOrderOutput = {
+  orderId: string;
+  authorizationId: string;
+};
+
+export class CreateOrderUseCase {
+  constructor(
+    private readonly orderRepository: OrderRepositoryPort,
+    private readonly paymentGateway: PaymentGatewayPort
+  ) {}
+
+  async execute(input: CreateOrderInput): Promise<CreateOrderOutput> {
+    const order = Order.create({ id: input.orderId, amountCents: input.amountCents });
+
+    const auth = await this.paymentGateway.authorize({
+      orderId: order.id,
+      amountCents: order.amountCents,
+    });
+
+    // markAuthorized returns a new Order instance; it does not mutate in place.
+    const authorizedOrder = order.markAuthorized(auth.authorizationId);
+    await this.orderRepository.save(authorizedOrder);
+
+    return {
+      orderId: order.id,
+      authorizationId: auth.authorizationId,
+    };
+  }
+}
+```
+
+### Outbound adapter
+
+```typescript
+export class PostgresOrderRepository implements OrderRepositoryPort {
+  constructor(private readonly db: SqlClient) {}
+
+  async save(order: Order): Promise<void> {
+    await this.db.query(
+      "insert into orders (id, amount_cents, status, authorization_id) values ($1, $2, $3, $4)",
+      [order.id, order.amountCents, order.status, order.authorizationId]
+    );
+  }
+
+  async findById(orderId: string): Promise<Order | null> {
+    const row = await this.db.oneOrNone("select * from orders where id = $1", [orderId]);
+    return row ? Order.rehydrate(row) : null;
+  }
+}
+```
+
+### Composition root
+
+```typescript
+export const buildCreateOrderUseCase = (deps: { db: SqlClient; stripe: StripeClient }) => {
+  const orderRepository = new PostgresOrderRepository(deps.db);
+  const paymentGateway = new StripePaymentGateway(deps.stripe);
+
+  return new CreateOrderUseCase(orderRepository, paymentGateway);
+};
+```
+
+## Multi-Language Mapping
+
+Use the same boundary rules across ecosystems; only syntax and wiring style change.
+
+- **TypeScript/JavaScript**
+  - Ports: `application/ports/*` as interfaces/types.
+  - Use cases: classes/functions with constructor/argument injection.
+  - Adapters: `adapters/inbound/*`, `adapters/outbound/*`.
+  - Composition: explicit factory/container module (no hidden globals).
+- **Java**
+  - Packages: `domain`, `application.port.in`, `application.port.out`, `application.usecase`, `adapter.in`, `adapter.out`.
+  - Ports: interfaces in `application.port.*`.
+  - Use cases: plain classes (Spring `@Service` is optional, not required).
+  - Composition: Spring config or manual wiring class; keep wiring out of domain/use-case classes.
+- **Kotlin**
+  - Modules/packages mirror the Java split (`domain`, `application.port`, `application.usecase`, `adapter`).
+  - Ports: Kotlin interfaces.
+  - Use cases: classes with constructor injection (Koin/Dagger/Spring/manual).
+  - Composition: module definitions or dedicated composition functions; avoid service locator patterns.
+- **Go**
+  - Packages: `internal/<feature>/domain`, `application`, `ports`, `adapters/inbound`, `adapters/outbound`.
+  - Ports: small interfaces owned by the consuming application package.
+  - Use cases: structs with interface fields plus explicit `New...` constructors.
+  - Composition: wire in `cmd/<app>/main.go` (or dedicated wiring package), keep constructors explicit.
+
+## Anti-Patterns to Avoid
+
+- Domain entities importing ORM models, web framework types, or SDK clients.
+- Use cases reading directly from `req`, `res`, or queue metadata.
+- Returning database rows directly from use cases without domain/application mapping.
+- Letting adapters call each other directly instead of flowing through use-case ports.
+- Spreading dependency wiring across many files with hidden global singletons.
+
+## Migration Playbook
+
+1. Pick one vertical slice (single endpoint/job) with frequent change pain.
+2. Extract a use-case boundary with explicit input/output types.
+3. Introduce outbound ports around existing infrastructure calls.
+4. Move orchestration logic from controllers/services into the use case.
+5. Keep old adapters, but make them delegate to the new use case.
+6. Add tests around the new boundary (unit + adapter integration).
+7. Repeat slice-by-slice; avoid full rewrites.
+
+### Refactoring Existing Systems
+
+- **Strangler approach**: keep current endpoints, route one use case at a time through new ports/adapters.
+- **No big-bang rewrites**: migrate per feature slice and preserve behavior with characterization tests.
+- **Facade first**: wrap legacy services behind outbound ports before replacing internals.
+- **Composition freeze**: centralize wiring early so new dependencies do not leak into domain/use-case layers.
+- **Slice selection rule**: prioritize high-churn, low-blast-radius flows first.
+- **Rollback path**: keep a reversible toggle or route switch per migrated slice until production behavior is verified.
+
+## Testing Guidance (Same Hexagonal Boundaries)
+
+- **Domain tests**: test entities/value objects as pure business rules (no mocks, no framework setup).
+- **Use-case unit tests**: test orchestration with fakes/stubs for outbound ports; assert business outcomes and port interactions.
+- **Outbound adapter contract tests**: define shared contract suites at port level and run them against each adapter implementation.
+- **Inbound adapter tests**: verify protocol mapping (HTTP/CLI/queue payload to use-case input and output/error mapping back to protocol).
+- **Adapter integration tests**: run against real infrastructure (DB/API/queue) for serialization, schema/query behavior, retries, and timeouts.
+- **End-to-end tests**: cover critical user journeys through inbound adapter -> use case -> outbound adapter.
+- **Refactor safety**: add characterization tests before extraction; keep them until new boundary behavior is stable and equivalent.
+
+## Best Practices Checklist
+
+- Domain and use-case layers import only internal types and ports.
+- Every external dependency is represented by an outbound port.
+- Validation occurs at boundaries (inbound adapter + use-case invariants).
+- Use immutable transformations (return new values/entities instead of mutating shared state).
+- Errors are translated across boundaries (infra errors -> application/domain errors).
+- Composition root is explicit and easy to audit.
+- Use cases are testable with simple in-memory fakes for ports.
+- Refactoring starts from one vertical slice with behavior-preserving tests.
+- Language/framework specifics stay in adapters, never in domain rules.