From 97fd9d2369056ea74dc20f164d441f58dbc7558b Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 24 Mar 2026 13:17:51 +0000 Subject: [PATCH 1/9] Initial plan From e570e870047465e5124cc386424b2ece5e7e3fd1 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 24 Mar 2026 13:30:53 +0000 Subject: [PATCH 2/9] Apply template improvements from TemplateDotNetTool PRs #58-#74 - PR #58: Add ReviewMark integration - Added .reviewmark.yaml configuration file - Added demaconsulting.reviewmark to .config/dotnet-tools.json - Updated buildmark to version 0.4.1 - PR #59/#65/#66/#67: Add Code Review Agent - Added .github/agents/code-review.agent.md - Added code-review entry to AGENTS.md agent list and selection guide - PR #61: Apply linting modernization and agent file standardization - Renamed .cspell.json to .cspell.yaml (YAML format with comments) - Renamed .markdownlint-cli2.jsonc to .markdownlint-cli2.yaml (YAML format) - Renamed all agent files to *.agent.md suffix - Updated lint.sh and lint.bat with pip/venv support and new file names - Updated package.json to add cspell and markdownlint-cli2 as devDependencies - Added pip-requirements.txt for yamllint - Updated build.yaml to reference new config file names - PR #63: Enforce cspell word list policy - Added Propagatable, versionmark and other words to .cspell.yaml - PR #64: Align lint YAML configs - Updated .yamllint.yaml with header comments and ignore section - PR #71: Add .gitattributes for LF line endings - Added .gitattributes for consistent line endings across platforms - Also: Updated .gitignore to add Python .venv exclusion --- .config/dotnet-tools.json | 8 +- .cspell.json | 113 --------- .cspell.yaml | 136 +++++++++++ .gitattributes | 7 + .github/agents/code-quality-agent.md | 83 ------- .github/agents/code-quality.agent.md | 219 ++++++++++++++++++ .github/agents/code-review.agent.md | 46 ++++ ...ncy-agent.md => repo-consistency.agent.md} | 0 .github/agents/requirements-agent.md | 63 ----- .github/agents/requirements.agent.md | 100 ++++++++ .github/agents/software-developer.agent.md | 129 +++++++++++ .github/agents/software-developer.md | 81 ------- .github/agents/technical-writer.agent.md | 114 +++++++++ .github/agents/technical-writer.md | 65 ------ .github/agents/test-developer.agent.md | 135 +++++++++++ .github/agents/test-developer.md | 147 ------------ .github/workflows/build.yaml | 4 +- .gitignore | 3 + .markdownlint-cli2.jsonc | 15 -- .markdownlint-cli2.yaml | 47 ++++ .reviewmark.yaml | 95 ++++++++ .yamllint.yaml | 23 +- AGENTS.md | 4 +- lint.bat | 46 ++-- lint.sh | 41 +++- package.json | 4 +- pip-requirements.txt | 1 + 27 files changed, 1129 insertions(+), 600 deletions(-) delete mode 100644 .cspell.json create mode 100644 .cspell.yaml create mode 100644 .gitattributes delete mode 100644 .github/agents/code-quality-agent.md create mode 100644 .github/agents/code-quality.agent.md create mode 100644 .github/agents/code-review.agent.md rename .github/agents/{repo-consistency-agent.md => repo-consistency.agent.md} (100%) delete mode 100644 .github/agents/requirements-agent.md create mode 100644 .github/agents/requirements.agent.md create mode 100644 .github/agents/software-developer.agent.md delete mode 100644 .github/agents/software-developer.md create mode 100644 .github/agents/technical-writer.agent.md delete mode 100644 .github/agents/technical-writer.md create mode 100644 .github/agents/test-developer.agent.md delete mode 100644 .github/agents/test-developer.md delete mode 100644 .markdownlint-cli2.jsonc create mode 100644 .markdownlint-cli2.yaml create mode 100644 .reviewmark.yaml create mode 100644 pip-requirements.txt diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json index 8019fdb..d22ce6e 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 deleted file mode 100644 index fdc4c2f..0000000 --- a/.cspell.json +++ /dev/null @@ -1,113 +0,0 @@ -{ - "version": "0.2", - "language": "en", - "words": [ - "Anson", - "Blockquotes", - "buildmark", - "BuildMark", - "buildMultiTargeting", - "buildnotes", - "camelcase", - "Checkmarx", - "CodeQL", - "copilot", - "cspell", - "csproj", - "dbproj", - "dcterms", - "declaredat", - "Dema", - "demaconsulting", - "DEMACONSULTINGNUGETKEY", - "Dependabot", - "dependabot", - "doctitle", - "dotnet", - "dotnettool", - "editorconfig", - "filepart", - "fsproj", - "Gidget", - "gitattributes", - "gitignore", - "hotspots", - "ibiqlik", - "LINQ", - "maintainer", - "markdownlint", - "mermaid", - "MSBUILD", - "MSBUILDDISABLENODEREUSE", - "MSTest", - "mstest", - "myterm", - "ncipollo", - "NOASSERTION", - "ntia", - "nuget", - "nupkg", - "opencover", - "pagetitle", - "Pandoc", - "pandoc", - "purl", - "rezip", - "Pylint", - "Qube", - "reqstream", - "ReqStream", - "sandboxed", - "Sarif", - "SarifMark", - "SBOM", - "Semgrep", - "semver", - "slnx", - "snupkg", - "Sonar", - "SonarAnalyzer", - "SonarCloud", - "sonarmark", - "SonarMark", - "sonarscanner", - "SonarQube", - "spdx", - "SPDX", - "SPDXID", - "SpdxModel", - "SpdxTool", - "streetsidesoftware", - "TemplateDotNetTool", - "templatetool", - "testname", - "TMPL", - "tracematrix", - "triaging", - "Trivy", - "trx", - "vbproj", - "vcxproj", - "versionmark", - "VersionMark", - "Weasyprint", - "wildcards", - "YamlDotNet", - "yamllint" - ], - "ignorePaths": [ - "node_modules", - ".git", - "bin", - "obj", - "*.nupkg", - "*.snupkg", - "*.dll", - "*.exe", - "*.trx", - "*.spdx.json", - "package-lock.json", - "yarn.lock", - "AGENT_REPORT_*.md" - ] -} diff --git a/.cspell.yaml b/.cspell.yaml new file mode 100644 index 0000000..af42425 --- /dev/null +++ b/.cspell.yaml @@ -0,0 +1,136 @@ +--- +# Spell-Checking +# +# PURPOSE: +# - Maintain professional documentation and code quality +# - Catch spelling errors before publication +# - Support consistent technical terminology usage +# - Misspelled words should be fixed in the source +# - NEVER add a misspelled word to the 'words' list +# - PROPOSE only genuine technical terms/names as needed + +version: "0.2" +language: en + +# Project-specific technical terms and tool names +words: + - Anson + - Blockquotes + - buildmark + - BuildMark + - build_notes + - buildMultiTargeting + - buildnotes + - camelcase + - Checkmarx + - code_quality + - code_review_plan + - code_review_report + - CodeQL + - copilot + - cspell + - csproj + - dbproj + - dcterms + - declaredat + - Dema + - demaconsulting + - DEMACONSULTINGNUGETKEY + - Dependabot + - dependabot + - doctitle + - dotnet + - dotnettool + - editorconfig + - filepart + - fsproj + - Gidget + - gitattributes + - gitignore + - hotspots + - ibiqlik + - LINQ + - maintainer + - markdownlint + - mermaid + - MSBUILD + - MSBUILDDISABLENODEREUSE + - MSTest + - mstest + - myterm + - ncipollo + - NOASSERTION + - ntia + - nuget + - nupkg + - opencover + - pagetitle + - pandoc + - Pandoc + - Propagatable + - purl + - Pylint + - Qube + - reqstream + - ReqStream + - requirements_doc + - requirements_report + - reviewmark + - ReviewMark + - rezip + - sandboxed + - Sarif + - SarifMark + - SBOM + - Semgrep + - semver + - slnx + - snupkg + - Sonar + - SonarAnalyzer + - SonarCloud + - sonarmark + - SonarMark + - sonarscanner + - SonarQube + - spdx + - SPDX + - SPDXID + - SpdxModel + - SpdxTool + - streetsidesoftware + - templatetool + - testname + - TMPL + - trace_matrix + - tracematrix + - triaging + - Trivy + - trx + - vbproj + - vcxproj + - versionmark + - VersionMark + - Weasyprint + - wildcards + - YamlDotNet + - yamllint + +# Exclude common build artifacts, dependencies, and vendored third-party code +ignorePaths: + - "**/.git/**" + - "**/node_modules/**" + - "**/.venv/**" + - "**/thirdparty/**" + - "**/third-party/**" + - "**/3rd-party/**" + - "**/AGENT_REPORT_*.md" + - "**/bin/**" + - "**/obj/**" + - "*.nupkg" + - "*.snupkg" + - "*.dll" + - "*.exe" + - "*.trx" + - "*.spdx.json" + - package-lock.json 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 487a9b9..0000000 --- a/.github/agents/code-quality-agent.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -name: Code Quality Agent -description: Ensures code quality through linting and static analysis - responsible for security, maintainability, and correctness ---- - -# Code Quality Agent - SpdxTool - -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 - -### 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 - -### SpdxTool-Specific - -- **XML Docs**: Enforce on ALL members (public/internal/private) -- **Code Style**: Verify `.editorconfig` compliance -- **Test Naming**: Check `SpdxTool_*` 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.SpdxTool \ - --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 - -- **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 -- Change functional code without consulting appropriate developer agent diff --git a/.github/agents/code-quality.agent.md b/.github/agents/code-quality.agent.md new file mode 100644 index 0000000..4253eb6 --- /dev/null +++ b/.github/agents/code-quality.agent.md @@ -0,0 +1,219 @@ +--- +name: code-quality +description: Ensures code quality through comprehensive linting and static analysis. +tools: [read, search, edit, execute, github, agent] +user-invocable: true +--- + +# Code Quality Agent - SpdxTool + +Enforce comprehensive quality standards through linting, static analysis, +security scanning, and Continuous Compliance gate verification. + +## Reporting + +If detailed documentation of code quality analysis is needed, create a report using the +filename pattern `AGENT_REPORT_quality_analysis.md` to document quality metrics, +identified patterns, and improvement recommendations. + +## When to Invoke This Agent + +Use the Code Quality Agent for: + +- Enforcing all quality gates before merge/release +- Running and resolving linting issues across all file types +- Ensuring static analysis passes with zero blockers +- Verifying security scanning results and addressing vulnerabilities +- Validating Continuous Compliance requirements +- Maintaining lint scripts and linting tool infrastructure +- Troubleshooting quality gate failures in CI/CD + +## Primary Responsibilities + +**Quality Enforcement Context**: Code quality is enforced through CI pipelines +and automated workflows. Your role is to analyze, validate, and ensure quality +standards are met using existing tools and infrastructure, not to create new +enforcement mechanisms or helper scripts. + +### Comprehensive Quality Gate Enforcement + +The project MUST be: + +- **Secure**: Zero security vulnerabilities (CodeQL, SonarQube) +- **Maintainable**: Clean, formatted, documented code with zero warnings +- **Compliant**: Requirements traceability enforced, file reviews current +- **Correct**: Does what requirements specify with passing tests + +### Universal Quality Gates (ALL Must Pass) + +#### 1. Linting Standards (Zero Tolerance) + +**Primary Interface**: Use the comprehensive linting scripts for all routine checks: + +```bash +# Run comprehensive linting suite +./lint.sh # Unix/Linux/macOS +# or +lint.bat # Windows +``` + +**Note**: The @code-quality agent is responsible for maintaining the `lint.sh`/`lint.bat` scripts. + +#### 2. Build Quality (Zero Warnings) + +All builds must be configured to treat warnings as errors. +This ensures that compiler warnings are addressed immediately rather than accumulating as technical debt. + +#### 3. Static Analysis (Zero Blockers) + +- **SonarQube/SonarCloud**: Code quality and security analysis +- **CodeQL**: Security vulnerability scanning (SARIF output) +- **Language Analyzers**: Microsoft.CodeAnalysis.NetAnalyzers, SonarAnalyzer.CSharp +- **Custom Rules**: Project-specific quality rules + +#### 4. Continuous Compliance Verification + +```bash +# Requirements traceability enforcement +dotnet reqstream \ + --requirements requirements.yaml \ + --tests "test-results/**/*.trx" \ + --enforce + +# File review status enforcement (uses .reviewmark.yaml) +dotnet reviewmark --enforce +``` + +#### 5. Test Quality & Coverage + +- All tests must pass (zero failures) +- Requirements coverage enforced (no uncovered requirements) +- Test result artifacts properly generated (TRX, JUnit XML) + +## Comprehensive Tool Configuration + +**The @code-quality agent is responsible for maintaining the repository's linting +infrastructure, specifically the `lint.sh`/`lint.bat` scripts.** + +### Lint Script Maintenance + +When updating tool versions or maintaining linting infrastructure, +modify the lint scripts: + +- **`lint.sh`** - Unix/Linux/macOS comprehensive linting script +- **`lint.bat`** - Windows comprehensive linting script + +**IMPORTANT**: Modifications should be limited to tool version updates, +path corrections, or infrastructure improvements. Do not modify enforcement +standards, rule configurations, or quality thresholds as these define +compliance requirements. + +These scripts automatically handle: + +- Node.js tool installation (markdownlint-cli2, cspell) +- Python virtual environment setup and yamllint installation +- Tool execution with proper error handling and reporting + +### Static Analysis Integration + +#### SonarQube Quality Profile + +- **Reliability**: A rating (zero bugs) +- **Security**: A rating (zero vulnerabilities) +- **Maintainability**: A rating (zero code smells for new code) +- **Coverage**: Minimum threshold (typically 80%+ for new code) +- **Duplication**: Maximum threshold (typically <3% for new code) + +#### CodeQL Security Scanning + +- **Schedule**: On every push and pull request +- **Language Coverage**: All supported languages in repository +- **SARIF Output**: Integration with GitHub Security tab +- **Blocking**: Pipeline fails on HIGH/CRITICAL findings + +## SpdxTool-Specific Quality Rules + +- **XML Docs**: Enforce on ALL members (public/internal/private) with spaces after `///` +- **Code Style**: Verify `.editorconfig` compliance (file-scoped namespaces, 4-space indent) +- **Test Naming**: Check `SpdxTool_*` pattern for self-validation tests +- **Self-Validation**: Run `dotnet run --project src/DemaConsulting.SpdxTool -- --validate` + +## Quality Gate Execution Workflow + +### 1. Pre-Merge Quality Gates + +```bash +# Run comprehensive linting suite +./lint.sh # Unix/Linux/macOS +# or +lint.bat # Windows + +# Build with warnings as errors +dotnet build --configuration Release + +# Run self-validation tests +dotnet run --project src/DemaConsulting.SpdxTool \ + --configuration Release --framework net10.0 --no-build -- --validate + +# Requirements enforcement +dotnet reqstream --requirements requirements.yaml \ + --tests "test-results/**/*.trx" --enforce +``` + +### 2. Security Gate Validation + +```bash +# Dependency vulnerability scanning +dotnet list package --vulnerable --include-transitive +npm audit --audit-level=moderate +``` + +### 3. Documentation & Compliance Gates + +```bash +# File review status validation +dotnet reviewmark --definition .reviewmark.yaml --enforce + +# Generate compliance documentation +dotnet buildmark --tools tools.yaml --output docs/buildnotes.md +dotnet reqstream --report docs/requirements/requirements.md \ + --justifications docs/justifications/justifications.md +``` + +## Cross-Agent Coordination + +### Hand-off to Other Agents + +- If code quality issues need to be fixed, then call the @software-developer agent with the **request** to fix code + quality, security, or linting issues with **context** of specific quality gate failures and + **additional instructions** to maintain coding standards. +- If test coverage needs improvement or tests are failing, then call the @test-developer agent with the **request** + to improve test coverage or fix failing tests with **context** of current coverage metrics and failing test details. +- If documentation linting fails or documentation is missing, then call the @technical-writer agent with the + **request** to fix documentation linting or generate missing docs with **context** of specific linting failures and + documentation gaps. +- If requirements traceability fails, then call the @requirements agent with the **request** to address requirements + traceability failures with **context** of enforcement errors and missing test linkages. + +## Compliance Verification Checklist + +### Before Approving Any Changes + +1. **Linting**: All linting tools pass (markdownlint, cspell, yamllint, language linters) +2. **Build**: Zero warnings, zero errors in all configurations +3. **Static Analysis**: SonarQube quality gate GREEN, CodeQL no HIGH/CRITICAL findings +4. **Requirements**: ReqStream enforcement passes, all requirements covered +5. **Tests**: All tests pass, adequate coverage maintained +6. **Documentation**: All generated docs current, spell-check passes +7. **Security**: No vulnerability findings in dependencies or code +8. **File Reviews**: All reviewable files have current reviews (if applicable) + +## Don't Do These Things + +- **Never disable quality checks** to make builds pass (fix the underlying issue) +- **Never ignore security warnings** without documented risk acceptance +- **Never skip requirements enforcement** for "quick fixes" +- **Never modify functional code** without appropriate developer agent involvement +- **Never lower quality thresholds** without compliance team approval +- **Never commit with linting failures** (CI should block this) +- **Never bypass static analysis** findings without documented justification diff --git a/.github/agents/code-review.agent.md b/.github/agents/code-review.agent.md new file mode 100644 index 0000000..fb5de0c --- /dev/null +++ b/.github/agents/code-review.agent.md @@ -0,0 +1,46 @@ +--- +name: code-review +description: Assists in performing formal file reviews. +tools: [read, search, edit, execute, github, web, agent] +user-invocable: true +--- + +# Code Review Agent - SpdxTool + +Execute comprehensive code reviews with emphasis on structured compliance verification and file review status +requirements. + +## Reporting + +Create a report using the filename pattern `AGENT_REPORT_code_review_[review-set].md` +(e.g., `AGENT_REPORT_code_review_SpdxTool-Context.md`) to document review criteria, identified issues, and +recommendations for the specific review-set. + +## Review 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 make the report + +## Hand-off to Other Agents + +Only attempt to apply review fixes if requested. + +- If code quality, logic, or structural issues need fixing, call the @software-developer agent +- If test coverage gaps or quality issues are identified, call the @test-developer agent +- If documentation accuracy or completeness issues are found, call the @technical-writer agent +- If quality gate verification is needed after fixes, call the @code-quality agent +- If requirements traceability issues are discovered, call the @requirements agent + +## Don't Do These Things + +- **Never modify code during review** (document findings only, delegate fixes) +- **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** diff --git a/.github/agents/repo-consistency-agent.md b/.github/agents/repo-consistency.agent.md similarity index 100% rename from .github/agents/repo-consistency-agent.md rename to .github/agents/repo-consistency.agent.md diff --git a/.github/agents/requirements-agent.md b/.github/agents/requirements-agent.md deleted file mode 100644 index 12f6a4c..0000000 --- a/.github/agents/requirements-agent.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -name: Requirements Agent -description: Develops requirements and ensures appropriate test coverage - knows which requirements need unit/integration/self-validation tests ---- - -# Requirements Agent - SpdxTool - -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 - -### 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 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** (`SpdxTool_*`): 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 - -## 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 considering test linkage -- Change code directly (delegate to developer agents) diff --git a/.github/agents/requirements.agent.md b/.github/agents/requirements.agent.md new file mode 100644 index 0000000..51c8067 --- /dev/null +++ b/.github/agents/requirements.agent.md @@ -0,0 +1,100 @@ +--- +name: requirements +description: Develops requirements and ensures appropriate test coverage. +tools: [read, search, edit, execute, github, web, agent] +user-invocable: true +--- + +# Requirements Agent - SpdxTool + +Develop and maintain high-quality requirements with comprehensive test coverage linkage following Continuous +Compliance methodology for automated evidence generation and audit compliance. + +## Reporting + +If detailed documentation of requirements analysis is needed, create a report using the filename pattern +`AGENT_REPORT_requirements.md` to document requirement mappings, gap analysis, and traceability results. + +## When to Invoke This Agent + +Use the Requirements Agent for: + +- Creating new requirements in organized `docs/reqstream/` structure +- Establishing subsystem and software unit requirement files for independent review +- Reviewing and improving existing requirements quality and organization +- Ensuring proper requirements-to-test traceability +- Validating requirements enforcement in CI/CD pipelines +- Differentiating requirements from design/implementation details + +## Continuous Compliance Methodology + +### Core Principles + +The @requirements agent implements the Continuous Compliance methodology +, which provides automated compliance evidence +generation through structured requirements management. + +### Test Coverage Strategy & Linking + +#### Coverage Rules + +- **Requirements coverage**: Mandatory for all stated requirements +- **Test flexibility**: Not all tests need requirement links (corner cases, design validation, failure scenarios allowed) +- **Platform evidence**: Use source filters for platform/framework-specific requirements + +#### Source Filter Patterns (CRITICAL - DO NOT REMOVE) + +```yaml +tests: + - "windows@TestMethodName" # Windows platform evidence only + - "ubuntu@TestMethodName" # Linux (Ubuntu) platform evidence only + - "net8.0@TestMethodName" # .NET 8 runtime evidence only + - "net9.0@TestMethodName" # .NET 9 runtime evidence only + - "net10.0@TestMethodName" # .NET 10 runtime evidence only + - "TestMethodName" # Any platform evidence acceptable +``` + +**WARNING**: Removing source filters invalidates platform-specific compliance evidence and may cause audit failures. + +### SpdxTool Test Types + +- **Self-validation tests** (`SpdxTool_*`): Preferred for command-line behavior and features that ship with the + product. Located in `src/DemaConsulting.SpdxTool/SelfValidation/`. Implemented by @software-developer agent. +- **Unit tests**: For internal component behavior and isolated logic. Located in + `test/DemaConsulting.SpdxTool.Tests/`. Implemented by @test-developer agent. +- **Integration tests**: For cross-component interactions. Implemented by @test-developer agent. + +### Requirements Format + +Follow the `requirements.yaml` structure: + +```yaml +# requirements.yaml - Root configuration with includes only +includes: + - docs/reqstream/unit-context.yaml + - docs/reqstream/unit-program.yaml + - docs/reqstream/unit-commands.yaml + - docs/reqstream/unit-utility.yaml + - docs/reqstream/platform-requirements.yaml + - docs/reqstream/ots-mstest.yaml +``` + +Enforcement: `dotnet reqstream --requirements requirements.yaml --tests "test-results/**/*.trx" --enforce` + +## Cross-Agent Coordination + +### Hand-off to Other Agents + +- If features need to be implemented to satisfy requirements, then call the @software-developer agent +- If tests need to be created to validate requirements, then call the @test-developer agent +- If requirements traceability needs to be enforced in CI/CD, then call the @code-quality agent +- If requirements documentation needs generation or maintenance, then call the @technical-writer agent + +## Don't Do These Things + +- Create requirements without test linkage (CI will fail) +- Remove source filters from platform-specific requirements (breaks compliance) +- Mix implementation details with requirements (separate concerns) +- Skip justification text (required for compliance audits) +- Change test code directly (delegate to @test-developer agent) +- Modify CI/CD enforcement thresholds without compliance review diff --git a/.github/agents/software-developer.agent.md b/.github/agents/software-developer.agent.md new file mode 100644 index 0000000..a57ad33 --- /dev/null +++ b/.github/agents/software-developer.agent.md @@ -0,0 +1,129 @@ +--- +name: software-developer +description: Writes production code and self-validation tests. +tools: [read, search, edit, execute, github, agent] +user-invocable: true +--- + +# Software Developer Agent - SpdxTool + +Develop production code and self-validation tests with emphasis on testability, clarity, and compliance integration. + +## Reporting + +If detailed documentation of development work is needed, create a report using the filename pattern +`AGENT_REPORT_development.md` to document code changes, design decisions, and implementation details. + +## When to Invoke This Agent + +Use the Software Developer Agent for: + +- Implementing production code features and APIs +- Refactoring existing code for testability and maintainability +- Creating and maintaining self-validation tests (`SpdxTool_*`) +- Implementing requirement-driven functionality +- Code architecture and design decisions +- Integration with Continuous Compliance tooling + +## Primary Responsibilities + +### Literate Programming Style (MANDATORY) + +Write all code in **literate style** for maximum clarity and maintainability. + +#### Literate Style Rules + +- **Intent Comments:** Every paragraph starts with a comment explaining intent (not mechanics) +- **Logical Separation:** Blank lines separate logical code paragraphs +- **Purpose Over Process:** Comments describe why, code shows how +- **Standalone Clarity:** Reading comments alone should explain the algorithm/approach +- **Verification Support:** Code can be verified against the literate comments for correctness + +#### Example + +```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 & Compliance + +#### Code Architecture Principles + +- **Single Responsibility**: Functions with focused, testable purposes +- **Dependency Injection**: External dependencies injected for testing +- **Pure Functions**: Minimize side effects and hidden state +- **Clear Interfaces**: Well-defined API contracts +- **Separation of Concerns**: Business logic separate from infrastructure + +#### Compliance-Ready Code Structure + +- **Documentation Standards**: XML documentation required on ALL members (public/internal/private) with spaces + after `///` +- **Error Handling**: `ArgumentException` for parsing, `InvalidOperationException` for runtime issues +- **Namespaces**: File-scoped namespaces only +- **Using Statements**: Top of file only + +### Quality Gate Verification + +Before completing any code changes, verify: + +#### 1. Code Quality Standards + +- [ ] Zero compiler warnings (`TreatWarningsAsErrors=true`) +- [ ] Follows `.editorconfig` formatting rules (file-scoped namespaces, 4-space indent, UTF-8+BOM, LF) +- [ ] All code follows literate programming style +- [ ] XML documentation complete on all members (public/internal/private) +- [ ] Passes static analysis (SonarQube, CodeQL, language analyzers) + +#### 2. Testability & Design + +- [ ] Functions have single, clear responsibilities +- [ ] External dependencies are injectable/mockable +- [ ] Code is structured for unit testing +- [ ] Error handling covers expected failure scenarios + +#### 3. Self-Validation Tests (SpdxTool-Specific) + +- **Naming**: `SpdxTool_FeatureBeingValidated` +- **Location**: `src/DemaConsulting.SpdxTool/SelfValidation/` +- **Run via**: `--validate` flag +- **Format**: TRX/JUnit output supported via DemaConsulting.TestResults +- **Link**: Requirements in `requirements.yaml` + +## Cross-Agent Coordination + +### Hand-off to Other Agents + +- If comprehensive tests need to be created for implemented functionality, then call the @test-developer agent +- If quality gates and linting requirements need verification, then call the @code-quality agent +- If documentation needs updating to reflect code changes, then call the @technical-writer agent +- If implementation validation against requirements is needed, then call the @requirements agent + +## Compliance Verification Checklist + +### Before Completing Implementation + +1. **Code Quality**: Zero warnings, passes all static analysis +2. **Documentation**: XML documentation on ALL members +3. **Testability**: Code structured for comprehensive testing +4. **Security**: Input validation, error handling, authorization checks +5. **Traceability**: Implementation traceable to requirements +6. **Standards**: Follows all coding standards and formatting rules + +## Don't Do These Things + +- Skip literate programming comments (mandatory for all code) +- Disable compiler warnings to make builds pass +- Create untestable code with hidden dependencies +- Skip XML documentation on any members +- Implement functionality without requirement traceability +- Ignore static analysis or security scanning results +- Write monolithic functions with multiple responsibilities diff --git a/.github/agents/software-developer.md b/.github/agents/software-developer.md deleted file mode 100644 index 7c173ad..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 - SpdxTool - -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 (`SpdxTool_*`) -- 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 - -### SpdxTool-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: `SpdxTool_FeatureBeingValidated` -- These tests ship with the product and run via `--validate` flag -- Must support TRX/JUnit output format -- Located in `src/DemaConsulting.SpdxTool/SelfValidation/` -- Link to requirements in `requirements.yaml` - -## Defer To - -- **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.agent.md b/.github/agents/technical-writer.agent.md new file mode 100644 index 0000000..16560f2 --- /dev/null +++ b/.github/agents/technical-writer.agent.md @@ -0,0 +1,114 @@ +--- +name: technical-writer +description: Ensures documentation is accurate and complete. +tools: [read, search, edit, execute, github, agent] +user-invocable: true +--- + +# Technical Writer Agent - SpdxTool + +Create and maintain clear, accurate, and compliance-ready documentation following regulatory best practices +and Continuous Compliance standards. + +## Reporting + +If detailed documentation of writing and editing activities is needed, +create a report using the filename pattern `AGENT_REPORT_documentation.md` to document content changes, +style decisions, and editorial processes. + +## When to Invoke This Agent + +Use the Technical Writer Agent for: + +- Creating and updating project documentation (README, guides, CONTRIBUTING, specifications) +- Ensuring documentation accuracy, completeness, and compliance +- Implementing regulatory documentation best practices +- Managing auto-generated compliance documentation +- Applying markdown linting and style standards + +## Primary Responsibilities + +### Continuous Compliance Documentation Standards + +#### Auto-Generated Documentation (CRITICAL - Do Not Edit Manually) + +```yaml +docs/ + requirements/ + requirements.md # Generated by ReqStream + justifications/ + justifications.md # Generated by ReqStream + tracematrix/ + tracematrix.md # Generated by ReqStream + buildnotes/ + versions.md # Generated by VersionMark + quality/ + sonar-quality.md # Generated by SonarMark + codeql-quality.md # Generated by SarifMark +``` + +**WARNING**: These files are regenerated on every CI/CD run. Manual edits will be lost. + +### Documentation Quality Standards + +#### Content Longevity Principles + +**Avoid Transitory Information**: Long-term documentation should not include information that becomes stale quickly: + +- **❌ Avoid**: Tool version numbers, specific counts, current dates, "latest" references +- **✅ Instead**: Reference auto-generated reports, use relative descriptions, focus on stable concepts + +### Link Style Rules by File Type + +#### Published Documents (README.md) + +Use absolute URLs for external links - these documents are published/distributed (shipped in NuGet package). + +#### AI Agent Files (`.github/agents/*.agent.md`) + +Use inline links `[text](url)` so URLs are visible in agent context. + +#### All Other Markdown Files + +Use reference-style links `[text][ref]` with `[ref]: url` at document end. + +## SpdxTool-Specific Documentation + +- **User Guide**: `docs/guide/` +- **Command Reference**: `docs/spdx-tool-command-line.md` +- **ARCHITECTURE.md**: System structure, component relationships, key design decisions +- **CONTRIBUTING.md**: Contribution workflow and standards +- **README.md**: Project overview with badges, features, installation, usage + +### Spell Checking + +All files are spell-checked using cspell. **Never** add a word to the `.cspell.yaml` word list in order to +silence a spell-checking failure. Only add genuine technical terms after proposal and review. + +## Quality Gate Verification + +### Documentation Linting Checklist + +- [ ] markdownlint-cli2 passes with zero errors +- [ ] cspell passes with zero spelling errors +- [ ] yamllint passes for any YAML content +- [ ] Links are functional and use correct style (per file type) +- [ ] Generated documents compile without errors + +## Cross-Agent Coordination + +### Hand-off to Other Agents + +- If code examples or code comments need updating, then call the @software-developer agent +- If documentation linting and quality checks need to be run, then call the @code-quality agent +- If test procedures and coverage need documentation, then call the @test-developer agent + +## Don't Do These Things + +- **Never edit auto-generated documentation** manually (will be overwritten) +- **Never edit code comments directly** (delegate to @software-developer agent) +- **Never skip purpose and scope sections** in regulatory documents +- **Never ignore spelling errors** (add terms to `.cspell.yaml` only after proper proposal/review) +- **Never use incorrect link styles** for file types (breaks tooling) +- **Never commit documentation** without linting verification +- **Never document non-existent features** (code is source of truth) diff --git a/.github/agents/technical-writer.md b/.github/agents/technical-writer.md deleted file mode 100644 index 19024ab..0000000 --- a/.github/agents/technical-writer.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -name: Technical Writer -description: Ensures documentation is accurate and complete - knowledgeable about regulatory documentation and special document types ---- - -# Technical Writer - SpdxTool - -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 - -### SpdxTool-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 - -- **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.agent.md b/.github/agents/test-developer.agent.md new file mode 100644 index 0000000..759edb3 --- /dev/null +++ b/.github/agents/test-developer.agent.md @@ -0,0 +1,135 @@ +--- +name: test-developer +description: Writes unit and integration tests. +tools: [read, search, edit, execute, github, agent] +user-invocable: true +--- + +# Test Developer Agent - SpdxTool + +Develop comprehensive unit and integration tests with emphasis on requirements coverage and +Continuous Compliance verification. + +## Reporting + +If detailed documentation of testing activities is needed, +create a report using the filename pattern `AGENT_REPORT_testing.md` to document test strategies, coverage analysis, +and validation results. + +## When to Invoke This Agent + +Use the Test Developer Agent for: + +- Creating unit tests for new functionality +- Writing integration tests for component interactions +- Improving test coverage for compliance requirements +- Implementing AAA (Arrange-Act-Assert) pattern tests +- Generating platform-specific test evidence +- Upgrading legacy test suites to modern standards + +## Primary Responsibilities + +### Comprehensive Test Coverage Strategy + +#### Requirements Coverage (MANDATORY) + +- **All requirements MUST have linked tests** - Enforced by ReqStream +- **Platform-specific tests** must generate evidence with source filters +- **Test result formats** must be compatible (TRX, JUnit XML) + +#### Test Type Strategy (SpdxTool-Specific) + +- **NOT self-validation tests** - those are handled by @software-developer agent +- Unit tests live in `test/DemaConsulting.SpdxTool.Tests/` directory +- Targets tests live in `test/DemaConsulting.SpdxTool.Targets.Tests/` directory +- Use MSTest V4 testing framework +- Follow existing naming conventions in the test suite + +### AAA Pattern Implementation (MANDATORY) + +All tests MUST follow Arrange-Act-Assert pattern: + +```csharp +[TestMethod] +public void ClassName_MethodUnderTest_Scenario_ExpectedBehavior() +{ + // Arrange - Set up test data and dependencies + var input = "test data"; + var expected = "expected result"; + var component = new Component(); + + // Act - Execute the system under test + var actual = component.Method(input); + + // Assert - Verify expected outcomes + Assert.AreEqual(expected, actual); +} +``` + +### Test Naming Standards + +```csharp +// Pattern: ClassName_MethodUnderTest_Scenario_ExpectedBehavior +AddPackage_Execute_ValidInput_ReturnsSuccess() +FindPackage_Execute_NotFound_ReturnsNull() +Context_Create_WithInvalidFlag_ThrowsArgumentException() +``` + +### MSTest V4 Best Practices + +1. **Use `Assert.ThrowsExactly()`** for exception testing (avoid assertions in catch blocks - MSTEST0058) +2. **Use `Assert.AreEqual`** instead of `Assert.IsTrue(a == b)` for better failure messages +3. **Use `Assert.HasCount`** instead of `Assert.IsTrue(collection.Count == N)` +4. **Use `Assert.StartsWith`** instead of `Assert.IsTrue(value.StartsWith("prefix"))` +5. **Always make test classes and methods `public`** (internal classes are silently ignored) + +### Test Source Filters + +```yaml +tests: + - "windows@TestName" # Windows platform evidence only + - "ubuntu@TestName" # Linux (Ubuntu) platform evidence only + - "net8.0@TestName" # .NET 8 runtime evidence only + - "net9.0@TestName" # .NET 9 runtime evidence only + - "net10.0@TestName" # .NET 10 runtime evidence only +``` + +**WARNING**: Removing source filters invalidates platform-specific compliance evidence. + +## Quality Gate Verification + +### Test Quality Standards + +- [ ] All tests follow AAA pattern consistently +- [ ] Test names clearly describe scenario and expected outcome +- [ ] Each test validates single, specific behavior +- [ ] Both happy path and edge cases covered +- [ ] Platform-specific tests generate appropriate evidence +- [ ] Test results in standard formats (TRX) + +### Requirements Traceability + +- [ ] Tests linked to specific requirements in requirements.yaml +- [ ] Source filters applied for platform-specific requirements +- [ ] Test coverage adequate for all stated requirements +- [ ] ReqStream validation passes with linked tests + +## Cross-Agent Coordination + +### Hand-off to Other Agents + +- If test quality gates and coverage metrics need verification, then call the @code-quality agent +- If test linkage needs to satisfy requirements traceability, then call the @requirements agent +- If testable code structure improvements are needed, then call the @software-developer agent + +## Don't Do These Things + +- **Never skip AAA pattern** in test structure (mandatory for consistency) +- **Never create tests without clear names** (must describe scenario/expectation) +- **Never write flaky tests** that pass/fail inconsistently +- **Never test implementation details** (test behavior, not internal mechanics) +- **Never skip edge cases** and error conditions +- **Never create tests without requirements linkage** (for compliance requirements) +- **Never ignore platform-specific test evidence** requirements +- **Never commit failing tests** (all tests must pass before merge) +- **Never write self-validation tests** (delegate to @software-developer agent) diff --git a/.github/agents/test-developer.md b/.github/agents/test-developer.md deleted file mode 100644 index 1b2b752..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 - SpdxTool - -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. - -### SpdxTool-Specific - -- **NOT self-validation tests** - those are handled by Software Developer Agent -- Unit tests live in `test/DemaConsulting.SpdxTool.Tests/` 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/workflows/build.yaml b/.github/workflows/build.yaml index 3fdb273..75e1bf6 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -61,13 +61,13 @@ jobs: - name: Run markdown linter uses: DavidAnson/markdownlint-cli2-action@v22 with: - config: .markdownlint-cli2.jsonc + config: .markdownlint-cli2.yaml globs: '**/*.md' - name: Run spell checker uses: streetsidesoftware/cspell-action@v8 with: - config: .cspell.json + config: .cspell.yaml incremental_files_only: false files: | **/*.md diff --git a/.gitignore b/.gitignore index b8d2d16..d16957a 100644 --- a/.gitignore +++ b/.gitignore @@ -328,6 +328,9 @@ paket-files/ __pycache__/ *.pyc +# Python virtual environment +.venv/ + # Cake - Uncomment if you are using it # tools/** # !tools/packages.config diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc deleted file mode 100644 index a46ee1a..0000000 --- a/.markdownlint-cli2.jsonc +++ /dev/null @@ -1,15 +0,0 @@ -{ - "config": { - "default": true, - "MD003": { "style": "atx" }, - "MD007": { "indent": 2 }, - "MD013": { "line_length": 120 }, - "MD025": false, - "MD033": false, - "MD041": false - }, - "ignores": [ - "node_modules", - "**/AGENT_REPORT_*.md" - ] -} diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml new file mode 100644 index 0000000..04f1f80 --- /dev/null +++ b/.markdownlint-cli2.yaml @@ -0,0 +1,47 @@ +--- +# Markdown Linting Standards +# +# PURPOSE: +# - Maintain professional technical documentation standards +# - Ensure consistent formatting for readability and maintenance +# - Support automated documentation generation and publishing +# +# DO NOT MODIFY: These rules represent coding standards +# - If files fail linting, fix the files to meet these standards +# - Do not relax rules to accommodate existing non-compliant files +# - Consistency across repositories is critical for documentation quality + +config: + # Enable all default rules + default: true + + # Require ATX-style headers (# Header) instead of Setext-style + MD003: + style: atx + + # Set consistent indentation for nested lists + MD007: + indent: 2 + + # Allow longer lines for URLs and technical content + MD013: + line_length: 120 + + # Allow multiple top-level headers per document + MD025: false + + # Allow inline HTML for enhanced documentation + MD033: false + + # Allow documents without top-level header (for fragments) + MD041: false + +# Exclude common build artifacts, dependencies, and vendored third-party code +ignores: + - "**/.git/**" + - "**/node_modules/**" + - "**/.venv/**" + - "**/thirdparty/**" + - "**/third-party/**" + - "**/3rd-party/**" + - "**/AGENT_REPORT_*.md" diff --git a/.reviewmark.yaml b/.reviewmark.yaml new file mode 100644 index 0000000..5858b5d --- /dev/null +++ b/.reviewmark.yaml @@ -0,0 +1,95 @@ +--- +# 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: + - "**/*.cs" # All C# source and test files + - "docs/reqstream/**/*.yaml" # Requirements 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/SpdxTool/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: SpdxTool-Context + title: Review of SpdxTool Context Unit + paths: + - "docs/reqstream/unit-context.yaml" + - "src/**/Context.cs" + - "test/**/LogTests.cs" + + - id: SpdxTool-Program + title: Review of SpdxTool Program Unit + paths: + - "docs/reqstream/unit-program.yaml" + - "src/**/Program.cs" + - "src/**/SelfValidation/**" + - "test/**/SelfValidationTests.cs" + - "test/**/Runner.cs" + - "test/**/AssemblyInfo.cs" + + - id: SpdxTool-Commands + title: Review of SpdxTool Commands Unit + paths: + - "docs/reqstream/unit-commands.yaml" + - "src/**/Commands/**" + - "test/**/AddPackageTests.cs" + - "test/**/AddRelationshipTests.cs" + - "test/**/CommandTests.cs" + - "test/**/CopyPackageTests.cs" + - "test/**/DiagramTests.cs" + - "test/**/FindPackageTests.cs" + - "test/**/GetVersionTests.cs" + - "test/**/HashTests.cs" + - "test/**/HelpTests.cs" + - "test/**/PrintTests.cs" + - "test/**/QueryTests.cs" + - "test/**/RenameIdTests.cs" + - "test/**/RunWorkflowTests.cs" + - "test/**/SetVariableTests.cs" + - "test/**/SilentTests.cs" + - "test/**/ToMarkdownTests.cs" + - "test/**/UnknownCommandTests.cs" + - "test/**/UpdatePackageTests.cs" + - "test/**/UsageTests.cs" + - "test/**/ValidateTests.cs" + - "test/**/VersionTests.cs" + + - id: SpdxTool-Utility + title: Review of SpdxTool Utility Unit + paths: + - "docs/reqstream/unit-utility.yaml" + - "src/**/Utility/**" + - "src/**/Spdx/**" + - "test/**/PathHelpersTests.cs" + + # Platform and OTS dependency reviews + - id: Platform-Support + title: Review of Platform and Runtime Support Requirements + paths: + - "docs/reqstream/platform-requirements.yaml" + + - id: OTS-Dependencies + title: Review of Off-The-Shelf Software Dependencies + paths: + - "docs/reqstream/ots-mstest.yaml" + - "docs/reqstream/ots-reqstream.yaml" + - "docs/reqstream/ots-buildmark.yaml" + - "docs/reqstream/ots-versionmark.yaml" + - "docs/reqstream/ots-sarifmark.yaml" + - "docs/reqstream/ots-sonarmark.yaml" + - "docs/reqstream/ots-reviewmark.yaml" + - "docs/reqstream/ots-yamldotnet.yaml" diff --git a/.yamllint.yaml b/.yamllint.yaml index efd8cce..6c6c4fb 100644 --- a/.yamllint.yaml +++ b/.yamllint.yaml @@ -1,14 +1,31 @@ --- -# yamllint configuration for SpdxTool -# This configuration defines the rules for YAML file linting +# YAML Linting Standards +# +# PURPOSE: +# - Maintain consistent code quality and readability standards +# - Support CI/CD workflows with reliable YAML parsing +# - Ensure professional documentation and configuration files +# +# DO NOT MODIFY: These rules represent coding standards +# - If files fail linting, fix the files to meet these standards +# - Do not relax rules to accommodate existing non-compliant files +# - Consistency across repositories is critical for maintainability extends: default +# Exclude common build artifacts, dependencies, and vendored third-party code +ignore: | + .git/ + node_modules/ + .venv/ + thirdparty/ + third-party/ + 3rd-party/ + rules: # Allow 'on:' in GitHub Actions workflows (not a boolean value) truthy: allowed-values: ['true', 'false', 'on', 'off'] - check-keys: true # Allow longer lines for URLs and complex expressions line-length: diff --git a/AGENTS.md b/AGENTS.md index 5f8b167..ee2847f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,6 +10,7 @@ manipulating SPDX SBOM files. - **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 +- **Code Review Agent** - Assists in performing formal file reviews - **Repo Consistency Agent** - Ensures SpdxTool remains consistent with TemplateDotNetTool patterns ## Agent Selection Guide @@ -22,6 +23,7 @@ manipulating SPDX SBOM files. - 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** +- Perform formal file reviews → **Code Review Agent** - Propagate template changes → **Repo Consistency Agent** ## Tech Stack @@ -32,7 +34,7 @@ manipulating SPDX SBOM files. - **`requirements.yaml`** - All requirements with test linkage (enforced via `dotnet reqstream --enforce`) - **`.editorconfig`** - Code style (file-scoped namespaces, 4-space indent, UTF-8+BOM, LF endings) -- **`.cspell.json`, `.markdownlint-cli2.jsonc`, `.yamllint.yaml`** - Linting configs +- **`.cspell.yaml`, `.markdownlint-cli2.yaml`, `.yamllint.yaml`** - Linting configs ## Requirements diff --git a/lint.bat b/lint.bat index 1fb5ff2..f94b53d 100644 --- a/lint.bat +++ b/lint.bat @@ -1,20 +1,40 @@ @echo off -REM Run all linters for SPDX Tool (Windows) +setlocal -echo Checking markdown... -call npx markdownlint-cli2 "**/*.md" -if %errorlevel% neq 0 exit /b %errorlevel% +REM Comprehensive Linting Script +REM +REM PURPOSE: +REM - Run ALL lint checks when executed (no options or modes) +REM - Output lint failures directly for agent parsing +REM - NO command-line arguments, pretty printing, or colorization +REM - Agents execute this script to identify files needing fixes + +set "LINT_ERROR=0" + +REM Install npm dependencies +call npm install -echo Checking spelling... -call npx cspell "**/*.{cs,md,json,yaml,yml}" --no-progress -if %errorlevel% neq 0 exit /b %errorlevel% +REM Create Python virtual environment (for yamllint) if missing +if not exist ".venv\Scripts\activate.bat" ( + python -m venv .venv +) +call .venv\Scripts\activate.bat +pip install -r pip-requirements.txt + +REM Run spell check +call npx cspell --no-progress --no-color "**/*.{md,yaml,yml,json,cs,cpp,hpp,h,txt}" +if errorlevel 1 set "LINT_ERROR=1" + +REM Run markdownlint check +call npx markdownlint-cli2 "**/*.md" +if errorlevel 1 set "LINT_ERROR=1" -echo Checking YAML... -call yamllint -c .yamllint.yaml . -if %errorlevel% neq 0 exit /b %errorlevel% +REM Run yamllint check +yamllint . +if errorlevel 1 set "LINT_ERROR=1" -echo Checking code formatting... +REM Run .NET formatting check (verifies no changes are needed) dotnet format --verify-no-changes -if %errorlevel% neq 0 exit /b %errorlevel% +if errorlevel 1 set "LINT_ERROR=1" -echo All linting passed! +exit /b %LINT_ERROR% diff --git a/lint.sh b/lint.sh index 671df6f..7d8116b 100755 --- a/lint.sh +++ b/lint.sh @@ -1,18 +1,35 @@ -#!/usr/bin/env bash -# Run all linters for SPDX Tool +#!/bin/bash -set -e # Exit on error +# Comprehensive Linting Script +# +# PURPOSE: +# - Run ALL lint checks when executed (no options or modes) +# - Output lint failures directly for agent parsing +# - NO command-line arguments, pretty printing, or colorization +# - Agents execute this script to identify files needing fixes -echo "📝 Checking markdown..." -npx markdownlint-cli2 "**/*.md" +lint_error=0 -echo "🔤 Checking spelling..." -npx cspell "**/*.{cs,md,json,yaml,yml}" --no-progress +# Install npm dependencies +npm install -echo "📋 Checking YAML..." -yamllint -c .yamllint.yaml . +# Create Python virtual environment (for yamllint) +if [ ! -d ".venv" ]; then + python -m venv .venv +fi +source .venv/bin/activate +pip install -r pip-requirements.txt -echo "🎨 Checking code formatting..." -dotnet format --verify-no-changes +# Run spell check +npx cspell --no-progress --no-color "**/*.{md,yaml,yml,json,cs,cpp,hpp,h,txt}" || lint_error=1 -echo "✨ All linting passed!" +# Run markdownlint check +npx markdownlint-cli2 "**/*.md" || lint_error=1 + +# Run yamllint check +yamllint . || lint_error=1 + +# Run .NET formatting check (verifies no changes are needed) +dotnet format --verify-no-changes || lint_error=1 + +exit $lint_error diff --git a/package.json b/package.json index ccccfb1..a57dc1f 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,9 @@ { "private": true, - "dependencies": { + "devDependencies": { "@mermaid-js/mermaid-cli": "11.12.0", + "cspell": "9.7.0", + "markdownlint-cli2": "0.21.0", "mermaid-filter": "1.4.7" } } diff --git a/pip-requirements.txt b/pip-requirements.txt new file mode 100644 index 0000000..7ce0eab --- /dev/null +++ b/pip-requirements.txt @@ -0,0 +1 @@ +yamllint==1.38.0 From cda0722aa3c89f3b3953249f054b131d1bde4d3d Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 24 Mar 2026 13:32:14 +0000 Subject: [PATCH 3/9] Add TemplateDotNetTool to cspell word list Referenced in AGENTS.md consistency guidance. --- .cspell.yaml | 1 + .github/agents/repo-consistency.agent.md | 141 +++++------------------ 2 files changed, 27 insertions(+), 115 deletions(-) diff --git a/.cspell.yaml b/.cspell.yaml index af42425..7bf70f1 100644 --- a/.cspell.yaml +++ b/.cspell.yaml @@ -100,6 +100,7 @@ words: - SpdxTool - streetsidesoftware - templatetool + - TemplateDotNetTool - testname - TMPL - trace_matrix diff --git a/.github/agents/repo-consistency.agent.md b/.github/agents/repo-consistency.agent.md index aa1af10..c67ce98 100644 --- a/.github/agents/repo-consistency.agent.md +++ b/.github/agents/repo-consistency.agent.md @@ -1,128 +1,39 @@ --- -name: Repo Consistency Agent -description: Ensures SpdxTool remains consistent with the TemplateDotNetTool template patterns and best practices +name: repo-consistency +description: Ensures SpdxTool remains consistent with the TemplateDotNetTool template patterns and best practices. +tools: [read, search, edit, execute, github, agent] +user-invocable: true --- -# Repo Consistency Agent - SpdxTool +# Repo Consistency Agent -Maintain consistency between SpdxTool and the TemplateDotNetTool template at . +Maintain consistency between SpdxTool and the TemplateDotNetTool template, ensuring this repository +benefits from template evolution while respecting project-specific customizations. -## When to Invoke This Agent +## Reporting -Invoke the repo-consistency-agent for: +If detailed documentation of consistency analysis is needed, create a report using the filename pattern +`AGENT_REPORT_consistency_SpdxTool.md` to document consistency gaps, template evolution updates, and +recommended changes for this repository. -- Periodic reviews to check if SpdxTool follows the latest TemplateDotNetTool patterns -- Identifying drift from template standards -- Recommending updates to bring SpdxTool back in sync with the template +## Consistency Steps -## Responsibilities +1. Fetch the 20 most recently merged PRs (`is:pr is:merged sort:updated-desc`) from +2. Determine the intent of the template pull requests (what changes were performed to which files) +3. Apply missing changes to this repository's files (if appropriate and with translation) -### Consistency Checks +## Don't Do These Things -The agent reviews the following areas of SpdxTool for consistency with the TemplateDotNetTool 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 workflows may need deviations for SpdxTool-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**: `SelfValidation/` 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 SpdxTool-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) - -### Tracking Template Evolution - -To ensure SpdxTool benefits 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 SpdxTool: - - Focus on structural changes (workflows, agents, configurations) over content-specific changes - - Note changes to `.github/`, linting configurations, project patterns, and documentation structure - -3. **Check SpdxTool Application**: Verify if identified changes exist in SpdxTool: - - Check if similar files/patterns exist in SpdxTool - - Compare file contents between template and SpdxTool - - Look for similar PR titles or commit messages in SpdxTool 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 SpdxTool - - Specific files or patterns that need updating - -### Review Process - -1. **Identify Differences**: Compare SpdxTool structure with TemplateDotNetTool 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 SpdxTool-specific customizations - -### What NOT to Flag - -- SpdxTool-specific naming (tool names, package IDs, repository URLs) -- SPDX/SBOM-specific commands, workflows, and features -- SpdxTool-specific spell check exceptions in `.cspell.json` -- Workflow variations for SpdxTool-specific project needs -- Additional requirements or features beyond the template -- SpdxTool-specific dependencies - -## Defer To - -- **Software Developer Agent**: For implementing code changes recommended by consistency check -- **Technical Writer Agent**: For updating documentation to match template -- **Test Developer Agent**: For updating test patterns -- **Code Quality Agent**: For applying linting and code style changes - -## Usage Pattern - -1. Access the TemplateDotNetTool template at -2. Compare SpdxTool structure and patterns against the template -3. Review any identified differences -4. Apply relevant changes using appropriate specialized agents -5. Test changes to ensure they don't break existing functionality +- **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) ## Key Principles -- **Template Evolution**: As the template evolves, this agent helps SpdxTool stay current -- **Respect Customization**: Not all differences are problems - some are valid SPDX-specific customizations -- **Incremental Adoption**: SpdxTool can adopt template changes incrementally -- **Documentation**: When recommending changes, explain why they align with best practices +- **Evolutionary Consistency**: Template improvements should enhance downstream projects systematically +- **Intelligent Customization Respect**: Distinguished valid customizations from unintentional drift +- **Incremental Template Adoption**: Support phased adoption of template improvements based on project capacity From 27af70141bce22f6d4d5116c48491a1805c8f227 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 24 Mar 2026 13:39:00 +0000 Subject: [PATCH 4/9] Fix reviewmark.yaml paths, cleanup cspell wordlist, and fix lint.sh variable naming Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> Agent-Logs-Url: https://github.com/demaconsulting/SpdxTool/sessions/70daa113-6d7e-4a84-929f-1b125a5aeed8 --- .cspell.yaml | 9 +-------- .reviewmark.yaml | 36 +++++++++--------------------------- lint.sh | 12 ++++++------ 3 files changed, 16 insertions(+), 41 deletions(-) diff --git a/.cspell.yaml b/.cspell.yaml index 7bf70f1..8624285 100644 --- a/.cspell.yaml +++ b/.cspell.yaml @@ -18,14 +18,10 @@ words: - Blockquotes - buildmark - BuildMark - - build_notes - - buildMultiTargeting - buildnotes + - buildMultiTargeting - camelcase - Checkmarx - - code_quality - - code_review_plan - - code_review_report - CodeQL - copilot - cspell @@ -73,8 +69,6 @@ words: - Qube - reqstream - ReqStream - - requirements_doc - - requirements_report - reviewmark - ReviewMark - rezip @@ -103,7 +97,6 @@ words: - TemplateDotNetTool - testname - TMPL - - trace_matrix - tracematrix - triaging - Trivy diff --git a/.reviewmark.yaml b/.reviewmark.yaml index 5858b5d..f6b6c8d 100644 --- a/.reviewmark.yaml +++ b/.reviewmark.yaml @@ -6,10 +6,9 @@ # Patterns identifying all files that require review. # Processed in order; prefix a pattern with '!' to exclude. needs-review: - - "**/*.cs" # All C# source and test files - - "docs/reqstream/**/*.yaml" # Requirements files - - "!**/obj/**" # Exclude build output - - "!**/bin/**" # Exclude build output + - "**/*.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. @@ -20,21 +19,19 @@ evidence-source: location: https://raw.githubusercontent.com/demaconsulting/SpdxTool/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 +# Each review-set groups 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 + # Software unit reviews - id: SpdxTool-Context title: Review of SpdxTool Context Unit paths: - - "docs/reqstream/unit-context.yaml" - "src/**/Context.cs" - "test/**/LogTests.cs" - id: SpdxTool-Program title: Review of SpdxTool Program Unit paths: - - "docs/reqstream/unit-program.yaml" - "src/**/Program.cs" - "src/**/SelfValidation/**" - "test/**/SelfValidationTests.cs" @@ -44,7 +41,6 @@ reviews: - id: SpdxTool-Commands title: Review of SpdxTool Commands Unit paths: - - "docs/reqstream/unit-commands.yaml" - "src/**/Commands/**" - "test/**/AddPackageTests.cs" - "test/**/AddRelationshipTests.cs" @@ -67,29 +63,15 @@ reviews: - "test/**/UsageTests.cs" - "test/**/ValidateTests.cs" - "test/**/VersionTests.cs" + - "test/**/WildcardTests.cs" - id: SpdxTool-Utility title: Review of SpdxTool Utility Unit paths: - - "docs/reqstream/unit-utility.yaml" - - "src/**/Utility/**" - "src/**/Spdx/**" - "test/**/PathHelpersTests.cs" - # Platform and OTS dependency reviews - - id: Platform-Support - title: Review of Platform and Runtime Support Requirements + - id: SpdxTool-Targets + title: Review of SpdxTool MSBuild Targets Unit paths: - - "docs/reqstream/platform-requirements.yaml" - - - id: OTS-Dependencies - title: Review of Off-The-Shelf Software Dependencies - paths: - - "docs/reqstream/ots-mstest.yaml" - - "docs/reqstream/ots-reqstream.yaml" - - "docs/reqstream/ots-buildmark.yaml" - - "docs/reqstream/ots-versionmark.yaml" - - "docs/reqstream/ots-sarifmark.yaml" - - "docs/reqstream/ots-sonarmark.yaml" - - "docs/reqstream/ots-reviewmark.yaml" - - "docs/reqstream/ots-yamldotnet.yaml" + - "test/DemaConsulting.SpdxTool.Targets.Tests/**" diff --git a/lint.sh b/lint.sh index 7d8116b..374ab79 100755 --- a/lint.sh +++ b/lint.sh @@ -8,7 +8,7 @@ # - NO command-line arguments, pretty printing, or colorization # - Agents execute this script to identify files needing fixes -lint_error=0 +LINT_ERROR=0 # Install npm dependencies npm install @@ -21,15 +21,15 @@ source .venv/bin/activate pip install -r pip-requirements.txt # Run spell check -npx cspell --no-progress --no-color "**/*.{md,yaml,yml,json,cs,cpp,hpp,h,txt}" || lint_error=1 +npx cspell --no-progress --no-color "**/*.{md,yaml,yml,json,cs,cpp,hpp,h,txt}" || LINT_ERROR=1 # Run markdownlint check -npx markdownlint-cli2 "**/*.md" || lint_error=1 +npx markdownlint-cli2 "**/*.md" || LINT_ERROR=1 # Run yamllint check -yamllint . || lint_error=1 +yamllint . || LINT_ERROR=1 # Run .NET formatting check (verifies no changes are needed) -dotnet format --verify-no-changes || lint_error=1 +dotnet format --verify-no-changes || LINT_ERROR=1 -exit $lint_error +exit $LINT_ERROR From 5c15cf5a8ed851851365e6cfb90d3404e8ea145a Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 30 Mar 2026 10:32:41 +0000 Subject: [PATCH 5/9] Apply TemplateDotNetTool PR #75, #76, #77 improvements PR #75 - Formalize build_notes.md path and artifact handling: - technical-writer.agent.md: Update docs structure to show build_notes.md at docs/ level and build_notes/ folder for versions.md - release.yaml: Remove 'Move buildnotes.md to root' step, use artifact path directly (artifacts/buildnotes.md) for release body PR #76 - Agent and lint cleanup: - .cspell.yaml: Add **/.agent-logs/** to ignorePaths - .markdownlint-cli2.yaml: Add noBanner/noProgress options and **/.agent-logs/** to ignores - .yamllint.yaml: Add .agent-logs/ to ignore list - .gitignore: Add .agent-logs/ directory - lint.sh: Lowercase LINT_ERROR variable, add --silent/--quiet flags - lint.bat: Add --silent/--quiet flags to npm/pip/cspell - Delete code-quality.agent.md (replaced by quality.agent.md) - Create quality.agent.md with standards-based quality assessment - Create developer.agent.md for general-purpose development - Create implementation.agent.md for orchestrated implementations - Update code-review.agent.md with new reporting to .agent-logs/ - Update repo-consistency.agent.md with mandatory workflow steps - Update reporting sections in requirements/software-developer/ technical-writer/test-developer agents to use .agent-logs/ - Update @code-quality references to @quality across all agents - Create .github/standards/ directory with 6 standards files: csharp-language.md, csharp-testing.md, reqstream-usage.md, reviewmark-usage.md, software-items.md, technical-documentation.md - AGENTS.md: Add standards application section, agent delegation guidelines, restructure available agents list, update reporting PR #77 - Markdown format requirements (included in technical-documentation.md) Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --- .cspell.yaml | 1 + .github/agents/code-quality.agent.md | 219 ------------------- .github/agents/code-review.agent.md | 75 +++++-- .github/agents/developer.agent.md | 49 +++++ .github/agents/implementation.agent.md | 93 ++++++++ .github/agents/quality.agent.md | 125 +++++++++++ .github/agents/repo-consistency.agent.md | 71 ++++-- .github/agents/requirements.agent.md | 7 +- .github/agents/software-developer.agent.md | 7 +- .github/agents/technical-writer.agent.md | 19 +- .github/agents/test-developer.agent.md | 6 +- .github/standards/csharp-language.md | 86 ++++++++ .github/standards/csharp-testing.md | 119 ++++++++++ .github/standards/reqstream-usage.md | 146 +++++++++++++ .github/standards/reviewmark-usage.md | 151 +++++++++++++ .github/standards/software-items.md | 45 ++++ .github/standards/technical-documentation.md | 172 +++++++++++++++ .github/workflows/release.yaml | 7 +- .gitignore | 3 + .markdownlint-cli2.yaml | 6 + .yamllint.yaml | 1 + AGENTS.md | 85 ++++--- lint.bat | 6 +- lint.sh | 16 +- 24 files changed, 1195 insertions(+), 320 deletions(-) delete mode 100644 .github/agents/code-quality.agent.md create mode 100644 .github/agents/developer.agent.md create mode 100644 .github/agents/implementation.agent.md create mode 100644 .github/agents/quality.agent.md create mode 100644 .github/standards/csharp-language.md create mode 100644 .github/standards/csharp-testing.md create mode 100644 .github/standards/reqstream-usage.md create mode 100644 .github/standards/reviewmark-usage.md create mode 100644 .github/standards/software-items.md create mode 100644 .github/standards/technical-documentation.md diff --git a/.cspell.yaml b/.cspell.yaml index 8624285..0fadb5a 100644 --- a/.cspell.yaml +++ b/.cspell.yaml @@ -119,6 +119,7 @@ ignorePaths: - "**/third-party/**" - "**/3rd-party/**" - "**/AGENT_REPORT_*.md" + - "**/.agent-logs/**" - "**/bin/**" - "**/obj/**" - "*.nupkg" diff --git a/.github/agents/code-quality.agent.md b/.github/agents/code-quality.agent.md deleted file mode 100644 index 4253eb6..0000000 --- a/.github/agents/code-quality.agent.md +++ /dev/null @@ -1,219 +0,0 @@ ---- -name: code-quality -description: Ensures code quality through comprehensive linting and static analysis. -tools: [read, search, edit, execute, github, agent] -user-invocable: true ---- - -# Code Quality Agent - SpdxTool - -Enforce comprehensive quality standards through linting, static analysis, -security scanning, and Continuous Compliance gate verification. - -## Reporting - -If detailed documentation of code quality analysis is needed, create a report using the -filename pattern `AGENT_REPORT_quality_analysis.md` to document quality metrics, -identified patterns, and improvement recommendations. - -## When to Invoke This Agent - -Use the Code Quality Agent for: - -- Enforcing all quality gates before merge/release -- Running and resolving linting issues across all file types -- Ensuring static analysis passes with zero blockers -- Verifying security scanning results and addressing vulnerabilities -- Validating Continuous Compliance requirements -- Maintaining lint scripts and linting tool infrastructure -- Troubleshooting quality gate failures in CI/CD - -## Primary Responsibilities - -**Quality Enforcement Context**: Code quality is enforced through CI pipelines -and automated workflows. Your role is to analyze, validate, and ensure quality -standards are met using existing tools and infrastructure, not to create new -enforcement mechanisms or helper scripts. - -### Comprehensive Quality Gate Enforcement - -The project MUST be: - -- **Secure**: Zero security vulnerabilities (CodeQL, SonarQube) -- **Maintainable**: Clean, formatted, documented code with zero warnings -- **Compliant**: Requirements traceability enforced, file reviews current -- **Correct**: Does what requirements specify with passing tests - -### Universal Quality Gates (ALL Must Pass) - -#### 1. Linting Standards (Zero Tolerance) - -**Primary Interface**: Use the comprehensive linting scripts for all routine checks: - -```bash -# Run comprehensive linting suite -./lint.sh # Unix/Linux/macOS -# or -lint.bat # Windows -``` - -**Note**: The @code-quality agent is responsible for maintaining the `lint.sh`/`lint.bat` scripts. - -#### 2. Build Quality (Zero Warnings) - -All builds must be configured to treat warnings as errors. -This ensures that compiler warnings are addressed immediately rather than accumulating as technical debt. - -#### 3. Static Analysis (Zero Blockers) - -- **SonarQube/SonarCloud**: Code quality and security analysis -- **CodeQL**: Security vulnerability scanning (SARIF output) -- **Language Analyzers**: Microsoft.CodeAnalysis.NetAnalyzers, SonarAnalyzer.CSharp -- **Custom Rules**: Project-specific quality rules - -#### 4. Continuous Compliance Verification - -```bash -# Requirements traceability enforcement -dotnet reqstream \ - --requirements requirements.yaml \ - --tests "test-results/**/*.trx" \ - --enforce - -# File review status enforcement (uses .reviewmark.yaml) -dotnet reviewmark --enforce -``` - -#### 5. Test Quality & Coverage - -- All tests must pass (zero failures) -- Requirements coverage enforced (no uncovered requirements) -- Test result artifacts properly generated (TRX, JUnit XML) - -## Comprehensive Tool Configuration - -**The @code-quality agent is responsible for maintaining the repository's linting -infrastructure, specifically the `lint.sh`/`lint.bat` scripts.** - -### Lint Script Maintenance - -When updating tool versions or maintaining linting infrastructure, -modify the lint scripts: - -- **`lint.sh`** - Unix/Linux/macOS comprehensive linting script -- **`lint.bat`** - Windows comprehensive linting script - -**IMPORTANT**: Modifications should be limited to tool version updates, -path corrections, or infrastructure improvements. Do not modify enforcement -standards, rule configurations, or quality thresholds as these define -compliance requirements. - -These scripts automatically handle: - -- Node.js tool installation (markdownlint-cli2, cspell) -- Python virtual environment setup and yamllint installation -- Tool execution with proper error handling and reporting - -### Static Analysis Integration - -#### SonarQube Quality Profile - -- **Reliability**: A rating (zero bugs) -- **Security**: A rating (zero vulnerabilities) -- **Maintainability**: A rating (zero code smells for new code) -- **Coverage**: Minimum threshold (typically 80%+ for new code) -- **Duplication**: Maximum threshold (typically <3% for new code) - -#### CodeQL Security Scanning - -- **Schedule**: On every push and pull request -- **Language Coverage**: All supported languages in repository -- **SARIF Output**: Integration with GitHub Security tab -- **Blocking**: Pipeline fails on HIGH/CRITICAL findings - -## SpdxTool-Specific Quality Rules - -- **XML Docs**: Enforce on ALL members (public/internal/private) with spaces after `///` -- **Code Style**: Verify `.editorconfig` compliance (file-scoped namespaces, 4-space indent) -- **Test Naming**: Check `SpdxTool_*` pattern for self-validation tests -- **Self-Validation**: Run `dotnet run --project src/DemaConsulting.SpdxTool -- --validate` - -## Quality Gate Execution Workflow - -### 1. Pre-Merge Quality Gates - -```bash -# Run comprehensive linting suite -./lint.sh # Unix/Linux/macOS -# or -lint.bat # Windows - -# Build with warnings as errors -dotnet build --configuration Release - -# Run self-validation tests -dotnet run --project src/DemaConsulting.SpdxTool \ - --configuration Release --framework net10.0 --no-build -- --validate - -# Requirements enforcement -dotnet reqstream --requirements requirements.yaml \ - --tests "test-results/**/*.trx" --enforce -``` - -### 2. Security Gate Validation - -```bash -# Dependency vulnerability scanning -dotnet list package --vulnerable --include-transitive -npm audit --audit-level=moderate -``` - -### 3. Documentation & Compliance Gates - -```bash -# File review status validation -dotnet reviewmark --definition .reviewmark.yaml --enforce - -# Generate compliance documentation -dotnet buildmark --tools tools.yaml --output docs/buildnotes.md -dotnet reqstream --report docs/requirements/requirements.md \ - --justifications docs/justifications/justifications.md -``` - -## Cross-Agent Coordination - -### Hand-off to Other Agents - -- If code quality issues need to be fixed, then call the @software-developer agent with the **request** to fix code - quality, security, or linting issues with **context** of specific quality gate failures and - **additional instructions** to maintain coding standards. -- If test coverage needs improvement or tests are failing, then call the @test-developer agent with the **request** - to improve test coverage or fix failing tests with **context** of current coverage metrics and failing test details. -- If documentation linting fails or documentation is missing, then call the @technical-writer agent with the - **request** to fix documentation linting or generate missing docs with **context** of specific linting failures and - documentation gaps. -- If requirements traceability fails, then call the @requirements agent with the **request** to address requirements - traceability failures with **context** of enforcement errors and missing test linkages. - -## Compliance Verification Checklist - -### Before Approving Any Changes - -1. **Linting**: All linting tools pass (markdownlint, cspell, yamllint, language linters) -2. **Build**: Zero warnings, zero errors in all configurations -3. **Static Analysis**: SonarQube quality gate GREEN, CodeQL no HIGH/CRITICAL findings -4. **Requirements**: ReqStream enforcement passes, all requirements covered -5. **Tests**: All tests pass, adequate coverage maintained -6. **Documentation**: All generated docs current, spell-check passes -7. **Security**: No vulnerability findings in dependencies or code -8. **File Reviews**: All reviewable files have current reviews (if applicable) - -## Don't Do These Things - -- **Never disable quality checks** to make builds pass (fix the underlying issue) -- **Never ignore security warnings** without documented risk acceptance -- **Never skip requirements enforcement** for "quick fixes" -- **Never modify functional code** without appropriate developer agent involvement -- **Never lower quality thresholds** without compliance team approval -- **Never commit with linting failures** (CI should block this) -- **Never bypass static analysis** findings without documented justification diff --git a/.github/agents/code-review.agent.md b/.github/agents/code-review.agent.md index fb5de0c..f28a9b7 100644 --- a/.github/agents/code-review.agent.md +++ b/.github/agents/code-review.agent.md @@ -1,46 +1,73 @@ --- name: code-review -description: Assists in performing formal file reviews. -tools: [read, search, edit, execute, github, web, agent] +description: Agent for performing formal reviews user-invocable: true --- -# Code Review Agent - SpdxTool +# Code Review Agent -Execute comprehensive code reviews with emphasis on structured compliance verification and file review status -requirements. +This agent runs the formal review based on the review-set it's told to perform. -## Reporting +# Formal Review Steps -Create a report using the filename pattern `AGENT_REPORT_code_review_[review-set].md` -(e.g., `AGENT_REPORT_code_review_SpdxTool-Context.md`) to document review criteria, identified issues, and -recommendations for the specific review-set. - -## 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 make the report - -## Hand-off to Other Agents - -Only attempt to apply review fixes if requested. +4. Populate the checklist with the findings to `.agent-logs/reviews/review-report-[review-set].md` of the project. -- If code quality, logic, or structural issues need fixing, call the @software-developer agent -- If test coverage gaps or quality issues are identified, call the @test-developer agent -- If documentation accuracy or completeness issues are found, call the @technical-writer agent -- If quality gate verification is needed after fixes, call the @code-quality agent -- If requirements traceability issues are discovered, call the @requirements agent +# Don't Do These Things -## Don't Do These Things - -- **Never modify code during review** (document findings only, delegate fixes) +- **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 index c67ce98..829758e 100644 --- a/.github/agents/repo-consistency.agent.md +++ b/.github/agents/repo-consistency.agent.md @@ -1,7 +1,8 @@ --- name: repo-consistency -description: Ensures SpdxTool remains consistent with the TemplateDotNetTool template patterns and best practices. -tools: [read, search, edit, execute, github, agent] +description: > + Ensures SpdxTool remains consistent with the TemplateDotNetTool template + patterns and best practices. user-invocable: true --- @@ -10,19 +11,26 @@ user-invocable: true Maintain consistency between SpdxTool and the TemplateDotNetTool template, ensuring this repository benefits from template evolution while respecting project-specific customizations. -## Reporting +# Consistency Workflow (MANDATORY) -If detailed documentation of consistency analysis is needed, create a report using the filename pattern -`AGENT_REPORT_consistency_SpdxTool.md` to document consistency gaps, template evolution updates, and -recommended changes for this repository. +**CRITICAL**: This agent MUST follow these steps systematically to ensure proper template consistency analysis: -## Consistency Steps +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 -1. Fetch the 20 most recently merged PRs (`is:pr is:merged sort:updated-desc`) from -2. Determine the intent of the template pull requests (what changes were performed to which files) -3. Apply missing changes to this repository's files (if appropriate and with translation) +## Key Principles -## Don't Do These Things +- **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 @@ -32,8 +40,41 @@ recommended changes for this repository. - **Never skip validation** of preserved functionality after template alignment - **Never assume all template patterns apply universally** (assess project-specific needs) -## Key Principles +# Reporting -- **Evolutionary Consistency**: Template improvements should enhance downstream projects systematically -- **Intelligent Customization Respect**: Distinguished valid customizations from unintentional drift -- **Incremental Template Adoption**: Support phased adoption of template improvements based on project capacity +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 index 51c8067..3bbba73 100644 --- a/.github/agents/requirements.agent.md +++ b/.github/agents/requirements.agent.md @@ -12,8 +12,9 @@ Compliance methodology for automated evidence generation and audit compliance. ## Reporting -If detailed documentation of requirements analysis is needed, create a report using the filename pattern -`AGENT_REPORT_requirements.md` to document requirement mappings, gap analysis, and traceability results. +If detailed documentation of requirements analysis is needed, create a report in +`.agent-logs/[agent-name]-[subject]-[unique-id].md` to document requirement mappings, gap analysis, +and traceability results. ## When to Invoke This Agent @@ -87,7 +88,7 @@ Enforcement: `dotnet reqstream --requirements requirements.yaml --tests "test-re - If features need to be implemented to satisfy requirements, then call the @software-developer agent - If tests need to be created to validate requirements, then call the @test-developer agent -- If requirements traceability needs to be enforced in CI/CD, then call the @code-quality agent +- If requirements traceability needs to be enforced in CI/CD, then call the @quality agent - If requirements documentation needs generation or maintenance, then call the @technical-writer agent ## Don't Do These Things diff --git a/.github/agents/software-developer.agent.md b/.github/agents/software-developer.agent.md index a57ad33..76ee295 100644 --- a/.github/agents/software-developer.agent.md +++ b/.github/agents/software-developer.agent.md @@ -11,8 +11,9 @@ Develop production code and self-validation tests with emphasis on testability, ## Reporting -If detailed documentation of development work is needed, create a report using the filename pattern -`AGENT_REPORT_development.md` to document code changes, design decisions, and implementation details. +If detailed documentation of development work is needed, create a report in +`.agent-logs/[agent-name]-[subject]-[unique-id].md` to document code changes, design decisions, +and implementation details. ## When to Invoke This Agent @@ -103,7 +104,7 @@ Before completing any code changes, verify: ### Hand-off to Other Agents - If comprehensive tests need to be created for implemented functionality, then call the @test-developer agent -- If quality gates and linting requirements need verification, then call the @code-quality agent +- If quality gates and linting requirements need verification, then call the @quality agent - If documentation needs updating to reflect code changes, then call the @technical-writer agent - If implementation validation against requirements is needed, then call the @requirements agent diff --git a/.github/agents/technical-writer.agent.md b/.github/agents/technical-writer.agent.md index 16560f2..d2f3198 100644 --- a/.github/agents/technical-writer.agent.md +++ b/.github/agents/technical-writer.agent.md @@ -13,7 +13,7 @@ and Continuous Compliance standards. ## Reporting If detailed documentation of writing and editing activities is needed, -create a report using the filename pattern `AGENT_REPORT_documentation.md` to document content changes, +create a report in `.agent-logs/[agent-name]-[subject]-[unique-id].md` to document content changes, style decisions, and editorial processes. ## When to Invoke This Agent @@ -34,17 +34,18 @@ Use the Technical Writer Agent for: ```yaml docs/ + build_notes.md # Generated by BuildMark + build_notes/ + versions.md # Generated by VersionMark requirements/ - requirements.md # Generated by ReqStream + requirements.md # Generated by ReqStream justifications/ - justifications.md # Generated by ReqStream + justifications.md # Generated by ReqStream tracematrix/ - tracematrix.md # Generated by ReqStream - buildnotes/ - versions.md # Generated by VersionMark + tracematrix.md # Generated by ReqStream quality/ - sonar-quality.md # Generated by SonarMark - codeql-quality.md # Generated by SarifMark + sonar-quality.md # Generated by SonarMark + codeql-quality.md # Generated by SarifMark ``` **WARNING**: These files are regenerated on every CI/CD run. Manual edits will be lost. @@ -100,7 +101,7 @@ silence a spell-checking failure. Only add genuine technical terms after proposa ### Hand-off to Other Agents - If code examples or code comments need updating, then call the @software-developer agent -- If documentation linting and quality checks need to be run, then call the @code-quality agent +- If documentation linting and quality checks need to be run, then call the @quality agent - If test procedures and coverage need documentation, then call the @test-developer agent ## Don't Do These Things diff --git a/.github/agents/test-developer.agent.md b/.github/agents/test-developer.agent.md index 759edb3..8d3de5d 100644 --- a/.github/agents/test-developer.agent.md +++ b/.github/agents/test-developer.agent.md @@ -13,8 +13,8 @@ Continuous Compliance verification. ## Reporting If detailed documentation of testing activities is needed, -create a report using the filename pattern `AGENT_REPORT_testing.md` to document test strategies, coverage analysis, -and validation results. +create a report in `.agent-logs/[agent-name]-[subject]-[unique-id].md` to document test strategies, +coverage analysis, and validation results. ## When to Invoke This Agent @@ -118,7 +118,7 @@ tests: ### Hand-off to Other Agents -- If test quality gates and coverage metrics need verification, then call the @code-quality agent +- If test quality gates and coverage metrics need verification, then call the @quality agent - If test linkage needs to satisfy requirements traceability, then call the @requirements agent - If testable code structure improvements are needed, then call the @software-developer agent 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..b7420d2 --- /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**: `SpdxTool-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..eb09e39 --- /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**: `SpdxTool-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**: `SpdxTool-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**: `SpdxTool-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**: `SpdxTool-Context`, `SpdxTool-Program` + +## [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**: `SpdxTool-Commands` + +# 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..f09ee83 --- /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.yaml` (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/release.yaml b/.github/workflows/release.yaml index 15d1a03..86b41ec 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -68,17 +68,12 @@ jobs: name: documents path: artifacts - - name: Move buildnotes.md to root - run: | - set -e - mv artifacts/buildnotes.md buildnotes.md - - name: Create release if: ${{ inputs.publish == 'release' || inputs.publish == 'publish' }} uses: ncipollo/release-action@v1 with: artifacts: "artifacts/*" - bodyFile: buildnotes.md + bodyFile: artifacts/buildnotes.md generateReleaseNotes: false tag: ${{ inputs.version }} diff --git a/.gitignore b/.gitignore index d16957a..6507239 100644 --- a/.gitignore +++ b/.gitignore @@ -429,3 +429,6 @@ versionmark-*.json # Agent report files (temporary inter-agent communication) AGENT_REPORT_*.md + +# Agent log files (temporary agent work logs) +.agent-logs/ diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml index 04f1f80..4532ba3 100644 --- a/.markdownlint-cli2.yaml +++ b/.markdownlint-cli2.yaml @@ -11,6 +11,11 @@ # - Do not relax rules to accommodate existing non-compliant files # - Consistency across repositories is critical for documentation quality +noBanner: true + +# Disable the progress indicator on stdout +noProgress: true + config: # Enable all default rules default: true @@ -45,3 +50,4 @@ ignores: - "**/third-party/**" - "**/3rd-party/**" - "**/AGENT_REPORT_*.md" + - "**/.agent-logs/**" diff --git a/.yamllint.yaml b/.yamllint.yaml index 6c6c4fb..4fbc811 100644 --- a/.yamllint.yaml +++ b/.yamllint.yaml @@ -21,6 +21,7 @@ ignore: | thirdparty/ third-party/ 3rd-party/ + .agent-logs/ rules: # Allow 'on:' in GitHub Actions workflows (not a boolean value) diff --git a/AGENTS.md b/AGENTS.md index ee2847f..eb3501f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,28 +3,49 @@ Project-specific guidance for agents working on SpdxTool - a .NET CLI tool for manipulating SPDX SBOM files. +## 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 -- **Code Review Agent** - Assists in performing formal file reviews -- **Repo Consistency Agent** - Ensures SpdxTool remains consistent with TemplateDotNetTool 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** -- Perform formal file reviews → **Code Review 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 SpdxTool remains consistent with TemplateDotNetTool patterns + +### SpdxTool-Specific Agents + +- **requirements** - Develops requirements and ensures test coverage linkage +- **software-developer** - Writes production code and self-validation tests in literate style +- **technical-writer** - Creates accurate documentation following regulatory best practices +- **test-developer** - Creates unit and integration tests following AAA pattern ## Tech Stack @@ -100,6 +121,7 @@ dotnet run --project src/DemaConsulting.SpdxTool \ - **User Guide**: `docs/guide/` - **Command Reference**: `docs/spdx-tool-command-line.md` - **CHANGELOG.md**: Not present - changes are captured in the auto-generated build notes +- **Build Notes**: `docs/build_notes.md` - Generated by BuildMark (see docs/build_notes/ for details) ## Markdown Link Style @@ -127,6 +149,16 @@ dotnet tool restore dotnet test --collect:"XPlat Code Coverage" ``` +## Quality Gate Enforcement (ALL Agents Must Verify) + +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 + ## Boundaries and Guardrails - **NEVER** modify files within the `/obj/` or `/bin/` directories @@ -136,11 +168,10 @@ dotnet test --collect:"XPlat Code Coverage" ## 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/lint.bat b/lint.bat index f94b53d..c7440d4 100644 --- a/lint.bat +++ b/lint.bat @@ -12,17 +12,17 @@ REM - Agents execute this script to identify files needing fixes set "LINT_ERROR=0" REM Install npm dependencies -call npm install +call npm install --silent REM Create Python virtual environment (for yamllint) if missing if not exist ".venv\Scripts\activate.bat" ( python -m venv .venv ) call .venv\Scripts\activate.bat -pip install -r pip-requirements.txt +pip install -r pip-requirements.txt --quiet --disable-pip-version-check REM Run spell check -call npx cspell --no-progress --no-color "**/*.{md,yaml,yml,json,cs,cpp,hpp,h,txt}" +call npx cspell --no-progress --no-color --quiet "**/*.{md,yaml,yml,json,cs,cpp,hpp,h,txt}" if errorlevel 1 set "LINT_ERROR=1" REM Run markdownlint check diff --git a/lint.sh b/lint.sh index 374ab79..c567e09 100755 --- a/lint.sh +++ b/lint.sh @@ -8,28 +8,28 @@ # - NO command-line arguments, pretty printing, or colorization # - Agents execute this script to identify files needing fixes -LINT_ERROR=0 +lint_error=0 # Install npm dependencies -npm install +npm install --silent # Create Python virtual environment (for yamllint) if [ ! -d ".venv" ]; then python -m venv .venv fi source .venv/bin/activate -pip install -r pip-requirements.txt +pip install -r pip-requirements.txt --quiet --disable-pip-version-check # Run spell check -npx cspell --no-progress --no-color "**/*.{md,yaml,yml,json,cs,cpp,hpp,h,txt}" || LINT_ERROR=1 +npx cspell --no-progress --no-color --quiet "**/*.{md,yaml,yml,json,cs,cpp,hpp,h,txt}" || lint_error=1 # Run markdownlint check -npx markdownlint-cli2 "**/*.md" || LINT_ERROR=1 +npx markdownlint-cli2 "**/*.md" || lint_error=1 # Run yamllint check -yamllint . || LINT_ERROR=1 +yamllint . || lint_error=1 # Run .NET formatting check (verifies no changes are needed) -dotnet format --verify-no-changes || LINT_ERROR=1 +dotnet format --verify-no-changes || lint_error=1 -exit $LINT_ERROR +exit $lint_error From aabc3539114e8d3db21dabda5262d97ae2047096 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 30 Mar 2026 13:21:44 +0000 Subject: [PATCH 6/9] Sync quality-checks CI job with TemplateDotNetTool pattern Replace individual linting GitHub Actions (markdownlint-cli2-action, cspell-action, ibiqlik/action-yamllint) with Setup Node.js, Setup Python, and bash ./lint.sh steps to align CI with the local lint script and the TemplateDotNetTool template pattern. This ensures the linting run in CI exactly matches what developers can run locally, preventing drift between local and CI lint behavior. Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --- .github/agents/technical-writer.agent.md | 4 +-- .github/standards/technical-documentation.md | 4 +-- .github/workflows/build.yaml | 35 ++++++++------------ AGENTS.md | 2 +- lint.bat | 4 +++ lint.sh | 11 +++--- 6 files changed, 28 insertions(+), 32 deletions(-) diff --git a/.github/agents/technical-writer.agent.md b/.github/agents/technical-writer.agent.md index d2f3198..92163f7 100644 --- a/.github/agents/technical-writer.agent.md +++ b/.github/agents/technical-writer.agent.md @@ -34,8 +34,8 @@ Use the Technical Writer Agent for: ```yaml docs/ - build_notes.md # Generated by BuildMark - build_notes/ + buildnotes.md # Generated by BuildMark + buildnotes/ versions.md # Generated by VersionMark requirements/ requirements.md # Generated by ReqStream diff --git a/.github/standards/technical-documentation.md b/.github/standards/technical-documentation.md index f09ee83..2671e44 100644 --- a/.github/standards/technical-documentation.md +++ b/.github/standards/technical-documentation.md @@ -24,8 +24,8 @@ consistency and tool compatibility: ```text docs/ - build_notes.md # Generated by BuildMark - build_notes/ # Auto-generated build notes + buildnotes.md # Generated by BuildMark + buildnotes/ # Auto-generated build notes versions.md # Generated by VersionMark code_review_plan/ # Auto-generated review plans plan.md # Generated by ReviewMark diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index 75e1bf6..f9bd41d 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -11,7 +11,6 @@ on: SONAR_TOKEN: required: true - jobs: # Performs quick quality checks for project formatting consistency including # markdown linting, spell checking, and YAML validation. @@ -37,6 +36,16 @@ jobs: run: > dotnet tool restore + - name: Setup Node.js + uses: actions/setup-node@v6 + with: + node-version: 24.x + + - name: Setup Python + uses: actions/setup-python@v6 + with: + python-version: '3.14' + - name: Capture tool versions shell: bash run: | @@ -58,27 +67,9 @@ jobs: # This section runs all quality checks for the project. # Downstream projects: Add any additional quality checks here. - - name: Run markdown linter - uses: DavidAnson/markdownlint-cli2-action@v22 - with: - config: .markdownlint-cli2.yaml - globs: '**/*.md' - - - name: Run spell checker - uses: streetsidesoftware/cspell-action@v8 - with: - config: .cspell.yaml - incremental_files_only: false - files: | - **/*.md - **/*.cs - **/*.yaml - **/*.yml - - - name: Run YAML linter - uses: ibiqlik/action-yamllint@v3 - with: - config_file: .yamllint.yaml + - name: Run linters + shell: bash + run: bash ./lint.sh - name: Upload quality artifacts uses: actions/upload-artifact@v7 diff --git a/AGENTS.md b/AGENTS.md index eb3501f..9966769 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -121,7 +121,7 @@ dotnet run --project src/DemaConsulting.SpdxTool \ - **User Guide**: `docs/guide/` - **Command Reference**: `docs/spdx-tool-command-line.md` - **CHANGELOG.md**: Not present - changes are captured in the auto-generated build notes -- **Build Notes**: `docs/build_notes.md` - Generated by BuildMark (see docs/build_notes/ for details) +- **Build Notes**: `docs/buildnotes.md` - Generated by BuildMark (see docs/buildnotes/ for details) ## Markdown Link Style diff --git a/lint.bat b/lint.bat index c7440d4..aeb4b08 100644 --- a/lint.bat +++ b/lint.bat @@ -13,13 +13,17 @@ set "LINT_ERROR=0" REM Install npm dependencies call npm install --silent +if errorlevel 1 set "LINT_ERROR=1" REM Create Python virtual environment (for yamllint) if missing if not exist ".venv\Scripts\activate.bat" ( python -m venv .venv + if errorlevel 1 set "LINT_ERROR=1" ) call .venv\Scripts\activate.bat +if errorlevel 1 set "LINT_ERROR=1" pip install -r pip-requirements.txt --quiet --disable-pip-version-check +if errorlevel 1 set "LINT_ERROR=1" REM Run spell check call npx cspell --no-progress --no-color --quiet "**/*.{md,yaml,yml,json,cs,cpp,hpp,h,txt}" diff --git a/lint.sh b/lint.sh index c567e09..16c6f7f 100755 --- a/lint.sh +++ b/lint.sh @@ -1,4 +1,4 @@ -#!/bin/bash +#!/usr/bin/env bash # Comprehensive Linting Script # @@ -11,14 +11,15 @@ lint_error=0 # Install npm dependencies -npm install --silent +npm install --silent || lint_error=1 # Create Python virtual environment (for yamllint) if [ ! -d ".venv" ]; then - python -m venv .venv + python -m venv .venv || lint_error=1 fi -source .venv/bin/activate -pip install -r pip-requirements.txt --quiet --disable-pip-version-check +# shellcheck disable=SC1091 +source .venv/bin/activate || lint_error=1 +pip install -r pip-requirements.txt --quiet --disable-pip-version-check || lint_error=1 # Run spell check npx cspell --no-progress --no-color --quiet "**/*.{md,yaml,yml,json,cs,cpp,hpp,h,txt}" || lint_error=1 From 19fed673be1ee01154f055cbe826ce024ec69209 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 30 Mar 2026 15:01:49 +0000 Subject: [PATCH 7/9] Changes before error encountered Agent-Logs-Url: https://github.com/demaconsulting/SpdxTool/sessions/0750abd2-5d0e-44a2-9bde-eb84bf3f589b Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --- .github/workflows/build.yaml | 109 ++++++++++++------ .gitignore | 16 +-- docs/build_notes/definition.yaml | 12 ++ .../introduction.md | 0 docs/{buildnotes => build_notes}/title.txt | 0 docs/buildnotes/definition.yaml | 12 -- docs/code_quality/definition.yaml | 12 ++ .../{quality => code_quality}/introduction.md | 0 docs/{quality => code_quality}/title.txt | 0 docs/code_review_plan/definition.yaml | 11 ++ docs/code_review_plan/introduction.md | 33 ++++++ docs/code_review_plan/title.txt | 13 +++ docs/code_review_report/definition.yaml | 11 ++ docs/code_review_report/introduction.md | 32 +++++ docs/code_review_report/title.txt | 13 +++ docs/justifications/definition.yaml | 11 -- docs/justifications/introduction.md | 48 -------- docs/justifications/title.txt | 15 --- docs/quality/definition.yaml | 15 --- docs/requirements/definition.yaml | 11 -- docs/requirements_doc/definition.yaml | 12 ++ .../introduction.md | 0 .../title.txt | 0 docs/requirements_report/definition.yaml | 11 ++ .../introduction.md | 0 .../title.txt | 0 docs/tracematrix/definition.yaml | 11 -- lint.bat | 4 - lint.sh | 11 +- 29 files changed, 249 insertions(+), 174 deletions(-) create mode 100644 docs/build_notes/definition.yaml rename docs/{buildnotes => build_notes}/introduction.md (100%) rename docs/{buildnotes => build_notes}/title.txt (100%) delete mode 100644 docs/buildnotes/definition.yaml create mode 100644 docs/code_quality/definition.yaml rename docs/{quality => code_quality}/introduction.md (100%) rename docs/{quality => code_quality}/title.txt (100%) create mode 100644 docs/code_review_plan/definition.yaml create mode 100644 docs/code_review_plan/introduction.md create mode 100644 docs/code_review_plan/title.txt create mode 100644 docs/code_review_report/definition.yaml create mode 100644 docs/code_review_report/introduction.md create mode 100644 docs/code_review_report/title.txt delete mode 100644 docs/justifications/definition.yaml delete mode 100644 docs/justifications/introduction.md delete mode 100644 docs/justifications/title.txt delete mode 100644 docs/quality/definition.yaml delete mode 100644 docs/requirements/definition.yaml create mode 100644 docs/requirements_doc/definition.yaml rename docs/{requirements => requirements_doc}/introduction.md (100%) rename docs/{requirements => requirements_doc}/title.txt (100%) create mode 100644 docs/requirements_report/definition.yaml rename docs/{tracematrix => requirements_report}/introduction.md (100%) rename docs/{tracematrix => requirements_report}/title.txt (100%) delete mode 100644 docs/tracematrix/definition.yaml diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index f9bd41d..7af9960 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -559,16 +559,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 "SpdxTool CodeQL Analysis" --report-depth 1 @@ -576,7 +576,7 @@ jobs: shell: bash run: | echo "=== CodeQL Quality Report ===" - cat docs/quality/codeql-quality.md + cat docs/code_quality/codeql-quality.md - name: Generate Code Quality Report with SonarMark env: @@ -587,14 +587,37 @@ jobs: --project-key demaconsulting_SpdxTool --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 + --definition .reviewmark.yaml + --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 @@ -603,20 +626,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" @@ -624,7 +647,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. @@ -634,11 +657,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/buildnotes.html - name: Generate Guide HTML with Pandoc shell: bash @@ -654,38 +677,49 @@ jobs: shell: bash run: > dotnet pandoc - docs/quality/title.txt - --defaults docs/quality/definition.yaml + docs/code_quality/title.txt + --defaults docs/code_quality/definition.yaml --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 --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 --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. @@ -695,7 +729,7 @@ jobs: run: > dotnet weasyprint --pdf-variant pdf/a-3u - docs/buildnotes/buildnotes.html + docs/build_notes/buildnotes.html "docs/SpdxTool Build Notes.pdf" - name: Generate Guide PDF with Weasyprint @@ -709,29 +743,36 @@ jobs: run: > dotnet weasyprint --pdf-variant pdf/a-3u - docs/quality/quality.html + docs/code_quality/quality.html "docs/SpdxTool 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/SpdxTool 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/SpdxTool Trace Matrix.pdf" + + - name: Generate Review Plan PDF with Weasyprint run: > dotnet weasyprint --pdf-variant pdf/a-3u - docs/justifications/justifications.html - "docs/SpdxTool Requirements Justifications.pdf" + docs/code_review_plan/plan.html + "docs/SpdxTool 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/SpdxTool Trace Matrix.pdf" + docs/code_review_report/report.html + "docs/SpdxTool Review Report.pdf" # === UPLOAD ARTIFACTS === # This section uploads all generated documentation artifacts. @@ -743,4 +784,4 @@ jobs: name: documents path: | docs/*.pdf - docs/buildnotes.md + docs/build_notes.md diff --git a/.gitignore b/.gitignore index 6507239..2c6b8a8 100644 --- a/.gitignore +++ b/.gitignore @@ -406,13 +406,15 @@ FodyWeavers.xsd 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/code_review_plan/plan.md +docs/code_review_report/report.md +docs/build_notes.md +docs/build_notes/versions.md # Test results TestResults/ 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..50a73dc --- /dev/null +++ b/docs/code_review_plan/introduction.md @@ -0,0 +1,33 @@ +# Introduction + +This document contains the review plan for the SpdxTool project. + +## Purpose + +This review plan provides a comprehensive overview of all files requiring formal review +in the SpdxTool 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 SpdxTool +- 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..5d437eb --- /dev/null +++ b/docs/code_review_plan/title.txt @@ -0,0 +1,13 @@ +--- +title: SpdxTool Review Plan +subtitle: File Review Plan for the DemaConsulting SpdxTool +author: DEMA Consulting +description: File Review Plan for the DemaConsulting SpdxTool +lang: en-US +keywords: + - SpdxTool + - 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..4ecbb93 --- /dev/null +++ b/docs/code_review_report/introduction.md @@ -0,0 +1,32 @@ +# Introduction + +This document contains the review report for the SpdxTool 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 SpdxTool 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 SpdxTool +- 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..1a99a36 --- /dev/null +++ b/docs/code_review_report/title.txt @@ -0,0 +1,13 @@ +--- +title: SpdxTool Review Report +subtitle: File Review Report for the DemaConsulting SpdxTool +author: DEMA Consulting +description: File Review Report for the DemaConsulting SpdxTool +lang: en-US +keywords: + - SpdxTool + - 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 aa6975e..0000000 --- a/docs/justifications/introduction.md +++ /dev/null @@ -1,48 +0,0 @@ -# Introduction - -This document provides rationale and justifications for the requirements -specified in the SpdxTool Requirements Specification. Each justification -explains the reasoning behind a requirement, including business needs, -technical constraints, regulatory considerations, and user expectations. - -## Purpose - -The purpose of this document is to: - -- Provide transparent reasoning for each requirement -- Support requirement review and validation processes -- Facilitate informed decision-making during requirement changes -- Document assumptions and constraints that influenced requirement definition -- Ensure stakeholder alignment on requirement priorities and rationale - -By documenting justifications, this specification enables better understanding -of why each requirement exists and supports more effective requirement -management throughout the project lifecycle. - -## Scope - -This justifications document covers the same functional areas as the -requirements specification: - -- **CLI Commands**: Rationale for command-line interface design decisions -- **Validation**: Justification for validation rules and standards compliance -- **Package Management**: Reasoning behind package operation requirements -- **Relationships**: Rationale for relationship management capabilities -- **Workflow Support**: Justification for automation and integration features -- **Platform Support**: Reasoning for cross-platform compatibility choices -- **File Format Support**: Justification for supported SPDX format decisions -- **Error Handling**: Rationale for error handling and user feedback approaches - -Each justification is linked to its corresponding requirement identifier, -maintaining clear traceability between requirements and their rationale. - -## Audience - -This document is intended for: - -- **Requirements Engineers**: Understanding requirement origins and rationale -- **Software Architects**: Making design decisions aligned with requirement intent -- **Project Stakeholders**: Evaluating requirement priorities and trade-offs -- **Quality Assurance**: Validating that implementations satisfy intended purposes -- **Product Managers**: Making informed decisions about requirement changes -- **Auditors**: Verifying that requirements are properly justified and traceable diff --git a/docs/justifications/title.txt b/docs/justifications/title.txt deleted file mode 100644 index 51f3ec0..0000000 --- a/docs/justifications/title.txt +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: SpdxTool Requirements Justifications -subtitle: Requirements Justifications for the DemaConsulting SpdxTool -author: DEMA Consulting -description: Requirements Justifications for the DemaConsulting SpdxTool -lang: en-US -keywords: - - SpdxTool - - SPDX - - SBOM - - Requirements - - Justifications - - .NET - - Documentation ---- diff --git a/docs/quality/definition.yaml b/docs/quality/definition.yaml deleted file mode 100644 index f5e3f15..0000000 --- a/docs/quality/definition.yaml +++ /dev/null @@ -1,15 +0,0 @@ ---- -resource-path: - - docs/quality - - docs/template - -input-files: - - 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/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 aeb4b08..c7440d4 100644 --- a/lint.bat +++ b/lint.bat @@ -13,17 +13,13 @@ set "LINT_ERROR=0" REM Install npm dependencies call npm install --silent -if errorlevel 1 set "LINT_ERROR=1" REM Create Python virtual environment (for yamllint) if missing if not exist ".venv\Scripts\activate.bat" ( python -m venv .venv - if errorlevel 1 set "LINT_ERROR=1" ) call .venv\Scripts\activate.bat -if errorlevel 1 set "LINT_ERROR=1" pip install -r pip-requirements.txt --quiet --disable-pip-version-check -if errorlevel 1 set "LINT_ERROR=1" REM Run spell check call npx cspell --no-progress --no-color --quiet "**/*.{md,yaml,yml,json,cs,cpp,hpp,h,txt}" diff --git a/lint.sh b/lint.sh index 16c6f7f..c567e09 100755 --- a/lint.sh +++ b/lint.sh @@ -1,4 +1,4 @@ -#!/usr/bin/env bash +#!/bin/bash # Comprehensive Linting Script # @@ -11,15 +11,14 @@ lint_error=0 # Install npm dependencies -npm install --silent || lint_error=1 +npm install --silent # Create Python virtual environment (for yamllint) if [ ! -d ".venv" ]; then - python -m venv .venv || lint_error=1 + python -m venv .venv fi -# shellcheck disable=SC1091 -source .venv/bin/activate || lint_error=1 -pip install -r pip-requirements.txt --quiet --disable-pip-version-check || lint_error=1 +source .venv/bin/activate +pip install -r pip-requirements.txt --quiet --disable-pip-version-check # Run spell check npx cspell --no-progress --no-color --quiet "**/*.{md,yaml,yml,json,cs,cpp,hpp,h,txt}" || lint_error=1 From 01c2030ac03afe4eabb7fc6c1b981697ea8542e8 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 30 Mar 2026 15:38:15 +0000 Subject: [PATCH 8/9] Apply TemplateDotNetTool PR #65: remove legacy agents, fix paths, update docs structure Agent-Logs-Url: https://github.com/demaconsulting/SpdxTool/sessions/f9c074e6-a286-4d90-b44e-98b5b9bd78a8 Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --- .cspell.yaml | 9 +- .github/agents/requirements.agent.md | 101 -------------- .github/agents/software-developer.agent.md | 130 ------------------ .github/agents/technical-writer.agent.md | 115 ---------------- .github/agents/test-developer.agent.md | 135 ------------------- .github/pull_request_template.md | 4 +- .github/standards/technical-documentation.md | 4 +- .github/workflows/release.yaml | 2 +- AGENTS.md | 9 +- 9 files changed, 12 insertions(+), 497 deletions(-) delete mode 100644 .github/agents/requirements.agent.md delete mode 100644 .github/agents/software-developer.agent.md delete mode 100644 .github/agents/technical-writer.agent.md delete mode 100644 .github/agents/test-developer.agent.md diff --git a/.cspell.yaml b/.cspell.yaml index 0fadb5a..45bcf94 100644 --- a/.cspell.yaml +++ b/.cspell.yaml @@ -18,10 +18,13 @@ words: - Blockquotes - buildmark - BuildMark - - buildnotes + - build_notes - buildMultiTargeting - camelcase - Checkmarx + - code_quality + - code_review_plan + - code_review_report - CodeQL - copilot - cspell @@ -69,6 +72,8 @@ words: - Qube - reqstream - ReqStream + - requirements_doc + - requirements_report - reviewmark - ReviewMark - rezip @@ -97,7 +102,7 @@ words: - TemplateDotNetTool - testname - TMPL - - tracematrix + - trace_matrix - triaging - Trivy - trx diff --git a/.github/agents/requirements.agent.md b/.github/agents/requirements.agent.md deleted file mode 100644 index 3bbba73..0000000 --- a/.github/agents/requirements.agent.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -name: requirements -description: Develops requirements and ensures appropriate test coverage. -tools: [read, search, edit, execute, github, web, agent] -user-invocable: true ---- - -# Requirements Agent - SpdxTool - -Develop and maintain high-quality requirements with comprehensive test coverage linkage following Continuous -Compliance methodology for automated evidence generation and audit compliance. - -## Reporting - -If detailed documentation of requirements analysis is needed, create a report in -`.agent-logs/[agent-name]-[subject]-[unique-id].md` to document requirement mappings, gap analysis, -and traceability results. - -## When to Invoke This Agent - -Use the Requirements Agent for: - -- Creating new requirements in organized `docs/reqstream/` structure -- Establishing subsystem and software unit requirement files for independent review -- Reviewing and improving existing requirements quality and organization -- Ensuring proper requirements-to-test traceability -- Validating requirements enforcement in CI/CD pipelines -- Differentiating requirements from design/implementation details - -## Continuous Compliance Methodology - -### Core Principles - -The @requirements agent implements the Continuous Compliance methodology -, which provides automated compliance evidence -generation through structured requirements management. - -### Test Coverage Strategy & Linking - -#### Coverage Rules - -- **Requirements coverage**: Mandatory for all stated requirements -- **Test flexibility**: Not all tests need requirement links (corner cases, design validation, failure scenarios allowed) -- **Platform evidence**: Use source filters for platform/framework-specific requirements - -#### Source Filter Patterns (CRITICAL - DO NOT REMOVE) - -```yaml -tests: - - "windows@TestMethodName" # Windows platform evidence only - - "ubuntu@TestMethodName" # Linux (Ubuntu) platform evidence only - - "net8.0@TestMethodName" # .NET 8 runtime evidence only - - "net9.0@TestMethodName" # .NET 9 runtime evidence only - - "net10.0@TestMethodName" # .NET 10 runtime evidence only - - "TestMethodName" # Any platform evidence acceptable -``` - -**WARNING**: Removing source filters invalidates platform-specific compliance evidence and may cause audit failures. - -### SpdxTool Test Types - -- **Self-validation tests** (`SpdxTool_*`): Preferred for command-line behavior and features that ship with the - product. Located in `src/DemaConsulting.SpdxTool/SelfValidation/`. Implemented by @software-developer agent. -- **Unit tests**: For internal component behavior and isolated logic. Located in - `test/DemaConsulting.SpdxTool.Tests/`. Implemented by @test-developer agent. -- **Integration tests**: For cross-component interactions. Implemented by @test-developer agent. - -### Requirements Format - -Follow the `requirements.yaml` structure: - -```yaml -# requirements.yaml - Root configuration with includes only -includes: - - docs/reqstream/unit-context.yaml - - docs/reqstream/unit-program.yaml - - docs/reqstream/unit-commands.yaml - - docs/reqstream/unit-utility.yaml - - docs/reqstream/platform-requirements.yaml - - docs/reqstream/ots-mstest.yaml -``` - -Enforcement: `dotnet reqstream --requirements requirements.yaml --tests "test-results/**/*.trx" --enforce` - -## Cross-Agent Coordination - -### Hand-off to Other Agents - -- If features need to be implemented to satisfy requirements, then call the @software-developer agent -- If tests need to be created to validate requirements, then call the @test-developer agent -- If requirements traceability needs to be enforced in CI/CD, then call the @quality agent -- If requirements documentation needs generation or maintenance, then call the @technical-writer agent - -## Don't Do These Things - -- Create requirements without test linkage (CI will fail) -- Remove source filters from platform-specific requirements (breaks compliance) -- Mix implementation details with requirements (separate concerns) -- Skip justification text (required for compliance audits) -- Change test code directly (delegate to @test-developer agent) -- Modify CI/CD enforcement thresholds without compliance review diff --git a/.github/agents/software-developer.agent.md b/.github/agents/software-developer.agent.md deleted file mode 100644 index 76ee295..0000000 --- a/.github/agents/software-developer.agent.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -name: software-developer -description: Writes production code and self-validation tests. -tools: [read, search, edit, execute, github, agent] -user-invocable: true ---- - -# Software Developer Agent - SpdxTool - -Develop production code and self-validation tests with emphasis on testability, clarity, and compliance integration. - -## Reporting - -If detailed documentation of development work is needed, create a report in -`.agent-logs/[agent-name]-[subject]-[unique-id].md` to document code changes, design decisions, -and implementation details. - -## When to Invoke This Agent - -Use the Software Developer Agent for: - -- Implementing production code features and APIs -- Refactoring existing code for testability and maintainability -- Creating and maintaining self-validation tests (`SpdxTool_*`) -- Implementing requirement-driven functionality -- Code architecture and design decisions -- Integration with Continuous Compliance tooling - -## Primary Responsibilities - -### Literate Programming Style (MANDATORY) - -Write all code in **literate style** for maximum clarity and maintainability. - -#### Literate Style Rules - -- **Intent Comments:** Every paragraph starts with a comment explaining intent (not mechanics) -- **Logical Separation:** Blank lines separate logical code paragraphs -- **Purpose Over Process:** Comments describe why, code shows how -- **Standalone Clarity:** Reading comments alone should explain the algorithm/approach -- **Verification Support:** Code can be verified against the literate comments for correctness - -#### Example - -```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 & Compliance - -#### Code Architecture Principles - -- **Single Responsibility**: Functions with focused, testable purposes -- **Dependency Injection**: External dependencies injected for testing -- **Pure Functions**: Minimize side effects and hidden state -- **Clear Interfaces**: Well-defined API contracts -- **Separation of Concerns**: Business logic separate from infrastructure - -#### Compliance-Ready Code Structure - -- **Documentation Standards**: XML documentation required on ALL members (public/internal/private) with spaces - after `///` -- **Error Handling**: `ArgumentException` for parsing, `InvalidOperationException` for runtime issues -- **Namespaces**: File-scoped namespaces only -- **Using Statements**: Top of file only - -### Quality Gate Verification - -Before completing any code changes, verify: - -#### 1. Code Quality Standards - -- [ ] Zero compiler warnings (`TreatWarningsAsErrors=true`) -- [ ] Follows `.editorconfig` formatting rules (file-scoped namespaces, 4-space indent, UTF-8+BOM, LF) -- [ ] All code follows literate programming style -- [ ] XML documentation complete on all members (public/internal/private) -- [ ] Passes static analysis (SonarQube, CodeQL, language analyzers) - -#### 2. Testability & Design - -- [ ] Functions have single, clear responsibilities -- [ ] External dependencies are injectable/mockable -- [ ] Code is structured for unit testing -- [ ] Error handling covers expected failure scenarios - -#### 3. Self-Validation Tests (SpdxTool-Specific) - -- **Naming**: `SpdxTool_FeatureBeingValidated` -- **Location**: `src/DemaConsulting.SpdxTool/SelfValidation/` -- **Run via**: `--validate` flag -- **Format**: TRX/JUnit output supported via DemaConsulting.TestResults -- **Link**: Requirements in `requirements.yaml` - -## Cross-Agent Coordination - -### Hand-off to Other Agents - -- If comprehensive tests need to be created for implemented functionality, then call the @test-developer agent -- If quality gates and linting requirements need verification, then call the @quality agent -- If documentation needs updating to reflect code changes, then call the @technical-writer agent -- If implementation validation against requirements is needed, then call the @requirements agent - -## Compliance Verification Checklist - -### Before Completing Implementation - -1. **Code Quality**: Zero warnings, passes all static analysis -2. **Documentation**: XML documentation on ALL members -3. **Testability**: Code structured for comprehensive testing -4. **Security**: Input validation, error handling, authorization checks -5. **Traceability**: Implementation traceable to requirements -6. **Standards**: Follows all coding standards and formatting rules - -## Don't Do These Things - -- Skip literate programming comments (mandatory for all code) -- Disable compiler warnings to make builds pass -- Create untestable code with hidden dependencies -- Skip XML documentation on any members -- Implement functionality without requirement traceability -- Ignore static analysis or security scanning results -- Write monolithic functions with multiple responsibilities diff --git a/.github/agents/technical-writer.agent.md b/.github/agents/technical-writer.agent.md deleted file mode 100644 index 92163f7..0000000 --- a/.github/agents/technical-writer.agent.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -name: technical-writer -description: Ensures documentation is accurate and complete. -tools: [read, search, edit, execute, github, agent] -user-invocable: true ---- - -# Technical Writer Agent - SpdxTool - -Create and maintain clear, accurate, and compliance-ready documentation following regulatory best practices -and Continuous Compliance standards. - -## Reporting - -If detailed documentation of writing and editing activities is needed, -create a report in `.agent-logs/[agent-name]-[subject]-[unique-id].md` to document content changes, -style decisions, and editorial processes. - -## When to Invoke This Agent - -Use the Technical Writer Agent for: - -- Creating and updating project documentation (README, guides, CONTRIBUTING, specifications) -- Ensuring documentation accuracy, completeness, and compliance -- Implementing regulatory documentation best practices -- Managing auto-generated compliance documentation -- Applying markdown linting and style standards - -## Primary Responsibilities - -### Continuous Compliance Documentation Standards - -#### Auto-Generated Documentation (CRITICAL - Do Not Edit Manually) - -```yaml -docs/ - buildnotes.md # Generated by BuildMark - buildnotes/ - versions.md # Generated by VersionMark - requirements/ - requirements.md # Generated by ReqStream - justifications/ - justifications.md # Generated by ReqStream - tracematrix/ - tracematrix.md # Generated by ReqStream - quality/ - sonar-quality.md # Generated by SonarMark - codeql-quality.md # Generated by SarifMark -``` - -**WARNING**: These files are regenerated on every CI/CD run. Manual edits will be lost. - -### Documentation Quality Standards - -#### Content Longevity Principles - -**Avoid Transitory Information**: Long-term documentation should not include information that becomes stale quickly: - -- **❌ Avoid**: Tool version numbers, specific counts, current dates, "latest" references -- **✅ Instead**: Reference auto-generated reports, use relative descriptions, focus on stable concepts - -### Link Style Rules by File Type - -#### Published Documents (README.md) - -Use absolute URLs for external links - these documents are published/distributed (shipped in NuGet package). - -#### AI Agent Files (`.github/agents/*.agent.md`) - -Use inline links `[text](url)` so URLs are visible in agent context. - -#### All Other Markdown Files - -Use reference-style links `[text][ref]` with `[ref]: url` at document end. - -## SpdxTool-Specific Documentation - -- **User Guide**: `docs/guide/` -- **Command Reference**: `docs/spdx-tool-command-line.md` -- **ARCHITECTURE.md**: System structure, component relationships, key design decisions -- **CONTRIBUTING.md**: Contribution workflow and standards -- **README.md**: Project overview with badges, features, installation, usage - -### Spell Checking - -All files are spell-checked using cspell. **Never** add a word to the `.cspell.yaml` word list in order to -silence a spell-checking failure. Only add genuine technical terms after proposal and review. - -## Quality Gate Verification - -### Documentation Linting Checklist - -- [ ] markdownlint-cli2 passes with zero errors -- [ ] cspell passes with zero spelling errors -- [ ] yamllint passes for any YAML content -- [ ] Links are functional and use correct style (per file type) -- [ ] Generated documents compile without errors - -## Cross-Agent Coordination - -### Hand-off to Other Agents - -- If code examples or code comments need updating, then call the @software-developer agent -- If documentation linting and quality checks need to be run, then call the @quality agent -- If test procedures and coverage need documentation, then call the @test-developer agent - -## Don't Do These Things - -- **Never edit auto-generated documentation** manually (will be overwritten) -- **Never edit code comments directly** (delegate to @software-developer agent) -- **Never skip purpose and scope sections** in regulatory documents -- **Never ignore spelling errors** (add terms to `.cspell.yaml` only after proper proposal/review) -- **Never use incorrect link styles** for file types (breaks tooling) -- **Never commit documentation** without linting verification -- **Never document non-existent features** (code is source of truth) diff --git a/.github/agents/test-developer.agent.md b/.github/agents/test-developer.agent.md deleted file mode 100644 index 8d3de5d..0000000 --- a/.github/agents/test-developer.agent.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -name: test-developer -description: Writes unit and integration tests. -tools: [read, search, edit, execute, github, agent] -user-invocable: true ---- - -# Test Developer Agent - SpdxTool - -Develop comprehensive unit and integration tests with emphasis on requirements coverage and -Continuous Compliance verification. - -## Reporting - -If detailed documentation of testing activities is needed, -create a report in `.agent-logs/[agent-name]-[subject]-[unique-id].md` to document test strategies, -coverage analysis, and validation results. - -## When to Invoke This Agent - -Use the Test Developer Agent for: - -- Creating unit tests for new functionality -- Writing integration tests for component interactions -- Improving test coverage for compliance requirements -- Implementing AAA (Arrange-Act-Assert) pattern tests -- Generating platform-specific test evidence -- Upgrading legacy test suites to modern standards - -## Primary Responsibilities - -### Comprehensive Test Coverage Strategy - -#### Requirements Coverage (MANDATORY) - -- **All requirements MUST have linked tests** - Enforced by ReqStream -- **Platform-specific tests** must generate evidence with source filters -- **Test result formats** must be compatible (TRX, JUnit XML) - -#### Test Type Strategy (SpdxTool-Specific) - -- **NOT self-validation tests** - those are handled by @software-developer agent -- Unit tests live in `test/DemaConsulting.SpdxTool.Tests/` directory -- Targets tests live in `test/DemaConsulting.SpdxTool.Targets.Tests/` directory -- Use MSTest V4 testing framework -- Follow existing naming conventions in the test suite - -### AAA Pattern Implementation (MANDATORY) - -All tests MUST follow Arrange-Act-Assert pattern: - -```csharp -[TestMethod] -public void ClassName_MethodUnderTest_Scenario_ExpectedBehavior() -{ - // Arrange - Set up test data and dependencies - var input = "test data"; - var expected = "expected result"; - var component = new Component(); - - // Act - Execute the system under test - var actual = component.Method(input); - - // Assert - Verify expected outcomes - Assert.AreEqual(expected, actual); -} -``` - -### Test Naming Standards - -```csharp -// Pattern: ClassName_MethodUnderTest_Scenario_ExpectedBehavior -AddPackage_Execute_ValidInput_ReturnsSuccess() -FindPackage_Execute_NotFound_ReturnsNull() -Context_Create_WithInvalidFlag_ThrowsArgumentException() -``` - -### MSTest V4 Best Practices - -1. **Use `Assert.ThrowsExactly()`** for exception testing (avoid assertions in catch blocks - MSTEST0058) -2. **Use `Assert.AreEqual`** instead of `Assert.IsTrue(a == b)` for better failure messages -3. **Use `Assert.HasCount`** instead of `Assert.IsTrue(collection.Count == N)` -4. **Use `Assert.StartsWith`** instead of `Assert.IsTrue(value.StartsWith("prefix"))` -5. **Always make test classes and methods `public`** (internal classes are silently ignored) - -### Test Source Filters - -```yaml -tests: - - "windows@TestName" # Windows platform evidence only - - "ubuntu@TestName" # Linux (Ubuntu) platform evidence only - - "net8.0@TestName" # .NET 8 runtime evidence only - - "net9.0@TestName" # .NET 9 runtime evidence only - - "net10.0@TestName" # .NET 10 runtime evidence only -``` - -**WARNING**: Removing source filters invalidates platform-specific compliance evidence. - -## Quality Gate Verification - -### Test Quality Standards - -- [ ] All tests follow AAA pattern consistently -- [ ] Test names clearly describe scenario and expected outcome -- [ ] Each test validates single, specific behavior -- [ ] Both happy path and edge cases covered -- [ ] Platform-specific tests generate appropriate evidence -- [ ] Test results in standard formats (TRX) - -### Requirements Traceability - -- [ ] Tests linked to specific requirements in requirements.yaml -- [ ] Source filters applied for platform-specific requirements -- [ ] Test coverage adequate for all stated requirements -- [ ] ReqStream validation passes with linked tests - -## Cross-Agent Coordination - -### Hand-off to Other Agents - -- If test quality gates and coverage metrics need verification, then call the @quality agent -- If test linkage needs to satisfy requirements traceability, then call the @requirements agent -- If testable code structure improvements are needed, then call the @software-developer agent - -## Don't Do These Things - -- **Never skip AAA pattern** in test structure (mandatory for consistency) -- **Never create tests without clear names** (must describe scenario/expectation) -- **Never write flaky tests** that pass/fail inconsistently -- **Never test implementation details** (test behavior, not internal mechanics) -- **Never skip edge cases** and error conditions -- **Never create tests without requirements linkage** (for compliance requirements) -- **Never ignore platform-specific test evidence** requirements -- **Never commit failing tests** (all tests must pass before merge) -- **Never write self-validation tests** (delegate to @software-developer agent) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 561250d..57100fa 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/technical-documentation.md b/.github/standards/technical-documentation.md index 2671e44..f09ee83 100644 --- a/.github/standards/technical-documentation.md +++ b/.github/standards/technical-documentation.md @@ -24,8 +24,8 @@ consistency and tool compatibility: ```text docs/ - buildnotes.md # Generated by BuildMark - buildnotes/ # Auto-generated build notes + 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 diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index 86b41ec..afe0edc 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -73,7 +73,7 @@ jobs: uses: ncipollo/release-action@v1 with: artifacts: "artifacts/*" - bodyFile: artifacts/buildnotes.md + bodyFile: artifacts/build_notes.md generateReleaseNotes: false tag: ${{ inputs.version }} diff --git a/AGENTS.md b/AGENTS.md index 9966769..41fbc56 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -40,13 +40,6 @@ Delegate to specialized agents only for specific scenarios: standards and Continuous Compliance practices - **repo-consistency** - Ensures SpdxTool remains consistent with TemplateDotNetTool patterns -### SpdxTool-Specific Agents - -- **requirements** - Develops requirements and ensures test coverage linkage -- **software-developer** - Writes production code and self-validation tests in literate style -- **technical-writer** - Creates accurate documentation following regulatory best practices -- **test-developer** - Creates unit and integration tests following AAA pattern - ## Tech Stack - C# (latest), .NET 8.0/9.0/10.0, dotnet CLI, NuGet @@ -121,7 +114,7 @@ dotnet run --project src/DemaConsulting.SpdxTool \ - **User Guide**: `docs/guide/` - **Command Reference**: `docs/spdx-tool-command-line.md` - **CHANGELOG.md**: Not present - changes are captured in the auto-generated build notes -- **Build Notes**: `docs/buildnotes.md` - Generated by BuildMark (see docs/buildnotes/ for details) +- **Build Notes**: `docs/build_notes.md` - Generated by BuildMark (see docs/build_notes/ for details) ## Markdown Link Style From 4c2d26e6379a722a05476ab69ff326fe217fcf32 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 30 Mar 2026 17:30:14 +0000 Subject: [PATCH 9/9] Fix Windows test failure: normalize TRX file line endings before Assert.Contains The .gitattributes change (eol=lf) causes .cs files to be checked out with LF on Windows. The raw string literal in the test then has LF, but the TRX file generated at runtime on Windows has CRLF. This caused Assert.Contains to fail when searching for the LF substring in the CRLF content. Fix by normalizing line endings in the read results string. Agent-Logs-Url: https://github.com/demaconsulting/SpdxTool/sessions/8ee39b14-6a76-47ac-971b-9783e04e67e1 Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --- test/DemaConsulting.SpdxTool.Tests/SelfValidationTests.cs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/test/DemaConsulting.SpdxTool.Tests/SelfValidationTests.cs b/test/DemaConsulting.SpdxTool.Tests/SelfValidationTests.cs index 7627ff6..78e0352 100644 --- a/test/DemaConsulting.SpdxTool.Tests/SelfValidationTests.cs +++ b/test/DemaConsulting.SpdxTool.Tests/SelfValidationTests.cs @@ -87,8 +87,8 @@ public void SelfValidation_ValidateFlagWithResults_GeneratesTrxFile() // Assert: Verify success Assert.AreEqual(0, exitCode); - // Read results file - var results = File.ReadAllText(resultFile); + // Read results file (normalize line endings for cross-platform compatibility) + var results = File.ReadAllText(resultFile).Replace("\r\n", "\n"); Assert.IsNotNull(results); // Assert: Verify the results contain expected content