diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json index 88d4aa0..a3f06a0 100644 --- a/.config/dotnet-tools.json +++ b/.config/dotnet-tools.json @@ -39,7 +39,7 @@ ] }, "demaconsulting.buildmark": { - "version": "0.4.0", + "version": "0.4.1", "commands": [ "buildmark" ] @@ -49,6 +49,12 @@ "commands": [ "versionmark" ] + }, + "demaconsulting.reviewmark": { + "version": "0.1.0", + "commands": [ + "reviewmark" + ] } } } \ No newline at end of file diff --git a/.cspell.json b/.cspell.json index b7a2812..778f039 100644 --- a/.cspell.json +++ b/.cspell.json @@ -6,10 +6,13 @@ "Blockquotes", "buildmark", "BuildMark", - "buildnotes", + "build_notes", "camelcase", "Checkmarx", "CodeQL", + "code_quality", + "code_review_plan", + "code_review_report", "copilot", "cspell", "csproj", @@ -44,8 +47,11 @@ "Qube", "reqstream", "ReqStream", + "reviewmark", + "ReviewMark", "Sarif", "SarifMark", + "sarifmark", "SBOM", "Semgrep", "semver", @@ -61,13 +67,17 @@ "Newtonsoft", "NuGetCacheTool", "testname", - "tracematrix", + "requirements_doc", + "requirements_report", + "trace_matrix", "triaging", "Trivy", "trx", "vbproj", "vcxproj", "Weasyprint", + "versionmark", + "VersionMark", "yamllint" ], "ignorePaths": [ @@ -83,6 +93,7 @@ "*.spdx.json", "package-lock.json", "yarn.lock", - "AGENT_REPORT_*.md" + "AGENT_REPORT_*.md", + "**/.agent-logs/**" ] } diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..2f09872 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,7 @@ +# Set default behavior: normalize line endings to LF on checkout for all text files. +# This ensures consistent SHA256 fingerprints for reviewmark across all platforms. +* text=auto eol=lf + +# Windows batch files require CRLF line endings to function correctly. +*.bat text eol=crlf +*.cmd text eol=crlf diff --git a/.github/agents/code-quality-agent.md b/.github/agents/code-quality-agent.md deleted file mode 100644 index 6f71c74..0000000 --- a/.github/agents/code-quality-agent.md +++ /dev/null @@ -1,85 +0,0 @@ ---- -name: Code Quality Agent -description: Ensures code quality through linting and static analysis - responsible for security, maintainability, and correctness ---- - -# Code Quality Agent - Template DotNet Tool - -Enforce quality standards through linting, static analysis, and security scanning. - -## When to Invoke This Agent - -Invoke the code-quality-agent for: - -- Running and fixing linting issues (markdown, YAML, spell check, code formatting) -- Ensuring static analysis passes with zero warnings -- Verifying code security -- Enforcing quality gates before merging -- Validating the project does what it claims to do - -## Responsibilities - -### Primary Responsibility - -Ensure the project is: - -- **Secure**: No security vulnerabilities -- **Maintainable**: Clean, well-formatted, documented code -- **Correct**: Does what it claims to do (requirements met) - -### Quality Gates (ALL Must Pass) - -1. **Build**: Zero warnings (TreatWarningsAsErrors=true) -2. **Linting**: - - markdownlint (`.markdownlint-cli2.jsonc`) - - cspell (`.cspell.json`) - - yamllint (`.yamllint.yaml`) - - dotnet format (`.editorconfig`) -3. **Static Analysis**: - - Microsoft.CodeAnalysis.NetAnalyzers - - SonarAnalyzer.CSharp -4. **Requirements Traceability**: - - `dotnet reqstream --requirements requirements.yaml --tests "test-results/**/*.trx" --enforce` -5. **Tests**: All validation tests passing - -### Template DotNet Tool-Specific - -- **XML Docs**: Enforce on ALL members (public/internal/private) -- **Code Style**: Verify `.editorconfig` compliance -- **Test Naming**: Check `TemplateTool_*` pattern for self-validation tests - -### Commands to Run - -```bash -# Code formatting -dotnet format --verify-no-changes - -# Build with zero warnings -dotnet build --configuration Release - -# Run self-validation tests -dotnet run --project src/DemaConsulting.TemplateDotNetTool \ - --configuration Release --framework net10.0 --no-build -- --validate - -# Requirements enforcement -dotnet reqstream --requirements requirements.yaml \ - --tests "test-results/**/*.trx" --enforce - -# Run all linters -./lint.sh # Linux/macOS -lint.bat # Windows -``` - -## Defer To - -- **Requirements Agent**: For requirements quality and test linkage strategy -- **Technical Writer Agent**: For fixing documentation content -- **Software Developer Agent**: For fixing production code issues -- **Test Developer Agent**: For fixing test code issues - -## Don't - -- Disable quality checks to make builds pass -- Ignore security warnings -- Skip enforcement of requirements traceability -- Change functional code without consulting appropriate developer agent diff --git a/.github/agents/code-review.agent.md b/.github/agents/code-review.agent.md new file mode 100644 index 0000000..f28a9b7 --- /dev/null +++ b/.github/agents/code-review.agent.md @@ -0,0 +1,73 @@ +--- +name: code-review +description: Agent for performing formal reviews +user-invocable: true +--- + +# Code Review Agent + +This agent runs the formal review based on the review-set it's told to perform. + +# Formal Review Steps + +Formal reviews are a quality enforcement mechanism, and as such MUST be performed using the following four steps: + +1. Download the + + to get the checklist to fill in +2. Use `dotnet reviewmark --elaborate [review-set]` to get the files to review +3. Review the files all together +4. Populate the checklist with the findings to `.agent-logs/reviews/review-report-[review-set].md` of the project. + +# Don't Do These Things + +- **Never modify code during review** (document findings only) +- **Never skip applicable checklist items** (comprehensive review required) +- **Never approve reviews with unresolved critical findings** +- **Never bypass review status requirements** for compliance +- **Never conduct reviews without proper documentation** +- **Never ignore security or compliance findings** +- **Never approve without verifying all quality gates** + +# Reporting + +Upon completion create a summary in `.agent-logs/[agent-name]-[subject]-[unique-id].md` +of the project consisting of: + +```markdown +# Code Review Report + +**Result**: + +## Review Summary + +- **Review Set**: [Review set name/identifier] +- **Review Report File**: [Name of detailed review report generated] +- **Files Reviewed**: [Count and list of files reviewed] +- **Review Template Used**: [Template source and version] + +## Review Results + +- **Overall Conclusion**: [Summary of review results] +- **Critical Issues**: [Count of critical findings] +- **High Issues**: [Count of high severity findings] +- **Medium Issues**: [Count of medium severity findings] +- **Low Issues**: [Count of low severity findings] + +## Issue Details + +[For each issue found, include:] +- **File**: [File name and line number where applicable] +- **Issue Type**: [Security, logic error, compliance violation, etc.] +- **Severity**: [Critical/High/Medium/Low] +- **Description**: [Issue description] +- **Recommendation**: [Specific remediation recommendation] + +## Compliance Status + +- **Review Status**: [Complete/Incomplete with reasoning] +- **Quality Gates**: [Status of review checklist items] +- **Approval Status**: [Approved/Rejected with justification] +``` + +Return summary to caller. diff --git a/.github/agents/developer.agent.md b/.github/agents/developer.agent.md new file mode 100644 index 0000000..955f9e9 --- /dev/null +++ b/.github/agents/developer.agent.md @@ -0,0 +1,49 @@ +--- +name: developer +description: > + General-purpose software development agent that applies appropriate standards + based on the work being performed. +user-invocable: true +--- + +# Developer Agent + +Perform software development tasks by determining and applying appropriate DEMA Consulting standards from `.github/standards/`. + +# Standards-Based Workflow + +1. **Analyze the request** to identify scope: languages, file types, requirements, testing, reviews +2. **Read relevant standards** from `.github/standards/` as defined in AGENTS.md based on work performed +3. **Apply loaded standards** throughout development process +4. **Execute work** following standards requirements and quality checks +5. **Generate completion report** with results and compliance status + +# Reporting + +Upon completion create a summary in `.agent-logs/[agent-name]-[subject]-[unique-id].md` +of the project consisting of: + +```markdown +# Developer Agent Report + +**Result**: + +## Work Summary + +- **Files Modified**: [List of files created/modified/deleted] +- **Languages Detected**: [Languages identified] +- **Standards Applied**: [Standards files consulted] + +## Tooling Executed + +- **Language Tools**: [Compilers, linters, formatters used] +- **Compliance Tools**: [ReqStream, ReviewMark tools used] +- **Validation Results**: [Tool execution results] + +## Compliance Status + +- **Quality Checks**: [Standards quality checks status] +- **Issues Resolved**: [Any problems encountered and resolved] +``` + +Return this summary to the caller. diff --git a/.github/agents/implementation.agent.md b/.github/agents/implementation.agent.md new file mode 100644 index 0000000..b3a6faf --- /dev/null +++ b/.github/agents/implementation.agent.md @@ -0,0 +1,93 @@ +--- +name: implementation +description: Orchestrator agent that manages quality implementations through a formal state machine workflow. +user-invocable: true +--- + +# Implementation Agent + +Orchestrate quality implementations through a formal state machine workflow +that ensures research, development, and quality validation are performed +systematically. + +# State Machine Workflow + +**MANDATORY**: This agent MUST follow the orchestration process below to ensure +the quality of the implementation. The process consists of the following +states: + +- **RESEARCH** - performs initial analysis +- **DEVELOPMENT** - develops the implementation changes +- **QUALITY** - performs quality validation +- **REPORT** - generates final implementation report + +The state-transitions include retrying a limited number of times, using a 'retry-count' +counting how many retries have occurred. + +## RESEARCH State (start) + +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 + +Once the explore sub-agent finishes, transition to the DEVELOPMENT state. + +## DEVELOPMENT State + +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 + +Once the developer sub-agent finishes: + +- IF developer SUCCEEDED: Transition to QUALITY state to check the quality of the work +- IF developer FAILED: Transition to REPORT state to report the failure + +## QUALITY State + +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 + +Once the quality sub-agent finishes: + +- IF quality SUCCEEDED: Transition to REPORT state to report completion +- IF quality FAILED and retry-count < 3: Transition to RESEARCH state to plan quality fixes +- IF quality FAILED and retry-count >= 3: Transition to REPORT state to report failure + +### REPORT State (end) + +Upon completion create a summary in `.agent-logs/[agent-name]-[subject]-[unique-id].md` +of the project consisting of: + +```markdown +# Implementation Orchestration Report + +**Result**: +**Final State**: +**Retry Count**: + +## State Machine Execution + +- **Research Results**: [Summary of explore agent findings] +- **Development Results**: [Summary of developer agent results] +- **Quality Results**: [Summary of quality agent results] +- **State Transitions**: [Log of state changes and decisions] + +## Sub-Agent Coordination + +- **Explore Agent**: [Research findings and context] +- **Developer Agent**: [Development status and files modified] +- **Quality Agent**: [Validation results and compliance status] + +## Final Status + +- **Implementation Success**: [Overall completion status] +- **Quality Compliance**: [Final quality validation status] +- **Issues Resolved**: [Problems encountered and resolution attempts] +``` + +Return this summary to the caller. diff --git a/.github/agents/quality.agent.md b/.github/agents/quality.agent.md new file mode 100644 index 0000000..8ecdad8 --- /dev/null +++ b/.github/agents/quality.agent.md @@ -0,0 +1,125 @@ +--- +name: quality +description: > + Quality assurance agent that grades developer work against DEMA Consulting + standards and Continuous Compliance practices. +user-invocable: true +--- + +# Quality Agent + +Grade and validate software development work by ensuring compliance with +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. + +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 +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` +of the project consisting of: + +```markdown +# Quality Assessment Report + +**Result**: +**Overall Grade**: + +## Assessment Summary + +- **Work Reviewed**: [Description of work assessed] +- **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] +- **Tools Executed**: [Quality tools used for validation] + +## Compliance Status + +- **Standards Adherence**: [Overall compliance rating] +- **Quality Gates**: [Status of automated quality checks] +``` + +Return this summary to the caller. diff --git a/.github/agents/repo-consistency-agent.md b/.github/agents/repo-consistency-agent.md deleted file mode 100644 index 3f289af..0000000 --- a/.github/agents/repo-consistency-agent.md +++ /dev/null @@ -1,150 +0,0 @@ ---- -name: Repo Consistency Agent -description: Ensures downstream repositories remain consistent with the TemplateDotNetTool template patterns and best practices ---- - -# Repo Consistency Agent - Template DotNet Tool - -Maintain consistency between downstream projects and the TemplateDotNetTool template at . - -## When to Invoke This Agent - -Invoke the repo-consistency-agent for: - -- Periodic reviews of downstream repositories based on this template -- Checking if downstream projects follow the latest template patterns -- Identifying drift from template standards -- Recommending updates to bring projects back in sync with template - -**Note**: This agent should NOT be invoked for the TemplateDotNetTool repository itself (), -as that would try to ensure the repository is consistent with itself (implicitly a no-op). - -## Responsibilities - -### Consistency Checks - -The agent reviews the following areas for consistency with the template: - -#### GitHub Configuration - -- **Issue Templates**: `.github/ISSUE_TEMPLATE/` files (bug_report.yml, feature_request.yml, config.yml) -- **Pull Request Template**: `.github/pull_request_template.md` -- **Workflow Patterns**: General structure of `.github/workflows/` (build.yaml, build_on_push.yaml, release.yaml) - - Note: Some projects may need workflow deviations for specific requirements - -#### Agent Configuration - -- **Agent Definitions**: `.github/agents/` directory structure -- **Agent Documentation**: `AGENTS.md` file listing available agents - -#### Code Structure and Patterns - -- **Context Parsing**: `Context.cs` pattern for command-line argument handling -- **Self-Validation**: `Validation.cs` pattern for built-in tests -- **Program Entry**: `Program.cs` pattern with version/help/validation routing -- **Standard Arguments**: Support for `-v`, `--version`, `-?`, `-h`, `--help`, `--silent`, `--validate`, `--results`, `--log` - -#### Documentation - -- **README Structure**: Follows template README.md pattern (badges, features, installation, - usage, structure, CI/CD, documentation, license) -- **Standard Files**: Presence and structure of: - - `CONTRIBUTING.md` - - `CODE_OF_CONDUCT.md` - - `SECURITY.md` - - `LICENSE` - -#### Quality Configuration - -- **Linting Rules**: `.cspell.json`, `.markdownlint-cli2.jsonc`, `.yamllint.yaml` - - Note: Spelling exceptions will be repository-specific -- **Editor Config**: `.editorconfig` settings (file-scoped namespaces, 4-space indent, UTF-8+BOM, LF endings) -- **Code Style**: C# code style rules and analyzer configuration - -#### Project Configuration - -- **csproj Sections**: Key sections in .csproj files: - - NuGet Tool Package Configuration - - Symbol Package Configuration - - Code Quality Configuration (TreatWarningsAsErrors, GenerateDocumentationFile, etc.) - - SBOM Configuration - - Common package references (DemaConsulting.TestResults, Microsoft.SourceLink.GitHub, analyzers) - -#### Documentation Generation - -- **Document Structure**: `docs/` directory with: - - `guide/` (user guide) - - `requirements/` (auto-generated) - - `justifications/` (auto-generated) - - `tracematrix/` (auto-generated) - - `buildnotes/` (auto-generated) - - `quality/` (auto-generated) -- **Definition Files**: `definition.yaml` files for document generation - -### Tracking Template Evolution - -To ensure downstream projects benefit from recent template improvements, review recent pull requests -merged into the template repository: - -1. **List Recent PRs**: Retrieve recently merged PRs from `demaconsulting/TemplateDotNetTool` - - Review the last 10-20 PRs to identify template improvements - -2. **Identify Propagatable Changes**: For each PR, determine if changes should apply to downstream - projects: - - Focus on structural changes (workflows, agents, configurations) over content-specific changes - - Note changes to `.github/`, linting configurations, project patterns, and documentation - structure - -3. **Check Downstream Application**: Verify if identified changes exist in the downstream project: - - Check if similar files/patterns exist in downstream - - Compare file contents between template and downstream project - - Look for similar PR titles or commit messages in downstream repository history - -4. **Recommend Missing Updates**: For changes not yet applied, include them in the consistency - review with: - - Description of the template change (reference PR number) - - Explanation of benefits for the downstream project - - Specific files or patterns that need updating - -This technique ensures downstream projects don't miss important template improvements and helps -maintain long-term consistency. - -### Review Process - -1. **Identify Differences**: Compare downstream repository structure with template -2. **Assess Impact**: Determine if differences are intentional variations or drift -3. **Recommend Updates**: Suggest specific files or patterns that should be updated -4. **Respect Customizations**: Recognize valid project-specific customizations - -### What NOT to Flag - -- Project-specific naming (tool names, package IDs, repository URLs) -- Project-specific spell check exceptions in `.cspell.json` -- Workflow variations for specific project needs -- Additional requirements or features beyond the template -- Project-specific dependencies - -## Defer To - -- **Software Developer Agent**: For implementing code changes recommended by consistency check -- **Technical Writer Agent**: For updating documentation to match template -- **Requirements Agent**: For updating requirements.yaml -- **Test Developer Agent**: For updating test patterns -- **Code Quality Agent**: For applying linting and code style changes - -## Usage Pattern - -This agent is typically invoked on downstream repositories (not on TemplateDotNetTool itself): - -1. Clone or access the downstream repository -2. Invoke repo-consistency-agent to review consistency with the TemplateDotNetTool template () -3. Review agent recommendations -4. Apply relevant changes using appropriate specialized agents -5. Test changes to ensure they don't break existing functionality - -## Key Principles - -- **Template Evolution**: As the template evolves, this agent helps downstream projects stay current -- **Respect Customization**: Not all differences are problems - some are valid customizations -- **Incremental Adoption**: Downstream projects can adopt template changes incrementally -- **Documentation**: When recommending changes, explain why they align with best practices diff --git a/.github/agents/repo-consistency.agent.md b/.github/agents/repo-consistency.agent.md new file mode 100644 index 0000000..dfaf702 --- /dev/null +++ b/.github/agents/repo-consistency.agent.md @@ -0,0 +1,80 @@ +--- +name: repo-consistency +description: > + Ensures downstream repositories remain consistent with the TemplateDotNetTool + template patterns and best practices. +user-invocable: true +--- + +# Repo Consistency Agent + +Maintain consistency between downstream projects and the TemplateDotNetTool template, ensuring repositories +benefit from template evolution while respecting project-specific customizations. + +# Consistency Workflow (MANDATORY) + +**CRITICAL**: This agent MUST follow these steps systematically to ensure proper template consistency analysis: + +1. **Fetch Recent Template Changes**: Use GitHub search to fetch the 20 most recently merged PRs + (`is:pr is:merged sort:updated-desc`) from +2. **Analyze Template Evolution**: For each relevant PR, determine the intent and scope of changes + (what files were modified, what improvements were made) +3. **Assess Downstream Applicability**: Evaluate which template changes would benefit this repository + while respecting project-specific customizations +4. **Apply Appropriate Updates**: Implement applicable template improvements with proper translation for project context +5. **Validate Consistency**: Verify that applied changes maintain functionality and follow project patterns + +## Key Principles + +- **Evolutionary Consistency**: Template improvements should enhance downstream projects systematically +- **Intelligent Customization Respect**: Distinguish valid customizations from unintentional drift +- **Incremental Template Adoption**: Support phased adoption of template improvements based on project capacity + +# Don't Do These Things + +- **Never recommend changes without understanding project context** (some differences are intentional) +- **Never flag valid project-specific customizations** as consistency problems +- **Never apply template changes blindly** without assessing downstream project impact +- **Never ignore template evolution benefits** when they clearly improve downstream projects +- **Never recommend breaking changes** without migration guidance and impact assessment +- **Never skip validation** of preserved functionality after template alignment +- **Never assume all template patterns apply universally** (assess project-specific needs) + +# Reporting + +Upon completion create a summary in `.agent-logs/[agent-name]-[subject]-[unique-id].md` +of the project consisting of: + +```markdown +# Repo Consistency Report + +**Result**: + +## Consistency Analysis + +- **Template PRs Analyzed**: [Number and timeframe of PRs reviewed] +- **Template Changes Identified**: [Count and types of template improvements] +- **Applicable Updates**: [Changes determined suitable for this repository] +- **Project Customizations Preserved**: [Valid differences maintained] + +## Template Evolution Applied + +- **Files Modified**: [List of files updated for template consistency] +- **Improvements Adopted**: [Specific template enhancements implemented] +- **Configuration Updates**: [Tool configurations, workflows, or standards updated] + +## Consistency Status + +- **Template Alignment**: [Overall consistency rating with template] +- **Customization Respect**: [How project-specific needs were preserved] +- **Functionality Validation**: [Verification that changes don't break existing features] +- **Future Consistency**: [Recommendations for ongoing template alignment] + +## Issues Resolved + +- **Drift Corrections**: [Template drift issues addressed] +- **Enhancement Adoptions**: [Template improvements successfully integrated] +- **Validation Results**: [Testing and validation outcomes] +``` + +Return this summary to the caller. diff --git a/.github/agents/requirements-agent.md b/.github/agents/requirements-agent.md deleted file mode 100644 index 4f56242..0000000 --- a/.github/agents/requirements-agent.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -name: Requirements Agent -description: Develops requirements and ensures appropriate test coverage - knows which requirements need unit/integration/self-validation tests ---- - -# Requirements Agent - Template DotNet Tool - -Develop and maintain high-quality requirements with proper test coverage linkage. - -## When to Invoke This Agent - -Invoke the requirements-agent for: - -- Creating new requirements in `requirements.yaml` -- Reviewing and improving existing requirements -- Ensuring requirements have appropriate test coverage -- Determining which type of test (unit, integration, or self-validation) is appropriate -- Differentiating requirements from design details - -## Responsibilities - -### Writing Good Requirements - -- Focus on **what** the system must do, not **how** it does it -- Requirements describe observable behavior or characteristics -- Design details (implementation choices) are NOT requirements -- Use clear, testable language with measurable acceptance criteria -- Each requirement should be traceable to test evidence - -### Test Coverage Strategy - -- **All requirements MUST be linked to tests** - this is enforced in CI -- **Not all tests need to be linked to requirements** - tests may exist for: - - Exploring corner cases - - Testing design decisions - - Failure-testing scenarios - - Implementation validation beyond requirement scope -- **Self-validation tests** (`TemplateTool_*`): Preferred for command-line behavior, features - that ship with the product -- **Unit tests**: For internal component behavior, isolated logic -- **Integration tests**: For cross-component interactions, end-to-end scenarios - -### Requirements Format - -Follow the `requirements.yaml` structure: - -- Clear ID and description -- Justification explaining why the requirement is needed -- Linked to appropriate test(s) -- Enforced via: `dotnet reqstream --requirements requirements.yaml --tests "test-results/**/*.trx" --enforce` - -### Test Source Filters - -Test links in `requirements.yaml` can include a source filter prefix to restrict which test results count as -evidence. This is critical for platform and framework requirements - **never remove these filters**. - -- `windows@TestName` - proves the test passed on a Windows platform -- `ubuntu@TestName` - proves the test passed on a Linux (Ubuntu) platform -- `net8.0@TestName` - proves the test passed under the .NET 8 target framework -- `net9.0@TestName` - proves the test passed under the .NET 9 target framework -- `net10.0@TestName` - proves the test passed under the .NET 10 target framework -- `dotnet8.x@TestName` - proves the self-validation test ran on a machine with .NET 8.x runtime -- `dotnet9.x@TestName` - proves the self-validation test ran on a machine with .NET 9.x runtime -- `dotnet10.x@TestName` - proves the self-validation test ran on a machine with .NET 10.x runtime - -Without the source filter, a test result from any platform/framework satisfies the requirement. Removing a -filter invalidates the evidence for platform/framework requirements. - -## Defer To - -- **Software Developer Agent**: For implementing self-validation tests -- **Test Developer Agent**: For implementing unit and integration tests -- **Technical Writer Agent**: For documentation of requirements and processes -- **Code Quality Agent**: For verifying test quality and enforcement - -## Don't - -- Mix requirements with implementation details -- Create requirements without test linkage -- Expect all tests to be linked to requirements (some tests exist for other purposes) -- Change code directly (delegate to developer agents) diff --git a/.github/agents/software-developer.md b/.github/agents/software-developer.md deleted file mode 100644 index 91aa379..0000000 --- a/.github/agents/software-developer.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -name: Software Developer -description: Writes production code and self-validation tests - targets design-for-testability and literate programming style ---- - -# Software Developer - Template DotNet Tool - -Develop production code and self-validation tests with emphasis on testability and clarity. - -## When to Invoke This Agent - -Invoke the software-developer for: - -- 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 - -## Responsibilities - -### Code Style - Literate Programming - -Write code in a **literate style**: - -- 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 - -Example: - -```csharp -// Parse the command line arguments -var options = ParseArguments(args); - -// Validate the input file exists -if (!File.Exists(options.InputFile)) - throw new InvalidOperationException($"Input file not found: {options.InputFile}"); - -// Process the file contents -var results = ProcessFile(options.InputFile); -``` - -### Design for Testability - -- Small, focused functions with single responsibilities -- Dependency injection for external dependencies -- Avoid hidden state and side effects -- Clear separation of concerns - -### Template DotNet Tool-Specific Rules - -- **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 - -### Self-Validation Tests - -- 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` - -## Defer To - -- **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 - -## Don't - -- Write code without explanatory comments -- Create large monolithic functions -- Skip XML documentation -- Ignore the literate programming style diff --git a/.github/agents/technical-writer.md b/.github/agents/technical-writer.md deleted file mode 100644 index 1f62e0c..0000000 --- a/.github/agents/technical-writer.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -name: Technical Writer -description: Ensures documentation is accurate and complete - knowledgeable about regulatory documentation and special document types ---- - -# Technical Writer - Template DotNet Tool - -Create and maintain clear, accurate, and complete documentation following best practices. - -## When to Invoke This Agent - -Invoke the technical-writer for: - -- Creating or updating project documentation (README, guides, CONTRIBUTING, etc.) -- Ensuring documentation accuracy and completeness -- Applying regulatory documentation best practices (purpose, scope statements) -- Special document types (architecture, design, user guides) -- Markdown and spell checking compliance - -## Responsibilities - -### Documentation Best Practices - -- **Purpose statements**: Why the document exists, what problem it solves -- **Scope statements**: What is covered and what is explicitly out of scope -- **Architecture docs**: System structure, component relationships, key design decisions -- **Design docs**: Implementation approach, algorithms, data structures -- **User guides**: Task-oriented, clear examples, troubleshooting - -### Template DotNet Tool-Specific Rules - -#### Markdown Style - -- **All markdown files**: Use reference-style links `[text][ref]` with `[ref]: url` at document end -- **Exceptions**: - - **README.md**: Use absolute URLs in the links (shipped in NuGet package) - - **AI agent markdown files** (`.github/agents/*.md`): Use inline links `[text](url)` so URLs are visible in agent context -- Max 120 characters per line -- Lists require blank lines (MD032) - -#### Linting Requirements - -- **markdownlint**: Style and structure compliance -- **cspell**: Spelling (add technical terms to `.cspell.json`) -- **yamllint**: YAML file validation - -### Regulatory Documentation - -For documents requiring regulatory compliance: - -- Clear purpose and scope sections -- Appropriate detail level for audience -- Traceability to requirements where applicable - -## Defer To - -- **Requirements Agent**: For requirements.yaml content and test linkage -- **Software Developer Agent**: For code examples and self-validation behavior -- **Test Developer Agent**: For test documentation -- **Code Quality Agent**: For running linters and fixing lint issues - -## Don't - -- Change code to match documentation (code is source of truth) -- Document non-existent features -- Skip linting before committing changes diff --git a/.github/agents/test-developer.md b/.github/agents/test-developer.md deleted file mode 100644 index ae33179..0000000 --- a/.github/agents/test-developer.md +++ /dev/null @@ -1,147 +0,0 @@ ---- -name: Test Developer -description: Writes unit and integration tests following AAA pattern - clear documentation of what's tested and proved ---- - -# Test Developer - Template DotNet Tool - -Develop comprehensive unit and integration tests following best practices. - -## When to Invoke This Agent - -Invoke the test-developer for: - -- Creating unit tests for individual components -- Creating integration tests for cross-component behavior -- Improving test coverage -- Refactoring existing tests for clarity - -## Responsibilities - -### AAA Pattern (Arrange-Act-Assert) - -All tests must follow the AAA pattern with clear sections: - -```csharp -[TestMethod] -public void ClassName_MethodUnderTest_Scenario_ExpectedBehavior() -{ - // Arrange - Set up test conditions - var input = "test data"; - var expected = "expected result"; - var component = new Component(); - - // Act - Execute the behavior being tested - var actual = component.Method(input); - - // Assert - Verify the results - Assert.AreEqual(expected, actual); -} -``` - -### Test Documentation - -- Test name clearly states what is being tested and the scenario -- Comments document: - - What is being tested (the behavior/requirement) - - What the assertions prove (the expected outcome) - - Any non-obvious setup or conditions - -### Test Quality - -- Tests should be independent and isolated -- Each test verifies one behavior/scenario -- Use meaningful test data (avoid magic values) -- Clear failure messages for assertions -- Consider edge cases and error conditions - -### Tests and Requirements - -- **All requirements MUST have linked tests** - this is enforced in CI -- **Not all tests need requirements** - tests may be created for: - - Exploring corner cases not explicitly stated in requirements - - Testing design decisions and implementation details - - Failure-testing and error handling scenarios - - Verifying internal behavior beyond requirement scope - -### Test Source Filters - -Test links in `requirements.yaml` can include a source filter prefix to restrict which test results count as -evidence. These filters are critical for platform and framework requirements - **do not remove them**. - -- `windows@TestName` - proves the test passed on a Windows platform -- `ubuntu@TestName` - proves the test passed on a Linux (Ubuntu) platform -- `net8.0@TestName` - proves the test passed under the .NET 8 target framework -- `net9.0@TestName` - proves the test passed under the .NET 9 target framework -- `net10.0@TestName` - proves the test passed under the .NET 10 target framework -- `dotnet8.x@TestName` - proves the self-validation test ran on a machine with .NET 8.x runtime -- `dotnet9.x@TestName` - proves the self-validation test ran on a machine with .NET 9.x runtime -- `dotnet10.x@TestName` - proves the self-validation test ran on a machine with .NET 10.x runtime - -Removing a source filter means a test result from any environment can satisfy the requirement, which invalidates -the evidence-based proof that the tool works on a specific platform or framework. - -### Template DotNet Tool-Specific - -- **NOT self-validation tests** - those are handled by Software Developer Agent -- Unit tests live in `test/` directory -- Use MSTest V4 testing framework -- Follow existing naming conventions in the test suite - -### MSTest V4 Best Practices - -Common anti-patterns to avoid (not exhaustive): - -1. **Avoid Assertions in Catch Blocks (MSTEST0058)** - Instead of wrapping code in try/catch and asserting in the - catch block, use `Assert.ThrowsExactly()`: - - ```csharp - var ex = Assert.ThrowsExactly(() => SomeWork()); - Assert.Contains("Some message", ex.Message); - ``` - -2. **Avoid using Assert.IsTrue / Assert.IsFalse for equality checks** - Use `Assert.AreEqual` / - `Assert.AreNotEqual` instead, as it provides better failure messages: - - ```csharp - // ❌ Bad: Assert.IsTrue(result == expected); - // ✅ Good: Assert.AreEqual(expected, result); - ``` - -3. **Avoid non-public test classes and methods** - Test classes and `[TestMethod]` methods must be `public` or - they will be silently ignored: - - ```csharp - // ❌ Bad: internal class MyTests - // ✅ Good: public class MyTests - ``` - -4. **Avoid Assert.IsTrue(collection.Count == N)** - Use `Assert.HasCount` for count assertions: - - ```csharp - // ❌ Bad: Assert.IsTrue(collection.Count == 3); - // ✅ Good: Assert.HasCount(3, collection); - ``` - -5. **Avoid Assert.IsTrue for string prefix checks** - Use `Assert.StartsWith` instead of wrapping - `string.StartsWith` in `Assert.IsTrue`, as it produces clearer failure messages that show the expected prefix - and actual value: - - ```csharp - // ❌ Bad: Assert.IsTrue(value.StartsWith("prefix")); - // ✅ Good: Assert.StartsWith("prefix", value); - ``` - -## Defer To - -- **Requirements Agent**: For test strategy and coverage requirements -- **Software Developer Agent**: For self-validation tests and production code issues -- **Technical Writer Agent**: For test documentation in markdown -- **Code Quality Agent**: For test linting and static analysis - -## Don't - -- Write tests that test multiple behaviors in one test -- Skip test documentation -- Create brittle tests with tight coupling to implementation details -- Write self-validation tests (delegate to Software Developer Agent) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index ef4e742..841fbb2 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -43,9 +43,7 @@ Before submitting this pull request, ensure you have completed the following: Please run the following checks before submitting: -- [ ] **Spell checker passes**: `cspell "**/*.{md,cs}"` -- [ ] **Markdown linter passes**: `markdownlint "**/*.md"` -- [ ] **YAML linter passes**: `yamllint .` +- [ ] **All linters pass**: `./lint.sh` (Unix/macOS) or `cmd /c lint.bat` / `./lint.bat` (Windows) ### Testing diff --git a/.github/standards/csharp-language.md b/.github/standards/csharp-language.md new file mode 100644 index 0000000..880544a --- /dev/null +++ b/.github/standards/csharp-language.md @@ -0,0 +1,86 @@ +# C# Language Coding Standards + +This document defines DEMA Consulting standards for C# software development +within Continuous Compliance environments. + +## Literate Programming Style (MANDATORY) + +Write all C# code in literate style because regulatory environments require +code that can be independently verified against requirements by reviewers. + +- **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. + +### Example + +```csharp +// 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); + +// Apply business rules and validation logic +var validatedResults = BusinessRuleEngine.ValidateAndProcess(processedData); + +// Return formatted results matching the expected output contract +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 + +## Quality Checks + +Before submitting C# code, verify: + +- [ ] 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 diff --git a/.github/standards/csharp-testing.md b/.github/standards/csharp-testing.md new file mode 100644 index 0000000..6cee284 --- /dev/null +++ b/.github/standards/csharp-testing.md @@ -0,0 +1,119 @@ +# C# Testing Standards (MSTest) + +This document defines DEMA Consulting standards for C# test development using +MSTest within Continuous Compliance environments. + +# AAA Pattern Implementation (MANDATORY) + +Structure all tests using Arrange-Act-Assert pattern because regulatory reviews +require clear test logic that can be independently verified against +requirements. + +```csharp +[TestMethod] +public void ServiceName_MethodName_Scenario_ExpectedBehavior() +{ + // Arrange - (description) + // TODO: Set up test data, mocks, and system under test. + + // Act - (description) + // TODO: Execute the action being tested + + // Assert - (description) + // TODO: Verify expected outcomes and interactions +} +``` + +# Test Naming Standards + +Use descriptive test names because test names appear in requirements traceability matrices and compliance reports. + +- **Pattern**: `ClassName_MethodUnderTest_Scenario_ExpectedBehavior` +- **Descriptive Scenarios**: Clearly describe the input condition being tested +- **Expected Behavior**: State the expected outcome or exception + +## Examples + +- `UserValidator_ValidateEmail_ValidFormat_ReturnsTrue` +- `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 + +# Mock Dependencies + +Mock external dependencies using NSubstitute (preferred) because tests must run in isolation to generate +reliable evidence. + +- **Isolate System Under Test**: Mock all external dependencies (databases, web services, file systems) +- **Verify Interactions**: Assert that expected method calls occurred with correct parameters +- **Predictable Behavior**: Set up mocks to return known values for consistent test results + +# MSTest V4 Antipatterns + +Avoid these common MSTest V4 patterns because they produce poor error messages or cause tests to be silently ignored. + +# Avoid Assertions in Catch Blocks (MSTEST0058) + +Instead of wrapping code in try/catch and asserting in the catch block, use `Assert.ThrowsExactly()`: + +```csharp +var ex = Assert.ThrowsExactly(() => SomeWork()); +Assert.Contains("Some message", ex.Message); +``` + +# Avoid Assert.IsTrue/IsFalse for Equality Checks + +Use `Assert.AreEqual`/`Assert.AreNotEqual` instead, as they provide better failure messages: + +```csharp +// ❌ Bad: Assert.IsTrue(result == expected); +// ✅ Good: Assert.AreEqual(expected, result); +``` + +# Avoid Non-Public Test Classes and Methods + +Test classes and `[TestMethod]` methods must be `public` or they will be silently ignored: + +```csharp +// ❌ Bad: internal class MyTests +// ✅ Good: public class MyTests +``` + +# Avoid Assert.IsTrue for Collection Count + +Use `Assert.HasCount` for count assertions: + +```csharp +// ❌ Bad: Assert.IsTrue(collection.Count == 3); +// ✅ Good: Assert.HasCount(3, collection); +``` + +# Avoid Assert.IsTrue for String Prefix Checks + +Use `Assert.StartsWith` instead, as it produces clearer failure messages: + +```csharp +// ❌ Bad: Assert.IsTrue(value.StartsWith("prefix")); +// ✅ Good: Assert.StartsWith("prefix", value); +``` + +# Quality Checks + +Before submitting C# tests, verify: + +- [ ] All tests follow AAA pattern with clear section comments +- [ ] Test names follow `ClassName_MethodUnderTest_Scenario_ExpectedBehavior` +- [ ] 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 linked to requirements with source filters where needed +- [ ] Test results generate TRX format for ReqStream compatibility +- [ ] MSTest V4 antipatterns avoided (proper assertions, public visibility, etc.) diff --git a/.github/standards/reqstream-usage.md b/.github/standards/reqstream-usage.md new file mode 100644 index 0000000..3f99929 --- /dev/null +++ b/.github/standards/reqstream-usage.md @@ -0,0 +1,146 @@ +# ReqStream Requirements Management Standards + +This document defines DEMA Consulting standards for requirements management +using ReqStream within Continuous Compliance environments. + +# Core Principles + +ReqStream implements Continuous Compliance methodology for automated evidence +generation: + +- **Requirements Traceability**: Every requirement MUST link to passing tests +- **Platform Evidence**: Source filters ensure correct testing environment + validation +- **Quality Gate Enforcement**: CI/CD fails on requirements without test + coverage +- **Audit Documentation**: Generated reports provide compliance evidence + +# Requirements Organization + +Organize requirements into separate files under `docs/reqstream/` for +independent review: + +```text +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 +``` + +# Requirements File Format + +```yaml +sections: + - title: Functional Requirements + requirements: + - id: Project-Component-Feature + title: The system shall perform the required function. + justification: | + Business rationale explaining why this requirement exists. + Include regulatory or standard references where applicable. + tests: + - TestMethodName + - windows@PlatformSpecificTest # Source filter for platform evidence +``` + +# OTS Software Requirements + +Document third-party component requirements with specific section structure: + +```yaml +sections: + - title: OTS Software Requirements + sections: + - title: System.Text.Json + requirements: + - id: Project-SystemTextJson-ReadJson + title: System.Text.Json shall be able to read JSON files. + tests: + - JsonReaderTests.TestReadValidJson +``` + +# Semantic IDs (MANDATORY) + +Use meaningful IDs following `Project-Section-ShortDesc` pattern: + +- **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: + +```yaml +tests: + - "windows@TestMethodName" # Windows platform evidence only + - "ubuntu@TestMethodName" # Linux platform evidence only + - "net8.0@TestMethodName" # .NET 8 runtime evidence only + - "TestMethodName" # Any platform evidence acceptable +``` + +**WARNING**: Removing source filters invalidates platform-specific compliance +evidence. + +# ReqStream Commands + +Essential ReqStream commands for Continuous Compliance: + +```bash +# Lint requirement files for issues (run before use) +dotnet reqstream \ + --requirements requirements.yaml \ + --lint + +# Enforce requirements traceability (use in CI/CD) +dotnet reqstream \ + --requirements requirements.yaml \ + --tests "artifacts/**/*.trx" \ + --enforce + +# Generate requirements report +dotnet reqstream \ + --requirements requirements.yaml \ + --report docs/requirements_doc/requirements.md + +# Generate justifications report +dotnet reqstream \ + --requirements requirements.yaml \ + --justifications docs/requirements_doc/justifications.md + +# Generate trace matrix +dotnet reqstream \ + --requirements requirements.yaml \ + --tests "artifacts/**/*.trx" \ + --matrix docs/requirements_report/trace_matrix.md +``` + +# Quality Checks + +Before submitting requirements, verify: + +- [ ] All requirements have semantic IDs (`Project-Section-Feature` pattern) +- [ ] Every requirement links to at least one passing test +- [ ] 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 +- [ ] 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 new file mode 100644 index 0000000..bdabd1d --- /dev/null +++ b/.github/standards/reviewmark-usage.md @@ -0,0 +1,151 @@ +# ReviewMark File Review Standards + +This document defines DEMA Consulting standards for managing file reviews using +ReviewMark within Continuous Compliance environments. + +# Core Purpose + +ReviewMark automates file review tracking using cryptographic fingerprints to +ensure: + +- Every file requiring review is covered by a current, valid review +- Reviews become stale when files change, triggering re-review +- Complete audit trail of review coverage for regulatory compliance + +# Review Definition Structure + +Configure reviews in `.reviewmark.yaml` at repository root: + +```yaml +# 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 + + # Exclude build output and generated content + - "!**/obj/**" # Exclude build output + - "!**/bin/**" # Exclude binary output + - "!**/generated/**" # Exclude auto-generated files + +# Source of review evidence +evidence-source: + type: none + +# Named review-sets grouping related files +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" + + - id: MyProduct-AllRequirements + title: All Requirements Review + paths: + - "requirements.yaml" + - "docs/reqstream/**/*.yaml" +``` + +# Review-Set Organization + +Organize review-sets using standard patterns to ensure comprehensive coverage +and consistent review processes: + +## [Project]-System Review + +Reviews system integration and operational validation: + +- **Files**: System-level requirements, design introduction, system design documents, integration tests +- **Purpose**: Validates system operates as designed and meets overall requirements +- **Example**: `TemplateTool-System` + +## [Product]-Design Review + +Reviews architectural and design consistency: + +- **Files**: System-level requirements, platform requirements, all design documents +- **Purpose**: Ensures design completeness and architectural coherence +- **Example**: `MyProduct-Design` + +## [Product]-AllRequirements Review + +Reviews requirements quality and traceability: + +- **Files**: All requirement files including root `requirements.yaml` +- **Purpose**: Validates requirements structure, IDs, justifications, and test linkage +- **Example**: `MyProduct-AllRequirements` + +## [Product]-[Unit] Review + +Reviews individual software unit implementation: + +- **Files**: Unit requirements, design documents, source code, unit tests +- **Purpose**: Validates unit meets requirements and is properly implemented +- **Example**: `MyProduct-PasswordValidator`, `MyProduct-ConfigParser` + +## [Product]-[Subsystem] Review + +Reviews subsystem architecture and interfaces: + +- **Files**: Subsystem requirements, design documents, integration tests (usually no source code) +- **Purpose**: Validates subsystem behavior and interface compliance +- **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 + +# Generate review report (shows status) +dotnet reviewmark \ + --report docs/code_review_report/report.md + +# Enforce review compliance (use in CI/CD) +dotnet reviewmark \ + --plan docs/code_review_plan/plan.md \ + --report docs/code_review_report/report.md \ + --enforce +``` + +# 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 + +- **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 + +# Quality Checks + +Before submitting ReviewMark configuration, verify: + +- [ ] `.reviewmark.yaml` exists at repository root with proper structure +- [ ] `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 +- [ ] Evidence source properly configured (`none` for dev, `url` for production) +- [ ] Environment variables used for credentials (never hardcoded) +- [ ] ReviewMark enforcement configured: `dotnet reviewmark --enforce` +- [ ] Generated documents accessible for compliance auditing +- [ ] Review-set organization follows standard patterns ([Product]-[Unit], [Product]-Design, etc.) diff --git a/.github/standards/software-items.md b/.github/standards/software-items.md new file mode 100644 index 0000000..7991add --- /dev/null +++ b/.github/standards/software-items.md @@ -0,0 +1,45 @@ +# Software Items Definition Standards + +This document defines DEMA Consulting standards for categorizing software +items within Continuous Compliance environments because proper categorization +determines requirements management approach, testing strategy, and review +scope. + +# Software Item Categories + +Categorize all software into four primary groups: + +- **Software System**: Complete deliverable product including all components + and external interfaces +- **Software Subsystem**: Major architectural component with well-defined + interfaces and responsibilities +- **Software Unit**: Individual class, function, or tightly coupled set of + functions that can be tested in isolation +- **OTS Software Item**: Third-party component (library, framework, tool) + providing functionality not developed in-house + +# Categorization Guidelines + +Choose the appropriate category based on scope and testability: + +## Software System + +- Represents the entire product boundary +- Tested through system integration and end-to-end tests + +## Software Subsystem + +- Major architectural boundary (authentication, data layer, UI, communications) +- 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 + +## OTS Software Item + +- External dependency not developed in-house +- Tested through integration tests proving required functionality works +- Examples: System.Text.Json, Entity Framework, third-party APIs diff --git a/.github/standards/technical-documentation.md b/.github/standards/technical-documentation.md new file mode 100644 index 0000000..9281f1c --- /dev/null +++ b/.github/standards/technical-documentation.md @@ -0,0 +1,172 @@ +# Technical Documentation Standards + +This document defines DEMA Consulting standards for technical documentation +within Continuous Compliance environments. + +# Core Principles + +Technical documentation serves as compliance evidence and must be structured +for regulatory review: + +- **Regulatory Compliance**: Documentation provides audit evidence and must be + current, accurate, and traceable to implementation +- **Agent-Readable Format**: Documentation may be processed by AI agents and + must follow consistent structure and formatting +- **Auto-Generation Support**: Compliance reports are generated automatically + and manual documentation must integrate seamlessly +- **Review Integration**: Documentation follows ReviewMark patterns for formal + review tracking + +# Documentation Organization + +Structure documentation under `docs/` following standard patterns for +consistency and tool compatibility: + +```text +docs/ + build_notes.md # Generated by BuildMark + build_notes/ # Auto-generated build notes + versions.md # Generated by VersionMark + code_review_plan/ # Auto-generated review plans + plan.md # Generated by ReviewMark + code_review_report/ # Auto-generated review reports + report.md # Generated by ReviewMark + design/ # Design documentation + introduction.md # Design overview + system.md # System architecture + {component}.md # Component-specific designs + reqstream/ # Requirements source files + {project}-system.yaml # System requirements + platform-requirements.yaml # Platform requirements + subsystem-{name}.yaml # Subsystem requirements + unit-{name}.yaml # Unit requirements + ots-{name}.yaml # OTS requirements + requirements_doc/ # Auto-generated requirements reports + requirements.md # Generated by ReqStream + justifications.md # Generated by ReqStream + requirements_report/ # Auto-generated trace matrices + trace_matrix.md # Generated by ReqStream + user_guide/ # User-facing documentation + introduction.md # User guide overview + {section}.md # User guide sections +``` + +# Pandoc Document Structure (MANDATORY) + +All document collections processed by Pandoc MUST include: + +- `definition.yaml` - specifying the files to include +- `title.txt` - document metadata +- `introduction.md` - document introduction +- `{sections}.md` - additional document sections + +## Introduction File Format + +```markdown +# Introduction + +Brief overview of the document collection purpose and audience. + +## Purpose + +Clear statement of why this documentation exists and what problem it solves. +Include regulatory or business drivers where applicable. + +## Scope + +Define what is covered and what is explicitly excluded from this documentation. +Specify version, system boundaries, and applicability constraints. +``` + +## Document Ordering + +List documents in logical reading order in Pandoc configuration because +readers need coherent information flow from general to specific topics. + +# Writing Guidelines + +Write technical documentation for clarity and compliance verification: + +- **Clear and Concise**: Use direct language and avoid unnecessary complexity. + Regulatory reviewers must understand content quickly. +- **Structured Sections**: Use consistent heading hierarchy and section + organization. Enables automated processing and review. +- **Specific Examples**: Include concrete examples with actual values rather + than placeholders. Supports implementation verification. +- **Current Information**: Keep documentation synchronized with code changes. + Outdated documentation invalidates compliance evidence. +- **Traceable Content**: Link documentation to requirements and implementation + where applicable for audit trails. + +# Markdown Format Requirements + +Markdown documentation in this repository must follow the formatting standards +defined in `.markdownlint-cli2.jsonc` (subject to any exclusions configured there) +for consistency and professional presentation: + +- **120 Character Line Limit**: Keep lines 120 characters or fewer for readability. + Break long lines naturally at punctuation or logical breaks. +- **No Trailing Whitespace**: Remove all trailing spaces and tabs from line + endings to prevent formatting inconsistencies. +- **Blank Lines Around Headings**: Include a blank line both before and after + each heading to improve document structure and readability. +- **Blank Lines Around Lists**: Include a blank line both before and after + numbered and bullet lists to ensure proper rendering and visual separation. +- **ATX-Style Headers**: Use `#` syntax for headers instead of underline style + for consistency across all documentation. +- **Consistent List Indentation**: Use 2-space indentation for nested list + items to maintain uniform formatting. + +# Auto-Generated Content (CRITICAL) + +**NEVER modify auto-generated markdown files** because changes will be +overwritten and break compliance automation: + +- **Read-Only Files**: Generated reports under `docs/requirements_doc/`, + `docs/requirements_report/`, `docs/code_review_plan/`, and + `docs/code_review_report/` are regenerated on every build +- **Source Modification**: Update source files (requirements YAML, code + comments) instead of generated output +- **Tool Integration**: Generated content integrates with CI/CD pipelines and + manual changes disrupt automation + +# README.md Best Practices + +Structure README.md for both human readers and AI agent processing: + +## Content Requirements + +- **Project Overview**: Clear description of what the software does and why it exists +- **Installation Instructions**: Step-by-step setup with specific version requirements +- **Usage Examples**: Concrete examples with expected outputs, not just syntax +- **API Documentation**: Links to detailed API docs or inline examples for key functions +- **Contributing Guidelines**: Link to CONTRIBUTING.md with development setup +- **License Information**: Clear license statement with link to LICENSE file + +## Agent-Friendly Formatting + +- **Absolute URLs**: Use full GitHub URLs (not relative paths) for links because + agents may process README content outside repository context +- **Structured Sections**: Use consistent heading hierarchy for automated parsing +- **Code Block Languages**: Specify language for syntax highlighting and tool processing +- **Clear Prerequisites**: List exact version requirements and dependencies + +## Quality Guidelines + +- **Scannable Structure**: Use bullet points, headings, and short paragraphs +- **Current Examples**: Verify all code examples work with current version +- **Link Validation**: Ensure all external links are accessible and current +- **Consistent Tone**: Professional, helpful tone appropriate for technical audience + +# Quality Checks + +Before submitting technical documentation, verify: + +- [ ] Documentation organized under `docs/` following standard folder structure +- [ ] Pandoc collections include `introduction.md` with Purpose and Scope sections +- [ ] Content follows clear and concise writing guidelines with specific examples +- [ ] No modifications made to auto-generated markdown files in compliance folders +- [ ] README.md includes all required sections with absolute URLs and concrete examples +- [ ] Documentation integrated into ReviewMark review-sets for formal review +- [ ] Links validated and external references accessible +- [ ] Content synchronized with current code implementation and requirements diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index 8090fdf..00e7652 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -463,7 +463,7 @@ jobs: echo "Capturing tool versions..." dotnet versionmark --capture --job-id "build-docs" \ --output "artifacts/versionmark-build-docs.json" -- \ - dotnet git node npm pandoc weasyprint sarifmark sonarmark reqstream buildmark versionmark + dotnet git node npm pandoc weasyprint sarifmark sonarmark reqstream buildmark versionmark reviewmark echo "✓ Tool versions captured" # === CAPTURE OTS SELF-VALIDATION RESULTS === @@ -485,6 +485,9 @@ jobs: - name: Run SonarMark self-validation run: dotnet sonarmark --validate --results artifacts/sonarmark-self-validation.trx + - name: Run ReviewMark self-validation + run: dotnet reviewmark --validate --results artifacts/reviewmark-self-validation.trx + # === GENERATE MARKDOWN REPORTS === # This section generates all markdown reports from various tools and sources. # Downstream projects: Add any additional markdown report generation steps here. @@ -494,16 +497,16 @@ jobs: dotnet reqstream --requirements requirements.yaml --tests "artifacts/**/*.trx" - --report docs/requirements/requirements.md - --justifications docs/justifications/justifications.md - --matrix docs/tracematrix/tracematrix.md + --report docs/requirements_doc/requirements.md + --justifications docs/requirements_doc/justifications.md + --matrix docs/requirements_report/trace_matrix.md --enforce - name: Generate CodeQL Quality Report with SarifMark run: > dotnet sarifmark --sarif artifacts/csharp.sarif - --report docs/quality/codeql-quality.md + --report docs/code_quality/codeql-quality.md --heading "NuGet Cache Tool CodeQL Analysis" --report-depth 1 @@ -511,7 +514,7 @@ jobs: shell: bash run: | echo "=== CodeQL Quality Report ===" - cat docs/quality/codeql-quality.md + cat docs/code_quality/codeql-quality.md - name: Generate SonarCloud Quality Report shell: bash @@ -523,14 +526,36 @@ jobs: --project-key demaconsulting_NuGetCacheTool --branch ${{ github.ref_name }} --token "$SONAR_TOKEN" - --report docs/quality/sonar-quality.md + --report docs/code_quality/sonar-quality.md --report-depth 1 - name: Display SonarCloud Quality Report shell: bash run: | echo "=== SonarCloud Quality Report ===" - cat docs/quality/sonar-quality.md + cat docs/code_quality/sonar-quality.md + + - name: Generate Review Plan and Review Report with ReviewMark + shell: bash + # TODO: Add --enforce once reviews branch is populated with review evidence PDFs and index.json + run: > + dotnet reviewmark + --plan docs/code_review_plan/plan.md + --plan-depth 1 + --report docs/code_review_report/report.md + --report-depth 1 + + - name: Display Review Plan + shell: bash + run: | + echo "=== Review Plan ===" + cat docs/code_review_plan/plan.md + + - name: Display Review Report + shell: bash + run: | + echo "=== Review Report ===" + cat docs/code_review_report/report.md - name: Generate Build Notes with BuildMark shell: bash @@ -539,20 +564,20 @@ jobs: run: > dotnet buildmark --build-version ${{ inputs.version }} - --report docs/buildnotes.md + --report docs/build_notes.md --report-depth 1 - name: Display Build Notes Report shell: bash run: | echo "=== Build Notes Report ===" - cat docs/buildnotes.md + cat docs/build_notes.md - name: Publish Tool Versions shell: bash run: | echo "Publishing tool versions..." - dotnet versionmark --publish --report docs/buildnotes/versions.md --report-depth 1 \ + dotnet versionmark --publish --report docs/build_notes/versions.md --report-depth 1 \ -- "artifacts/**/versionmark-*.json" echo "✓ Tool versions published" @@ -560,7 +585,7 @@ jobs: shell: bash run: | echo "=== Tool Versions Report ===" - cat docs/buildnotes/versions.md + cat docs/build_notes/versions.md # === GENERATE HTML DOCUMENTS WITH PANDOC === # This section converts markdown documents to HTML using Pandoc. @@ -570,11 +595,11 @@ jobs: shell: bash run: > dotnet pandoc - --defaults docs/buildnotes/definition.yaml + --defaults docs/build_notes/definition.yaml --filter node_modules/.bin/mermaid-filter.cmd --metadata version="${{ inputs.version }}" --metadata date="$(date +'%Y-%m-%d')" - --output docs/buildnotes/buildnotes.html + --output docs/build_notes/build_notes.html - name: Generate Guide HTML with Pandoc shell: bash @@ -590,41 +615,51 @@ jobs: shell: bash run: > dotnet pandoc - --defaults docs/quality/definition.yaml + --defaults docs/code_quality/definition.yaml --filter node_modules/.bin/mermaid-filter.cmd --metadata version="${{ inputs.version }}" --metadata date="$(date +'%Y-%m-%d')" - --output docs/quality/quality.html + --output docs/code_quality/quality.html - name: Generate Requirements HTML with Pandoc shell: bash run: > dotnet pandoc - --defaults docs/requirements/definition.yaml + --defaults docs/requirements_doc/definition.yaml --filter node_modules/.bin/mermaid-filter.cmd --metadata version="${{ inputs.version }}" --metadata date="$(date +'%Y-%m-%d')" - --output docs/requirements/requirements.html + --output docs/requirements_doc/requirements.html - - name: Generate Requirements Justifications HTML with Pandoc + - name: Generate Trace Matrix HTML with Pandoc shell: bash run: > dotnet pandoc - --defaults docs/justifications/definition.yaml + --defaults docs/requirements_report/definition.yaml --filter node_modules/.bin/mermaid-filter.cmd --metadata version="${{ inputs.version }}" --metadata date="$(date +'%Y-%m-%d')" - --output docs/justifications/justifications.html + --output docs/requirements_report/trace_matrix.html - - name: Generate Trace Matrix HTML with Pandoc + - name: Generate Review Plan HTML with Pandoc + shell: bash + run: > + dotnet pandoc + --defaults docs/code_review_plan/definition.yaml + --filter node_modules/.bin/mermaid-filter.cmd + --metadata version="${{ inputs.version }}" + --metadata date="$(date +'%Y-%m-%d')" + --output docs/code_review_plan/plan.html + + - name: Generate Review Report HTML with Pandoc shell: bash run: > dotnet pandoc - --defaults docs/tracematrix/definition.yaml + --defaults docs/code_review_report/definition.yaml --filter node_modules/.bin/mermaid-filter.cmd --metadata version="${{ inputs.version }}" --metadata date="$(date +'%Y-%m-%d')" - --output docs/tracematrix/tracematrix.html + --output docs/code_review_report/report.html # === GENERATE PDF DOCUMENTS WITH WEASYPRINT === # This section converts HTML documents to PDF using Weasyprint. @@ -634,7 +669,7 @@ jobs: run: > dotnet weasyprint --pdf-variant pdf/a-3u - docs/buildnotes/buildnotes.html + docs/build_notes/build_notes.html "docs/NuGetCacheTool Build Notes.pdf" - name: Generate Guide PDF with Weasyprint @@ -648,29 +683,36 @@ jobs: run: > dotnet weasyprint --pdf-variant pdf/a-3u - docs/quality/quality.html + docs/code_quality/quality.html "docs/NuGetCacheTool Code Quality.pdf" - name: Generate Requirements PDF with Weasyprint run: > dotnet weasyprint --pdf-variant pdf/a-3u - docs/requirements/requirements.html + docs/requirements_doc/requirements.html "docs/NuGetCacheTool Requirements.pdf" - - name: Generate Requirements Justifications PDF with Weasyprint + - name: Generate Trace Matrix PDF with Weasyprint + run: > + dotnet weasyprint + --pdf-variant pdf/a-3u + docs/requirements_report/trace_matrix.html + "docs/NuGetCacheTool Trace Matrix.pdf" + + - name: Generate Review Plan PDF with Weasyprint run: > dotnet weasyprint --pdf-variant pdf/a-3u - docs/justifications/justifications.html - "docs/NuGetCacheTool Requirements Justifications.pdf" + docs/code_review_plan/plan.html + "docs/NuGetCacheTool Review Plan.pdf" - - name: Generate Trace Matrix PDF with Weasyprint + - name: Generate Review Report PDF with Weasyprint run: > dotnet weasyprint --pdf-variant pdf/a-3u - docs/tracematrix/tracematrix.html - "docs/NuGetCacheTool Trace Matrix.pdf" + docs/code_review_report/report.html + "docs/NuGetCacheTool Review Report.pdf" # === UPLOAD ARTIFACTS === # This section uploads all generated documentation artifacts. @@ -682,4 +724,4 @@ jobs: name: documents path: | docs/*.pdf - docs/buildnotes.md + docs/build_notes.md diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index 9a81642..842250d 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -63,18 +63,13 @@ jobs: name: documents path: artifacts - - name: Move buildnotes.md to root - run: | - set -e - mv artifacts/buildnotes.md buildnotes.md - - name: Create GitHub Release if: inputs.publish == 'release' || inputs.publish == 'publish' uses: ncipollo/release-action@v1 with: tag: ${{ inputs.version }} artifacts: artifacts/* - bodyFile: buildnotes.md + bodyFile: artifacts/build_notes.md generateReleaseNotes: false - name: Publish to NuGet.org diff --git a/.gitignore b/.gitignore index 467dfd7..2e3a6a0 100644 --- a/.gitignore +++ b/.gitignore @@ -90,13 +90,15 @@ __pycache__/ docs/**/*.html docs/**/*.pdf !docs/template/** -docs/requirements/requirements.md -docs/justifications/justifications.md -docs/tracematrix/tracematrix.md -docs/quality/codeql-quality.md -docs/quality/sonar-quality.md -docs/buildnotes.md -docs/buildnotes/versions.md +docs/requirements_doc/requirements.md +docs/requirements_doc/justifications.md +docs/requirements_report/trace_matrix.md +docs/code_quality/codeql-quality.md +docs/code_quality/sonar-quality.md +docs/build_notes.md +docs/build_notes/versions.md +docs/code_review_plan/plan.md +docs/code_review_report/report.md # Test results TestResults/ @@ -114,3 +116,4 @@ versionmark-*.json # Agent report files AGENT_REPORT_*.md +.agent-logs/ diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc index a46ee1a..17429e9 100644 --- a/.markdownlint-cli2.jsonc +++ b/.markdownlint-cli2.jsonc @@ -1,4 +1,6 @@ { + "noBanner": true, + "noProgress": true, "config": { "default": true, "MD003": { "style": "atx" }, @@ -10,6 +12,7 @@ }, "ignores": [ "node_modules", - "**/AGENT_REPORT_*.md" + "**/AGENT_REPORT_*.md", + "**/.agent-logs/**" ] } diff --git a/.reviewmark.yaml b/.reviewmark.yaml new file mode 100644 index 0000000..b7512b6 --- /dev/null +++ b/.reviewmark.yaml @@ -0,0 +1,62 @@ +--- +# ReviewMark Configuration File +# This file defines which files require review, where the evidence store is located, +# and how files are grouped into named review-sets following software unit boundaries. + +# Patterns identifying all files that require review. +# Processed in order; prefix a pattern with '!' to exclude. +needs-review: + - "requirements.yaml" # Requirement (top-level) + - "docs/reqstream/**/*.yaml" # Requirements files + - "docs/design/**/*.md" # Design documentation + - "**/*.cs" # All C# source and test files + - "!**/obj/**" # Exclude build output + - "!**/bin/**" # Exclude build output + +# Evidence source: review data and index.json are located in the 'reviews' branch +# of this repository, accessed through the GitHub public HTTPS raw content access. +# Note: The 'reviews' branch must be created and populated with review evidence PDFs +# and an index.json before enforcement (--enforce flag) can be enabled in the pipeline. +evidence-source: + type: url + location: https://raw.githubusercontent.com/demaconsulting/NuGetCacheTool/reviews/index.json + +# Review sets grouping files by logical unit of review. +# Each review-set groups requirements, source, and tests for a coherent software unit +# so that an AI-assisted review can verify consistency across the full evidence chain. +reviews: + # Software unit reviews - one per class + - id: NuGetCacheTool-Context + title: Review of NuGet Cache Tool Context Unit + paths: + - "docs/reqstream/ots-mstest.yaml" + - "src/**/Context.cs" + - "test/**/ContextTests.cs" + + - id: NuGetCacheTool-Program + title: Review of NuGet Cache Tool Program Unit + paths: + - "src/**/Program.cs" + - "test/**/IntegrationTests.cs" + - "test/**/AssemblyInfo.cs" + + - id: NuGetCacheTool-Validation + title: Review of NuGet Cache Tool Validation Unit + paths: + - "src/**/Validation.cs" + + - id: NuGetCacheTool-PathHelpers + title: Review of NuGet Cache Tool PathHelpers Unit + paths: + - "src/**/PathHelpers.cs" + + # Platform and OTS dependency reviews + - id: OTS-Dependencies + title: Review of Off-The-Shelf Software Dependencies + paths: + - "docs/reqstream/ots-buildmark.yaml" + - "docs/reqstream/ots-reqstream.yaml" + - "docs/reqstream/ots-sarifmark.yaml" + - "docs/reqstream/ots-sonarmark.yaml" + - "docs/reqstream/ots-reviewmark.yaml" + - "docs/reqstream/ots-versionmark.yaml" diff --git a/.versionmark.yaml b/.versionmark.yaml index b8bf259..6fa4e84 100644 --- a/.versionmark.yaml +++ b/.versionmark.yaml @@ -26,39 +26,44 @@ tools: # SonarScanner for .NET (from dotnet tool list) dotnet-sonarscanner: command: dotnet tool list - regex: '(?i)dotnet-sonarscanner\s+(?\d+\.\d+\.\d+)' + regex: '(?i)dotnet-sonarscanner\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)' # Pandoc (DemaConsulting.PandocTool from dotnet tool list) pandoc: command: dotnet tool list - regex: '(?i)demaconsulting\.pandoctool\s+(?\d+\.\d+\.\d+)' + regex: '(?i)demaconsulting\.pandoctool\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)' # WeasyPrint (DemaConsulting.WeasyPrintTool from dotnet tool list) weasyprint: command: dotnet tool list - regex: '(?i)demaconsulting\.weasyprinttool\s+(?\d+\.\d+\.\d+)' + regex: '(?i)demaconsulting\.weasyprinttool\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)' # SarifMark (DemaConsulting.SarifMark from dotnet tool list) sarifmark: command: dotnet tool list - regex: '(?i)demaconsulting\.sarifmark\s+(?\d+\.\d+\.\d+)' + regex: '(?i)demaconsulting\.sarifmark\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)' # SonarMark (DemaConsulting.SonarMark from dotnet tool list) sonarmark: command: dotnet tool list - regex: '(?i)demaconsulting\.sonarmark\s+(?\d+\.\d+\.\d+)' + regex: '(?i)demaconsulting\.sonarmark\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)' # ReqStream (DemaConsulting.ReqStream from dotnet tool list) reqstream: command: dotnet tool list - regex: '(?i)demaconsulting\.reqstream\s+(?\d+\.\d+\.\d+)' + regex: '(?i)demaconsulting\.reqstream\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)' # BuildMark (DemaConsulting.BuildMark from dotnet tool list) buildmark: command: dotnet tool list - regex: '(?i)demaconsulting\.buildmark\s+(?\d+\.\d+\.\d+)' + regex: '(?i)demaconsulting\.buildmark\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)' # VersionMark (DemaConsulting.VersionMark from dotnet tool list) versionmark: command: dotnet tool list - regex: '(?i)demaconsulting\.versionmark\s+(?\d+\.\d+\.\d+)' + regex: '(?i)demaconsulting\.versionmark\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)' + + # ReviewMark (DemaConsulting.ReviewMark from dotnet tool list) + reviewmark: + command: dotnet tool list + regex: '(?i)demaconsulting\.reviewmark\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)' diff --git a/.yamllint.yaml b/.yamllint.yaml index d0aef17..a0c19c9 100644 --- a/.yamllint.yaml +++ b/.yamllint.yaml @@ -4,6 +4,9 @@ extends: default +ignore: | + .agent-logs/ + rules: # Allow 'on:' in GitHub Actions workflows (not a boolean value) truthy: diff --git a/AGENTS.md b/AGENTS.md index 0245590..c162f9a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,26 +3,57 @@ Project-specific guidance for agents working on NuGet Cache Tool - a NuGet cache management tool for DEMA Consulting .NET developers. +## Standards Application (ALL Agents Must Follow) + +Before performing any work, agents must read and apply the relevant standards from `.github/standards/`: + +- **`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) +- **`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) + +Load only the standards relevant to your specific task scope and apply their +quality checks and guidelines throughout your work. + +## Agent Delegation Guidelines + +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 + ## Available Specialized Agents -- **Requirements Agent** - Develops requirements and ensures test coverage linkage -- **Technical Writer** - Creates accurate documentation following regulatory best practices -- **Software Developer** - Writes production code and self-validation tests in literate style -- **Test Developer** - Creates unit and integration tests following AAA pattern -- **Code Quality Agent** - Enforces linting, static analysis, and security standards -- **Repo Consistency Agent** - Ensures downstream repositories remain consistent with template patterns - -## Agent Selection Guide - -- Fix a bug → **Software Developer** -- Add a new feature → **Requirements Agent** → **Software Developer** → **Test Developer** -- Write a test → **Test Developer** -- Fix linting or static analysis issues → **Code Quality Agent** -- Update documentation → **Technical Writer** -- Add or update requirements → **Requirements Agent** -- Ensure test coverage linkage in `requirements.yaml` → **Requirements Agent** -- Run security scanning or address CodeQL alerts → **Code Quality Agent** -- Propagate template changes → **Repo Consistency Agent** +- **code-review** - Agent for performing formal reviews using standardized + review processes +- **developer** - General-purpose software development agent that applies + appropriate standards based on the work being performed +- **implementation** - Orchestrator agent that manages quality implementations + through a formal state machine workflow +- **quality** - Quality assurance agent that grades developer work against DEMA + Consulting standards and Continuous Compliance practices +- **repo-consistency** - Ensures downstream repositories remain consistent with + the TemplateDotNetTool template patterns and best practices + +## Quality Gate Enforcement (ALL Agents Must Verify) + +Configuration files and scripts are self-documenting with their design intent and +modification policies in header comments. + +1. **Linting Standards**: `./lint.sh` (Unix) or `lint.bat` (Windows) - comprehensive linting suite +2. **Build Quality**: Zero warnings (`TreatWarningsAsErrors=true`) +3. **Static Analysis**: SonarQube/CodeQL passing with no blockers +4. **Requirements Traceability**: `dotnet reqstream --enforce` passing +5. **Test Coverage**: All requirements linked to passing tests +6. **Documentation Currency**: All docs current and generated +7. **File Review Status**: All reviewable files have current reviews ## Tech Stack @@ -59,26 +90,6 @@ evidence. This is critical for platform and framework requirements - **do not re Without the source filter, a test result from any platform/framework satisfies the requirement. Adding the filter ensures the CI evidence comes specifically from the required environment. -## Testing - -- **Test Naming**: `NuGetCache_MethodUnderTest_Scenario` for self-validation tests -- **Self-Validation**: All tests run via `--validate` flag and can output TRX/JUnit format -- **Test Framework**: Uses DemaConsulting.TestResults library for test result generation - -## Code Style - -- **XML Docs**: On ALL members (public/internal/private) with spaces after `///` in summaries -- **Errors**: `ArgumentException` for parsing, `InvalidOperationException` for runtime issues -- **Namespace**: File-scoped namespaces only -- **Using Statements**: Top of file only (no nested using declarations except for IDisposable) -- **String Formatting**: Use interpolated strings ($"") for clarity - -## Project Structure - -- **Context.cs**: Handles command-line argument parsing, logging, and output -- **Program.cs**: Main entry point with version/help/validation routing -- **Validation.cs**: Self-validation tests with TRX/JUnit output support - ## Build and Test ```bash @@ -97,15 +108,6 @@ dotnet run --project src/DemaConsulting.NuGet.CacheTool \ build.bat # Windows ``` -## Documentation - -- **User Guide**: `docs/guide/guide.md` -- **Requirements**: `requirements.yaml` -> auto-generated docs -- **Build Notes**: Auto-generated via BuildMark -- **Code Quality**: Auto-generated via CodeQL and SonarMark -- **Trace Matrix**: Auto-generated via ReqStream -- **CHANGELOG.md**: Not present - changes are captured in the auto-generated build notes - ## Markdown Link Style - **AI agent markdown files** (`.github/agents/*.md`): Use inline links `[text](url)` so URLs are visible in agent context @@ -120,27 +122,12 @@ build.bat # Windows - **Integration Tests**: .NET 8/9/10 on Windows/Linux/macOS - **Documentation**: Auto-generated via Pandoc + Weasyprint -## Common Tasks - -```bash -# Format code -dotnet format - -# Run all linters -./lint.sh # Linux/macOS -lint.bat # Windows - -# Pack as NuGet tool -dotnet pack --configuration Release -``` - ## Agent Report Files -When agents need to write report files to communicate with each other or the user, follow these guidelines: +Upon completion, create a report file at `.agent-logs/[agent-name]-[subject]-[unique-id].md` that includes: + +- A concise summary of the work performed +- Any important decisions made and their rationale +- Follow-up items, open questions, or TODOs -- **Naming Convention**: Use the pattern `AGENT_REPORT_xxxx.md` (e.g., `AGENT_REPORT_analysis.md`, `AGENT_REPORT_results.md`) -- **Purpose**: These files are for temporary inter-agent communication and should not be committed -- **Exclusions**: Files matching `AGENT_REPORT_*.md` are automatically: - - Excluded from git (via .gitignore) - - Excluded from markdown linting - - Excluded from spell checking +Store agent logs in the `.agent-logs/` folder so they are ignored via `.gitignore` and excluded from linting and commits. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d6314a9..b3e721b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -187,15 +187,13 @@ All markdown files must follow these rules (enforced by markdownlint): ### Spell Checking -All files are spell-checked using cspell. Add project-specific terms to `.cspell.json`: +All files are spell-checked using cspell. **Never** add a word to the `.cspell.json` word list in order to silence a +spell-checking failure. Doing so defeats the purpose of spell-checking and reduces the quality of the repository. -```json -{ - "words": [ - "myterm" - ] -} -``` +- If cspell flags a word that is **misspelled**, fix the spelling in the source file. +- If cspell flags a word that is a **genuine technical term** (tool name, project identifier, etc.) and is spelled + correctly, raise a **proposal** (e.g. comment in a pull request) explaining why the word should be added. The + proposal must be reviewed and approved before the word is added to the list. ## Quality Checks diff --git a/docs/build_notes/definition.yaml b/docs/build_notes/definition.yaml new file mode 100644 index 0000000..207a375 --- /dev/null +++ b/docs/build_notes/definition.yaml @@ -0,0 +1,12 @@ +--- +resource-path: + - docs/build_notes + - docs/template +input-files: + - docs/build_notes/title.txt + - docs/build_notes/introduction.md + - docs/build_notes.md + - docs/build_notes/versions.md +template: template.html +table-of-contents: true +number-sections: true diff --git a/docs/buildnotes/introduction.md b/docs/build_notes/introduction.md similarity index 100% rename from docs/buildnotes/introduction.md rename to docs/build_notes/introduction.md diff --git a/docs/buildnotes/title.txt b/docs/build_notes/title.txt similarity index 100% rename from docs/buildnotes/title.txt rename to docs/build_notes/title.txt diff --git a/docs/buildnotes/definition.yaml b/docs/buildnotes/definition.yaml deleted file mode 100644 index 62699f2..0000000 --- a/docs/buildnotes/definition.yaml +++ /dev/null @@ -1,12 +0,0 @@ ---- -resource-path: - - docs/buildnotes - - docs/template -input-files: - - docs/buildnotes/title.txt - - docs/buildnotes/introduction.md - - docs/buildnotes.md - - docs/buildnotes/versions.md -template: template.html -table-of-contents: true -number-sections: true diff --git a/docs/code_quality/definition.yaml b/docs/code_quality/definition.yaml new file mode 100644 index 0000000..68c58f2 --- /dev/null +++ b/docs/code_quality/definition.yaml @@ -0,0 +1,12 @@ +--- +resource-path: + - docs/code_quality + - docs/template +input-files: + - docs/code_quality/title.txt + - docs/code_quality/introduction.md + - docs/code_quality/codeql-quality.md + - docs/code_quality/sonar-quality.md +template: template.html +table-of-contents: true +number-sections: true diff --git a/docs/quality/introduction.md b/docs/code_quality/introduction.md similarity index 100% rename from docs/quality/introduction.md rename to docs/code_quality/introduction.md diff --git a/docs/quality/title.txt b/docs/code_quality/title.txt similarity index 100% rename from docs/quality/title.txt rename to docs/code_quality/title.txt diff --git a/docs/code_review_plan/definition.yaml b/docs/code_review_plan/definition.yaml new file mode 100644 index 0000000..3a24f0b --- /dev/null +++ b/docs/code_review_plan/definition.yaml @@ -0,0 +1,11 @@ +--- +resource-path: + - docs/code_review_plan + - docs/template +input-files: + - docs/code_review_plan/title.txt + - docs/code_review_plan/introduction.md + - docs/code_review_plan/plan.md +template: template.html +table-of-contents: true +number-sections: true diff --git a/docs/code_review_plan/introduction.md b/docs/code_review_plan/introduction.md new file mode 100644 index 0000000..25649e4 --- /dev/null +++ b/docs/code_review_plan/introduction.md @@ -0,0 +1,33 @@ +# Introduction + +This document contains the review plan for the NuGet Cache Tool project. + +## Purpose + +This review plan provides a comprehensive overview of all files requiring formal review +in the NuGet Cache Tool project. It identifies which review-sets cover which +files and serves as evidence that every file requiring review is covered by at least +one named review-set. + +## Scope + +This review plan covers: + +- C# source code files requiring formal review +- YAML configuration and requirements files requiring formal review +- Mapping of reviewed files to named review-sets + +## Generation Source + +This plan is automatically generated by the ReviewMark tool, analyzing the +`.reviewmark.yaml` configuration and the review evidence store. It serves as evidence +that every file requiring review is covered by a current, valid review. + +## Audience + +This document is intended for: + +- Software developers working on NuGet Cache Tool +- Quality assurance teams validating review coverage +- Project stakeholders reviewing compliance status +- Auditors verifying that all required files have been reviewed diff --git a/docs/code_review_plan/title.txt b/docs/code_review_plan/title.txt new file mode 100644 index 0000000..ea04087 --- /dev/null +++ b/docs/code_review_plan/title.txt @@ -0,0 +1,13 @@ +--- +title: NuGet Cache Tool Review Plan +subtitle: File Review Plan for the NuGet Cache Tool +author: DEMA Consulting +description: File Review Plan for the NuGet Cache Tool +lang: en-US +keywords: + - NuGet Cache Tool + - Review Plan + - File Reviews + - .NET + - Tool +--- diff --git a/docs/code_review_report/definition.yaml b/docs/code_review_report/definition.yaml new file mode 100644 index 0000000..6498e6c --- /dev/null +++ b/docs/code_review_report/definition.yaml @@ -0,0 +1,11 @@ +--- +resource-path: + - docs/code_review_report + - docs/template +input-files: + - docs/code_review_report/title.txt + - docs/code_review_report/introduction.md + - docs/code_review_report/report.md +template: template.html +table-of-contents: true +number-sections: true diff --git a/docs/code_review_report/introduction.md b/docs/code_review_report/introduction.md new file mode 100644 index 0000000..28b748b --- /dev/null +++ b/docs/code_review_report/introduction.md @@ -0,0 +1,33 @@ +# Introduction + +This document contains the review report for the NuGet Cache Tool project. + +## Purpose + +This review report provides evidence that each review-set is current — the review +evidence matches the current file fingerprints. It confirms that all formal reviews +conducted for NuGet Cache Tool remain valid for the current state of the +reviewed files. + +## Scope + +This review report covers: + +- Current review-set status (current, stale, or missing) +- File fingerprints and review evidence matching +- Review coverage verification + +## Generation Source + +This report is automatically generated by the ReviewMark tool, comparing the current +file fingerprints against the review evidence store. It serves as evidence that all +review-sets are current and no reviewed file has changed since its review was conducted. + +## Audience + +This document is intended for: + +- Software developers working on NuGet Cache Tool +- Quality assurance teams validating review currency +- Project stakeholders reviewing compliance status +- Auditors verifying that all reviews remain valid for the current release diff --git a/docs/code_review_report/title.txt b/docs/code_review_report/title.txt new file mode 100644 index 0000000..01d0467 --- /dev/null +++ b/docs/code_review_report/title.txt @@ -0,0 +1,13 @@ +--- +title: NuGet Cache Tool Review Report +subtitle: File Review Report for the NuGet Cache Tool +author: DEMA Consulting +description: File Review Report for the NuGet Cache Tool +lang: en-US +keywords: + - NuGet Cache Tool + - Review Report + - File Reviews + - .NET + - Tool +--- diff --git a/docs/justifications/definition.yaml b/docs/justifications/definition.yaml deleted file mode 100644 index d0bbbee..0000000 --- a/docs/justifications/definition.yaml +++ /dev/null @@ -1,11 +0,0 @@ ---- -resource-path: - - docs/justifications - - docs/template -input-files: - - docs/justifications/title.txt - - docs/justifications/introduction.md - - docs/justifications/justifications.md -template: template.html -table-of-contents: true -number-sections: true diff --git a/docs/justifications/introduction.md b/docs/justifications/introduction.md deleted file mode 100644 index e3eac8f..0000000 --- a/docs/justifications/introduction.md +++ /dev/null @@ -1,29 +0,0 @@ -# Introduction - -This document contains the justifications for the requirements of the NuGet Cache Tool project. - -## Purpose - -This justifications document provides the rationale behind each requirement in the NuGet Cache Tool -project. Each requirement justification explains why the requirement exists, what problem it -solves, and how it contributes to the overall value of the tool. - -## Scope - -This document covers justifications for: - -- Command-line interface requirements -- Self-validation framework requirements -- Test result output requirements -- Logging requirements -- Platform support requirements -- Documentation generation requirements - -## Audience - -This document is intended for: - -- Software developers understanding design decisions -- Quality assurance teams reviewing requirement rationale -- Project stakeholders evaluating project scope -- Compliance and audit teams reviewing requirements traceability diff --git a/docs/justifications/title.txt b/docs/justifications/title.txt deleted file mode 100644 index 900d708..0000000 --- a/docs/justifications/title.txt +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: NuGet Cache Tool Requirements Justifications -subtitle: Requirements Justifications for the NuGet Cache Tool -author: DEMA Consulting -description: Requirements Justifications for the NuGet Cache Tool -lang: en-US -keywords: - - NuGet Cache Tool - - Requirements - - Justifications - - .NET - - Documentation ---- diff --git a/docs/quality/definition.yaml b/docs/quality/definition.yaml deleted file mode 100644 index 1b63510..0000000 --- a/docs/quality/definition.yaml +++ /dev/null @@ -1,12 +0,0 @@ ---- -resource-path: - - docs/quality - - docs/template -input-files: - - docs/quality/title.txt - - docs/quality/introduction.md - - docs/quality/codeql-quality.md - - docs/quality/sonar-quality.md -template: template.html -table-of-contents: true -number-sections: true diff --git a/docs/reqstream/cmd-requirements.yaml b/docs/reqstream/cmd-requirements.yaml new file mode 100644 index 0000000..c85b469 --- /dev/null +++ b/docs/reqstream/cmd-requirements.yaml @@ -0,0 +1,118 @@ +--- +# NuGet Cache Tool Command-Line Interface Requirements +# +# Requirements for the command-line interface functionality of the NuGet Cache Tool. + +sections: + - title: NuGet Cache Tool Requirements + sections: + - title: Command-Line Interface + requirements: + - id: NuGetCache-Cmd-Context + title: The tool shall implement a Context class for command-line argument handling. + justification: | + Provides a standardized approach to command-line argument parsing and output + handling across all DEMA Consulting DotNet Tools. + tests: + - Context_Create_NoArguments_ReturnsDefaultContext + - Context_Create_VersionFlag_SetsVersionTrue + - Context_Create_HelpFlag_SetsHelpTrue + - Context_Create_SilentFlag_SetsSilentTrue + - Context_Create_ValidateFlag_SetsValidateTrue + - Context_Create_ResultsFlag_SetsResultsFile + - Context_Create_LogFlag_OpensLogFile + + - id: NuGetCache-Cmd-Version + title: The tool shall support -v and --version flags to display version information. + justification: | + Users need to quickly identify the version of the tool they are using for + troubleshooting and compatibility verification. + tests: + - Context_Create_VersionFlag_SetsVersionTrue + - Context_Create_ShortVersionFlag_SetsVersionTrue + - Program_Run_WithVersionFlag_DisplaysVersionOnly + - Program_Version_ReturnsNonEmptyString + - IntegrationTest_VersionFlag_OutputsVersion + + - id: NuGetCache-Cmd-Help + title: The tool shall support -?, -h, and --help flags to display usage information. + justification: | + Users need access to command-line usage documentation without requiring + external resources. + tests: + - Context_Create_HelpFlag_SetsHelpTrue + - Context_Create_ShortHelpFlag_H_SetsHelpTrue + - Context_Create_ShortHelpFlag_Question_SetsHelpTrue + - Program_Run_WithHelpFlag_DisplaysUsageInformation + - IntegrationTest_HelpFlag_OutputsUsageInformation + + - id: NuGetCache-Cmd-Silent + title: The tool shall support --silent flag to suppress console output. + justification: | + Enables automated scripts and CI/CD pipelines to run the tool without + cluttering output logs. + tests: + - Context_Create_SilentFlag_SetsSilentTrue + - Context_WriteLine_Silent_DoesNotWriteToConsole + - IntegrationTest_SilentFlag_SuppressesOutput + + - id: NuGetCache-Cmd-Validate + title: The tool shall support --validate flag to run self-validation tests. + justification: | + Provides a built-in mechanism to verify the tool is functioning correctly + in the deployment environment. + tests: + - Context_Create_ValidateFlag_SetsValidateTrue + - Program_Run_WithValidateFlag_RunsValidation + - IntegrationTest_ValidateFlag_RunsValidation + + - id: NuGetCache-Cmd-Results + title: The tool shall support --results flag to write validation results in TRX or JUnit format. + justification: | + Enables integration with CI/CD systems that expect standard test result formats. + tests: + - Context_Create_ResultsFlag_SetsResultsFile + - IntegrationTest_ValidateWithResults_GeneratesTrxFile + - IntegrationTest_ValidateWithResults_GeneratesJUnitFile + + - id: NuGetCache-Cmd-Log + title: The tool shall support --log flag to write output to a log file. + justification: | + Provides persistent logging for debugging and audit trails. + tests: + - Context_Create_LogFlag_OpensLogFile + - IntegrationTest_LogFlag_WritesOutputToFile + - IntegrationTest_LogFlag_WithInvalidFilename_ReturnsError + + - id: NuGetCache-Cmd-Cache + title: The tool shall cache NuGet packages specified as [package-name]:[version] arguments. + justification: | + The core purpose of the tool is to ensure NuGet packages are cached in the + global packages folder for use by downstream build steps. + tests: + - Context_Create_PackageArgument_AddsToPackagesList + - IntegrationTest_CachePackage_OutputsPath + - NuGetCache_CachePackage + + - id: NuGetCache-Cmd-ErrorOutput + title: The tool shall report errors and return a non-zero exit code on failure. + justification: | + Callers (scripts, CI/CD pipelines) must be able to detect failure conditions + programmatically via the process exit code, and error messages must be visible + to the user unless silent mode is active. + tests: + - Context_WriteError_SetsErrorExitCode + - Context_WriteError_NotSilent_WritesToConsole + - IntegrationTest_UnknownArgument_ReturnsError + - IntegrationTest_CacheNonexistentPackage_ReturnsError + + - id: NuGetCache-Cmd-InvalidArgs + title: The tool shall reject unknown or malformed command-line arguments with a descriptive error. + justification: | + Providing clear feedback for invalid arguments helps users quickly correct + mistakes and prevents silent misconfiguration. + tests: + - Context_Create_UnknownArgument_ThrowsArgumentException + - Context_Create_LogFlag_WithoutValue_ThrowsArgumentException + - Context_Create_ResultsFlag_WithoutValue_ThrowsArgumentException + - IntegrationTest_UnknownArgument_ReturnsError diff --git a/docs/reqstream/ots-buildmark.yaml b/docs/reqstream/ots-buildmark.yaml new file mode 100644 index 0000000..5e7c733 --- /dev/null +++ b/docs/reqstream/ots-buildmark.yaml @@ -0,0 +1,20 @@ +--- +# BuildMark OTS Software Requirements +# +# Requirements for the BuildMark build documentation tool functionality. + +sections: + - title: OTS Software Requirements + sections: + - title: BuildMark Requirements + requirements: + - id: NuGetCache-OTS-BuildMark + title: BuildMark shall generate build-notes documentation from GitHub Actions metadata. + justification: | + DemaConsulting.BuildMark queries the GitHub API to capture workflow run details and + renders them as a markdown build-notes document included in the release artifacts. + It runs as part of the same CI pipeline that produces the TRX test results, so a + successful pipeline run is evidence that BuildMark executed without error. + tags: [ots] + tests: + - BuildMark_MarkdownReportGeneration diff --git a/docs/reqstream/ots-mstest.yaml b/docs/reqstream/ots-mstest.yaml new file mode 100644 index 0000000..40ec99f --- /dev/null +++ b/docs/reqstream/ots-mstest.yaml @@ -0,0 +1,28 @@ +--- +# MSTest OTS Software Requirements +# +# Requirements for the MSTest testing framework functionality. + +sections: + - title: OTS Software Requirements + sections: + - title: MSTest Requirements + requirements: + - id: NuGetCache-OTS-MSTest + title: MSTest shall execute unit tests and report results. + justification: | + MSTest (MSTest.TestFramework and MSTest.TestAdapter) is the unit-testing framework used + by the project. It discovers and runs all test methods and writes TRX result files that + feed into coverage reporting and requirements traceability. Passing tests confirm the + framework is functioning correctly. + tags: [ots] + tests: + - Context_Create_NoArguments_ReturnsDefaultContext + - Context_Create_VersionFlag_SetsVersionTrue + - Context_Create_HelpFlag_SetsHelpTrue + - Context_Create_SilentFlag_SetsSilentTrue + - Context_Create_ValidateFlag_SetsValidateTrue + - Context_Create_ResultsFlag_SetsResultsFile + - Context_Create_LogFlag_OpensLogFile + - Context_Create_UnknownArgument_ThrowsArgumentException + - Context_Create_ShortVersionFlag_SetsVersionTrue diff --git a/docs/reqstream/ots-reqstream.yaml b/docs/reqstream/ots-reqstream.yaml new file mode 100644 index 0000000..8646ed3 --- /dev/null +++ b/docs/reqstream/ots-reqstream.yaml @@ -0,0 +1,21 @@ +--- +# ReqStream OTS Software Requirements +# +# Requirements for the ReqStream requirements traceability tool functionality. + +sections: + - title: OTS Software Requirements + sections: + - title: ReqStream Requirements + requirements: + - id: NuGetCache-OTS-ReqStream + title: ReqStream shall enforce that every requirement is linked to passing test evidence. + justification: | + DemaConsulting.ReqStream processes requirements.yaml and the TRX test-result files to + produce a requirements report, justifications document, and traceability matrix. When + run with --enforce, it exits with a non-zero code if any requirement lacks test evidence, + making unproven requirements a build-breaking condition. A successful pipeline run with + --enforce proves all requirements are covered and that ReqStream is functioning. + tags: [ots] + tests: + - ReqStream_EnforcementMode diff --git a/docs/reqstream/ots-reviewmark.yaml b/docs/reqstream/ots-reviewmark.yaml new file mode 100644 index 0000000..41d23cc --- /dev/null +++ b/docs/reqstream/ots-reviewmark.yaml @@ -0,0 +1,21 @@ +--- +# ReviewMark OTS Software Requirements +# +# Requirements for the ReviewMark file review tool functionality. + +sections: + - title: OTS Software Requirements + sections: + - title: ReviewMark Requirements + requirements: + - id: NuGetCache-OTS-ReviewMark + title: ReviewMark shall generate a review plan and review report from the review configuration. + justification: | + DemaConsulting.ReviewMark reads the .reviewmark.yaml configuration and the review + evidence store to produce a review plan and review report documenting file review + coverage and currency. It runs in the same CI pipeline that produces the TRX test + results, so a successful pipeline run is evidence that ReviewMark executed without error. + tags: [ots] + tests: + - ReviewMark_ReviewPlanGeneration + - ReviewMark_ReviewReportGeneration diff --git a/docs/reqstream/ots-sarifmark.yaml b/docs/reqstream/ots-sarifmark.yaml new file mode 100644 index 0000000..57e2e0b --- /dev/null +++ b/docs/reqstream/ots-sarifmark.yaml @@ -0,0 +1,21 @@ +--- +# SarifMark OTS Software Requirements +# +# Requirements for the SarifMark SARIF report processing tool functionality. + +sections: + - title: OTS Software Requirements + sections: + - title: SarifMark Requirements + requirements: + - id: NuGetCache-OTS-SarifMark + title: SarifMark shall convert CodeQL SARIF results into a markdown report. + justification: | + DemaConsulting.SarifMark reads the SARIF output produced by CodeQL code scanning and + renders it as a human-readable markdown document included in the release artifacts. + It runs in the same CI pipeline that produces the TRX test results, so a successful + pipeline run is evidence that SarifMark executed without error. + tags: [ots] + tests: + - SarifMark_SarifReading + - SarifMark_MarkdownReportGeneration diff --git a/docs/reqstream/ots-sonarmark.yaml b/docs/reqstream/ots-sonarmark.yaml new file mode 100644 index 0000000..d0c202b --- /dev/null +++ b/docs/reqstream/ots-sonarmark.yaml @@ -0,0 +1,23 @@ +--- +# SonarMark OTS Software Requirements +# +# Requirements for the SonarMark quality reporting tool functionality. + +sections: + - title: OTS Software Requirements + sections: + - title: SonarMark Requirements + requirements: + - id: NuGetCache-OTS-SonarMark + title: SonarMark shall generate a SonarCloud quality report. + justification: | + DemaConsulting.SonarMark retrieves quality-gate and metrics data from SonarCloud and + renders it as a markdown document included in the release artifacts. It runs in the + same CI pipeline that produces the TRX test results, so a successful pipeline run is + evidence that SonarMark executed without error. + tags: [ots] + tests: + - SonarMark_QualityGateRetrieval + - SonarMark_IssuesRetrieval + - SonarMark_HotSpotsRetrieval + - SonarMark_MarkdownReportGeneration diff --git a/docs/reqstream/ots-versionmark.yaml b/docs/reqstream/ots-versionmark.yaml new file mode 100644 index 0000000..8463142 --- /dev/null +++ b/docs/reqstream/ots-versionmark.yaml @@ -0,0 +1,21 @@ +--- +# VersionMark OTS Software Requirements +# +# Requirements for the VersionMark version tracking tool functionality. + +sections: + - title: OTS Software Requirements + sections: + - title: VersionMark Requirements + requirements: + - id: NuGetCache-OTS-VersionMark + title: VersionMark shall publish captured tool-version information. + justification: | + DemaConsulting.VersionMark reads version metadata for each dotnet tool used in the + pipeline and writes a versions markdown document included in the release artifacts. + It runs in the same CI pipeline that produces the TRX test results, so a successful + pipeline run is evidence that VersionMark executed without error. + tags: [ots] + tests: + - VersionMark_CapturesVersions + - VersionMark_GeneratesMarkdownReport diff --git a/docs/reqstream/platform-requirements.yaml b/docs/reqstream/platform-requirements.yaml new file mode 100644 index 0000000..fc88179 --- /dev/null +++ b/docs/reqstream/platform-requirements.yaml @@ -0,0 +1,60 @@ +--- +# NuGet Cache Tool Platform Requirements +# +# Requirements for the platform support of the NuGet Cache Tool. + +sections: + - title: NuGet Cache Tool Requirements + sections: + - title: Platform Support + requirements: + - id: NuGetCache-PLT-Windows + title: The tool shall build and run on Windows platforms. + justification: | + DEMA Consulting tools must support Windows as a major development platform. + tests: + # Tests link to "windows" to ensure results come from Windows platform + - "windows@NuGetCache_VersionDisplay" + - "windows@NuGetCache_HelpDisplay" + + - id: NuGetCache-PLT-Linux + title: The tool shall build and run on Linux platforms. + justification: | + DEMA Consulting tools must support Linux for CI/CD and containerized environments. + tests: + # Tests link to "ubuntu" to ensure results come from Linux platform + - "ubuntu@NuGetCache_VersionDisplay" + - "ubuntu@NuGetCache_HelpDisplay" + + - id: NuGetCache-PLT-MacOS + title: The tool shall build and run on macOS platforms. + justification: | + DEMA Consulting tools must support macOS for developers using Apple platforms. + tests: + # Tests link to "macos" to ensure results come from macOS platform + - "macos@NuGetCache_VersionDisplay" + - "macos@NuGetCache_HelpDisplay" + + - id: NuGetCache-PLT-Net8 + title: The tool shall support .NET 8 runtime. + justification: | + .NET 8 is an LTS release providing long-term stability for enterprise users. + tests: + - "dotnet8.x@NuGetCache_VersionDisplay" + - "dotnet8.x@NuGetCache_HelpDisplay" + + - id: NuGetCache-PLT-Net9 + title: The tool shall support .NET 9 runtime. + justification: | + .NET 9 support enables users to leverage the latest .NET features. + tests: + - "dotnet9.x@NuGetCache_VersionDisplay" + - "dotnet9.x@NuGetCache_HelpDisplay" + + - id: NuGetCache-PLT-Net10 + title: The tool shall support .NET 10 runtime. + justification: | + .NET 10 support ensures the tool remains compatible with the latest .NET ecosystem. + tests: + - "dotnet10.x@NuGetCache_VersionDisplay" + - "dotnet10.x@NuGetCache_HelpDisplay" diff --git a/docs/reqstream/security-requirements.yaml b/docs/reqstream/security-requirements.yaml new file mode 100644 index 0000000..df60b2c --- /dev/null +++ b/docs/reqstream/security-requirements.yaml @@ -0,0 +1,25 @@ +--- +# NuGet Cache Tool Security Requirements +# +# Requirements for the security functionality of the NuGet Cache Tool. + +sections: + - title: NuGet Cache Tool Requirements + sections: + - title: Security + requirements: + - id: NuGetCache-Sec-PathTraversal + title: The tool shall prevent path traversal attacks when combining file paths. + justification: | + Accepting user-controlled path components without validation could allow + an attacker to read or write files outside intended directories. The + SafePathCombine helper must reject absolute paths and parent-directory + references (e.g. "..") in the relative component. + tests: + - PathHelpers_SafePathCombine_ValidPaths_CombinesCorrectly + - PathHelpers_SafePathCombine_PathTraversalWithDoubleDots_ThrowsArgumentException + - PathHelpers_SafePathCombine_DoubleDotsInMiddle_ThrowsArgumentException + - PathHelpers_SafePathCombine_AbsolutePath_ThrowsArgumentException + - PathHelpers_SafePathCombine_CurrentDirectoryReference_CombinesCorrectly + - PathHelpers_SafePathCombine_NestedPaths_CombinesCorrectly + - PathHelpers_SafePathCombine_EmptyRelativePath_ReturnsBasePath diff --git a/docs/requirements/definition.yaml b/docs/requirements/definition.yaml deleted file mode 100644 index a0f3371..0000000 --- a/docs/requirements/definition.yaml +++ /dev/null @@ -1,11 +0,0 @@ ---- -resource-path: - - docs/requirements - - docs/template -input-files: - - docs/requirements/title.txt - - docs/requirements/introduction.md - - docs/requirements/requirements.md -template: template.html -table-of-contents: true -number-sections: true diff --git a/docs/requirements_doc/definition.yaml b/docs/requirements_doc/definition.yaml new file mode 100644 index 0000000..0f4ccd2 --- /dev/null +++ b/docs/requirements_doc/definition.yaml @@ -0,0 +1,12 @@ +--- +resource-path: + - docs/requirements_doc + - docs/template +input-files: + - docs/requirements_doc/title.txt + - docs/requirements_doc/introduction.md + - docs/requirements_doc/requirements.md + - docs/requirements_doc/justifications.md +template: template.html +table-of-contents: true +number-sections: true diff --git a/docs/requirements/introduction.md b/docs/requirements_doc/introduction.md similarity index 100% rename from docs/requirements/introduction.md rename to docs/requirements_doc/introduction.md diff --git a/docs/requirements/title.txt b/docs/requirements_doc/title.txt similarity index 100% rename from docs/requirements/title.txt rename to docs/requirements_doc/title.txt diff --git a/docs/requirements_report/definition.yaml b/docs/requirements_report/definition.yaml new file mode 100644 index 0000000..918a645 --- /dev/null +++ b/docs/requirements_report/definition.yaml @@ -0,0 +1,11 @@ +--- +resource-path: + - docs/requirements_report + - docs/template +input-files: + - docs/requirements_report/title.txt + - docs/requirements_report/introduction.md + - docs/requirements_report/trace_matrix.md +template: template.html +table-of-contents: true +number-sections: true diff --git a/docs/tracematrix/introduction.md b/docs/requirements_report/introduction.md similarity index 100% rename from docs/tracematrix/introduction.md rename to docs/requirements_report/introduction.md diff --git a/docs/tracematrix/title.txt b/docs/requirements_report/title.txt similarity index 100% rename from docs/tracematrix/title.txt rename to docs/requirements_report/title.txt diff --git a/docs/tracematrix/definition.yaml b/docs/tracematrix/definition.yaml deleted file mode 100644 index ba93d57..0000000 --- a/docs/tracematrix/definition.yaml +++ /dev/null @@ -1,11 +0,0 @@ ---- -resource-path: - - docs/tracematrix - - docs/template -input-files: - - docs/tracematrix/title.txt - - docs/tracematrix/introduction.md - - docs/tracematrix/tracematrix.md -template: template.html -table-of-contents: true -number-sections: true diff --git a/lint.bat b/lint.bat index 3e63609..3a7c2fe 100644 --- a/lint.bat +++ b/lint.bat @@ -6,7 +6,7 @@ call npx markdownlint-cli2 "**/*.md" if %errorlevel% neq 0 exit /b %errorlevel% echo Checking spelling... -call npx cspell "**/*.{cs,md,json,yaml,yml}" --no-progress +call npx cspell "**/*.{cs,md,json,yaml,yml}" --no-progress --no-color --quiet if %errorlevel% neq 0 exit /b %errorlevel% echo Checking YAML... diff --git a/lint.sh b/lint.sh index 6cbc7d5..9743744 100755 --- a/lint.sh +++ b/lint.sh @@ -7,7 +7,7 @@ echo "📝 Checking markdown..." npx markdownlint-cli2 "**/*.md" echo "🔤 Checking spelling..." -npx cspell "**/*.{cs,md,json,yaml,yml}" --no-progress +npx cspell "**/*.{cs,md,json,yaml,yml}" --no-progress --no-color --quiet echo "📋 Checking YAML..." yamllint -c .yamllint.yaml . diff --git a/requirements.yaml b/requirements.yaml index 87216c2..11b4866 100644 --- a/requirements.yaml +++ b/requirements.yaml @@ -28,269 +28,15 @@ # dotnet10.x@TestName - proves the self-validation test ran with .NET 10.x runtime # --- -sections: - - title: NuGet Cache Tool Requirements - sections: - - title: Command-Line Interface - requirements: - - id: NuGetCache-Cmd-Context - title: The tool shall implement a Context class for command-line argument handling. - justification: | - Provides a standardized approach to command-line argument parsing and output - handling across all DEMA Consulting DotNet Tools. - tests: - - Context_Create_NoArguments_ReturnsDefaultContext - - Context_Create_VersionFlag_SetsVersionTrue - - Context_Create_HelpFlag_SetsHelpTrue - - Context_Create_SilentFlag_SetsSilentTrue - - Context_Create_ValidateFlag_SetsValidateTrue - - Context_Create_ResultsFlag_SetsResultsFile - - Context_Create_LogFlag_OpensLogFile - - - id: NuGetCache-Cmd-Version - title: The tool shall support -v and --version flags to display version information. - justification: | - Users need to quickly identify the version of the tool they are using for - troubleshooting and compatibility verification. - tests: - - Context_Create_VersionFlag_SetsVersionTrue - - Context_Create_ShortVersionFlag_SetsVersionTrue - - Program_Run_WithVersionFlag_DisplaysVersionOnly - - Program_Version_ReturnsNonEmptyString - - IntegrationTest_VersionFlag_OutputsVersion - - - id: NuGetCache-Cmd-Help - title: The tool shall support -?, -h, and --help flags to display usage information. - justification: | - Users need access to command-line usage documentation without requiring - external resources. - tests: - - Context_Create_HelpFlag_SetsHelpTrue - - Context_Create_ShortHelpFlag_H_SetsHelpTrue - - Context_Create_ShortHelpFlag_Question_SetsHelpTrue - - Program_Run_WithHelpFlag_DisplaysUsageInformation - - IntegrationTest_HelpFlag_OutputsUsageInformation - - - id: NuGetCache-Cmd-Silent - title: The tool shall support --silent flag to suppress console output. - justification: | - Enables automated scripts and CI/CD pipelines to run the tool without - cluttering output logs. - tests: - - Context_Create_SilentFlag_SetsSilentTrue - - Context_WriteLine_Silent_DoesNotWriteToConsole - - IntegrationTest_SilentFlag_SuppressesOutput - - - id: NuGetCache-Cmd-Validate - title: The tool shall support --validate flag to run self-validation tests. - justification: | - Provides a built-in mechanism to verify the tool is functioning correctly - in the deployment environment. - tests: - - Context_Create_ValidateFlag_SetsValidateTrue - - Program_Run_WithValidateFlag_RunsValidation - - IntegrationTest_ValidateFlag_RunsValidation - - - id: NuGetCache-Cmd-Results - title: The tool shall support --results flag to write validation results in TRX or JUnit format. - justification: | - Enables integration with CI/CD systems that expect standard test result formats. - tests: - - Context_Create_ResultsFlag_SetsResultsFile - - IntegrationTest_ValidateWithResults_GeneratesTrxFile - - IntegrationTest_ValidateWithResults_GeneratesJUnitFile - - - id: NuGetCache-Cmd-Log - title: The tool shall support --log flag to write output to a log file. - justification: | - Provides persistent logging for debugging and audit trails. - tests: - - Context_Create_LogFlag_OpensLogFile - - IntegrationTest_LogFlag_WritesOutputToFile - - IntegrationTest_LogFlag_WithInvalidFilename_ReturnsError - - - id: NuGetCache-Cmd-Cache - title: The tool shall cache NuGet packages specified as [package-name]:[version] arguments. - justification: | - The core purpose of the tool is to ensure NuGet packages are cached in the - global packages folder for use by downstream build steps. - tests: - - Context_Create_PackageArgument_AddsToPackagesList - - IntegrationTest_CachePackage_OutputsPath - - NuGetCache_CachePackage - - - id: NuGetCache-Cmd-ErrorOutput - title: The tool shall report errors and return a non-zero exit code on failure. - justification: | - Callers (scripts, CI/CD pipelines) must be able to detect failure conditions - programmatically via the process exit code, and error messages must be visible - to the user unless silent mode is active. - tests: - - Context_WriteError_SetsErrorExitCode - - Context_WriteError_NotSilent_WritesToConsole - - IntegrationTest_UnknownArgument_ReturnsError - - IntegrationTest_CacheNonexistentPackage_ReturnsError - - - id: NuGetCache-Cmd-InvalidArgs - title: The tool shall reject unknown or malformed command-line arguments with a descriptive error. - justification: | - Providing clear feedback for invalid arguments helps users quickly correct - mistakes and prevents silent misconfiguration. - tests: - - Context_Create_UnknownArgument_ThrowsArgumentException - - Context_Create_LogFlag_WithoutValue_ThrowsArgumentException - - Context_Create_ResultsFlag_WithoutValue_ThrowsArgumentException - - IntegrationTest_UnknownArgument_ReturnsError - - - title: Security - requirements: - - id: NuGetCache-Sec-PathTraversal - title: The tool shall prevent path traversal attacks when combining file paths. - justification: | - Accepting user-controlled path components without validation could allow - an attacker to read or write files outside intended directories. The - SafePathCombine helper must reject absolute paths and parent-directory - references (e.g. "..") in the relative component. - tests: - - PathHelpers_SafePathCombine_ValidPaths_CombinesCorrectly - - PathHelpers_SafePathCombine_PathTraversalWithDoubleDots_ThrowsArgumentException - - PathHelpers_SafePathCombine_DoubleDotsInMiddle_ThrowsArgumentException - - PathHelpers_SafePathCombine_AbsolutePath_ThrowsArgumentException - - PathHelpers_SafePathCombine_CurrentDirectoryReference_CombinesCorrectly - - PathHelpers_SafePathCombine_NestedPaths_CombinesCorrectly - - PathHelpers_SafePathCombine_EmptyRelativePath_ReturnsBasePath - - - title: Platform Support - requirements: - - id: NuGetCache-PLT-Windows - title: The tool shall build and run on Windows platforms. - justification: | - DEMA Consulting tools must support Windows as a major development platform. - tests: - # Tests link to "windows" to ensure results come from Windows platform - - "windows@NuGetCache_VersionDisplay" - - "windows@NuGetCache_HelpDisplay" - - - id: NuGetCache-PLT-Linux - title: The tool shall build and run on Linux platforms. - justification: | - DEMA Consulting tools must support Linux for CI/CD and containerized environments. - tests: - # Tests link to "ubuntu" to ensure results come from Linux platform - - "ubuntu@NuGetCache_VersionDisplay" - - "ubuntu@NuGetCache_HelpDisplay" - - - id: NuGetCache-PLT-MacOS - title: The tool shall build and run on macOS platforms. - justification: | - DEMA Consulting tools must support macOS for developers using Apple platforms. - tests: - # Tests link to "macos" to ensure results come from macOS platform - - "macos@NuGetCache_VersionDisplay" - - "macos@NuGetCache_HelpDisplay" - - - id: NuGetCache-PLT-Net8 - title: The tool shall support .NET 8 runtime. - justification: | - .NET 8 is an LTS release providing long-term stability for enterprise users. - tests: - - "dotnet8.x@NuGetCache_VersionDisplay" - - "dotnet8.x@NuGetCache_HelpDisplay" - - - id: NuGetCache-PLT-Net9 - title: The tool shall support .NET 9 runtime. - justification: | - .NET 9 support enables users to leverage the latest .NET features. - tests: - - "dotnet9.x@NuGetCache_VersionDisplay" - - "dotnet9.x@NuGetCache_HelpDisplay" - - - id: NuGetCache-PLT-Net10 - title: The tool shall support .NET 10 runtime. - justification: | - .NET 10 support ensures the tool remains compatible with the latest .NET ecosystem. - tests: - - "dotnet10.x@NuGetCache_VersionDisplay" - - "dotnet10.x@NuGetCache_HelpDisplay" - - - title: OTS Software - requirements: - - id: NuGetCache-OTS-MSTest - title: MSTest shall execute unit tests and report results. - justification: | - MSTest (MSTest.TestFramework and MSTest.TestAdapter) is the unit-testing framework used - by the project. It discovers and runs all test methods and writes TRX result files that - feed into coverage reporting and requirements traceability. Passing tests confirm the - framework is functioning correctly. - tags: [ots] - tests: - - Context_Create_NoArguments_ReturnsDefaultContext - - Context_Create_VersionFlag_SetsVersionTrue - - Context_Create_HelpFlag_SetsHelpTrue - - Context_Create_SilentFlag_SetsSilentTrue - - Context_Create_ValidateFlag_SetsValidateTrue - - Context_Create_ResultsFlag_SetsResultsFile - - Context_Create_LogFlag_OpensLogFile - - Context_Create_UnknownArgument_ThrowsArgumentException - - Context_Create_ShortVersionFlag_SetsVersionTrue - - - id: NuGetCache-OTS-ReqStream - title: ReqStream shall enforce that every requirement is linked to passing test evidence. - justification: | - DemaConsulting.ReqStream processes requirements.yaml and the TRX test-result files to - produce a requirements report, justifications document, and traceability matrix. When - run with --enforce, it exits with a non-zero code if any requirement lacks test evidence, - making unproven requirements a build-breaking condition. A successful pipeline run with - --enforce proves all requirements are covered and that ReqStream is functioning. - tags: [ots] - tests: - - ReqStream_EnforcementMode - - - id: NuGetCache-OTS-BuildMark - title: BuildMark shall generate build-notes documentation from GitHub Actions metadata. - justification: | - DemaConsulting.BuildMark queries the GitHub API to capture workflow run details and - renders them as a markdown build-notes document included in the release artifacts. - It runs as part of the same CI pipeline that produces the TRX test results, so a - successful pipeline run is evidence that BuildMark executed without error. - tags: [ots] - tests: - - BuildMark_MarkdownReportGeneration - - - id: NuGetCache-OTS-VersionMark - title: VersionMark shall publish captured tool-version information. - justification: | - DemaConsulting.VersionMark reads version metadata for each dotnet tool used in the - pipeline and writes a versions markdown document included in the release artifacts. - It runs in the same CI pipeline that produces the TRX test results, so a successful - pipeline run is evidence that VersionMark executed without error. - tags: [ots] - tests: - - VersionMark_CapturesVersions - - VersionMark_GeneratesMarkdownReport - - - id: NuGetCache-OTS-SarifMark - title: SarifMark shall convert CodeQL SARIF results into a markdown report. - justification: | - DemaConsulting.SarifMark reads the SARIF output produced by CodeQL code scanning and - renders it as a human-readable markdown document included in the release artifacts. - It runs in the same CI pipeline that produces the TRX test results, so a successful - pipeline run is evidence that SarifMark executed without error. - tags: [ots] - tests: - - SarifMark_SarifReading - - SarifMark_MarkdownReportGeneration - - - id: NuGetCache-OTS-SonarMark - title: SonarMark shall generate a SonarCloud quality report. - justification: | - DemaConsulting.SonarMark retrieves quality-gate and metrics data from SonarCloud and - renders it as a markdown document included in the release artifacts. It runs in the - same CI pipeline that produces the TRX test results, so a successful pipeline run is - evidence that SonarMark executed without error. - tags: [ots] - tests: - - SonarMark_QualityGateRetrieval - - SonarMark_IssuesRetrieval - - SonarMark_HotSpotsRetrieval - - SonarMark_MarkdownReportGeneration +# Root requirements file - includes all subsystem, platform, and OTS requirements +includes: + - docs/reqstream/cmd-requirements.yaml + - docs/reqstream/security-requirements.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