Sync with TemplateDotNetTool template PRs (#58, #65, #66, #67, #70, #75)

.cspell.yaml

@@ -16,11 +16,14 @@ language: en
 words:
   - Anson
   - Blockquotes
+  - build_notes
   - buildmark
   - BuildMark
-  - buildnotes
   - camelcase
   - Checkmarx
+  - code_quality
+  - code_review_plan
+  - code_review_report
   - CodeQL
   - copilot
   - cspell
@@ -62,6 +65,8 @@ words:
   - reindex
   - reqstream
   - ReqStream
+  - requirements_doc
+  - requirements_report
   - reviewmark
   - ReviewMark
   - Sarif
@@ -77,7 +82,7 @@ words:
   - spdx
   - streetsidesoftware
   - testname
-  - tracematrix
+  - trace_matrix
   - triaging
   - Trivy
   - trx

.github/agents/software-developer.agent.md

@@ -5,79 +5,249 @@ tools: [read, search, edit, execute, github, agent]
 user-invocable: true
 ---
 
-# Software Developer - Template DotNet Tool
+# Software Developer Agent
 
-Develop production code and self-validation tests with emphasis on testability and clarity.
+Develop production code with emphasis on testability, clarity, and compliance integration.
+
+## Reporting
+
+If detailed documentation of development work is needed, create a report using the filename pattern
+`AGENT_REPORT_development.md` to document code changes, design decisions, and implementation details.
 
 ## When to Invoke This Agent
 
-Invoke the software-developer for:
+Use the Software Developer Agent for:
+
+- Implementing production code features and APIs
+- Refactoring existing code for testability and maintainability
+- Creating self-validation and demonstration code
+- Implementing requirement-driven functionality
+- Code architecture and design decisions
+- Integration with Continuous Compliance tooling
 
-- Implementing production code features
-- Creating and maintaining self-validation tests (`TemplateTool_*`)
-- Code refactoring for testability and maintainability
-- Implementing command-line argument parsing and program logic
+## Primary Responsibilities
 
-## Responsibilities
+### Literate Programming Style (MANDATORY)
 
-### Code Style - Literate Programming
+Write all code in **literate style** for maximum clarity and maintainability.
 
-Write code in a **literate style**:
+#### Literate Style Rules
 
-- Every paragraph of code starts with a comment explaining what it's trying to do
-- Blank lines separate logical paragraphs
-- Comments describe intent, not mechanics
-- Code should read like a well-structured document
-- Reading just the literate comments should explain how the code works
-- The code can be reviewed against the literate comments to check the implementation
+- **Intent Comments:** - Every paragraph starts with a comment explaining intent (not mechanics)
+- **Logical Separation:** - Blank lines separate logical code paragraphs
+- **Purpose Over Process:** - Comments describe why, code shows how
+- **Standalone Clarity:** - Reading comments alone should explain the algorithm/approach
+- **Verification Support:** - Code can be verified against the literate comments for correctness
 
-Example:
+#### Examples
+
+**C# Example:**
 
 ```csharp
-// Parse the command line arguments
-var options = ParseArguments(args);
+// Validate input parameters to prevent downstream errors
+if (string.IsNullOrEmpty(input))
+{
+    throw new ArgumentException("Input cannot be null or empty", nameof(input));
+}
+
+// Transform input data using the configured processing pipeline
+var processedData = ProcessingPipeline.Transform(input);
 
-// Validate the input file exists
-if (!File.Exists(options.InputFile))
-    throw new InvalidOperationException($"Input file not found: {options.InputFile}");
+// Apply business rules and validation logic
+var validatedResults = BusinessRuleEngine.ValidateAndProcess(processedData);
 
-// Process the file contents
-var results = ProcessFile(options.InputFile);
+// Return formatted results matching the expected output contract
+return OutputFormatter.Format(validatedResults);
 ```
 
-### Design for Testability
+**C++ Example:**
+
+```cpp
+// Acquire exclusive hardware access using RAII pattern
+std::lock_guard<std::mutex> hardwareLock(m_hardwareMutex);
+
+// Validate sensor data integrity before processing
+if (!sensorData.IsValid() || sensorData.GetTimestamp() < m_lastValidTimestamp)
+{
+    throw std::invalid_argument("Sensor data failed integrity validation");
+}
+
+// Apply hardware-specific calibration coefficients
+auto calibratedReading = ApplyCalibration(sensorData.GetRawValue(), 
+                                        m_calibrationCoefficients);
+
+// Filter noise using moving average with bounds checking
+const auto filteredValue = m_noiseFilter.ApplyFilter(calibratedReading);
+if (filteredValue < kMinOperationalThreshold || filteredValue > kMaxOperationalThreshold)
+{
+    LogWarning("Filtered sensor value outside operational range");
+}
+
+// Package result with quality metadata for downstream consumers  
+return SensorResult{filteredValue, CalculateQualityMetric(sensorData), 
+                   std::chrono::steady_clock::now()};
+```
+
+### Design for Testability & Compliance
+
+#### Code Architecture Principles
+
+- **Single Responsibility**: Functions with focused, testable purposes
+- **Dependency Injection**: External dependencies injected for testing
+- **Pure Functions**: Minimize side effects and hidden state
+- **Clear Interfaces**: Well-defined API contracts
+- **Separation of Concerns**: Business logic separate from infrastructure
+
+#### Compliance-Ready Code Structure
+
+- **Documentation Standards**: Language-specific documentation required on ALL members for compliance
+- **Error Handling**: Comprehensive error cases with appropriate logging
+- **Configuration**: Externalize settings for different compliance environments
+- **Traceability**: Code comments linking back to requirements where applicable
+
+### Quality Gate Verification
+
+Before completing any code changes, verify:
+
+#### 1. Code Quality Standards
 
-- Small, focused functions with single responsibilities
-- Dependency injection for external dependencies
-- Avoid hidden state and side effects
-- Clear separation of concerns
+- [ ] Zero compiler warnings (`TreatWarningsAsErrors=true`)
+- [ ] Follows `.editorconfig` and `.clang-format` formatting rules
+- [ ] All code follows literate programming style
+- [ ] Language-specific documentation complete on all members (XML for C#, Doxygen for C++)
+- [ ] Passes static analysis (SonarQube, CodeQL, language analyzers)
 
-### Template DotNet Tool-Specific Rules
+#### 2. Testability & Design
 
-- **XML Docs**: On ALL members (public/internal/private) with spaces after `///`
-  - Follow standard XML indentation rules with four-space indentation
-- **Errors**: `ArgumentException` for parsing, `InvalidOperationException` for runtime issues
-- **Namespace**: File-scoped namespaces only
-- **Using Statements**: Top of file only
-- **String Formatting**: Use interpolated strings ($"") for clarity
+- [ ] Functions have single, clear responsibilities
+- [ ] External dependencies are injectable/mockable
+- [ ] Code is structured for unit testing
+- [ ] Error handling covers expected failure scenarios
+- [ ] Configuration externalized from business logic
 
-### Self-Validation Tests
+#### 3. Compliance Integration
+
+- [ ] Code supports requirements traceability
+- [ ] Logging/telemetry appropriate for audit trails
+- [ ] Security considerations addressed (input validation, authorization)
+- [ ] Platform compatibility maintained for multi-platform requirements
+
+## Tool Integration Requirements
+
+### Required Development Tools
+
+- **Language Formatters**: Applied via `.editorconfig`, `.clang-format`
+- **Static Analyzers**: Microsoft.CodeAnalysis.NetAnalyzers, SonarAnalyzer.CSharp
+- **Security Scanning**: CodeQL integration for vulnerability detection
+- **Documentation**: XML docs generation for API documentation
+
+### Code Quality Tools Integration
+
+- **SonarQube/SonarCloud**: Continuous code quality monitoring
+- **Build Integration**: Warnings as errors enforcement
+- **IDE Integration**: Real-time feedback on code quality issues
+- **CI/CD Integration**: Automated quality gate enforcement
+
+## Cross-Agent Coordination
+
+### Hand-off to Other Agents
+
+- If comprehensive tests need to be created for implemented functionality, then call the @test-developer agent with the
+  **request** to create comprehensive tests for implemented functionality with **context** of new code changes and
+  **goal** of achieving adequate test coverage.
+- If quality gates and linting requirements need verification, then call the @code-quality agent with the **request**
+  to verify all quality gates and linting requirements with **context** of completed implementation and **goal** of
+  compliance verification.
+- If documentation needs updating to reflect code changes, then call the @technical-writer agent with the **request**
+  to update documentation reflecting code changes with **context** of specific implementation changes and
+  **additional instructions** for maintaining documentation currency.
+- If implementation validation against requirements is needed, then call the @requirements agent with the **request**
+  to validate implementation satisfies requirements with **context** of completed functionality and **goal** of
+  requirements compliance verification.
+
+## Implementation Standards by Language
+
+### C# Development
+
+#### C# Documentation Standards
+
+- **XML Documentation**: Required on ALL members (public/internal/private) with spaces after `///`
+- **Standard XML Tags**: Use `<summary>`, `<param>`, `<returns>`, `<exception>`
+- **Compliance**: XML docs support automated compliance documentation generation
+
+**Example:**
+
+```csharp
+/// <summary>
+/// Processes user input data according to business rules
+/// </summary>
+/// <param name="userData">User input data to process</param>
+/// <returns>Processed result with validation status</returns>
+/// <exception cref="ArgumentException">Thrown when input is invalid</exception>
+public ProcessingResult ProcessUserData(UserData userData)
+{
+    // Validate input parameters meet business rule constraints
+    if (!InputValidator.IsValid(userData))
+    {
+        throw new ArgumentException("User data does not meet validation requirements");
+    }
+
+    // Apply business transformation logic
+    var transformedData = BusinessEngine.Transform(userData);
+
+    // Return structured result with success indicators
+    return new ProcessingResult(transformedData, ProcessingStatus.Success);
+}
+```
+
+### C++ Development
+
+#### C++ Documentation Standards
+
+- **Doxygen Documentation**: Required on ALL members (public/protected/private)
+- **Standard Doxygen Tags**: Use `@brief`, `@param`, `@return`, `@throws`
+- **Compliance**: Doxygen comments support automated API documentation and compliance reports
+
+**Example:**
+
+```cpp
+/// @brief Processes sensor data and validates against specifications
+/// @param sensorReading Raw sensor data from hardware interface
+/// @return Processed measurement with validation status
+/// @throws std::invalid_argument if sensor reading is out of range
+ProcessedMeasurement ProcessSensorData(const SensorReading& sensorReading)
+{
+    // Validate sensor reading falls within expected operational range
+    if (!IsValidSensorReading(sensorReading))
+    {
+        throw std::invalid_argument("Sensor reading outside valid operational range");
+    }
+
+    // Apply calibration and filtering algorithms
+    auto calibratedValue = CalibrationEngine::Apply(sensorReading);
+
+    // Return measurement with quality indicators
+    return ProcessedMeasurement{calibratedValue, MeasurementQuality::Valid};
+}
+```
 
-- Naming: `TemplateTool_FeatureBeingValidated`
-- These tests ship with the product and run via `--validate` flag
-- Must support TRX/JUnit output format
-- Link to requirements in `requirements.yaml`
+## Compliance Verification Checklist
 
-## Defer To
+### Before Completing Implementation
 
-- **Requirements Agent**: For new requirement creation and test strategy
-- **Test Developer Agent**: For unit and integration tests
-- **Technical Writer Agent**: For documentation updates
-- **Code Quality Agent**: For linting, formatting, and static analysis
+1. **Code Quality**: Zero warnings, passes all static analysis
+2. **Documentation**: Comprehensive XML documentation (C#) or Doxygen comments (C++) on ALL members
+3. **Testability**: Code structured for comprehensive testing
+4. **Security**: Input validation, error handling, authorization checks
+5. **Traceability**: Implementation traceable to requirements
+6. **Standards**: Follows all coding standards and formatting rules
 
-## Don't
+## Don't Do These Things
 
-- Write code without explanatory comments
-- Create large monolithic functions
-- Skip XML documentation
-- Ignore the literate programming style
+- Skip literate programming comments (mandatory for all code)
+- Disable compiler warnings to make builds pass
+- Create untestable code with hidden dependencies
+- Skip XML documentation (C#) or Doxygen comments (C++) on any members
+- Implement functionality without requirement traceability
+- Ignore static analysis or security scanning results
+- Write monolithic functions with multiple responsibilities