From d484f7e5513ba32283083ee7fe1d8859aabd67d6 Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Tue, 31 Mar 2026 22:48:21 -0400 Subject: [PATCH 1/4] Updated standards, clarified quality reports, and adjusted repository to align with new standards. --- .github/agents/implementation.agent.md | 6 +- .github/agents/quality.agent.md | 156 +++++++++--------- .github/standards/design-documentation.md | 142 ++++++++++++++++ .github/standards/reqstream-usage.md | 73 +++++--- .github/standards/reviewmark-usage.md | 80 +++++---- .github/standards/technical-documentation.md | 12 +- .reviewmark.yaml | 6 +- AGENTS.md | 15 +- docs/design/system.md | 52 ++++++ .../buildmark.yaml} | 0 .../{ots-mstest.yaml => ots/mstest.yaml} | 0 .../reqstream.yaml} | 0 .../reviewmark.yaml} | 0 .../sarifmark.yaml} | 0 .../sonarmark.yaml} | 0 .../versionmark.yaml} | 0 .../{library-system.yaml => system.yaml} | 0 requirements.yaml | 16 +- 18 files changed, 391 insertions(+), 167 deletions(-) create mode 100644 .github/standards/design-documentation.md create mode 100644 docs/design/system.md rename docs/reqstream/{ots-buildmark.yaml => ots/buildmark.yaml} (100%) rename docs/reqstream/{ots-mstest.yaml => ots/mstest.yaml} (100%) rename docs/reqstream/{ots-reqstream.yaml => ots/reqstream.yaml} (100%) rename docs/reqstream/{ots-reviewmark.yaml => ots/reviewmark.yaml} (100%) rename docs/reqstream/{ots-sarifmark.yaml => ots/sarifmark.yaml} (100%) rename docs/reqstream/{ots-sonarmark.yaml => ots/sonarmark.yaml} (100%) rename docs/reqstream/{ots-versionmark.yaml => ots/versionmark.yaml} (100%) rename docs/reqstream/{library-system.yaml => system.yaml} (100%) diff --git a/.github/agents/implementation.agent.md b/.github/agents/implementation.agent.md index 767c66d..dd203ef 100644 --- a/.github/agents/implementation.agent.md +++ b/.github/agents/implementation.agent.md @@ -26,7 +26,7 @@ counting how many retries have occurred. ## RESEARCH State (start) -Call the built-in @explore sub-agent with: +Call the built-in explore sub-agent with: - **context**: the user's request and any current quality findings - **goal**: analyze the implementation state and develop a plan to implement the request @@ -35,7 +35,7 @@ Once the explore sub-agent finishes, transition to the DEVELOPMENT state. ## DEVELOPMENT State -Call the @developer sub-agent with: +Call the developer sub-agent with: - **context** the user's request and the current implementation plan - **goal** implement the user's request and any identified quality fixes @@ -47,7 +47,7 @@ Once the developer sub-agent finishes: ## QUALITY State -Call the @quality sub-agent with: +Call the quality sub-agent with: - **context** the user's request and the current implementation report - **goal** check the quality of the work performed for any issues diff --git a/.github/agents/quality.agent.md b/.github/agents/quality.agent.md index 4dd6902..48e7a37 100644 --- a/.github/agents/quality.agent.md +++ b/.github/agents/quality.agent.md @@ -13,76 +13,14 @@ DEMA Consulting standards and Continuous Compliance practices. # Standards-Based Quality Assessment -This assessment is a quality control system of the project and MUST be performed. +This assessment is a quality control system of the project and MUST be performed systematically. 1. **Analyze completed work** to identify scope and changes made 2. **Read relevant standards** from `.github/standards/` as defined in AGENTS.md based on work performed -3. **Execute comprehensive quality checks** across all compliance areas - EVERY checkbox item must be evaluated +3. **Execute comprehensive quality assessment** using the structured evaluation criteria in the reporting template 4. **Validate tool compliance** using ReqStream, ReviewMark, and language tools 5. **Generate quality assessment report** with findings and recommendations -## Requirements Compliance - -- [ ] Were requirements updated to reflect functional changes? -- [ ] Were new requirements created for new features? -- [ ] Do requirement IDs follow semantic naming standards? -- [ ] Were source filters applied appropriately for platform-specific requirements? -- [ ] Does ReqStream enforcement pass without errors? -- [ ] Is requirements traceability maintained to tests? - -## Design Documentation Compliance - -- [ ] Were design documents updated for architectural changes? -- [ ] Were new design artifacts created for new components? -- [ ] Are design decisions documented with rationale? -- [ ] Is system/subsystem/unit categorization maintained? -- [ ] Is design-to-implementation traceability preserved? - -## Code Quality Compliance - -- [ ] Are language-specific standards followed (from applicable standards files)? -- [ ] Are quality checks from standards files satisfied? -- [ ] Is code properly categorized (system/subsystem/unit/OTS)? -- [ ] Is appropriate separation of concerns maintained? -- [ ] Was language-specific tooling executed and passing? - -## Testing Compliance - -- [ ] Were tests created/updated for all functional changes? -- [ ] Is test coverage maintained for all requirements? -- [ ] Are testing standards followed (AAA pattern, etc.)? -- [ ] Does test categorization align with code structure? -- [ ] Do all tests pass without failures? - -## Review Management Compliance - -- [ ] Were review-sets updated to include new/modified files? -- [ ] Do file patterns follow include-then-exclude approach? -- [ ] Is review scope appropriate for change magnitude? -- [ ] Was ReviewMark tooling executed and passing? -- [ ] Were review artifacts generated correctly? - -## Documentation Compliance - -- [ ] Was README.md updated for user-facing changes? -- [ ] Were user guides updated for feature changes? -- [ ] Does API documentation reflect code changes? -- [ ] Was compliance documentation generated? -- [ ] Does documentation follow standards formatting? -- [ ] Is documentation organized under `docs/` following standard folder structure? -- [ ] Do Pandoc collections include proper `introduction.md` files with Purpose and Scope sections? -- [ ] Are auto-generated markdown files left unmodified? -- [ ] Do README.md files use absolute URLs and include concrete examples? -- [ ] Is documentation integrated into ReviewMark review-sets for formal review? - -## Process Compliance - -- [ ] Was Continuous Compliance workflow followed? -- [ ] Did all quality gates execute successfully? -- [ ] Were appropriate tools used for validation? -- [ ] Were standards consistently applied across work? -- [ ] Was compliance evidence generated and preserved? - # Reporting Upon completion create a summary in `.agent-logs/[agent-name]-[subject]-[unique-id].md` @@ -100,26 +38,84 @@ of the project consisting of: - **Standards Applied**: [Standards files used for assessment] - **Categories Evaluated**: [Quality check categories assessed] -## Quality Check Results - -- **Requirements Compliance**: - [Summary] -- **Design Documentation**: - [Summary] -- **Code Quality**: - [Summary] -- **Testing Compliance**: - [Summary] -- **Review Management**: - [Summary] -- **Documentation**: - [Summary] -- **Process Compliance**: - [Summary] - -## Findings - -- **Issues Found**: [List of compliance issues] -- **Recommendations**: [Suggested improvements] +## Requirements Compliance: (PASS|FAIL|N/A) + +- Were requirements updated to reflect functional changes? (PASS|FAIL|N/A) - [Evidence/Details] +- Were new requirements created for new features? (PASS|FAIL|N/A) - [Evidence/Details] +- Do requirement IDs follow semantic naming standards? (PASS|FAIL|N/A) - [Evidence/Details] +- Do requirement files follow kebab-case naming convention? (PASS|FAIL|N/A) - [Evidence/Details] +- Are requirement files organized under `docs/reqstream/` with proper folder structure? (PASS|FAIL|N/A) - [Evidence/Details] +- Are OTS requirements properly placed in `docs/reqstream/ots/` subfolder? (PASS|FAIL|N/A) - [Evidence/Details] +- Were source filters applied appropriately for platform-specific requirements? (PASS|FAIL|N/A) - [Evidence/Details] +- Does ReqStream enforcement pass without errors? (PASS|FAIL|N/A) - [Evidence/Details] +- Is requirements traceability maintained to tests? (PASS|FAIL|N/A) - [Evidence/Details] + +## Design Documentation Compliance: (PASS|FAIL|N/A) + +- Were design documents updated for architectural changes? (PASS|FAIL|N/A) - [Evidence/Details] +- Were new design artifacts created for new components? (PASS|FAIL|N/A) - [Evidence/Details] +- Do design folder names use kebab-case convention matching source structure? (PASS|FAIL|N/A) - [Evidence/Details] +- Are design files properly named ({subsystem-name}.md, {unit-name}.md patterns)? (PASS|FAIL|N/A) - [Evidence/Details] +- Is `docs/design/introduction.md` present with required Software Structure section? (PASS|FAIL|N/A) - [Evidence/Details] +- Are design decisions documented with rationale? (PASS|FAIL|N/A) - [Evidence/Details] +- Is system/subsystem/unit categorization maintained? (PASS|FAIL|N/A) - [Evidence/Details] +- Is design-to-implementation traceability preserved? (PASS|FAIL|N/A) - [Evidence/Details] + +## Code Quality Compliance: (PASS|FAIL|N/A) + +- Are language-specific standards followed (from applicable standards files)? (PASS|FAIL|N/A) - [Evidence/Details] +- Are quality checks from standards files satisfied? (PASS|FAIL|N/A) - [Evidence/Details] +- Is code properly categorized (system/subsystem/unit/OTS)? (PASS|FAIL|N/A) - [Evidence/Details] +- Is appropriate separation of concerns maintained? (PASS|FAIL|N/A) - [Evidence/Details] +- Was language-specific tooling executed and passing? (PASS|FAIL|N/A) - [Evidence/Details] + +## Testing Compliance: (PASS|FAIL|N/A) + +- Were tests created/updated for all functional changes? (PASS|FAIL|N/A) - [Evidence/Details] +- Is test coverage maintained for all requirements? (PASS|FAIL|N/A) - [Evidence/Details] +- Are testing standards followed (AAA pattern, etc.)? (PASS|FAIL|N/A) - [Evidence/Details] +- Does test categorization align with code structure? (PASS|FAIL|N/A) - [Evidence/Details] +- Do all tests pass without failures? (PASS|FAIL|N/A) - [Evidence/Details] + +## Review Management Compliance: (PASS|FAIL|N/A) + +- Were review-sets updated to include new/modified files? (PASS|FAIL|N/A) - [Evidence/Details] +- Do file patterns follow include-then-exclude approach? (PASS|FAIL|N/A) - [Evidence/Details] +- Is review scope appropriate for change magnitude? (PASS|FAIL|N/A) - [Evidence/Details] +- Was ReviewMark tooling executed and passing? (PASS|FAIL|N/A) - [Evidence/Details] +- Were review artifacts generated correctly? (PASS|FAIL|N/A) - [Evidence/Details] + +## Documentation Compliance: (PASS|FAIL|N/A) + +- Was README.md updated for user-facing changes? (PASS|FAIL|N/A) - [Evidence/Details] +- Were user guides updated for feature changes? (PASS|FAIL|N/A) - [Evidence/Details] +- Does API documentation reflect code changes? (PASS|FAIL|N/A) - [Evidence/Details] +- Was compliance documentation generated? (PASS|FAIL|N/A) - [Evidence/Details] +- Does documentation follow standards formatting? (PASS|FAIL|N/A) - [Evidence/Details] +- Is documentation organized under `docs/` following standard folder structure? (PASS|FAIL|N/A) - [Evidence/Details] +- Do Pandoc collections include proper `introduction.md` files with Purpose and Scope sections? (PASS|FAIL|N/A) - [Evidence/Details] +- Are auto-generated markdown files left unmodified? (PASS|FAIL|N/A) - [Evidence/Details] +- Do README.md files use absolute URLs and include concrete examples? (PASS|FAIL|N/A) - [Evidence/Details] +- Is documentation integrated into ReviewMark review-sets for formal review? (PASS|FAIL|N/A) - [Evidence/Details] + +## Process Compliance: (PASS|FAIL|N/A) + +- Was Continuous Compliance workflow followed? (PASS|FAIL|N/A) - [Evidence/Details] +- Did all quality gates execute successfully? (PASS|FAIL|N/A) - [Evidence/Details] +- Were appropriate tools used for validation? (PASS|FAIL|N/A) - [Evidence/Details] +- Were standards consistently applied across work? (PASS|FAIL|N/A) - [Evidence/Details] +- Was compliance evidence generated and preserved? (PASS|FAIL|N/A) - [Evidence/Details] + +## Overall Findings + +- **Critical Issues**: [Count and description of critical findings] +- **Recommendations**: [Suggested improvements and next steps] - **Tools Executed**: [Quality tools used for validation] ## Compliance Status -- **Standards Adherence**: [Overall compliance rating] -- **Quality Gates**: [Status of automated quality checks] +- **Standards Adherence**: [Overall compliance rating with specific standards] +- **Quality Gates**: [Status of automated quality checks with tool outputs] ``` Return this summary to the caller. diff --git a/.github/standards/design-documentation.md b/.github/standards/design-documentation.md new file mode 100644 index 0000000..fac8901 --- /dev/null +++ b/.github/standards/design-documentation.md @@ -0,0 +1,142 @@ +# Design Documentation Standards + +This document defines DEMA Consulting standards for design documentation +within Continuous Compliance environments, extending the general technical +documentation standards with specific requirements for software design +artifacts. + +# Core Principles + +Design documentation serves as the bridge between requirements and +implementation, providing detailed technical specifications that enable: + +- **Formal Code Review**: Reviewers can verify implementation matches design +- **Compliance Evidence**: Auditors can trace requirements through design to code +- **Maintenance Support**: Developers can understand system structure and interactions +- **Quality Assurance**: Testing teams can validate against detailed specifications + +# Required Structure and Documents + +Design documentation must be organized under `docs/design/` with folder structure +mirroring source code organization because reviewers need clear navigation from +design to implementation: + +```text +docs/design/ +├── introduction.md # Design overview with software structure +├── system.md # System-level design documentation +├── {subsystem-name}/ # Subsystem design documents (kebab-case folder names) +│ ├── {subsystem-name}.md # Subsystem overview and design +│ └── {unit-name}.md # Unit-level design documents +└── {unit-name}.md # Top-level unit design documents (if not in subsystem) +``` + +## introduction.md (MANDATORY) + +The `introduction.md` file serves as the design entry point and MUST include +these sections because auditors need clear scope boundaries and architectural +overview: + +### Purpose Section + +Clear statement of the design document's purpose, audience, and regulatory +or compliance drivers. + +### Scope Section + +Define what software items are covered and what is explicitly excluded. +Specify version boundaries and applicability constraints. + +### Software Structure Section (MANDATORY) + +Include a text-based tree diagram showing the software organization across +System, Subsystem, and Unit levels. Agents MUST read `software-items.md` +to understand these classifications before creating this section. + +Example format: + +```text +ProjectName (System) +├── ComponentA (Subsystem) +│ ├── ClassX (Unit) +│ └── ClassY (Unit) +├── ComponentB (Subsystem) +│ └── ClassZ (Unit) +└── UtilityClass (Unit) +``` + +### Folder Layout Section (MANDATORY) + +Include a text-based tree diagram showing how the source code folders +mirror the software structure, with file paths and brief descriptions. + +Example format: + +```text +src/ProjectName/ +├── ComponentA/ +│ ├── ClassX.cs — brief description +│ └── ClassY.cs — brief description +├── ComponentB/ +│ └── ClassZ.cs — brief description +└── UtilityClass.cs — brief description +``` + +## system.md (MANDATORY) + +The `system.md` file contains system-level design documentation including: + +- System architecture and major components +- External interfaces and dependencies +- Data flow and control flow +- System-wide design constraints and decisions +- Integration patterns and communication protocols + +## Subsystem and Unit Design Documents + +For each subsystem identified in the software structure: + +- Create a kebab-case folder matching the subsystem name (enables automated tooling) +- Include `{subsystem-name}.md` with subsystem overview and design +- Include unit design documents for complex units within the subsystem + +For significant units requiring detailed design: + +- Document data models, algorithms, and key methods +- Describe interactions with other units +- Include sufficient detail for formal code review +- Place in appropriate subsystem folder or at design root level + +# Software Items Integration (CRITICAL) + +Before creating design documentation, agents MUST: + +1. **Read `.github/standards/software-items.md`** to understand System/Subsystem/Unit classifications +2. **Apply proper categorization** when creating software structure diagrams +3. **Ensure consistency** between software structure and folder layout +4. **Validate mapping** from design categories to source code organization + +# Writing Guidelines + +Design documentation must be technical and specific because it serves as the +implementation specification for formal code review: + +- **Implementation Detail**: Provide sufficient detail for code review and implementation +- **Architectural Clarity**: Clearly define component boundaries and interfaces +- **Traceability**: Link to requirements where applicable using ReqStream patterns +- **Concrete Examples**: Use actual class names, method signatures, and data structures +- **Current Information**: Keep synchronized with code changes and refactoring + +# Quality Checks + +Before submitting design documentation, verify: + +- [ ] `introduction.md` includes both Software Structure and Folder Layout sections +- [ ] Software structure correctly categorizes items as System/Subsystem/Unit per `software-items.md` +- [ ] Folder layout matches actual source code organization +- [ ] `system.md` provides comprehensive system-level design +- [ ] Subsystem folders use kebab-case naming matching source code +- [ ] Design documents contain sufficient implementation detail +- [ ] All documents follow technical documentation formatting standards +- [ ] Content is current with implementation and requirements +- [ ] Documents are integrated into ReviewMark review-sets for formal review diff --git a/.github/standards/reqstream-usage.md b/.github/standards/reqstream-usage.md index 3f99929..aa75a1f 100644 --- a/.github/standards/reqstream-usage.md +++ b/.github/standards/reqstream-usage.md @@ -15,28 +15,54 @@ generation: coverage - **Audit Documentation**: Generated reports provide compliance evidence +# Software Items Integration (CRITICAL) + +Before creating requirements files, agents MUST: + +1. **Read `.github/standards/software-items.md`** to understand System/Subsystem/Unit/OTS classifications +2. **Apply proper categorization** when organizing requirements files +3. **Mirror source code structure** in requirements folder organization + # Requirements Organization -Organize requirements into separate files under `docs/reqstream/` for -independent review: +Organize requirements into separate files under `docs/reqstream/` mirroring +the source code structure because reviewers need clear navigation from +requirements to design to implementation: ```text -requirements.yaml # Root file (includes only) +requirements.yaml # Root file (includes only) docs/reqstream/ - {project}-system.yaml # System-level requirements - platform-requirements.yaml # Platform support requirements - subsystem-{subsystem}.yaml # Subsystem requirements - unit-{unit}.yaml # Unit (class) requirements - ots-{component}.yaml # OTS software item requirements +├── system.yaml # System-level requirements +├── platform-requirements.yaml # Platform support requirements +├── {subsystem-name}/ # Subsystem requirements (kebab-case folders) +│ └── {subsystem-name}.yaml # Requirements for this subsystem +├── {unit-name}.yaml # Unit requirements (for top-level units) +└── ots/ # OTS software item requirements + └── {ots-name}.yaml # Requirements for OTS components ``` +The folder structure MUST mirror the source code organization to maintain +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: + +- **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 + +This prevents circular dependencies and ensures clear hierarchical relationships +for compliance auditing. + # Requirements File Format ```yaml sections: - title: Functional Requirements requirements: - - id: Project-Component-Feature + - id: Project-Subsystem-Feature title: The system shall perform the required function. justification: | Business rationale explaining why this requirement exists. @@ -46,9 +72,15 @@ sections: - windows@PlatformSpecificTest # Source filter for platform evidence ``` +Requirements specify WHAT the system shall do, not HOW, because implementation +details belong in design documentation while requirements focus on externally +observable behavior with clear, testable acceptance criteria. + # OTS Software Requirements -Document third-party component requirements with specific section structure: +Document third-party component requirements in the `docs/reqstream/ots/` folder +with nested sections because auditors need clear separation between in-house +and external component evidence: ```yaml sections: @@ -64,25 +96,12 @@ sections: # Semantic IDs (MANDATORY) -Use meaningful IDs following `Project-Section-ShortDesc` pattern: +Use meaningful IDs following `Project-Section-ShortDesc` pattern because +auditors need to understand requirements without cross-referencing: - **Good**: `TemplateTool-Core-DisplayHelp` - **Bad**: `REQ-042` (requires lookup to understand) -# Requirement Best Practices - -Requirements specify WHAT the system shall do, not HOW: - -- Focus on externally observable characteristics and behavior -- Avoid implementation details, design constraints, or technology choices -- Each requirement must have clear, testable acceptance criteria - -Include business rationale for each requirement: - -- Business need or regulatory requirement -- Risk mitigation or quality improvement -- Standard or regulation references - # Source Filter Requirements (CRITICAL) Platform-specific requirements MUST use source filters for compliance evidence: @@ -140,7 +159,9 @@ Before submitting requirements, verify: - [ ] Platform-specific requirements use source filters (`platform@TestName`) - [ ] Requirements specify observable behavior (WHAT), not implementation (HOW) - [ ] Comprehensive justification explains business/regulatory need -- [ ] Files organized under `docs/reqstream/` following naming patterns +- [ ] Files organized under `docs/reqstream/` following folder structure patterns +- [ ] Subsystem folders use kebab-case naming matching source code +- [ ] OTS requirements placed in `ots/` subfolder - [ ] Valid YAML syntax passes yamllint validation - [ ] ReqStream enforcement passes: `dotnet reqstream --enforce` - [ ] Test result formats compatible (TRX, JUnit XML) diff --git a/.github/standards/reviewmark-usage.md b/.github/standards/reviewmark-usage.md index bdabd1d..c914634 100644 --- a/.github/standards/reviewmark-usage.md +++ b/.github/standards/reviewmark-usage.md @@ -20,9 +20,9 @@ Configure reviews in `.reviewmark.yaml` at repository root: # Patterns identifying all files that require review needs-review: # Include core development artifacts - - "**/*.cs" # All C# source and test files - - "**/*.md" # Requirements and design documentation - "docs/reqstream/**/*.yaml" # Requirements files only + - "**/*.md" # Requirements and design documentation + - "**/*.cs" # All C# source and test files # Exclude build output and generated content - "!**/obj/**" # Exclude build output @@ -38,10 +38,10 @@ reviews: - id: MyProduct-PasswordValidator title: Password Validator Unit Review paths: - - "src/Auth/PasswordValidator.cs" - - "docs/reqstream/auth-passwordvalidator-class.yaml" - - "test/Auth/PasswordValidatorTests.cs" - - "docs/design/password-validation.md" + - "docs/reqstream/authentication/password-validator.yaml" + - "docs/design/authentication/password-validator.md" + - "src/Authentication/PasswordValidator.cs" + - "test/Authentication/PasswordValidatorTests.cs" - id: MyProduct-AllRequirements title: All Requirements Review @@ -59,7 +59,9 @@ and consistent review processes: Reviews system integration and operational validation: -- **Files**: System-level requirements, design introduction, system design documents, integration tests +- **Files**: System requirements (`docs/reqstream/system.yaml`), design introduction + (`docs/design/introduction.md`), system design (`docs/design/system.md`), + integration tests - **Purpose**: Validates system operates as designed and meets overall requirements - **Example**: `TemplateTool-System` @@ -67,7 +69,7 @@ Reviews system integration and operational validation: Reviews architectural and design consistency: -- **Files**: System-level requirements, platform requirements, all design documents +- **Files**: System requirements, platform requirements, all design documents under `docs/design/` - **Purpose**: Ensures design completeness and architectural coherence - **Example**: `MyProduct-Design` @@ -75,7 +77,7 @@ Reviews architectural and design consistency: Reviews requirements quality and traceability: -- **Files**: All requirement files including root `requirements.yaml` +- **Files**: All requirement files including root `requirements.yaml` and all files under `docs/reqstream/` - **Purpose**: Validates requirements structure, IDs, justifications, and test linkage - **Example**: `MyProduct-AllRequirements` @@ -85,6 +87,11 @@ Reviews individual software unit implementation: - **Files**: Unit requirements, design documents, source code, unit tests - **Purpose**: Validates unit meets requirements and is properly implemented +- **File Path Pattern**: + - Requirements: `docs/reqstream/{subsystem-name}/{unit-name}.yaml` or `docs/reqstream/{unit-name}.yaml` + - Design: `docs/design/{subsystem-name}/{unit-name}.md` or `docs/design/{unit-name}.md` + - Source: `src/{SubsystemName}/{UnitName}.cs` + - Tests: `test/{SubsystemName}/{UnitName}Tests.cs` - **Example**: `MyProduct-PasswordValidator`, `MyProduct-ConfigParser` ## [Product]-[Subsystem] Review @@ -93,48 +100,48 @@ Reviews subsystem architecture and interfaces: - **Files**: Subsystem requirements, design documents, integration tests (usually no source code) - **Purpose**: Validates subsystem behavior and interface compliance +- **File Path Pattern**: + - Requirements: `docs/reqstream/{subsystem-name}/{subsystem-name}.yaml` + - Design: `docs/design/{subsystem-name}/{subsystem-name}.md` + - Tests: `test/{SubsystemName}Integration/` or similar - **Example**: `MyProduct-Authentication`, `MyProduct-DataLayer` -# ReviewMark Commands - -Essential ReviewMark commands for Continuous Compliance: - -```bash -# Lint review configuration for issues (run before use) -dotnet reviewmark \ - --lint - -# Generate review plan (shows coverage) -dotnet reviewmark \ - --plan docs/code_review_plan/plan.md +## [Product]-OTS Review -# Generate review report (shows status) -dotnet reviewmark \ - --report docs/code_review_report/report.md +Reviews OTS (Off-The-Shelf) software integration: -# Enforce review compliance (use in CI/CD) -dotnet reviewmark \ - --plan docs/code_review_plan/plan.md \ - --report docs/code_review_report/report.md \ - --enforce -``` +- **Files**: OTS requirements and integration test evidence +- **Purpose**: Validates OTS components meet integration requirements +- **File Path Pattern**: + - Requirements: `docs/reqstream/ots/{ots-name}.yaml` + - Tests: Integration tests proving OTS functionality +- **Example**: `MyProduct-SystemTextJson`, `MyProduct-EntityFramework` # File Pattern Best Practices Use "include-then-exclude" approach for `needs-review` patterns because it ensures comprehensive coverage while removing unwanted files: -## Include-Then-Exclude Strategy - 1. **Start broad**: Include all files of potential interest with generous patterns 2. **Exclude overreach**: Use `!` patterns to remove build output, generated files, and temporary files 3. **Test patterns**: Verify patterns match intended files using `dotnet reviewmark --elaborate` -## Pattern Guidelines +**Order matters**: Patterns are processed sequentially, excludes override earlier includes. + +# ReviewMark Commands + +Essential ReviewMark commands for Continuous Compliance: + +```bash +# Lint review configuration for issues (run before use) +dotnet reviewmark --lint -- **Be generous with includes**: Better to include too much initially than miss important files -- **Be specific with excludes**: Target exact paths and patterns that should never be reviewed -- **Order matters**: Patterns are processed sequentially, excludes override earlier includes +# Generate review plan and report (use in CI/CD) +dotnet reviewmark \ + --plan docs/code_review_plan/plan.md \ + --report docs/code_review_report/report.md \ + --enforce +``` # Quality Checks @@ -144,6 +151,7 @@ Before submitting ReviewMark configuration, verify: - [ ] `needs-review` patterns cover requirements, design, code, and tests with proper exclusions - [ ] Each review-set has unique `id` and groups architecturally related files - [ ] File patterns use correct glob syntax and match intended files +- [ ] File paths reflect current naming conventions (kebab-case design/requirements folders, PascalCase source folders) - [ ] Evidence source properly configured (`none` for dev, `url` for production) - [ ] Environment variables used for credentials (never hardcoded) - [ ] ReviewMark enforcement configured: `dotnet reviewmark --enforce` diff --git a/.github/standards/technical-documentation.md b/.github/standards/technical-documentation.md index f09ee83..d76b1f3 100644 --- a/.github/standards/technical-documentation.md +++ b/.github/standards/technical-documentation.md @@ -34,13 +34,15 @@ docs/ design/ # Design documentation introduction.md # Design overview system.md # System architecture - {component}.md # Component-specific designs + {subsystem-name}.md # Subsystem-specific designs + {unit-name}.md # Unit-specific designs reqstream/ # Requirements source files - {project}-system.yaml # System requirements + system.yaml # System requirements platform-requirements.yaml # Platform requirements - subsystem-{name}.yaml # Subsystem requirements - unit-{name}.yaml # Unit requirements - ots-{name}.yaml # OTS requirements + {subsystem-name}.yaml # Subsystem requirements + {unit-name}.yaml # Unit requirements + ots/ # OTS requirement files + {ots-name}.yaml # OTS requirements requirements_doc/ # Auto-generated requirements reports requirements.md # Generated by ReqStream justifications.md # Generated by ReqStream diff --git a/.reviewmark.yaml b/.reviewmark.yaml index a7c2fc3..04ff172 100644 --- a/.reviewmark.yaml +++ b/.reviewmark.yaml @@ -28,15 +28,17 @@ reviews: - id: TemplateDotNetLibrary-System title: Review of Template DotNet Library System Requirements and Design paths: - - "docs/reqstream/library-system.yaml" + - "docs/reqstream/system.yaml" - "docs/design/introduction.md" + - "docs/design/system.md" - id: TemplateDotNetLibrary-Design title: Review of Template DotNet Library Architectural and Design Consistency paths: - - "docs/reqstream/library-system.yaml" + - "docs/reqstream/system.yaml" - "docs/reqstream/platform-requirements.yaml" - "docs/design/introduction.md" + - "docs/design/system.md" - "docs/design/demo.md" - id: TemplateDotNetLibrary-Demo diff --git a/AGENTS.md b/AGENTS.md index db67cc7..e0349d2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,6 +8,7 @@ Before performing any work, agents must read and apply the relevant standards fr - **`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) - **`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) @@ -21,12 +22,12 @@ quality checks and guidelines throughout your work. The default agent should handle simple, straightforward tasks directly. Delegate to specialized agents only for specific scenarios: -- **Light development work** (small fixes, simple features) → Call @developer agent -- **Light quality checking** (linting, basic validation) → Call @quality agent -- **Formal feature implementation** (complex, multi-step) → Call the `@implementation` agent -- **Formal bug resolution** (complex debugging, systematic fixes) → Call the `@implementation` agent -- **Formal reviews** (compliance verification, detailed analysis) → Call @code-review agent -- **Template consistency** (downstream repository alignment) → Call @repo-consistency agent +- **Light development work** (small fixes, simple features) → Call developer agent +- **Light quality checking** (linting, basic validation) → Call quality agent +- **Formal feature implementation** (complex, multi-step) → Call the `implementation` agent +- **Formal bug resolution** (complex debugging, systematic fixes) → Call the `implementation` agent +- **Formal reviews** (compliance verification, detailed analysis) → Call code-review agent +- **Template consistency** (downstream repository alignment) → Call repo-consistency agent ## Available Specialized Agents @@ -156,7 +157,7 @@ Continuous Compliance . - **Source filters are critical** - Platform/framework requirements need specific test evidence For detailed requirements format, test linkage patterns, and ReqStream -integration, call the @developer agent with requirements management context. +integration, call the developer agent with requirements management context. ## Agent Report Files diff --git a/docs/design/system.md b/docs/design/system.md new file mode 100644 index 0000000..c7a9859 --- /dev/null +++ b/docs/design/system.md @@ -0,0 +1,52 @@ +# System Design + +This document provides the system-level design for the Template DotNet Library. + +## System Architecture + +The Template DotNet Library is a minimal .NET library template demonstrating DEMA Consulting +best practices. The system consists of: + +- **Demo Unit**: Simple greeting functionality demonstrating library patterns +- **Testing Framework**: MSTest-based unit tests with requirements traceability +- **Compliance Framework**: Integrated ReqStream, ReviewMark, and quality tooling + +## External Interfaces + +### Dependencies + +The system depends on the following OTS components: + +- **.NET Runtime**: Provides core framework functionality +- **MSTest**: Unit testing framework for verification +- **ReqStream**: Requirements traceability enforcement +- **ReviewMark**: File review management +- **BuildMark/VersionMark**: Build and version documentation +- **SonarMark/SARIFMark**: Quality analysis integration + +### Public API + +The system exposes: + +- **Demo.GetGreeting()**: Returns greeting string for demonstration purposes +- Package metadata and documentation for NuGet distribution + +## Data Flow + +1. **Input**: Method parameters (optional name for greeting) +2. **Processing**: Simple string formatting within Demo unit +3. **Output**: Formatted greeting string + +## System Constraints + +- **Simplicity**: Minimal functionality to serve as template +- **Compliance**: All functionality must be traceable to requirements +- **Quality**: Zero warnings, full test coverage, complete documentation +- **Portability**: Compatible across supported .NET platforms + +## Integration Patterns + +- **NuGet Packaging**: Standard .NET library packaging and distribution +- **CI/CD Integration**: Automated build, test, and quality validation +- **Requirements Traceability**: All features linked to passing tests +- **Review Management**: Systematic file review using ReviewMark patterns diff --git a/docs/reqstream/ots-buildmark.yaml b/docs/reqstream/ots/buildmark.yaml similarity index 100% rename from docs/reqstream/ots-buildmark.yaml rename to docs/reqstream/ots/buildmark.yaml diff --git a/docs/reqstream/ots-mstest.yaml b/docs/reqstream/ots/mstest.yaml similarity index 100% rename from docs/reqstream/ots-mstest.yaml rename to docs/reqstream/ots/mstest.yaml diff --git a/docs/reqstream/ots-reqstream.yaml b/docs/reqstream/ots/reqstream.yaml similarity index 100% rename from docs/reqstream/ots-reqstream.yaml rename to docs/reqstream/ots/reqstream.yaml diff --git a/docs/reqstream/ots-reviewmark.yaml b/docs/reqstream/ots/reviewmark.yaml similarity index 100% rename from docs/reqstream/ots-reviewmark.yaml rename to docs/reqstream/ots/reviewmark.yaml diff --git a/docs/reqstream/ots-sarifmark.yaml b/docs/reqstream/ots/sarifmark.yaml similarity index 100% rename from docs/reqstream/ots-sarifmark.yaml rename to docs/reqstream/ots/sarifmark.yaml diff --git a/docs/reqstream/ots-sonarmark.yaml b/docs/reqstream/ots/sonarmark.yaml similarity index 100% rename from docs/reqstream/ots-sonarmark.yaml rename to docs/reqstream/ots/sonarmark.yaml diff --git a/docs/reqstream/ots-versionmark.yaml b/docs/reqstream/ots/versionmark.yaml similarity index 100% rename from docs/reqstream/ots-versionmark.yaml rename to docs/reqstream/ots/versionmark.yaml diff --git a/docs/reqstream/library-system.yaml b/docs/reqstream/system.yaml similarity index 100% rename from docs/reqstream/library-system.yaml rename to docs/reqstream/system.yaml diff --git a/requirements.yaml b/requirements.yaml index cf1af53..1043e76 100644 --- a/requirements.yaml +++ b/requirements.yaml @@ -1,13 +1,13 @@ --- # Root requirements file - includes all system, unit, platform, and OTS requirements includes: - - docs/reqstream/library-system.yaml + - docs/reqstream/system.yaml - docs/reqstream/demo.yaml - docs/reqstream/platform-requirements.yaml - - docs/reqstream/ots-mstest.yaml - - docs/reqstream/ots-reqstream.yaml - - docs/reqstream/ots-buildmark.yaml - - docs/reqstream/ots-versionmark.yaml - - docs/reqstream/ots-sarifmark.yaml - - docs/reqstream/ots-sonarmark.yaml - - docs/reqstream/ots-reviewmark.yaml + - docs/reqstream/ots/mstest.yaml + - docs/reqstream/ots/reqstream.yaml + - docs/reqstream/ots/buildmark.yaml + - docs/reqstream/ots/versionmark.yaml + - docs/reqstream/ots/sarifmark.yaml + - docs/reqstream/ots/sonarmark.yaml + - docs/reqstream/ots/reviewmark.yaml From 87680bf9de0126b112f0ac001b4b0da5a3f9898b Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Tue, 31 Mar 2026 23:01:53 -0400 Subject: [PATCH 2/4] Update docs/design/system.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/design/system.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/design/system.md b/docs/design/system.md index c7a9859..68f62bf 100644 --- a/docs/design/system.md +++ b/docs/design/system.md @@ -28,7 +28,7 @@ The system depends on the following OTS components: The system exposes: -- **Demo.GetGreeting()**: Returns greeting string for demonstration purposes +- **Demo.DemoMethod(string name)**: Returns greeting string for demonstration purposes - Package metadata and documentation for NuGet distribution ## Data Flow From f09c18c9f24d9d388eed72f3c6abe9eeedf01c60 Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Tue, 31 Mar 2026 23:02:09 -0400 Subject: [PATCH 3/4] Update docs/design/system.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- docs/design/system.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/design/system.md b/docs/design/system.md index 68f62bf..f548823 100644 --- a/docs/design/system.md +++ b/docs/design/system.md @@ -33,9 +33,9 @@ The system exposes: ## Data Flow -1. **Input**: Method parameters (optional name for greeting) -2. **Processing**: Simple string formatting within Demo unit -3. **Output**: Formatted greeting string +1. **Input**: Method parameter `name` (required, non-empty string for greeting; null or empty values result in an error) +2. **Processing**: Input validation and simple string formatting within Demo unit +3. **Output**: Formatted greeting string when a valid `name` is provided ## System Constraints From 1372cfc05869d2d4f4652436019b7e6716f420fa Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Tue, 31 Mar 2026 23:03:06 -0400 Subject: [PATCH 4/4] Update .github/standards/technical-documentation.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- .github/standards/technical-documentation.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/.github/standards/technical-documentation.md b/.github/standards/technical-documentation.md index d76b1f3..ca64eac 100644 --- a/.github/standards/technical-documentation.md +++ b/.github/standards/technical-documentation.md @@ -39,10 +39,11 @@ docs/ reqstream/ # Requirements source files system.yaml # System requirements platform-requirements.yaml # Platform requirements - {subsystem-name}.yaml # Subsystem requirements - {unit-name}.yaml # Unit requirements - ots/ # OTS requirement files - {ots-name}.yaml # OTS requirements + {subsystem-name}/ # Subsystem requirements folder + {subsystem-name}.yaml # Subsystem requirements + {unit-name}.yaml # Unit requirements + ots/ # OTS requirement files + {ots-name}.yaml # OTS requirements requirements_doc/ # Auto-generated requirements reports requirements.md # Generated by ReqStream justifications.md # Generated by ReqStream