KArtSell.Aegis/docs/COMMON_WORKFLOWS.md

# Common Workflows

**Reference:** For quick commands, see CLAUDE.md "Quick Start" section.  
**Governance:** All work follows AGENTS.md v16.0 and VIBE Coding Guardrails.

## Adding a New Vertical Slice

1. **Scaffold the structure:**
   ```bash
   python tools/scaffold_vertical_slice.py --name MyFeature --module ModelOperations
   ```

2. **Define the contract** (before code):
   - Request/Response DTOs in `Contracts/`
   - Event schema in `Contracts/Events/` if async coupling needed
   - Validation rules (vee-validate schema on FE, Fluent on BE)

3. **Implement backend slice:**
   - `Handler.cs`: Orchestration, transaction handling
   - `Policy.cs`: Pure business logic
   - `Sql.cs`: Dapper queries (schema-qualified, no SELECT *)
   - `Endpoint.cs`: HTTP routing & status codes
   - `README.md`: Traceability link to requirement/ADR

4. **Write tests:**
   - Unit: Policy, Mapper logic
   - Integration: Handler + Dapper + real DB
   - Verify Outbox events are created if async

5. **Implement frontend feature:**
   - Feature module under `features/<feature>/`
   - Use `features/<feature>/pages/` for route-level components
   - Use `shared/ui/adapter/` for any UI component usage
   - Form validation with vee-validate + Zod schema from BE contract

6. **Validation gates (pre-merge):**
   - Architecture tests pass
   - DB migration is idempotent (fresh/upgrade test)
   - No SELECT *, no direct cross-module queries
   - Outbox/Inbox tests if async
   - Frontend typecheck + test + build
   - E2E smoke test (if user-facing)

## Refactoring (Characterized, Isolated, Verified)

1. **Characterize:** Lock current behavior with tests + perf baseline + Golden data.
2. **Isolate:** Separate I/O (Dapper queries, HTTP) from logic (Policy).
3. **Transform:** One small change at a time (rename, extract, move).
4. **Verify:** All tests pass, no perf regression, backtest algorithm changes against Golden.
5. **Simplify:** Delete dead abstractions, feature flags, branches.
6. **Observe:** Post-release SLO/DQ/model drift monitoring.
7. **Close Debt:** Update Debt ID, leave ADR for future maintainers.

## Creating a Background Job

1. **Define the command:**
   ```csharp
   public class MyJobCommand : ICommand
   {
       public Guid IdempotencyKey { get; set; }
       public Guid CorrelationId { get; set; }
       public string InputData { get; set; }
   }
   ```

2. **Implement the handler:**
   - Idempotent: Re-run should be safe and produce same result.
   - Classify failures: transient/permanent/dq/business-hold.
   - Emit events to Outbox for async notifications.

3. **Schedule via Hangfire:**
   ```csharp
   await backgroundJobClient.EnqueueAsync<MyJobHandler>(h => h.Handle(command));
   ```

4. **Test retry & replay scenarios:**
   - Job runs successfully.
   - Job fails and is retried (verify idempotency).
   - Job is replayed from cold state (verify determinism).

## Testing Strategy

### xUnit Backend Tests

```bash
dotnet test KArtSell.sln -c Release
dotnet test --filter "Category=Integration" -c Release
dotnet test --filter "FullyQualifiedName~UnitTests" -c Release --verbosity quiet
```

**Test Levels:**
1. **Unit:** Pure functions (Policy, Mapper), no I/O. Fast, deterministic.
2. **Integration:** Handler + Dapper + real PostgreSQL. Validates transaction boundaries, Outbox/Inbox.
3. **Data:** SQL query validation, schema conformance, index effectiveness.
4. **E2E:** Full HTTP stack; used sparingly for critical paths.
5. **Golden/Frozen OOS:** Before merging algorithm changes, lock baseline and diff against new run.

### Vitest Frontend Tests

```bash
cd frontend
pnpm test                           # Run all tests
pnpm test -- --reporter=verbose     # Verbose output
pnpm test -- <test-file-pattern>    # Run subset
pnpm test -- --coverage             # Coverage report
```

### Playwright E2E

```bash
cd frontend
pnpm e2e                            # Run all E2E tests headless
pnpm e2e -- --debug                 # Debug mode (browser stays open)
pnpm exec playwright test --headed  # Run with browser UI
```

## Tools & Scripts

### Scaffolding
```bash
python tools/scaffold_vertical_slice.py --name MyFeature --module ModelOperations
python tools/scaffold_ui_screen.py --name MyScreen --feature MyFeature
```

### Validation
```bash
python tools/validate_v16.py          # Full v16 validation (contracts, migrations, Python tests)
python -m unittest discover           # Run all Python unit tests
```