# Issue #166: Stitcher Module Structure

## Objective

Create the mosaic-stitcher module - the workflow orchestration layer that wraps OpenClaw.

## Prerequisites

- #165 (BullMQ module) complete - BullMqService available
- #164 (Database schema) complete - RunnerJob, JobStep, JobEvent models available

## Responsibilities

- Receive webhooks from @mosaic bot
- Apply Guard Rails (capability permissions)
- Apply Quality Rails (mandatory gates)
- Track all job steps and events
- Dispatch work to OpenClaw with constraints

## Approach

1. Examine existing module patterns (tasks, events, brain)
2. RED: Write failing tests for StitcherService and StitcherController
3. GREEN: Implement minimal code to pass tests
4. REFACTOR: Clean up and improve code quality
5. Verify quality gates pass

## Progress

- [x] Create scratchpad
- [x] Examine existing module patterns
- [x] Create directory structure
- [x] RED: Write StitcherService tests
- [x] RED: Write StitcherController tests
- [x] GREEN: Implement StitcherService
- [x] GREEN: Implement StitcherController
- [x] Create DTOs and interfaces
- [x] Create StitcherModule
- [x] Register in AppModule
- [x] REFACTOR: Improve code quality
- [x] Run quality gates (typecheck, lint, build, test)
- [x] Commit changes

## Quality Gates Results

- **Typecheck**: PASS
- **Lint**: PASS
- **Build**: PASS
- **Tests**: PASS (12 tests passing)

## Patterns Observed

- BullMqService is @Global() and provides queue management
- Controllers use @UseGuards(AuthGuard, WorkspaceGuard, PermissionGuard)
- DTOs use class-validator decorators
- Services inject PrismaService for database operations
- Modules follow: imports, controllers, providers, exports structure
- Tests use Jest with describe/it blocks

## Testing

- Unit tests for StitcherService
- Unit tests for StitcherController
- Integration test for webhook endpoint

## Implementation Details

### Files Created

1. `apps/api/src/stitcher/stitcher.module.ts` - Module definition
2. `apps/api/src/stitcher/stitcher.service.ts` - Core orchestration service
3. `apps/api/src/stitcher/stitcher.controller.ts` - Webhook and dispatch endpoints
4. `apps/api/src/stitcher/dto/webhook.dto.ts` - Request/response DTOs
5. `apps/api/src/stitcher/dto/index.ts` - DTO barrel export
6. `apps/api/src/stitcher/interfaces/job-dispatch.interface.ts` - Job dispatch interfaces
7. `apps/api/src/stitcher/interfaces/index.ts` - Interface barrel export
8. `apps/api/src/stitcher/index.ts` - Module barrel export
9. `apps/api/src/stitcher/stitcher.service.spec.ts` - Service unit tests
10. `apps/api/src/stitcher/stitcher.controller.spec.ts` - Controller unit tests

### Key Features Implemented

- **Webhook endpoint**: POST /stitcher/webhook - Receives webhooks from @mosaic bot
- **Job dispatch**: POST /stitcher/dispatch - Manual job dispatch
- **Guard Rails**: applyGuardRails() - Capability permission checks
- **Quality Rails**: applyQualityRails() - Mandatory gate determination
- **Event tracking**: trackJobEvent() - Audit log for all job events

### TDD Process

1. **RED**: Created failing tests for service and controller
2. **GREEN**: Implemented minimal code to pass tests
3. **REFACTOR**: Fixed TypeScript strict mode issues with exactOptionalPropertyTypes

### Integration

- Registered StitcherModule in AppModule
- Imports PrismaModule and BullMqModule
- Exports StitcherService for use in other modules

## Notes