diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 524bab5..f597884 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -30,5 +30,17 @@ What actually happened. ## Logs / Screenshots Paste logs or screenshots that help explain the issue. +## Acceptance Criteria +- [ ] Root cause identified. +- [ ] Fix validated in local or CI environment. +- [ ] No regression introduced for related paths. + +## Validation Steps +List exact commands or manual steps used to verify the fix. +```bash +# example: +# dotnet test ... +``` + ## Additional Context Any additional information that may help. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index 7e3dfad..82a7fd0 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -15,5 +15,17 @@ Describe the change or feature you would like to see. ## Alternatives Considered Any alternative solutions or workarounds you have considered. +## Acceptance Criteria +- [ ] Clear, testable success criteria are defined. +- [ ] Backward compatibility impact is assessed. +- [ ] Documentation impact is assessed. + +## Validation Steps +List the tests/checks that prove the feature works as intended. +```bash +# example: +# npm run build +``` + ## Additional Context Add any additional context, mockups, or screenshots here. diff --git a/.github/ISSUE_TEMPLATE/task.md b/.github/ISSUE_TEMPLATE/task.md new file mode 100644 index 0000000..9782af8 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/task.md @@ -0,0 +1,29 @@ +--- +name: Task +about: Track scoped implementation work +title: "[Task] " +labels: todo +assignees: "" +--- + +## Summary +Describe the task in one or two sentences. + +## Scope +- In scope: +- Out of scope: + +## Acceptance Criteria +- [ ] Criteria 1 +- [ ] Criteria 2 +- [ ] Criteria 3 + +## Validation Steps +List exact checks for completion. +```bash +# example: +# dotnet build ... +``` + +## Dependencies / Related Issues +Link dependencies and related tickets (e.g. `Epic: #`). diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index d1ab05d..6183c48 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -6,6 +6,18 @@ For v2.3 release-track PRs, you can use: ## Summary Describe the changes and their purpose. +## Linked Issue +Closes # + +## Validation +- Commands/tests run: +```bash +# paste exact validation commands and key outcomes +``` + +## Rollback Notes +Describe rollback plan or why rollback is low risk. + ## Testing - [ ] Tests added/updated - [ ] Tests run locally @@ -13,8 +25,6 @@ Describe the changes and their purpose. ## Checklist - [ ] Code style and formatting checked - [ ] Documentation updated (if applicable) +- [ ] Security impact reviewed (auth/secrets/supply-chain) - [ ] No secrets or credentials committed - [ ] Breaking changes documented - -## Related Issues -Link to issues or discussions. diff --git a/CHANGELOG.md b/CHANGELOG.md index 8bc37cc..9684a17 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -24,6 +24,7 @@ Semantic Versioning. - Verification scripts now support API key headers and optional agent build flags. - Optional HTTP listener when mTLS is enabled to keep dashboard/AI traffic on port 8080. - v2.3 release notes (`docs/Release-Notes-v2.3.md`) and PR acceptance template (`docs/PR-Template-v2.3-Acceptance.md`). +- Course-process docs pack: issue templates (bug/feature/task), expanded PR template, and v2.3 Mermaid class diagrams. ### Changed - Agent now injects W3C trace headers for HTTP requests. diff --git a/README.md b/README.md index ace45f1..b6f3032 100644 --- a/README.md +++ b/README.md @@ -194,6 +194,7 @@ Open the dashboard at http://localhost:3000. - Observability (OpenTelemetry): docs/Observability.md - v2.3 architecture roadmap: docs/ARCHITECTURE-v2.3.md - v2.3 delivery roadmap: docs/ROADMAP-v2.3.md +- v2.3 class diagrams (Mermaid): docs/diagrams/Class-Diagram-v2.3.md - v2.3 Milestone 1 smoke test: docs/QA-SmokeTest-v2.3-M1.md - v2.3 M2 data provenance: docs/Data-Provenance-v2.3-M2.md - v2.3 M2 data acquisition scripts: scripts/data_acquisition/README.md diff --git a/docs/diagrams/Class-Diagram-v2.3.md b/docs/diagrams/Class-Diagram-v2.3.md new file mode 100644 index 0000000..7c16bff --- /dev/null +++ b/docs/diagrams/Class-Diagram-v2.3.md @@ -0,0 +1,222 @@ +# v2.3 Class Diagrams (Mermaid) + +This document provides UML-style class diagrams for the four major service domains: + +- Core (.NET) +- Agent (C++) +- AI Engine (Python/FastAPI) +- Web Dashboard (Next.js) + +## Cross-Service Overview + +```mermaid +classDiagram + class AgentService { + +register() + +heartbeat() + +checkpoint() + +restore() + } + + class CoreApi { + +ingestTelemetry() + +queueCommand() + +runMigrationCycle() + +getDashboardLatest() + } + + class AiEngine { + +analyze() + +enrichSignals() + +enrichSignalsBatch() + } + + class WebDashboard { + +fetchFleetStatus() + +fetchRiskHistory() + +renderExplainability() + } + + class PostgreSQL + class RabbitMQ + class SnapshotStorage + + AgentService --> CoreApi : telemetry/heartbeat + CoreApi --> AiEngine : risk + enrichment calls + CoreApi --> PostgreSQL : persistence + CoreApi --> RabbitMQ : async ingestion + CoreApi --> SnapshotStorage : snapshot artifacts + WebDashboard --> CoreApi : dashboard APIs +``` + +## Core (.NET) + +```mermaid +classDiagram + class DashboardController { + +GetLatest() + +GetHistory() + } + + class ControlPlaneService { + +QueueCommandAsync() + +GetLatestAsync() + +GetHistoryAsync() + } + + class TelemetryIngestionService { + +IngestAsync() + } + + class MigrationOrchestrator { + +RunMigrationCycle() + } + + class DynamicRiskPolicy { + +Evaluate() + +ComputeAlpha() + } + + class AnalysisService { + +AnalyzeAsync() + } + + class CommandService { + +QueueCommand() + } + + class TelemetryStore { + +Update() + +GetLatest() + } + + class ApplicationDbContext + class TelemetryPayload + class AnalysisResult + + DashboardController --> ControlPlaneService + ControlPlaneService --> TelemetryStore + ControlPlaneService --> CommandService + ControlPlaneService --> DynamicRiskPolicy + ControlPlaneService --> ApplicationDbContext + TelemetryIngestionService --> AnalysisService + TelemetryIngestionService --> TelemetryStore + MigrationOrchestrator --> DynamicRiskPolicy + MigrationOrchestrator --> AnalysisService + MigrationOrchestrator --> CommandService + TelemetryStore --> TelemetryPayload + TelemetryStore --> AnalysisResult +``` + +## Agent (C++) + +```mermaid +classDiagram + class NetworkClient { + +Register() + +Heartbeat() + +PollCommands() + +SendFeedback() + } + + class CommandPoller { + +Poll() + } + + class CommandDispatcher { + +Dispatch() + } + + class InferenceEngine { + +Initialize() + +Evaluate() + } + + class ArchiveManager { + +CreateSnapshotArchive() + +RestoreFromSnapshot() + } + + class CriuManager { + +Checkpoint() + +Restore() + } + + class LifecycleManager { + +Start() + +Stop() + } + + class SemanticFeatures + + LifecycleManager --> NetworkClient + LifecycleManager --> CommandPoller + CommandPoller --> CommandDispatcher + CommandDispatcher --> ArchiveManager + CommandDispatcher --> InferenceEngine + ArchiveManager --> CriuManager + InferenceEngine --> SemanticFeatures +``` + +## AI Engine (Python / FastAPI) + +```mermaid +classDiagram + class FastAPIApp { + +POST /analyze + +POST /signals/enrich + +POST /signals/enrich/batch + } + + class RiskModel { + +analyzeTelemetry() + } + + class SignalEnrichmentModel { + +enrichSignal() + +enrichBatch() + } + + class FinBertAdapter { + +predictSentiment() + } + + class Summarizer { + +summarize() + } + + FastAPIApp --> RiskModel + FastAPIApp --> SignalEnrichmentModel + SignalEnrichmentModel --> FinBertAdapter + SignalEnrichmentModel --> Summarizer +``` + +## Web Dashboard (Next.js) + +```mermaid +classDiagram + class DashboardClient { + +load() + +handleSimulateChaos() + } + + class ApiLib { + +fetchFleetStatus() + +fetchRiskHistory() + +fetchAuditLogs() + } + + class ExplainabilityPanel { + +render(alpha, P_preempt, topSignals) + } + + class ExternalSignalsPanel + class ControlPanel + class HistoryChart + + DashboardClient --> ApiLib + DashboardClient --> ExplainabilityPanel + DashboardClient --> ExternalSignalsPanel + DashboardClient --> ControlPanel + DashboardClient --> HistoryChart +```