save progress

src/AdvisoryAI/StellaOps.AdvisoryAI.WebService/AGENTS.md

@@ -0,0 +1,64 @@
+# AdvisoryAI WebService Agent Charter
+
+## Mission
+- Expose HTTP API endpoints for Advisory AI interactions.
+- Handle request validation, rate limiting, and response formatting.
+- Coordinate with consent, justification, and orchestration services.
+
+## Responsibilities
+- Maintain API endpoint definitions in Program.cs (minimal APIs).
+- Keep request/response contracts stable and documented.
+- Enforce rate limiting, consent checks, and proper error handling.
+- Wire hosting extensions and router integration.
+
+## Required Reading
+- docs/README.md
+- docs/07_HIGH_LEVEL_ARCHITECTURE.md
+- docs/modules/platform/architecture-overview.md
+- docs/modules/advisory-ai/architecture.md
+- src/AdvisoryAI/AGENTS.md (parent module charter)
+- docs/policy/assistant-parameters.md (guardrail and ops knobs)
+- docs/modules/advisory-ai/deployment.md (service configuration)
+
+## Working Directory & Scope
+- Primary: src/AdvisoryAI/StellaOps.AdvisoryAI.WebService/
+- Dependencies: StellaOps.AdvisoryAI, StellaOps.AdvisoryAI.Hosting
+- Shared libraries: Router.AspNet for Stella Router integration
+
+## Key Components
+- `Program.cs` — WebApplication setup, endpoint mapping, middleware pipeline.
+- `Contracts/` — Request/response DTOs for API endpoints:
+  - `AdvisoryPlanRequest/Response` — plan generation
+  - `AdvisoryExecuteRequest` — execution trigger
+  - `AdvisoryQueueRequest/Response` — queue management
+  - `ExplainRequest/Response` — explanation endpoints
+  - `ConsentContracts` — AI consent management (VEX-AI-016)
+  - `JustifyContracts` — justification generation
+  - `PolicyStudioContracts` — policy studio integration
+  - `RemediationContracts` — remediation plan endpoints
+- `Services/` — Service implementations:
+  - `IAiConsentStore` / `InMemoryAiConsentStore` — consent tracking
+  - `IAiJustificationGenerator` / `DefaultAiJustificationGenerator` — justification generation
+
+## API Endpoints
+- POST /api/advisory/plan — Generate advisory plan
+- POST /api/advisory/execute — Execute advisory plan
+- POST /api/advisory/queue — Queue advisory task
+- GET /api/advisory/output/{id} — Retrieve advisory output
+- POST /api/advisory/explain — Generate explanation
+- Consent and justification endpoints per VEX-AI-016
+
+## Testing Expectations
+- Unit tests in `__Tests/StellaOps.AdvisoryAI.Tests` cover endpoint logic.
+- Integration tests use WebApplicationFactory for full pipeline testing.
+- Test rate limiting behavior, consent enforcement, and error responses.
+- Verify request validation and contract serialization.
+
+## Working Agreement
+- Determinism: stable response ordering, content-addressed output IDs.
+- Offline-friendly: endpoints must degrade gracefully when inference is unavailable.
+- Observability: structured logs with request correlation ids; expose rate limiter metrics.
+- Configuration: bind from appsettings.json and environment variables (ADVISORYAI__ prefix).
+- Security: validate all input, enforce consent where required, no embedding secrets.
+- Update sprint status in docs/implplan/SPRINT_*.md when starting/completing work.
+- Mirror decisions in sprint Decisions & Risks section.