From caf770d19aadd6c8fc23099f1aeb8a2635a1444f Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Mon, 6 Apr 2026 15:49:20 -0400 Subject: [PATCH 01/12] Avoid adding testing infrastructure to design documentation. --- .github/standards/design-documentation.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/standards/design-documentation.md b/.github/standards/design-documentation.md index e14cd30..27b214f 100644 --- a/.github/standards/design-documentation.md +++ b/.github/standards/design-documentation.md @@ -46,7 +46,9 @@ or compliance drivers. ### Scope Section Define what software items are covered and what is explicitly excluded. -Specify version boundaries and applicability constraints. +Design documentation must NOT include test projects, test classes, or test +infrastructure because design documentation documents the architecture of +shipping product code, not ancillary content used to validate it. ### Software Structure Section (MANDATORY) From 1019c6873e2516e81f3dbc3b3bcd03e38bef196d Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Mon, 6 Apr 2026 22:43:24 -0400 Subject: [PATCH 02/12] Improvements around testing dependencies --- .github/agents/quality.agent.md | 2 ++ .github/standards/csharp-testing.md | 14 +++++++++++++- 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/.github/agents/quality.agent.md b/.github/agents/quality.agent.md index 18fc7c6..6aaa41f 100644 --- a/.github/agents/quality.agent.md +++ b/.github/agents/quality.agent.md @@ -81,6 +81,8 @@ This ensures orchestrators properly halt workflows when quality gates fail. - Were tests created/updated for all functional changes? (PASS|FAIL|N/A) - {Evidence} - Is test coverage maintained for all requirements? (PASS|FAIL|N/A) - {Evidence} - Are testing standards followed (AAA pattern, etc.)? (PASS|FAIL|N/A) - {Evidence} +- Do tests respect software item hierarchy boundaries (System/Subsystem/Unit scope)? (PASS|FAIL|N/A) - {Evidence} +- Are cross-hierarchy test dependencies documented in design docs? (PASS|FAIL|N/A) - {Evidence} - Does test categorization align with code structure? (PASS|FAIL|N/A) - {Evidence} - Do all tests pass without failures? (PASS|FAIL|N/A) - {Evidence} diff --git a/.github/standards/csharp-testing.md b/.github/standards/csharp-testing.md index f96a3c3..d343f34 100644 --- a/.github/standards/csharp-testing.md +++ b/.github/standards/csharp-testing.md @@ -26,7 +26,7 @@ public void ServiceName_MethodName_Scenario_ExpectedBehavior() Use descriptive test names because test names appear in requirements traceability matrices and compliance reports. - **System tests**: `{SystemName}_{Functionality}_{Scenario}_{ExpectedBehavior}` -- **Subsystem tests**: `{SubsystemName}_{Functionality}_{Scenario}_{ExpectedBehavior}` +- **Subsystem tests**: `{SubsystemName}_{Functionality}_{Scenario}_{ExpectedBehavior}` - **Unit tests**: `{ClassName}_{MethodUnderTest}_{Scenario}_{ExpectedBehavior}` - **Descriptive Scenarios**: Clearly describe the input condition being tested - **Expected Behavior**: State the expected outcome or exception @@ -46,6 +46,16 @@ Link tests to requirements because every requirement must have passing test evid - **TRX Format**: Generate test results in TRX format for ReqStream compatibility - **Coverage Completeness**: Test both success paths and error conditions +# Test Dependency Boundaries (MANDATORY) + +Respect software item hierarchy boundaries to ensure review-sets can validate proper architectural scope. + +- **System Tests**: May use functionality from any subsystem or unit within the system +- **Subsystem Tests**: May only use units within the subsystem + documented dependencies in design docs +- **Unit Tests**: May only test the unit + documented dependencies in design docs + +Undocumented cross-hierarchy dependencies indicate either missing design documentation or architectural violations. + # Mock Dependencies Mock external dependencies using NSubstitute (preferred) because tests must run in isolation to generate @@ -113,6 +123,8 @@ Before submitting C# tests, verify: - [ ] Each test verifies single, specific behavior (no shared state) - [ ] Both success and failure scenarios covered including edge cases - [ ] External dependencies mocked with NSubstitute or equivalent +- [ ] Tests respect software item hierarchy boundaries (System/Subsystem/Unit scope) +- [ ] Cross-hierarchy test dependencies documented in design documentation - [ ] Tests linked to requirements with source filters where needed - [ ] Test results generate TRX format for ReqStream compatibility - [ ] MSTest V4 anti-patterns avoided (proper assertions, public visibility, etc.) From c125b5fb529410b64da302f3c00672a5c0336f0d Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Thu, 9 Apr 2026 16:46:52 -0400 Subject: [PATCH 03/12] Improve linting --- lint.bat | 22 +++++++++++++++++++++- lint.sh | 22 +++++++++++++++++++++- 2 files changed, 42 insertions(+), 2 deletions(-) diff --git a/lint.bat b/lint.bat index 433421b..ad777b8 100644 --- a/lint.bat +++ b/lint.bat @@ -38,6 +38,7 @@ REM === NPM SECTION === :npm_section REM Install npm dependencies +set "PUPPETEER_SKIP_DOWNLOAD=true" call npm install --silent if errorlevel 1 goto skip_npm @@ -57,8 +58,27 @@ REM === DOTNET SECTION === :dotnet_section +REM Restore dotnet tools +dotnet tool restore > nul +if errorlevel 1 goto skip_dotnet_tools + +REM Run reqstream lint +dotnet reqstream --lint --requirements requirements.yaml +if errorlevel 1 set "LINT_ERROR=1" + +REM Run versionmark lint +dotnet versionmark --lint +if errorlevel 1 set "LINT_ERROR=1" + +REM Run reviewmark lint +dotnet reviewmark --lint +if errorlevel 1 set "LINT_ERROR=1" + +:skip_dotnet_tools + REM Run dotnet format -dotnet format --verify-no-changes +dotnet restore > nul +dotnet format --verify-no-changes --no-restore if errorlevel 1 set "LINT_ERROR=1" REM Report result diff --git a/lint.sh b/lint.sh index 13ac584..a6b96c3 100755 --- a/lint.sh +++ b/lint.sh @@ -35,6 +35,7 @@ fi # === NPM SECTION === # Install npm dependencies +export PUPPETEER_SKIP_DOWNLOAD=true npm install --silent || { lint_error=1; skip_npm=1; } # Run cspell @@ -49,8 +50,27 @@ fi # === DOTNET SECTION === +# Restore dotnet tools +dotnet tool restore > /dev/null || { lint_error=1; skip_dotnet_tools=1; } + +# Run reqstream lint +if [ "$skip_dotnet_tools" != "1" ]; then + dotnet reqstream --lint --requirements requirements.yaml || lint_error=1 +fi + +# Run versionmark lint +if [ "$skip_dotnet_tools" != "1" ]; then + dotnet versionmark --lint || lint_error=1 +fi + +# Run reviewmark lint +if [ "$skip_dotnet_tools" != "1" ]; then + dotnet reviewmark --lint || lint_error=1 +fi + # Run dotnet format -dotnet format --verify-no-changes || lint_error=1 +dotnet restore > /dev/null +dotnet format --verify-no-changes --no-restore || lint_error=1 # Report result exit $lint_error From 77cfaa2a8a378d5516c008e8b565e677c0fde5d8 Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Thu, 9 Apr 2026 17:06:55 -0400 Subject: [PATCH 04/12] Updating agent files and introduce common coding and testing principles. --- .github/agents/quality.agent.md | 14 ++-- .github/standards/coding-principles.md | 70 +++++++++++++++++ .github/standards/csharp-language.md | 82 ++++++-------------- .github/standards/csharp-testing.md | 38 ++++----- .github/standards/design-documentation.md | 13 ++++ .github/standards/reqstream-usage.md | 20 ++++- .github/standards/reviewmark-usage.md | 11 +++ .github/standards/software-items.md | 10 ++- .github/standards/technical-documentation.md | 13 ++++ .github/standards/testing-principles.md | 40 ++++++++++ AGENTS.md | 6 +- 11 files changed, 218 insertions(+), 99 deletions(-) create mode 100644 .github/standards/coding-principles.md create mode 100644 .github/standards/testing-principles.md diff --git a/.github/agents/quality.agent.md b/.github/agents/quality.agent.md index 6aaa41f..8376693 100644 --- a/.github/agents/quality.agent.md +++ b/.github/agents/quality.agent.md @@ -26,13 +26,6 @@ This assessment is a quality control system of the project and MUST be performed Upon completion create a summary in `.agent-logs/{agent-name}-{subject}-{unique-id}.md` of the project consisting of: -The **Result** field MUST reflect the quality validation outcome for orchestrator decision-making: - -- **Result: SUCCEEDED** - Only when Overall Grade is PASS (all compliance requirements met) -- **Result: FAILED** - When Overall Grade is FAIL or NEEDS_WORK (compliance failures present) - -This ensures orchestrators properly halt workflows when quality gates fail. - ```markdown # Quality Assessment Report @@ -134,4 +127,11 @@ This ensures orchestrators properly halt workflows when quality gates fail. - **Quality Gates**: {Status of automated quality checks with tool outputs} ``` +The **Result** field MUST reflect the quality validation outcome for orchestrator decision-making: + +- **Result: SUCCEEDED** - Only when Overall Grade is PASS (all compliance requirements met) +- **Result: FAILED** - When Overall Grade is FAIL or NEEDS_WORK (compliance failures present) + +This ensures orchestrators properly halt workflows when quality gates fail. + Return this summary to the caller. diff --git a/.github/standards/coding-principles.md b/.github/standards/coding-principles.md new file mode 100644 index 0000000..3d1a8a1 --- /dev/null +++ b/.github/standards/coding-principles.md @@ -0,0 +1,70 @@ +--- +name: Coding Principles +description: Follow these standards when developing any software code. +--- + +# Coding Principles Standards + +This document defines universal coding principles and quality standards for software development within +Continuous Compliance environments. + +# Core Principles + +## Literate Coding + +All code MUST follow literate programming principles: + +- **Intent Comments**: Every function/method begins with a comment explaining WHY (not what) +- **Logical Separation**: Complex functions use comments to separate logical blocks +- **Public Documentation**: All public interfaces have comprehensive documentation +- **Clarity Over Cleverness**: Code should be immediately understandable by team members + +## Universal Code Architecture Principles + +### Design Patterns + +- **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 +- **Repository Structure Adherence**: Before creating any new files, analyze the repository structure to + understand established directory conventions and file placement patterns. Place new files in locations + consistent with existing patterns. + +### Compliance-Ready Code Structure + +- **Documentation Standards**: Language-appropriate documentation required on ALL public members +- **Error Handling**: Comprehensive error cases with appropriate exception handling and logging +- **Configuration**: Externalize settings for different compliance environments +- **Resource Management**: Proper resource cleanup using language-appropriate patterns + +# Quality Gates + +## Code Quality Standards + +- [ ] Zero compiler warnings (use language-specific warning-as-error flags) +- [ ] All code follows literate programming style +- [ ] Language-appropriate documentation complete on all public members +- [ ] Passes static analysis (language-specific tools) + +## Universal Anti-Patterns + +- **Skip Literate Coding**: Don't skip literate programming comments - they are required for maintainability +- **Ignore Compiler Warnings**: Don't ignore compiler warnings - they exist for quality enforcement +- **Hidden Dependencies**: Don't create untestable code with hidden dependencies +- **Hidden Functionality**: Don't implement functionality without requirement traceability +- **Monolithic Functions**: Don't write monolithic functions with multiple responsibilities +- **Overcomplicated Solutions**: Don't make solutions more complex than necessary - favor simplicity and clarity +- **Premature Optimization**: Don't optimize for performance before establishing correctness and identifying actual bottlenecks +- **Copy-Paste Programming**: Don't duplicate logic - extract common functionality into reusable components +- **Magic Numbers**: Don't use unexplained constants - either name them or add clear comments + +# Language-Specific Implementation + +For each detected language: + +- **Load Standards**: Read the appropriate `{language}-language.md` file from `.github/standards/` +- **Apply Tooling**: Use language-specific formatting, linting, and build tools +- **Follow Conventions**: Apply language-specific naming, patterns, and best practices +- **Generate Documentation**: Use language-appropriate documentation format (XmlDoc, Doxygen, JSDoc, etc.) diff --git a/.github/standards/csharp-language.md b/.github/standards/csharp-language.md index 880544a..cb4fd44 100644 --- a/.github/standards/csharp-language.md +++ b/.github/standards/csharp-language.md @@ -1,23 +1,23 @@ -# C# Language Coding Standards +--- +name: C# Language +description: Follow these standards when developing C# source code. +globs: ["**/*.cs"] +--- -This document defines DEMA Consulting standards for C# software development -within Continuous Compliance environments. +# C# Language Development Standard -## Literate Programming Style (MANDATORY) +## Required Standards -Write all C# code in literate style because regulatory environments require -code that can be independently verified against requirements by reviewers. +Read these standards first before applying this standard: -- **Intent Comments**: Start every code paragraph with a comment explaining - intent (not mechanics). Enables verification that code matches requirements. -- **Logical Separation**: Use blank lines to separate logical code paragraphs. - Makes algorithm structure visible to reviewers. -- **Purpose Over Process**: Comments describe why, code shows how. Separates - business logic from implementation details. -- **Standalone Clarity**: Reading comments alone should explain the algorithm - approach. Supports independent code review. +- **`coding-principles.md`** - Universal coding principles and quality gates -### Example +# File Patterns + +- **Source Files**: `**/*.cs` +- **Project Files**: `**/*.csproj`, `**/*.sln` + +# Literate Coding Example ```csharp // Validate input parameters to prevent downstream errors @@ -36,51 +36,13 @@ var validatedResults = BusinessRuleEngine.ValidateAndProcess(processedData); return OutputFormatter.Format(validatedResults); ``` -## XML Documentation (MANDATORY) - -Document ALL members (public, internal, private) with XML comments because -compliance documentation is auto-generated from source code comments and review -agents need to validate implementation against documented intent. - -## Dependency Management - -Structure code for testability because all functionality must be validated -through automated tests linked to requirements. - -### Rules - -- **Inject Dependencies**: Use constructor injection for all external dependencies. - Enables mocking for unit tests. -- **Avoid Static Dependencies**: Use dependency injection instead of static - calls. Makes code testable in isolation. -- **Single Responsibility**: Each class should have one reason to change. - Simplifies testing and requirements traceability. -- **Pure Functions**: Minimize side effects and hidden state. Makes behavior - predictable and testable. - -## Error Handling - -Implement comprehensive error handling because failures must be logged for -audit trails and compliance reporting. - -- **Validate Inputs**: Check all parameters and throw appropriate exceptions - with clear messages -- **Use Typed Exceptions**: Throw specific exception types - (`ArgumentException`, `InvalidOperationException`) for different error - conditions -- **Include Context**: Exception messages should include enough information - for troubleshooting -- **Log Appropriately**: Use structured logging for audit trails in regulated - environments +# Code Formatting -## Quality Checks +- **Format entire solution**: `dotnet format` +- **Format specific project**: `dotnet format MyProject.csproj` +- **Format specific file**: `dotnet format --include MyFile.cs` -Before submitting C# code, verify: +# Quality Checks -- [ ] Code follows Literate Programming Style rules (intent comments, logical separation) -- [ ] XML documentation on ALL members with required tags -- [ ] Dependencies injected via constructor (no static dependencies) -- [ ] Single responsibility principle followed (one reason to change) -- [ ] Input validation with typed exceptions and clear messages -- [ ] Zero compiler warnings with `TreatWarningsAsErrors=true` -- [ ] Compatible with ReqStream requirements traceability +- [ ] Zero compiler warnings (`TreatWarningsAsErrors=true`) +- [ ] XmlDoc documentation complete on all members diff --git a/.github/standards/csharp-testing.md b/.github/standards/csharp-testing.md index d343f34..3d9de81 100644 --- a/.github/standards/csharp-testing.md +++ b/.github/standards/csharp-testing.md @@ -1,13 +1,22 @@ +--- +name: C# Testing +description: Follow these standards when developing C# tests. +globs: ["**/test/**/*.cs", "**/tests/**/*.cs", "**/*Tests.cs", "**/*Test.cs"] +--- + # C# Testing Standards (MSTest) This document defines DEMA Consulting standards for C# test development using MSTest within Continuous Compliance environments. -# AAA Pattern Implementation (MANDATORY) +## Required Standards + +Read these standards first before applying this standard: + +- **`testing-principles.md`** - Universal testing principles and dependency boundaries +- **`csharp-language.md`** - C# language development standards -Structure all tests using Arrange-Act-Assert pattern because regulatory reviews -require clear test logic that can be independently verified against -requirements. +# C# AAA Pattern Implementation ```csharp [TestMethod] @@ -37,25 +46,6 @@ Use descriptive test names because test names appear in requirements traceabilit - `UserValidator_ValidateEmail_InvalidFormat_ThrowsArgumentException` - `PaymentProcessor_ProcessPayment_InsufficientFunds_ReturnsFailureResult` -# Requirements Coverage - -Link tests to requirements because every requirement must have passing test evidence for compliance validation. - -- **ReqStream Integration**: Tests must be linkable in requirements YAML files -- **Platform Filters**: Use source filters for platform-specific requirements (`windows@TestName`) -- **TRX Format**: Generate test results in TRX format for ReqStream compatibility -- **Coverage Completeness**: Test both success paths and error conditions - -# Test Dependency Boundaries (MANDATORY) - -Respect software item hierarchy boundaries to ensure review-sets can validate proper architectural scope. - -- **System Tests**: May use functionality from any subsystem or unit within the system -- **Subsystem Tests**: May only use units within the subsystem + documented dependencies in design docs -- **Unit Tests**: May only test the unit + documented dependencies in design docs - -Undocumented cross-hierarchy dependencies indicate either missing design documentation or architectural violations. - # Mock Dependencies Mock external dependencies using NSubstitute (preferred) because tests must run in isolation to generate @@ -123,8 +113,6 @@ Before submitting C# tests, verify: - [ ] Each test verifies single, specific behavior (no shared state) - [ ] Both success and failure scenarios covered including edge cases - [ ] External dependencies mocked with NSubstitute or equivalent -- [ ] Tests respect software item hierarchy boundaries (System/Subsystem/Unit scope) -- [ ] Cross-hierarchy test dependencies documented in design documentation - [ ] Tests linked to requirements with source filters where needed - [ ] Test results generate TRX format for ReqStream compatibility - [ ] MSTest V4 anti-patterns avoided (proper assertions, public visibility, etc.) diff --git a/.github/standards/design-documentation.md b/.github/standards/design-documentation.md index 27b214f..f5bbbcd 100644 --- a/.github/standards/design-documentation.md +++ b/.github/standards/design-documentation.md @@ -1,3 +1,9 @@ +--- +name: Design Documentation +description: Follow these standards when creating design documentation. +globs: ["docs/design/**/*.md"] +--- + # Design Documentation Standards This document defines DEMA Consulting standards for design documentation @@ -5,6 +11,13 @@ within Continuous Compliance environments, extending the general technical documentation standards with specific requirements for software design artifacts. +## Required Standards + +Read these standards first before applying this standard: + +- **`technical-documentation.md`** - General technical documentation standards +- **`software-items.md`** - Software categorization (System/Subsystem/Unit/OTS) + # Core Principles Design documentation serves as the bridge between requirements and diff --git a/.github/standards/reqstream-usage.md b/.github/standards/reqstream-usage.md index ff3bc95..781c76c 100644 --- a/.github/standards/reqstream-usage.md +++ b/.github/standards/reqstream-usage.md @@ -1,8 +1,20 @@ +--- +name: ReqStream Usage +description: Follow these standards when managing requirements with ReqStream. +globs: ["requirements.yaml", "docs/reqstream/**/*.yaml"] +--- + # ReqStream Requirements Management Standards This document defines DEMA Consulting standards for requirements management using ReqStream within Continuous Compliance environments. +## Required Standards + +Read these standards first before applying this standard: + +- **`software-items.md`** - Software categorization (System/Subsystem/Unit/OTS) + # Core Principles ReqStream implements Continuous Compliance methodology for automated evidence @@ -48,12 +60,12 @@ consistency with design documentation and enable automated tooling. # Requirement Hierarchies and Links -When linking requirements between different software item levels, links MUST -only flow downward in the hierarchy to maintain clear traceability: +Requirements link downward only - higher-level requirements reference lower-level +ones they decompose into: - **System requirements** → may link to subsystem or unit requirements - **Subsystem requirements** → may link to unit requirements within that subsystem -- **Unit requirements** → should NOT link to higher-level requirements +- **Unit requirements** → should NOT link upward to parent requirements This prevents circular dependencies and ensures clear hierarchical relationships for compliance auditing. @@ -80,7 +92,7 @@ sections: justification: | Business rationale explaining why this requirement exists. Include regulatory or standard references where applicable. - children: # Links to child requirements (optional) + children: # Downward links to decomposed requirements (optional) - ChildSystem-Feature-Behavior tests: # Links to test methods (required) - TestMethodName diff --git a/.github/standards/reviewmark-usage.md b/.github/standards/reviewmark-usage.md index e2e380a..48380c5 100644 --- a/.github/standards/reviewmark-usage.md +++ b/.github/standards/reviewmark-usage.md @@ -1,5 +1,16 @@ +--- +name: ReviewMark Usage +description: Follow these standards when configuring file reviews with ReviewMark. +--- + # ReviewMark Usage Standard +## Required Standards + +Read these standards first before applying this standard: + +- **`software-items.md`** - Software categorization (System/Subsystem/Unit/OTS) + ## Purpose ReviewMark manages file review status enforcement and formal review processes. It tracks which files need diff --git a/.github/standards/software-items.md b/.github/standards/software-items.md index ce7e328..62abb9f 100644 --- a/.github/standards/software-items.md +++ b/.github/standards/software-items.md @@ -1,3 +1,8 @@ +--- +name: Software Items +description: Follow these standards when categorizing software components. +--- + # Software Items Definition Standards This document defines DEMA Consulting standards for categorizing software @@ -35,13 +40,16 @@ Choose the appropriate category based on scope and testability: ## Software Subsystem - Major architectural boundary (authentication, data layer, UI, communications) +- Contains multiple software units working together +- Typically maps to project folders or namespaces - Tested through subsystem integration tests ## Software Unit - Smallest independently testable component -- Tested through unit tests with mocked dependencies - Typically a single class or cohesive set of functions +- Methods within a class are NOT separate units +- Tested through unit tests with mocked dependencies ## OTS Software Item diff --git a/.github/standards/technical-documentation.md b/.github/standards/technical-documentation.md index 5bcc937..23bb5d3 100644 --- a/.github/standards/technical-documentation.md +++ b/.github/standards/technical-documentation.md @@ -1,3 +1,9 @@ +--- +name: Technical Documentation +description: Follow these standards when creating technical documentation. +globs: ["docs/**/*.md", "README.md"] +--- + # Technical Documentation Standards This document defines DEMA Consulting standards for technical documentation @@ -106,6 +112,13 @@ Write technical documentation for clarity and compliance verification: - **Traceable Content**: Link documentation to requirements and implementation where applicable for audit trails. +## References Sections + +References in design/technical documents must point to **external specifications only**: + +- **? INCLUDE**: Requirements documents, system specifications, program documents, standards (IEEE, ISO, etc.) +- **? NEVER INCLUDE**: Internal development standards (`.github/standards/` files) - these are coding guides, not specifications + # Markdown Format Requirements Markdown documentation in this repository must follow the formatting standards diff --git a/.github/standards/testing-principles.md b/.github/standards/testing-principles.md new file mode 100644 index 0000000..d9059e0 --- /dev/null +++ b/.github/standards/testing-principles.md @@ -0,0 +1,40 @@ +--- +name: Testing Principles +description: Follow these standards when developing any software tests. +--- + +# Testing Principles Standards + +This document defines universal testing principles and quality standards for test development within +Continuous Compliance environments. + +# Test Dependency Boundaries (MANDATORY) + +Respect software item hierarchy boundaries to ensure review-sets can validate proper architectural scope. + +- **System Tests**: May use functionality from any subsystem or unit within the system +- **Subsystem Tests**: May only use units within the subsystem + documented dependencies in design docs +- **Unit Tests**: May only test the unit + documented dependencies in design docs + +Undocumented cross-hierarchy dependencies indicate either missing design documentation or architectural violations. + +# AAA Pattern (MANDATORY) + +All tests MUST follow Arrange-Act-Assert pattern with descriptive comments because regulatory reviews +require clear test logic that can be independently verified against requirements. + +# Language-Specific Implementation + +Load the appropriate `{language}-testing.md` file for framework-specific implementation details, +file organization patterns, and tooling requirements. + +# Quality Gates + +- [ ] Tests respect software item hierarchy boundaries (System/Subsystem/Unit scope) +- [ ] Cross-hierarchy test dependencies documented in design documentation +- [ ] All tests follow AAA pattern with descriptive comments +- [ ] Test names follow hierarchical naming conventions for requirement linkage +- [ ] Tests linkable to requirements through ReqStream +- [ ] Platform-specific tests use appropriate source filters +- [ ] Both success and error scenarios covered +- [ ] External dependencies properly mocked for isolation diff --git a/AGENTS.md b/AGENTS.md index 511d444..0cd003c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,9 +18,9 @@ existing files and to know where to make new files. │ ├── requirements_report/ │ └── reqstream/ ├── src/ -│ └── / +│ └── {project}/ └── test/ - └── / + └── {test-project}/ ``` # Key Configuration Files @@ -42,6 +42,8 @@ existing files and to know where to make new files. Before performing any work, agents must read and apply the relevant standards from `.github/standards/`: +- **`coding-principles.md`** - For universal coding standards (literate programming, architecture principles, quality gates) +- **`testing-principles.md`** - For universal testing standards (dependency boundaries, AAA pattern, requirements traceability) - **`csharp-language.md`** - For C# code development (literate programming, XML docs, dependency injection) - **`csharp-testing.md`** - For C# test development (AAA pattern, naming, MSTest anti-patterns) - **`design-documentation.md`** - For design documentation (software structure diagrams, system.md, subsystem organization) From d0a56d14d4b30e8d4bf5140ab6ca652e95a9c6ea Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Thu, 9 Apr 2026 17:10:32 -0400 Subject: [PATCH 05/12] Fix minor linting issues. --- .github/standards/reqstream-usage.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/standards/reqstream-usage.md b/.github/standards/reqstream-usage.md index 781c76c..e4103b1 100644 --- a/.github/standards/reqstream-usage.md +++ b/.github/standards/reqstream-usage.md @@ -60,7 +60,7 @@ consistency with design documentation and enable automated tooling. # Requirement Hierarchies and Links -Requirements link downward only - higher-level requirements reference lower-level +Requirements link downward only - higher-level requirements reference lower-level ones they decompose into: - **System requirements** → may link to subsystem or unit requirements From 2ca89872d5bdc5b8f0a0d8e4dab5d5feab8ebf64 Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Thu, 9 Apr 2026 17:25:12 -0400 Subject: [PATCH 06/12] Minor formatting corrections. --- .github/standards/coding-principles.md | 2 +- .github/standards/technical-documentation.md | 4 ++-- AGENTS.md | 8 ++++---- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/.github/standards/coding-principles.md b/.github/standards/coding-principles.md index 3d1a8a1..4859fa5 100644 --- a/.github/standards/coding-principles.md +++ b/.github/standards/coding-principles.md @@ -56,7 +56,7 @@ All code MUST follow literate programming principles: - **Hidden Functionality**: Don't implement functionality without requirement traceability - **Monolithic Functions**: Don't write monolithic functions with multiple responsibilities - **Overcomplicated Solutions**: Don't make solutions more complex than necessary - favor simplicity and clarity -- **Premature Optimization**: Don't optimize for performance before establishing correctness and identifying actual bottlenecks +- **Premature Optimization**: Don't optimize for performance before establishing correctness - **Copy-Paste Programming**: Don't duplicate logic - extract common functionality into reusable components - **Magic Numbers**: Don't use unexplained constants - either name them or add clear comments diff --git a/.github/standards/technical-documentation.md b/.github/standards/technical-documentation.md index 23bb5d3..9da6eab 100644 --- a/.github/standards/technical-documentation.md +++ b/.github/standards/technical-documentation.md @@ -116,8 +116,8 @@ Write technical documentation for clarity and compliance verification: References in design/technical documents must point to **external specifications only**: -- **? INCLUDE**: Requirements documents, system specifications, program documents, standards (IEEE, ISO, etc.) -- **? NEVER INCLUDE**: Internal development standards (`.github/standards/` files) - these are coding guides, not specifications +- **INCLUDE**: Requirements documents, system specifications, program documents, standards (IEEE, ISO, etc.) +- **NEVER INCLUDE**: Internal development standards (`.github/standards/` files) - these are agent guides # Markdown Format Requirements diff --git a/AGENTS.md b/AGENTS.md index 0cd003c..81b610a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -42,15 +42,15 @@ existing files and to know where to make new files. Before performing any work, agents must read and apply the relevant standards from `.github/standards/`: -- **`coding-principles.md`** - For universal coding standards (literate programming, architecture principles, quality gates) -- **`testing-principles.md`** - For universal testing standards (dependency boundaries, AAA pattern, requirements traceability) +- **`coding-principles.md`** - For universal coding standards (literate programming, architecture principles) +- **`testing-principles.md`** - For universal testing standards (dependency boundaries, AAA pattern) - **`csharp-language.md`** - For C# code development (literate programming, XML docs, dependency injection) - **`csharp-testing.md`** - For C# test development (AAA pattern, naming, MSTest anti-patterns) -- **`design-documentation.md`** - For design documentation (software structure diagrams, system.md, subsystem organization) +- **`design-documentation.md`** - For design documentation (software structure diagrams, system.md, hierarchy) - **`reqstream-usage.md`** - For requirements management (traceability, semantic IDs, source filters) - **`reviewmark-usage.md`** - For file review management (review-sets, file patterns, enforcement) - **`software-items.md`** - For software categorization (system/subsystem/unit/OTS classification) -- **`technical-documentation.md`** - For documentation creation and maintenance (structure, Pandoc, README best practices) +- **`technical-documentation.md`** - For documentation creation and maintenance (structure, Pandoc, best practices) Load only the standards relevant to your specific task scope and apply their quality checks and guidelines throughout your work. From d01972d328d6da84cfdd6af765200781d266783a Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Thu, 9 Apr 2026 17:39:30 -0400 Subject: [PATCH 07/12] Improve linting scripts --- lint.bat | 47 +++++++++++++++++++++++++++++++---------------- lint.sh | 14 ++++++++++---- 2 files changed, 41 insertions(+), 20 deletions(-) diff --git a/lint.bat b/lint.bat index ad777b8..f373b99 100644 --- a/lint.bat +++ b/lint.bat @@ -15,32 +15,32 @@ REM === PYTHON SECTION === REM Create python venv if necessary if not exist ".venv\Scripts\activate.bat" python -m venv .venv -if errorlevel 1 goto skip_python +if errorlevel 1 goto abort_python REM Activate python venv call .venv\Scripts\activate.bat -if errorlevel 1 goto skip_python +if errorlevel 1 goto abort_python REM Install python tools pip install -r pip-requirements.txt --quiet --disable-pip-version-check -if errorlevel 1 goto skip_python +if errorlevel 1 goto abort_python REM Run yamllint yamllint . if errorlevel 1 set "LINT_ERROR=1" -goto npm_section -:skip_python +REM Section error handling +goto npm_section +:abort_python set "LINT_ERROR=1" +:npm_section REM === NPM SECTION === -:npm_section - REM Install npm dependencies set "PUPPETEER_SKIP_DOWNLOAD=true" call npm install --silent -if errorlevel 1 goto skip_npm +if errorlevel 1 goto abort_npm REM Run cspell call npx cspell --no-progress --no-color --quiet "**/*.{md,yaml,yml,json,cs,cpp,hpp,h,txt}" @@ -49,18 +49,18 @@ if errorlevel 1 set "LINT_ERROR=1" REM Run markdownlint-cli2 call npx markdownlint-cli2 "**/*.md" if errorlevel 1 set "LINT_ERROR=1" -goto dotnet_section -:skip_npm +REM Section error handling +goto dotnet_linting_section +:abort_npm set "LINT_ERROR=1" +:dotnet_linting_section -REM === DOTNET SECTION === - -:dotnet_section +REM === DOTNET LINTING SECTION === REM Restore dotnet tools dotnet tool restore > nul -if errorlevel 1 goto skip_dotnet_tools +if errorlevel 1 goto abort_dotnet_tools REM Run reqstream lint dotnet reqstream --lint --requirements requirements.yaml @@ -74,12 +74,27 @@ REM Run reviewmark lint dotnet reviewmark --lint if errorlevel 1 set "LINT_ERROR=1" -:skip_dotnet_tools +REM Section error handling +goto dotnet_format_section +:abort_dotnet_tools +set "LINT_ERROR=1" +:dotnet_format_section -REM Run dotnet format +REM === DOTNET FORMATTING SECTION === + +REM Restore dotnet packages dotnet restore > nul +if errorlevel 1 goto abort_dotnet_format + +REM Run dotnet format dotnet format --verify-no-changes --no-restore if errorlevel 1 set "LINT_ERROR=1" +REM Section error handling +goto end +:abort_dotnet_format +set "LINT_ERROR=1" +:end + REM Report result exit /b %LINT_ERROR% diff --git a/lint.sh b/lint.sh index a6b96c3..6864b33 100755 --- a/lint.sh +++ b/lint.sh @@ -36,7 +36,7 @@ fi # Install npm dependencies export PUPPETEER_SKIP_DOWNLOAD=true -npm install --silent || { lint_error=1; skip_npm=1; } +npm install --silent || skip_npm=1 # Run cspell if [ "$skip_npm" != "1" ]; then @@ -48,7 +48,7 @@ if [ "$skip_npm" != "1" ]; then npx markdownlint-cli2 "**/*.md" || lint_error=1 fi -# === DOTNET SECTION === +# === DOTNET LINTING SECTION === # Restore dotnet tools dotnet tool restore > /dev/null || { lint_error=1; skip_dotnet_tools=1; } @@ -68,9 +68,15 @@ if [ "$skip_dotnet_tools" != "1" ]; then dotnet reviewmark --lint || lint_error=1 fi +# === DOTNET FORMATTING SECTION === + +# Restore dotnet packages +dotnet restore > /dev/null || { lint_error=1; skip_dotnet_format=1; } + # Run dotnet format -dotnet restore > /dev/null -dotnet format --verify-no-changes --no-restore || lint_error=1 +if [ "$skip_dotnet_format" != "1" ]; then + dotnet format --verify-no-changes --no-restore || lint_error=1 +fi # Report result exit $lint_error From 268a8356740cb58f79fca06a66c97a3b3094c8b8 Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Thu, 9 Apr 2026 17:50:09 -0400 Subject: [PATCH 08/12] Update lint.sh Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- lint.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lint.sh b/lint.sh index 6864b33..4588497 100755 --- a/lint.sh +++ b/lint.sh @@ -36,7 +36,7 @@ fi # Install npm dependencies export PUPPETEER_SKIP_DOWNLOAD=true -npm install --silent || skip_npm=1 +npm install --silent || { lint_error=1; skip_npm=1; } # Run cspell if [ "$skip_npm" != "1" ]; then From ed04140b98b50076561191ce0c1a45d3e70c549c Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 9 Apr 2026 21:54:32 +0000 Subject: [PATCH 09/12] Clarify XmlDoc requirement covers all members including private Agent-Logs-Url: https://github.com/demaconsulting/TemplateDotNetLibrary/sessions/380f5d42-690a-4d8a-8390-f0d9d475e688 Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --- .github/standards/csharp-language.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/standards/csharp-language.md b/.github/standards/csharp-language.md index cb4fd44..d930a8a 100644 --- a/.github/standards/csharp-language.md +++ b/.github/standards/csharp-language.md @@ -45,4 +45,4 @@ return OutputFormatter.Format(validatedResults); # Quality Checks - [ ] Zero compiler warnings (`TreatWarningsAsErrors=true`) -- [ ] XmlDoc documentation complete on all members +- [ ] XmlDoc documentation complete on all members (public, internal, protected, private) From 90005b929dd60d85ac6e66e5e797982c72e5a5dd Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 9 Apr 2026 22:05:31 +0000 Subject: [PATCH 10/12] Remove project/solution file patterns from C# language standard Agent-Logs-Url: https://github.com/demaconsulting/TemplateDotNetLibrary/sessions/124eeb64-6752-44e7-a20d-fab39ca8cf1b Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --- .github/standards/csharp-language.md | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/standards/csharp-language.md b/.github/standards/csharp-language.md index d930a8a..5dbdda6 100644 --- a/.github/standards/csharp-language.md +++ b/.github/standards/csharp-language.md @@ -15,7 +15,6 @@ Read these standards first before applying this standard: # File Patterns - **Source Files**: `**/*.cs` -- **Project Files**: `**/*.csproj`, `**/*.sln` # Literate Coding Example From acadf54cb7654a5b71f7233957c2e22b5ff724ff Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Thu, 9 Apr 2026 18:24:51 -0400 Subject: [PATCH 11/12] Update AGENTS.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 81b610a..a2654ac 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -44,7 +44,7 @@ Before performing any work, agents must read and apply the relevant standards fr - **`coding-principles.md`** - For universal coding standards (literate programming, architecture principles) - **`testing-principles.md`** - For universal testing standards (dependency boundaries, AAA pattern) -- **`csharp-language.md`** - For C# code development (literate programming, XML docs, dependency injection) +- **`csharp-language.md`** - For C# code development (formatting, XML docs, C#-specific guidance) - **`csharp-testing.md`** - For C# test development (AAA pattern, naming, MSTest anti-patterns) - **`design-documentation.md`** - For design documentation (software structure diagrams, system.md, hierarchy) - **`reqstream-usage.md`** - For requirements management (traceability, semantic IDs, source filters) From 917f008daf391e82581ca0405850c71a16ff3a0e Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 9 Apr 2026 22:32:06 +0000 Subject: [PATCH 12/12] Update documentation standard to require ALL members (not just public) Agent-Logs-Url: https://github.com/demaconsulting/TemplateDotNetLibrary/sessions/f9f1b3f3-8e05-4331-80ac-7d66dfc52a00 Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --- .github/standards/coding-principles.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/standards/coding-principles.md b/.github/standards/coding-principles.md index 4859fa5..b00143d 100644 --- a/.github/standards/coding-principles.md +++ b/.github/standards/coding-principles.md @@ -34,7 +34,7 @@ All code MUST follow literate programming principles: ### Compliance-Ready Code Structure -- **Documentation Standards**: Language-appropriate documentation required on ALL public members +- **Documentation Standards**: Language-appropriate documentation required on ALL members - **Error Handling**: Comprehensive error cases with appropriate exception handling and logging - **Configuration**: Externalize settings for different compliance environments - **Resource Management**: Proper resource cleanup using language-appropriate patterns @@ -45,7 +45,7 @@ All code MUST follow literate programming principles: - [ ] Zero compiler warnings (use language-specific warning-as-error flags) - [ ] All code follows literate programming style -- [ ] Language-appropriate documentation complete on all public members +- [ ] Language-appropriate documentation complete on all members - [ ] Passes static analysis (language-specific tools) ## Universal Anti-Patterns