diff --git a/.cspell.yaml b/.cspell.yaml index d1ff363..107de45 100644 --- a/.cspell.yaml +++ b/.cspell.yaml @@ -14,81 +14,19 @@ language: en # Project-specific technical terms and tool names words: - - Anson - - Blockquotes - buildmark - - BuildMark - - buildnotes - - build_notes - - camelcase - - Checkmarx - - CodeQL - - copilot - - cspell - - csproj - - dbproj - - dcterms + - DEMA - Dema - - demaconsulting - - DEMACONSULTINGNUGETKEY - - Dependabot - - dependabot - - doctitle - - dotnet - - editorconfig - - filepart - - fsproj - - Gidget - - gitattributes - - ibiqlik - - LINQ - - maintainer - - markdownlint - - mermaid - mstest - - myterm - - ncipollo - - nuget - - nupkg - - opencover - - pagetitle - - pandoc - - Pylint + - Pandoc - Qube - reqstream - - ReqStream - reviewmark - - ReviewMark - - code_quality - - code_review_plan - - code_review_report - - requirements_doc - - requirements_report - - trace_matrix - Sarif - - SarifMark - - SBOM - - Semgrep - - semver - - slnx - - snupkg + - SARIF + - sarifmark - sonarmark - - SonarMark - - SonarQube - - spdx - - streetsidesoftware - - templatetool - - testname - - TMPL - - tracematrix - - triaging - - Trivy - - trx - - vbproj - - vcxproj - versionmark - - Weasyprint - - yamllint # Exclude common build artifacts, dependencies, and vendored third-party code ignorePaths: diff --git a/.github/agents/code-review.agent.md b/.github/agents/code-review.agent.md index f28a9b7..cee797f 100644 --- a/.github/agents/code-review.agent.md +++ b/.github/agents/code-review.agent.md @@ -17,7 +17,7 @@ Formal reviews are a quality enforcement mechanism, and as such MUST be performe to get the checklist to fill in 2. Use `dotnet reviewmark --elaborate [review-set]` to get the files to review 3. Review the files all together -4. Populate the checklist with the findings to `.agent-logs/reviews/review-report-[review-set].md` of the project. +4. Populate the checklist with the findings to `.agent-logs/reviews/review-report-{review-set}.md` of the project. # Don't Do These Things @@ -31,13 +31,13 @@ Formal reviews are a quality enforcement mechanism, and as such MUST be performe # Reporting -Upon completion create a summary in `.agent-logs/[agent-name]-[subject]-[unique-id].md` +Upon completion create a summary in `.agent-logs/{agent-name}-{subject}-{unique-id}.md` of the project consisting of: ```markdown # Code Review Report -**Result**: +**Result**: (SUCCEEDED|FAILED) ## Review Summary diff --git a/.github/agents/developer.agent.md b/.github/agents/developer.agent.md index 955f9e9..2028f79 100644 --- a/.github/agents/developer.agent.md +++ b/.github/agents/developer.agent.md @@ -20,13 +20,13 @@ Perform software development tasks by determining and applying appropriate DEMA # Reporting -Upon completion create a summary in `.agent-logs/[agent-name]-[subject]-[unique-id].md` +Upon completion create a summary in `.agent-logs/{agent-name}-{subject}-{unique-id}.md` of the project consisting of: ```markdown # Developer Agent Report -**Result**: +**Result**: (SUCCEEDED|FAILED) ## Work Summary diff --git a/.github/agents/implementation.agent.md b/.github/agents/implementation.agent.md index dd203ef..91b44d7 100644 --- a/.github/agents/implementation.agent.md +++ b/.github/agents/implementation.agent.md @@ -60,14 +60,14 @@ Once the quality sub-agent finishes: ### REPORT State (end) -Upon completion create a summary in `.agent-logs/[agent-name]-[subject]-[unique-id].md` +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**: +**Result**: (SUCCEEDED|FAILED) +**Final State**: (RESEARCH|DEVELOPMENT|QUALITY|REPORT) **Retry Count**: ## State Machine Execution diff --git a/.github/agents/quality.agent.md b/.github/agents/quality.agent.md index 48e7a37..a7b57d4 100644 --- a/.github/agents/quality.agent.md +++ b/.github/agents/quality.agent.md @@ -23,14 +23,14 @@ This assessment is a quality control system of the project and MUST be performed # Reporting -Upon completion create a summary in `.agent-logs/[agent-name]-[subject]-[unique-id].md` +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**: +**Result**: (SUCCEEDED|FAILED) +**Overall Grade**: (PASS|FAIL|NEEDS_WORK) ## Assessment Summary @@ -40,71 +40,71 @@ of the project consisting of: ## Requirements Compliance: (PASS|FAIL|N/A) -- Were requirements updated to reflect functional changes? (PASS|FAIL|N/A) - [Evidence/Details] -- Were new requirements created for new features? (PASS|FAIL|N/A) - [Evidence/Details] -- Do requirement IDs follow semantic naming standards? (PASS|FAIL|N/A) - [Evidence/Details] -- Do requirement files follow kebab-case naming convention? (PASS|FAIL|N/A) - [Evidence/Details] -- Are requirement files organized under `docs/reqstream/` with proper folder structure? (PASS|FAIL|N/A) - [Evidence/Details] -- Are OTS requirements properly placed in `docs/reqstream/ots/` subfolder? (PASS|FAIL|N/A) - [Evidence/Details] -- Were source filters applied appropriately for platform-specific requirements? (PASS|FAIL|N/A) - [Evidence/Details] -- Does ReqStream enforcement pass without errors? (PASS|FAIL|N/A) - [Evidence/Details] -- Is requirements traceability maintained to tests? (PASS|FAIL|N/A) - [Evidence/Details] +- Were requirements updated to reflect functional changes? (PASS|FAIL|N/A) - [Evidence] +- Were new requirements created for new features? (PASS|FAIL|N/A) - [Evidence] +- Do requirement IDs follow semantic naming standards? (PASS|FAIL|N/A) - [Evidence] +- Do requirement files follow kebab-case naming convention? (PASS|FAIL|N/A) - [Evidence] +- Are requirement files organized under `docs/reqstream/` with proper folder structure? (PASS|FAIL|N/A) - [Evidence] +- Are OTS requirements properly placed in `docs/reqstream/ots/` subfolder? (PASS|FAIL|N/A) - [Evidence] +- Were source filters applied appropriately for platform-specific requirements? (PASS|FAIL|N/A) - [Evidence] +- Does ReqStream enforcement pass without errors? (PASS|FAIL|N/A) - [Evidence] +- Is requirements traceability maintained to tests? (PASS|FAIL|N/A) - [Evidence] ## Design Documentation Compliance: (PASS|FAIL|N/A) -- Were design documents updated for architectural changes? (PASS|FAIL|N/A) - [Evidence/Details] -- Were new design artifacts created for new components? (PASS|FAIL|N/A) - [Evidence/Details] -- Do design folder names use kebab-case convention matching source structure? (PASS|FAIL|N/A) - [Evidence/Details] -- Are design files properly named ({subsystem-name}.md, {unit-name}.md patterns)? (PASS|FAIL|N/A) - [Evidence/Details] -- Is `docs/design/introduction.md` present with required Software Structure section? (PASS|FAIL|N/A) - [Evidence/Details] -- Are design decisions documented with rationale? (PASS|FAIL|N/A) - [Evidence/Details] -- Is system/subsystem/unit categorization maintained? (PASS|FAIL|N/A) - [Evidence/Details] -- Is design-to-implementation traceability preserved? (PASS|FAIL|N/A) - [Evidence/Details] +- Were design documents updated for architectural changes? (PASS|FAIL|N/A) - [Evidence] +- Were new design artifacts created for new components? (PASS|FAIL|N/A) - [Evidence] +- Do design folder names use kebab-case convention matching source structure? (PASS|FAIL|N/A) - [Evidence] +- Are design files properly named ({subsystem-name}.md, {unit-name}.md patterns)? (PASS|FAIL|N/A) - [Evidence] +- Is `docs/design/introduction.md` present with required Software Structure section? (PASS|FAIL|N/A) - [Evidence] +- Are design decisions documented with rationale? (PASS|FAIL|N/A) - [Evidence] +- Is system/subsystem/unit categorization maintained? (PASS|FAIL|N/A) - [Evidence] +- Is design-to-implementation traceability preserved? (PASS|FAIL|N/A) - [Evidence] ## Code Quality Compliance: (PASS|FAIL|N/A) -- Are language-specific standards followed (from applicable standards files)? (PASS|FAIL|N/A) - [Evidence/Details] -- Are quality checks from standards files satisfied? (PASS|FAIL|N/A) - [Evidence/Details] -- Is code properly categorized (system/subsystem/unit/OTS)? (PASS|FAIL|N/A) - [Evidence/Details] -- Is appropriate separation of concerns maintained? (PASS|FAIL|N/A) - [Evidence/Details] -- Was language-specific tooling executed and passing? (PASS|FAIL|N/A) - [Evidence/Details] +- Are language-specific standards followed (from applicable standards files)? (PASS|FAIL|N/A) - [Evidence] +- Are quality checks from standards files satisfied? (PASS|FAIL|N/A) - [Evidence] +- Is code properly categorized (system/subsystem/unit/OTS)? (PASS|FAIL|N/A) - [Evidence] +- Is appropriate separation of concerns maintained? (PASS|FAIL|N/A) - [Evidence] +- Was language-specific tooling executed and passing? (PASS|FAIL|N/A) - [Evidence] ## Testing Compliance: (PASS|FAIL|N/A) -- Were tests created/updated for all functional changes? (PASS|FAIL|N/A) - [Evidence/Details] -- Is test coverage maintained for all requirements? (PASS|FAIL|N/A) - [Evidence/Details] -- Are testing standards followed (AAA pattern, etc.)? (PASS|FAIL|N/A) - [Evidence/Details] -- Does test categorization align with code structure? (PASS|FAIL|N/A) - [Evidence/Details] -- Do all tests pass without failures? (PASS|FAIL|N/A) - [Evidence/Details] +- Were tests created/updated for all functional changes? (PASS|FAIL|N/A) - [Evidence] +- Is test coverage maintained for all requirements? (PASS|FAIL|N/A) - [Evidence] +- Are testing standards followed (AAA pattern, etc.)? (PASS|FAIL|N/A) - [Evidence] +- Does test categorization align with code structure? (PASS|FAIL|N/A) - [Evidence] +- Do all tests pass without failures? (PASS|FAIL|N/A) - [Evidence] ## Review Management Compliance: (PASS|FAIL|N/A) -- Were review-sets updated to include new/modified files? (PASS|FAIL|N/A) - [Evidence/Details] -- Do file patterns follow include-then-exclude approach? (PASS|FAIL|N/A) - [Evidence/Details] -- Is review scope appropriate for change magnitude? (PASS|FAIL|N/A) - [Evidence/Details] -- Was ReviewMark tooling executed and passing? (PASS|FAIL|N/A) - [Evidence/Details] -- Were review artifacts generated correctly? (PASS|FAIL|N/A) - [Evidence/Details] +- Were review-sets updated to include new/modified files? (PASS|FAIL|N/A) - [Evidence] +- Do file patterns follow include-then-exclude approach? (PASS|FAIL|N/A) - [Evidence] +- Is review scope appropriate for change magnitude? (PASS|FAIL|N/A) - [Evidence] +- Was ReviewMark tooling executed and passing? (PASS|FAIL|N/A) - [Evidence] +- Were review artifacts generated correctly? (PASS|FAIL|N/A) - [Evidence] ## Documentation Compliance: (PASS|FAIL|N/A) -- Was README.md updated for user-facing changes? (PASS|FAIL|N/A) - [Evidence/Details] -- Were user guides updated for feature changes? (PASS|FAIL|N/A) - [Evidence/Details] -- Does API documentation reflect code changes? (PASS|FAIL|N/A) - [Evidence/Details] -- Was compliance documentation generated? (PASS|FAIL|N/A) - [Evidence/Details] -- Does documentation follow standards formatting? (PASS|FAIL|N/A) - [Evidence/Details] -- Is documentation organized under `docs/` following standard folder structure? (PASS|FAIL|N/A) - [Evidence/Details] -- Do Pandoc collections include proper `introduction.md` files with Purpose and Scope sections? (PASS|FAIL|N/A) - [Evidence/Details] -- Are auto-generated markdown files left unmodified? (PASS|FAIL|N/A) - [Evidence/Details] -- Do README.md files use absolute URLs and include concrete examples? (PASS|FAIL|N/A) - [Evidence/Details] -- Is documentation integrated into ReviewMark review-sets for formal review? (PASS|FAIL|N/A) - [Evidence/Details] +- Was README.md updated for user-facing changes? (PASS|FAIL|N/A) - [Evidence] +- Were user guides updated for feature changes? (PASS|FAIL|N/A) - [Evidence] +- Does API documentation reflect code changes? (PASS|FAIL|N/A) - [Evidence] +- Was compliance documentation generated? (PASS|FAIL|N/A) - [Evidence] +- Does documentation follow standards formatting? (PASS|FAIL|N/A) - [Evidence] +- Is documentation organized under `docs/` following standard folder structure? (PASS|FAIL|N/A) - [Evidence] +- Do Pandoc collections include proper `introduction.md` with Purpose and Scope sections? (PASS|FAIL|N/A) - [Evidence] +- Are auto-generated markdown files left unmodified? (PASS|FAIL|N/A) - [Evidence] +- Do README.md files use absolute URLs and include concrete examples? (PASS|FAIL|N/A) - [Evidence] +- Is documentation integrated into ReviewMark review-sets for formal review? (PASS|FAIL|N/A) - [Evidence] ## Process Compliance: (PASS|FAIL|N/A) -- Was Continuous Compliance workflow followed? (PASS|FAIL|N/A) - [Evidence/Details] -- Did all quality gates execute successfully? (PASS|FAIL|N/A) - [Evidence/Details] -- Were appropriate tools used for validation? (PASS|FAIL|N/A) - [Evidence/Details] -- Were standards consistently applied across work? (PASS|FAIL|N/A) - [Evidence/Details] -- Was compliance evidence generated and preserved? (PASS|FAIL|N/A) - [Evidence/Details] +- Was Continuous Compliance workflow followed? (PASS|FAIL|N/A) - [Evidence] +- Did all quality gates execute successfully? (PASS|FAIL|N/A) - [Evidence] +- Were appropriate tools used for validation? (PASS|FAIL|N/A) - [Evidence] +- Were standards consistently applied across work? (PASS|FAIL|N/A) - [Evidence] +- Was compliance evidence generated and preserved? (PASS|FAIL|N/A) - [Evidence] ## Overall Findings diff --git a/.github/agents/repo-consistency.agent.md b/.github/agents/repo-consistency.agent.md index 9889965..baf982c 100644 --- a/.github/agents/repo-consistency.agent.md +++ b/.github/agents/repo-consistency.agent.md @@ -42,13 +42,13 @@ benefit from template evolution while respecting project-specific customizations # Reporting -Upon completion create a summary in `.agent-logs/[agent-name]-[subject]-[unique-id].md` +Upon completion create a summary in `.agent-logs/{agent-name}-{subject}-{unique-id}.md` of the project consisting of: ```markdown # Repo Consistency Report -**Result**: +**Result**: (SUCCEEDED|FAILED) ## Consistency Analysis diff --git a/.github/standards/csharp-testing.md b/.github/standards/csharp-testing.md index 6cee284..2f26520 100644 --- a/.github/standards/csharp-testing.md +++ b/.github/standards/csharp-testing.md @@ -56,7 +56,7 @@ reliable evidence. - **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 +# MSTest V4 Anti-patterns Avoid these common MSTest V4 patterns because they produce poor error messages or cause tests to be silently ignored. @@ -116,4 +116,4 @@ Before submitting C# tests, verify: - [ ] 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.) +- [ ] MSTest V4 anti-patterns avoided (proper assertions, public visibility, etc.) diff --git a/.github/standards/design-documentation.md b/.github/standards/design-documentation.md index fac8901..6312275 100644 --- a/.github/standards/design-documentation.md +++ b/.github/standards/design-documentation.md @@ -135,7 +135,7 @@ Before submitting design documentation, verify: - [ ] Software structure correctly categorizes items as System/Subsystem/Unit per `software-items.md` - [ ] Folder layout matches actual source code organization - [ ] `system.md` provides comprehensive system-level design -- [ ] Subsystem folders use kebab-case naming matching source code +- [ ] Subsystem documentation folders use kebab-case names while mirroring source subsystem names and structure - [ ] Design documents contain sufficient implementation detail - [ ] All documents follow technical documentation formatting standards - [ ] Content is current with implementation and requirements diff --git a/.github/standards/reviewmark-usage.md b/.github/standards/reviewmark-usage.md index c914634..a40179f 100644 --- a/.github/standards/reviewmark-usage.md +++ b/.github/standards/reviewmark-usage.md @@ -20,8 +20,9 @@ Configure reviews in `.reviewmark.yaml` at repository root: # Patterns identifying all files that require review needs-review: # Include core development artifacts - - "docs/reqstream/**/*.yaml" # Requirements files only - - "**/*.md" # Requirements and design documentation + - "requirements.yaml" # Root requirements file + - "docs/reqstream/**/*.yaml" # Requirements files + - "docs/design/**/*.md" # Design documentation - "**/*.cs" # All C# source and test files # Exclude build output and generated content @@ -40,8 +41,8 @@ reviews: paths: - "docs/reqstream/authentication/password-validator.yaml" - "docs/design/authentication/password-validator.md" - - "src/Authentication/PasswordValidator.cs" - - "test/Authentication/PasswordValidatorTests.cs" + - "src/{ProjectName}/Authentication/PasswordValidator.cs" + - "test/{ProjectName}.Tests/Authentication/PasswordValidatorTests.cs" - id: MyProduct-AllRequirements title: All Requirements Review @@ -90,8 +91,8 @@ Reviews individual software unit implementation: - **File Path Pattern**: - Requirements: `docs/reqstream/{subsystem-name}/{unit-name}.yaml` or `docs/reqstream/{unit-name}.yaml` - Design: `docs/design/{subsystem-name}/{unit-name}.md` or `docs/design/{unit-name}.md` - - Source: `src/{SubsystemName}/{UnitName}.cs` - - Tests: `test/{SubsystemName}/{UnitName}Tests.cs` + - Source: `src/{ProjectName}/{SubsystemName}/{UnitName}.cs` + - Tests: `test/{ProjectName}.Tests/{SubsystemName}/{UnitName}Tests.cs` - **Example**: `MyProduct-PasswordValidator`, `MyProduct-ConfigParser` ## [Product]-[Subsystem] Review @@ -103,7 +104,7 @@ Reviews subsystem architecture and interfaces: - **File Path Pattern**: - Requirements: `docs/reqstream/{subsystem-name}/{subsystem-name}.yaml` - Design: `docs/design/{subsystem-name}/{subsystem-name}.md` - - Tests: `test/{SubsystemName}Integration/` or similar + - Tests: `test/{ProjectName}.Tests/{SubsystemName}Integration/` or similar - **Example**: `MyProduct-Authentication`, `MyProduct-DataLayer` ## [Product]-OTS Review diff --git a/.github/standards/technical-documentation.md b/.github/standards/technical-documentation.md index ca64eac..c117aa2 100644 --- a/.github/standards/technical-documentation.md +++ b/.github/standards/technical-documentation.md @@ -34,16 +34,18 @@ docs/ design/ # Design documentation introduction.md # Design overview system.md # System architecture - {subsystem-name}.md # Subsystem-specific designs - {unit-name}.md # Unit-specific designs + {subsystem-name}/ # Subsystem design folder + {subsystem-name}.md # Subsystem-specific designs + {unit-name}.md # Unit-specific designs + {unit-name}.md # Top-level unit design reqstream/ # Requirements source files system.yaml # System requirements platform-requirements.yaml # Platform requirements {subsystem-name}/ # Subsystem requirements folder {subsystem-name}.yaml # Subsystem requirements {unit-name}.yaml # Unit requirements - ots/ # OTS requirement files - {ots-name}.yaml # OTS requirements + ots/ # OTS requirement files + {ots-name}.yaml # OTS requirements requirements_doc/ # Auto-generated requirements reports requirements.md # Generated by ReqStream justifications.md # Generated by ReqStream diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index b8f39a4..4127858 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -508,7 +508,7 @@ jobs: --filter node_modules/.bin/mermaid-filter.cmd --metadata version="${{ inputs.version }}" --metadata date="$(date +'%Y-%m-%d')" - --output docs/build_notes/buildnotes.html + --output docs/build_notes/build_notes.html - name: Generate User Guide HTML with Pandoc shell: bash @@ -588,7 +588,7 @@ jobs: run: > dotnet weasyprint --pdf-variant pdf/a-3u - docs/build_notes/buildnotes.html + docs/build_notes/build_notes.html "docs/TemplateDotNetLibrary Build Notes.pdf" - name: Generate User Guide PDF with Weasyprint diff --git a/.reviewmark.yaml b/.reviewmark.yaml index 04ff172..1bb6ae2 100644 --- a/.reviewmark.yaml +++ b/.reviewmark.yaml @@ -6,6 +6,7 @@ # Patterns identifying all files that require review. # Processed in order; prefix a pattern with '!' to exclude. needs-review: + - "requirements.yaml" # Root requirements file - "**/*.cs" # All C# source and test files - "docs/reqstream/**/*.yaml" # Requirements files - "docs/design/**/*.md" # Design documentation files diff --git a/AGENTS.md b/AGENTS.md index e0349d2..8c6640d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -97,8 +97,8 @@ compliance gates on every CI/CD run instead of as a last-mile activity. - `introduction.md` - System/Subsystem/Unit breakdown for this repository - `reqstream/` - Subsystem requirements YAML files (included by root requirements.yaml) - Auto-generated reports (requirements, justifications, trace matrix) -- `src/` - Source code files -- `test/` - Test files +- `src/{ProjectName}/` - Source code projects +- `test/{ProjectName}.Tests/` - Test projects - `.github/workflows/` - CI/CD pipeline definitions (build.yaml, build_on_push.yaml, release.yaml) - Configuration files: `.editorconfig`, `.clang-format`, `nuget.config`, `.reviewmark.yaml`, etc. @@ -161,7 +161,7 @@ integration, call the developer agent with requirements management context. ## Agent Report Files -Upon completion, create a report file at `.agent-logs/[agent-name]-[subject]-[unique-id].md` that includes: +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 diff --git a/lint.bat b/lint.bat index 7806c82..c7440d4 100644 --- a/lint.bat +++ b/lint.bat @@ -33,4 +33,8 @@ REM Run yamllint check yamllint . if errorlevel 1 set "LINT_ERROR=1" +REM Run .NET formatting check (verifies no changes are needed) +dotnet format --verify-no-changes +if errorlevel 1 set "LINT_ERROR=1" + exit /b %LINT_ERROR% diff --git a/lint.sh b/lint.sh index 3365efe..c567e09 100755 --- a/lint.sh +++ b/lint.sh @@ -29,4 +29,7 @@ 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