save progress

src/AdvisoryAI/StellaOps.AdvisoryAI.Worker/AGENTS.md

@@ -0,0 +1,59 @@
+# AdvisoryAI Worker Agent Charter
+
+## Mission
+- Execute queued advisory tasks asynchronously as a background service.
+- Process advisory plans, orchestrate pipeline execution, and record metrics.
+
+## Responsibilities
+- Maintain `AdvisoryTaskWorker` background service for queue consumption.
+- Coordinate plan creation/caching and pipeline execution.
+- Track metrics for plan creation, execution latency, and cache hit rates.
+- Handle graceful shutdown and task cancellation.
+
+## Required Reading
+- docs/README.md
+- docs/07_HIGH_LEVEL_ARCHITECTURE.md
+- docs/modules/platform/architecture-overview.md
+- docs/modules/advisory-ai/architecture.md
+- docs/modules/advisory-ai/orchestration-pipeline.md
+- src/AdvisoryAI/AGENTS.md (parent module charter)
+- docs/policy/assistant-parameters.md (guardrail and ops knobs)
+
+## Working Directory & Scope
+- Primary: src/AdvisoryAI/StellaOps.AdvisoryAI.Worker/
+- Dependencies: StellaOps.AdvisoryAI, StellaOps.AdvisoryAI.Hosting
+- Coordinates with: WebService (queues tasks), core orchestrator (executes plans)
+
+## Key Components
+- `Program.cs` — Host builder setup with AdvisoryAI core and hosted service registration.
+- `Services/AdvisoryTaskWorker.cs` — BackgroundService that:
+  - Dequeues tasks from `IAdvisoryTaskQueue`
+  - Checks `IAdvisoryPlanCache` for existing plans
+  - Creates new plans via `IAdvisoryPipelineOrchestrator`
+  - Executes plans via `IAdvisoryPipelineExecutor`
+  - Records metrics via `AdvisoryPipelineMetrics`
+  - Uses injected `TimeProvider` for deterministic timing
+
+## Processing Flow
+1. Dequeue message from `IAdvisoryTaskQueue`
+2. Check plan cache by `PlanCacheKey` (unless `ForceRefresh`)
+3. If cache miss, create plan via orchestrator and cache it
+4. Execute plan via executor
+5. Record metrics and log completion
+6. Loop until cancellation
+
+## Testing Expectations
+- Unit tests in `__Tests/StellaOps.AdvisoryAI.Tests` cover worker logic.
+- Test with mocked queue, cache, orchestrator, and executor.
+- Verify cancellation handling and graceful shutdown.
+- Test cache hit/miss scenarios and ForceRefresh behavior.
+- Use FakeTimeProvider for deterministic timing tests.
+
+## Working Agreement
+- Determinism: use injected TimeProvider, stable plan caching keys, ordered execution.
+- Offline-friendly: worker must handle unavailable inference gracefully.
+- Observability: structured logs with activity tracing, expose pipeline metrics.
+- Configuration: bind from appsettings.json and environment variables (ADVISORYAI__ prefix).
+- Queue/cache: respect bounded capacities and TTLs configured via options.
+- Update sprint status in docs/implplan/SPRINT_*.md when starting/completing work.
+- Mirror decisions in sprint Decisions & Risks section.