From 9e4af3364c8f814c4704e4d0d433654f568c7758 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 31 Mar 2026 00:13:22 +0000 Subject: [PATCH 01/15] Initial plan From d00342d153cbf798e078968f17f40add5333bd4d Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 31 Mar 2026 00:25:41 +0000 Subject: [PATCH 02/15] Bring in template changes from TemplateDotNetLibrary Agent-Logs-Url: https://github.com/demaconsulting/SpdxModel/sessions/26211952-bc68-4474-9026-8b4fb4187e2f Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --- .cspell.json | 10 ++ .gitattributes | 7 + .github/pull_request_template.md | 5 +- .github/standards/csharp-language.md | 86 ++++++++++ .github/standards/csharp-testing.md | 119 +++++++++++++ .github/standards/reqstream-usage.md | 145 ++++++++++++++++ .github/standards/reviewmark-usage.md | 143 ++++++++++++++++ .github/standards/software-items.md | 45 +++++ .github/standards/technical-documentation.md | 159 ++++++++++++++++++ .gitignore | 3 + .markdownlint-cli2.jsonc | 3 + .yamllint.yaml | 21 ++- AGENTS.md | 24 +++ .../DemaConsulting.SpdxModel.csproj | 4 +- .../DemaConsulting.SpdxModel.Tests.csproj | 2 +- 15 files changed, 767 insertions(+), 9 deletions(-) create mode 100644 .gitattributes 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.json b/.cspell.json index c03be6c..d94f91f 100644 --- a/.cspell.json +++ b/.cspell.json @@ -28,6 +28,14 @@ "Pylint", "Qube", "ReqStream", + "reviewmark", + "ReviewMark", + "code_quality", + "code_review_plan", + "code_review_report", + "requirements_doc", + "requirements_report", + "trace_matrix", "Sarif", "SarifMark", "SBOM", @@ -91,6 +99,7 @@ "trx", "vbproj", "vcxproj", + "versionmark", "weasyprint", "workflow", "workflows", @@ -99,6 +108,7 @@ "ignorePaths": [ "node_modules", ".git", + ".agent-logs", "bin", "obj", "*.nupkg", 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/pull_request_template.md b/.github/pull_request_template.md index 51a73fb..4f38c3a 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -40,9 +40,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 @@ -57,6 +55,7 @@ Please run the following checks before submitting: - [ ] Added code examples for new features (if applicable) - [ ] Updated requirements.yaml (if applicable) - [ ] Updated XML documentation comments for changed APIs +- [ ] Updated ARCHITECTURE.md (if applicable) ## Additional Notes 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..b1b47e8 --- /dev/null +++ b/.github/standards/reqstream-usage.md @@ -0,0 +1,145 @@ +# 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**: `SpdxModel-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/requirements.md + +# Generate justifications report +dotnet reqstream \ + --requirements requirements.yaml \ + --justifications docs/justifications/justifications.md + +# Generate trace matrix +dotnet reqstream \ + --requirements requirements.yaml \ + --tests "artifacts/**/*.trx" \ + --matrix docs/tracematrix/tracematrix.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 +- [ ] 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..aa715f7 --- /dev/null +++ b/.github/standards/reviewmark-usage.md @@ -0,0 +1,143 @@ +# 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: SpdxModel-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**: `SpdxModel-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**: `SpdxModel-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**: `SpdxModel-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**: `SpdxModel-SpdxDocument`, `SpdxModel-SpdxPackage` + +## [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**: `SpdxModel-IO`, `SpdxModel-Validation` + +# 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..0b50665 --- /dev/null +++ b/.github/standards/technical-documentation.md @@ -0,0 +1,159 @@ +# 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 + buildnotes/ # Auto-generated build notes + versions.md # Generated by VersionMark + guide/ # User-facing documentation + introduction.md # User guide overview + {section}.md # User guide sections + requirements/ # Auto-generated requirements reports + requirements.md # Generated by ReqStream + justifications/ # Auto-generated justifications reports + justifications.md # Generated by ReqStream + tracematrix/ # Auto-generated trace matrices + tracematrix.md # Generated by ReqStream + quality/ # Auto-generated quality reports +``` + +# Pandoc Document Structure (MANDATORY) + +All document collections processed by Pandoc MUST include: + +- `definition.yaml` - specifying the files to include +- `title.txt` - document metadata +- `introduction.md` - document introduction +- `{sections}.md` - additional document sections + +## Introduction File Format + +```markdown +# Introduction + +Brief overview of the document collection purpose and audience. + +## Purpose + +Clear statement of why this documentation exists and what problem it solves. +Include regulatory or business drivers where applicable. + +## Scope + +Define what is covered and what is explicitly excluded from this documentation. +Specify version, system boundaries, and applicability constraints. +``` + +## Document Ordering + +List documents in logical reading order in Pandoc configuration because +readers need coherent information flow from general to specific topics. + +# Writing Guidelines + +Write technical documentation for clarity and compliance verification: + +- **Clear and Concise**: Use direct language and avoid unnecessary complexity. + Regulatory reviewers must understand content quickly. +- **Structured Sections**: Use consistent heading hierarchy and section + organization. Enables automated processing and review. +- **Specific Examples**: Include concrete examples with actual values rather + than placeholders. Supports implementation verification. +- **Current Information**: Keep documentation synchronized with code changes. + Outdated documentation invalidates compliance evidence. +- **Traceable Content**: Link documentation to requirements and implementation + where applicable for audit trails. + +# Markdown Format Requirements + +Markdown documentation in this repository must follow the formatting standards +defined in `.markdownlint-cli2.jsonc` (subject to any exclusions configured there) +for consistency and professional presentation: + +- **120 Character Line Limit**: Keep lines 120 characters or fewer for readability. + Break long lines naturally at punctuation or logical breaks. +- **No Trailing Whitespace**: Remove all trailing spaces and tabs from line + endings to prevent formatting inconsistencies. +- **Blank Lines Around Headings**: Include a blank line both before and after + each heading to improve document structure and readability. +- **Blank Lines Around Lists**: Include a blank line both before and after + numbered and bullet lists to ensure proper rendering and visual separation. +- **ATX-Style Headers**: Use `#` syntax for headers instead of underline style + for consistency across all documentation. +- **Consistent List Indentation**: Use 2-space indentation for nested list + items to maintain uniform formatting. + +# Auto-Generated Content (CRITICAL) + +**NEVER modify auto-generated markdown files** because changes will be +overwritten and break compliance automation: + +- **Read-Only Files**: Generated reports under `docs/requirements/`, + `docs/justifications/`, `docs/tracematrix/`, and `docs/quality/` 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 +- [ ] Links validated and external references accessible +- [ ] Content synchronized with current code implementation and requirements diff --git a/.gitignore b/.gitignore index 467dfd7..6509060 100644 --- a/.gitignore +++ b/.gitignore @@ -114,3 +114,6 @@ versionmark-*.json # Agent report files AGENT_REPORT_*.md + +# Agent log files +.agent-logs/ diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc index a46ee1a..6fbe8ba 100644 --- a/.markdownlint-cli2.jsonc +++ b/.markdownlint-cli2.jsonc @@ -1,4 +1,6 @@ { + "noBanner": true, + "noProgress": true, "config": { "default": true, "MD003": { "style": "atx" }, @@ -10,6 +12,7 @@ }, "ignores": [ "node_modules", + ".agent-logs", "**/AGENT_REPORT_*.md" ] } diff --git a/.yamllint.yaml b/.yamllint.yaml index c11c667..c5fb81a 100644 --- a/.yamllint.yaml +++ b/.yamllint.yaml @@ -1,12 +1,27 @@ --- -# yamllint configuration for SpdxModel -# 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: | - node_modules/ .git/ + node_modules/ + .venv/ + 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 dfb78ec..e165c7f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,6 +3,20 @@ Project-specific guidance for agents working on SpdxModel - a C# library for serializing and deserializing SPDX SBOMs into an in-memory representation. +## 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. + ## Available Specialized Agents - **Requirements Agent** - Develops requirements and ensures test coverage linkage @@ -120,6 +134,16 @@ npx markdownlint-cli2 "**/*.md" yamllint . ``` +## Agent Log Files + +Upon completion, agents should create a log 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 + +Agent logs are stored in `.agent-logs/` which is excluded from git (via `.gitignore`) and excluded from linting. + ## Agent Report Files When agents need to write report files to communicate with each other or the user, follow these guidelines: diff --git a/src/DemaConsulting.SpdxModel/DemaConsulting.SpdxModel.csproj b/src/DemaConsulting.SpdxModel/DemaConsulting.SpdxModel.csproj index c17714d..94335df 100644 --- a/src/DemaConsulting.SpdxModel/DemaConsulting.SpdxModel.csproj +++ b/src/DemaConsulting.SpdxModel/DemaConsulting.SpdxModel.csproj @@ -49,7 +49,7 @@ - + @@ -64,7 +64,7 @@ all runtime; build; native; contentfiles; analyzers; buildtransitive - + all runtime; build; native; contentfiles; analyzers; buildtransitive diff --git a/test/DemaConsulting.SpdxModel.Tests/DemaConsulting.SpdxModel.Tests.csproj b/test/DemaConsulting.SpdxModel.Tests/DemaConsulting.SpdxModel.Tests.csproj index 2f8dac7..3591984 100644 --- a/test/DemaConsulting.SpdxModel.Tests/DemaConsulting.SpdxModel.Tests.csproj +++ b/test/DemaConsulting.SpdxModel.Tests/DemaConsulting.SpdxModel.Tests.csproj @@ -45,7 +45,7 @@ all runtime; build; native; contentfiles; analyzers; buildtransitive - + all runtime; build; native; contentfiles; analyzers; buildtransitive From 4cee650676efed160861c56a550a8201add10a99 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 31 Mar 2026 00:38:03 +0000 Subject: [PATCH 03/15] Switch to new agent naming convention and update lint scripts Agent-Logs-Url: https://github.com/demaconsulting/SpdxModel/sessions/c7f83615-a494-4d14-ae25-bf5d25356f28 Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --- .github/agents/code-quality-agent.md | 84 ------------- .github/agents/code-review.agent.md | 73 +++++++++++ .github/agents/developer.agent.md | 70 +++++++++++ .github/agents/implementation.agent.md | 93 ++++++++++++++ .github/agents/quality.agent.md | 119 ++++++++++++++++++ .github/agents/repo-consistency-agent.md | 118 ----------------- .github/agents/repo-consistency.agent.md | 88 +++++++++++++ ...rements-agent.md => requirements.agent.md} | 7 +- .github/agents/software-developer.md | 72 ----------- ...al-writer.md => technical-writer.agent.md} | 7 +- ...t-developer.md => test-developer.agent.md} | 7 +- .gitignore | 1 + AGENTS.md | 43 ++++--- lint.bat | 46 +++++-- lint.sh | 41 ++++-- pip-requirements.txt | 1 + 16 files changed, 547 insertions(+), 323 deletions(-) delete mode 100644 .github/agents/code-quality-agent.md create mode 100644 .github/agents/code-review.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 delete mode 100644 .github/agents/repo-consistency-agent.md create mode 100644 .github/agents/repo-consistency.agent.md rename .github/agents/{requirements-agent.md => requirements.agent.md} (93%) delete mode 100644 .github/agents/software-developer.md rename .github/agents/{technical-writer.md => technical-writer.agent.md} (92%) rename .github/agents/{test-developer.md => test-developer.agent.md} (96%) create mode 100644 pip-requirements.txt diff --git a/.github/agents/code-quality-agent.md b/.github/agents/code-quality-agent.md deleted file mode 100644 index a5259d5..0000000 --- a/.github/agents/code-quality-agent.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -name: Code Quality Agent -description: Ensures code quality through linting and static analysis - responsible for security, maintainability, and correctness ---- - -# Code Quality Agent - SpdxModel - -Enforce quality standards through linting, static analysis, and security scanning. - -## When to Invoke This Agent - -Invoke the code-quality-agent for: - -- Running and fixing linting issues (markdown, YAML, spell check, code formatting) -- Ensuring static analysis passes with zero warnings -- Verifying code security -- Enforcing quality gates before merging -- Validating the project does what it claims to do - -## Responsibilities - -### Primary Responsibility - -Ensure the project is: - -- **Secure**: No security vulnerabilities -- **Maintainable**: Clean, well-formatted, documented code -- **Correct**: Does what it claims to do (requirements met) - -### Quality Gates (ALL Must Pass) - -1. **Build**: Zero warnings (TreatWarningsAsErrors=true) -2. **Linting**: - - markdownlint (`.markdownlint-cli2.jsonc`) - - cspell (`.cspell.json`) - - yamllint (`.yamllint.yaml`) - - dotnet format (`.editorconfig`) -3. **Static Analysis**: - - Microsoft.CodeAnalysis.NetAnalyzers - - SonarAnalyzer.CSharp -4. **Requirements Traceability**: - - `dotnet reqstream --requirements requirements.yaml --tests "test-results/**/*.trx" --enforce` -5. **Tests**: All validation tests passing - -### SpdxModel-Specific - -- **XML Docs**: Enforce on ALL members (public/internal/private) -- **Code Style**: Verify `.editorconfig` compliance -- **Test Quality**: Ensure test coverage and quality - -### Commands to Run - -```bash -# Code formatting -dotnet format --verify-no-changes - -# Build with zero warnings -dotnet build --configuration Release - -# Run unit tests -dotnet test --configuration Release - -# Requirements enforcement -dotnet reqstream --requirements requirements.yaml \ - --tests "test-results/**/*.trx" --enforce - -# Run all linters -./lint.sh # Linux/macOS -lint.bat # Windows -``` - -## Defer To - -- **Requirements Agent**: For requirements quality and test linkage strategy -- **Technical Writer Agent**: For fixing documentation content -- **Software Developer Agent**: For fixing production code issues -- **Test Developer Agent**: For fixing test code issues - -## Don't - -- Disable quality checks to make builds pass -- Ignore security warnings -- Skip enforcement of requirements traceability -- Change functional code without consulting appropriate developer agent diff --git a/.github/agents/code-review.agent.md b/.github/agents/code-review.agent.md new file mode 100644 index 0000000..f28a9b7 --- /dev/null +++ b/.github/agents/code-review.agent.md @@ -0,0 +1,73 @@ +--- +name: code-review +description: Agent for performing formal reviews +user-invocable: true +--- + +# Code Review Agent + +This agent runs the formal review based on the review-set it's told to perform. + +# Formal Review Steps + +Formal reviews are a quality enforcement mechanism, and as such MUST be performed using the following four steps: + +1. Download the + + to get the checklist to fill in +2. Use `dotnet reviewmark --elaborate [review-set]` to get the files to review +3. Review the files all together +4. Populate the checklist with the findings to `.agent-logs/reviews/review-report-[review-set].md` of the project. + +# Don't Do These Things + +- **Never modify code during review** (document findings only) +- **Never skip applicable checklist items** (comprehensive review required) +- **Never approve reviews with unresolved critical findings** +- **Never bypass review status requirements** for compliance +- **Never conduct reviews without proper documentation** +- **Never ignore security or compliance findings** +- **Never approve without verifying all quality gates** + +# Reporting + +Upon completion create a summary in `.agent-logs/[agent-name]-[subject]-[unique-id].md` +of the project consisting of: + +```markdown +# Code Review Report + +**Result**: + +## Review Summary + +- **Review Set**: [Review set name/identifier] +- **Review Report File**: [Name of detailed review report generated] +- **Files Reviewed**: [Count and list of files reviewed] +- **Review Template Used**: [Template source and version] + +## Review Results + +- **Overall Conclusion**: [Summary of review results] +- **Critical Issues**: [Count of critical findings] +- **High Issues**: [Count of high severity findings] +- **Medium Issues**: [Count of medium severity findings] +- **Low Issues**: [Count of low severity findings] + +## Issue Details + +[For each issue found, include:] +- **File**: [File name and line number where applicable] +- **Issue Type**: [Security, logic error, compliance violation, etc.] +- **Severity**: [Critical/High/Medium/Low] +- **Description**: [Issue description] +- **Recommendation**: [Specific remediation recommendation] + +## Compliance Status + +- **Review Status**: [Complete/Incomplete with reasoning] +- **Quality Gates**: [Status of review checklist items] +- **Approval Status**: [Approved/Rejected with justification] +``` + +Return summary to caller. diff --git a/.github/agents/developer.agent.md b/.github/agents/developer.agent.md new file mode 100644 index 0000000..d383fa8 --- /dev/null +++ b/.github/agents/developer.agent.md @@ -0,0 +1,70 @@ +--- +name: developer +description: > + General-purpose software development agent that applies appropriate standards + based on the work being performed. +user-invocable: true +--- + +# Developer Agent - SpdxModel + +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 + +## SpdxModel-Specific Rules + +- **XML Docs**: On ALL members (public/internal/private) with spaces after `///` +- **Namespace**: File-scoped namespaces only +- **Using Statements**: Top of file only +- **String Formatting**: Use interpolated strings ($"") for clarity + +## Defer To + +- **Requirements Agent**: For new requirement creation and test strategy +- **Test Developer Agent**: For unit and integration tests +- **Technical Writer Agent**: For documentation updates +- **Code Quality Agent**: For linting, formatting, and static analysis + +## Don't + +- Write code without explanatory comments +- Create large monolithic functions +- Skip XML documentation +- Ignore the literate programming style + +## 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..6bb2c31 --- /dev/null +++ b/.github/agents/quality.agent.md @@ -0,0 +1,119 @@ +--- +name: quality +description: > + Quality assurance agent that grades developer work against DEMA Consulting + standards and Continuous Compliance practices. +user-invocable: true +--- + +# Quality Agent - SpdxModel + +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 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? + +### 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? + +### 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? + +## SpdxModel-Specific Quality Gates (ALL Must Pass) + +1. **Build**: Zero warnings (`TreatWarningsAsErrors=true`) +2. **Linting**: `./lint.sh` (Linux/macOS) or `lint.bat` (Windows) +3. **Static Analysis**: Microsoft.CodeAnalysis.NetAnalyzers, SonarAnalyzer.CSharp +4. **Requirements Traceability**: `dotnet reqstream --requirements requirements.yaml --tests "artifacts/**/*.trx" --enforce` +5. **Tests**: All unit tests passing + +## 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] +- **Documentation**: - [Summary] +- **Process Compliance**: - [Summary] + +## Findings + +- **Issues Found**: [List of compliance issues] +- **Recommendations**: [Suggested improvements] +- **Tools Executed**: [Quality tools used for validation] + +## Compliance Status + +- **Standards Adherence**: [Overall compliance rating] +- **Quality Gates**: [Status of automated quality checks] +``` + +Return this summary to the caller. diff --git a/.github/agents/repo-consistency-agent.md b/.github/agents/repo-consistency-agent.md deleted file mode 100644 index 68f7129..0000000 --- a/.github/agents/repo-consistency-agent.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -name: Repo Consistency Agent -description: Ensures SpdxModel remains consistent with the TemplateDotNetLibrary template patterns and best practices ---- - -# Repo Consistency Agent - SpdxModel - -Maintain consistency between SpdxModel and the TemplateDotNetLibrary template at -. - -## When to Invoke This Agent - -Invoke the repo-consistency-agent for: - -- Periodic reviews of SpdxModel based on the TemplateDotNetLibrary template -- Checking if SpdxModel follows the latest template patterns -- Identifying drift from template standards -- Recommending updates to bring SpdxModel back in sync with template - -## Responsibilities - -### Consistency Checks - -The agent reviews the following areas for consistency with the template: - -#### GitHub Configuration - -- **Issue Templates**: `.github/ISSUE_TEMPLATE/` files (bug_report.yml, feature_request.yml, config.yml) -- **Pull Request Template**: `.github/pull_request_template.md` -- **Workflow Patterns**: General structure of `.github/workflows/` (build.yaml, build_on_push.yaml, release.yaml) - - Note: Some projects may need workflow deviations for specific requirements - -#### Agent Configuration - -- **Agent Definitions**: `.github/agents/` directory structure -- **Agent Documentation**: `AGENTS.md` file listing available agents - -#### Code Structure and Patterns - -- **Library API**: Public API design following .NET library best practices -- **Self-Validation**: Self-validation pattern for built-in tests -- **Standard Patterns**: Following common library design patterns - -#### Documentation - -- **README Structure**: Follows template README.md pattern (badges, features, installation, - usage, structure, CI/CD, documentation, license) -- **Standard Files**: Presence and structure of: - - `CONTRIBUTING.md` - - `CODE_OF_CONDUCT.md` - - `SECURITY.md` - - `LICENSE` - -#### Quality Configuration - -- **Linting Rules**: `.cspell.json`, `.markdownlint-cli2.jsonc`, `.yamllint.yaml` - - Note: Spelling exceptions will be repository-specific (e.g. spdx, sbom, etc.) -- **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 Package Configuration - - Symbol Package Configuration - - Code Quality Configuration (TreatWarningsAsErrors, GenerateDocumentationFile, etc.) - - SBOM Configuration - - Common package references (DemaConsulting.TestResults, Microsoft.SourceLink.GitHub, analyzers) - -#### Documentation Generation - -- **Document Structure**: `docs/` directory with: - - `guide/` (user guide) - - `requirements/` (auto-generated) - - `justifications/` (auto-generated) - - `tracematrix/` (auto-generated) - - `buildnotes/` (auto-generated) - - `quality/` (auto-generated) -- **Definition Files**: `definition.yaml` files for document generation - -### Review Process - -1. **Identify Differences**: Compare SpdxModel structure with the TemplateDotNetLibrary 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 SpdxModel-specific customizations - -### What NOT to Flag - -- Project-specific naming (SpdxModel package IDs, repository URLs, etc.) -- SpdxModel-specific spell check exceptions in `.cspell.json` (e.g. spdx, sbom, etc.) -- Workflow variations for SpdxModel-specific needs -- Additional requirements or features beyond the template -- SpdxModel-specific dependencies (e.g. System.Text.Json) - -## Defer To - -- **Software Developer Agent**: For implementing code changes recommended by consistency check -- **Technical Writer Agent**: For updating documentation to match template -- **Requirements Agent**: For updating requirements.yaml -- **Test Developer Agent**: For updating test patterns -- **Code Quality Agent**: For applying linting and code style changes - -## Usage Pattern - -1. Access the SpdxModel repository -2. Invoke repo-consistency-agent to review consistency with the TemplateDotNetLibrary template - () -3. Review agent recommendations -4. Apply relevant changes using appropriate specialized agents -5. Test changes to ensure they don't break existing functionality - -## Key Principles - -- **Template Evolution**: As the template evolves, this agent helps SpdxModel stay current -- **Respect Customization**: Not all differences are problems - some are valid customizations -- **Incremental Adoption**: SpdxModel can adopt template changes incrementally -- **Documentation**: When recommending changes, explain why they align with best practices diff --git a/.github/agents/repo-consistency.agent.md b/.github/agents/repo-consistency.agent.md new file mode 100644 index 0000000..4e62871 --- /dev/null +++ b/.github/agents/repo-consistency.agent.md @@ -0,0 +1,88 @@ +--- +name: repo-consistency +description: > + Ensures SpdxModel remains consistent with the TemplateDotNetLibrary + template patterns and best practices. +user-invocable: true +--- + +# Repo Consistency Agent - SpdxModel + +Maintain consistency between SpdxModel and the TemplateDotNetLibrary template at +. + +## Consistency Workflow (MANDATORY) + +**CRITICAL**: This agent MUST follow these steps systematically to ensure proper template consistency analysis: + +1. **Fetch Recent Template Changes**: Use GitHub search to fetch the 20 most recently merged PRs + (`is:pr is:merged sort:updated-desc`) from +2. **Analyze Template Evolution**: For each relevant PR, determine the intent and scope of changes + (what files were modified, what improvements were made) +3. **Assess Downstream Applicability**: Evaluate which template changes would benefit this repository + while respecting project-specific customizations +4. **Apply Appropriate Updates**: Implement applicable template improvements with proper translation for project context +5. **Validate Consistency**: Verify that applied changes maintain functionality and follow project patterns + +## Key Principles + +- **Evolutionary Consistency**: Template improvements should enhance downstream projects systematically +- **Intelligent Customization Respect**: Distinguish valid customizations from unintentional drift +- **Incremental Template Adoption**: Support phased adoption of template improvements based on project capacity + +## What NOT to Flag + +- Project-specific naming (SpdxModel package IDs, repository URLs, etc.) +- SpdxModel-specific spell check exceptions in `.cspell.json` (e.g. spdx, sbom, etc.) +- Workflow variations for SpdxModel-specific needs +- Additional requirements or features beyond the template +- SpdxModel-specific dependencies (e.g. System.Text.Json) + +## Don't Do These Things + +- **Never recommend changes without understanding project context** (some differences are intentional) +- **Never flag valid project-specific customizations** as consistency problems +- **Never apply template changes blindly** without assessing downstream project impact +- **Never ignore template evolution benefits** when they clearly improve downstream projects +- **Never recommend breaking changes** without migration guidance and impact assessment +- **Never skip validation** of preserved functionality after template alignment +- **Never assume all template patterns apply universally** (assess project-specific needs) + +## Reporting + +Upon completion create a summary in `.agent-logs/[agent-name]-[subject]-[unique-id].md` +of the project consisting of: + +```markdown +# Repo Consistency Report + +**Result**: + +## Consistency Analysis + +- **Template PRs Analyzed**: [Number and timeframe of PRs reviewed] +- **Template Changes Identified**: [Count and types of template improvements] +- **Applicable Updates**: [Changes determined suitable for this repository] +- **Project Customizations Preserved**: [Valid differences maintained] + +## Template Evolution Applied + +- **Files Modified**: [List of files updated for template consistency] +- **Improvements Adopted**: [Specific template enhancements implemented] +- **Configuration Updates**: [Tool configurations, workflows, or standards updated] + +## Consistency Status + +- **Template Alignment**: [Overall consistency rating with template] +- **Customization Respect**: [How project-specific needs were preserved] +- **Functionality Validation**: [Verification that changes don't break existing features] +- **Future Consistency**: [Recommendations for ongoing template alignment] + +## Issues Resolved + +- **Drift Corrections**: [Template drift issues addressed] +- **Enhancement Adoptions**: [Template improvements successfully integrated] +- **Validation Results**: [Testing and validation outcomes] +``` + +Return this summary to the caller. diff --git a/.github/agents/requirements-agent.md b/.github/agents/requirements.agent.md similarity index 93% rename from .github/agents/requirements-agent.md rename to .github/agents/requirements.agent.md index ec9bfc7..b7395d1 100644 --- a/.github/agents/requirements-agent.md +++ b/.github/agents/requirements.agent.md @@ -1,6 +1,9 @@ --- -name: Requirements Agent -description: Develops requirements and ensures appropriate test coverage - knows which requirements need unit/integration/self-validation tests +name: requirements +description: > + Develops requirements and ensures appropriate test coverage - knows which + requirements need unit/integration/self-validation tests. +user-invocable: true --- # Requirements Agent - SpdxModel diff --git a/.github/agents/software-developer.md b/.github/agents/software-developer.md deleted file mode 100644 index 84ab06f..0000000 --- a/.github/agents/software-developer.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -name: Software Developer -description: Writes production code and self-validation tests - targets design-for-testability and literate programming style ---- - -# Software Developer - SpdxModel - -Develop production code with emphasis on testability and clarity. - -## When to Invoke This Agent - -Invoke the software-developer for: - -- Implementing production code features -- Code refactoring for testability and maintainability -- Implementing library APIs and functionality - -## 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 -// Validate the input parameter -if (string.IsNullOrEmpty(input)) - throw new ArgumentException("Input cannot be null or empty", nameof(input)); - -// Process the input data -var results = ProcessData(input); - -// Return the formatted results -return FormatResults(results); -``` - -### Design for Testability - -- Small, focused functions with single responsibilities -- Dependency injection for external dependencies -- Avoid hidden state and side effects -- Clear separation of concerns - -### SpdxModel-Specific Rules - -- **XML Docs**: On ALL members (public/internal/private) with spaces after `///` - - Follow standard XML indentation rules with four-space indentation -- **Namespace**: File-scoped namespaces only -- **Using Statements**: Top of file only -- **String Formatting**: Use interpolated strings ($"") for clarity - -## Defer To - -- **Requirements Agent**: For new requirement creation and test strategy -- **Test Developer Agent**: For unit and integration tests -- **Technical Writer Agent**: For documentation updates -- **Code Quality Agent**: For linting, formatting, and static analysis - -## Don't - -- Write code without explanatory comments -- Create large monolithic functions -- Skip XML documentation -- Ignore the literate programming style diff --git a/.github/agents/technical-writer.md b/.github/agents/technical-writer.agent.md similarity index 92% rename from .github/agents/technical-writer.md rename to .github/agents/technical-writer.agent.md index e03ecca..eff2c4d 100644 --- a/.github/agents/technical-writer.md +++ b/.github/agents/technical-writer.agent.md @@ -1,6 +1,9 @@ --- -name: Technical Writer -description: Ensures documentation is accurate and complete - knowledgeable about regulatory documentation and special document types +name: technical-writer +description: > + Ensures documentation is accurate and complete - knowledgeable about + regulatory documentation and special document types. +user-invocable: true --- # Technical Writer - SpdxModel diff --git a/.github/agents/test-developer.md b/.github/agents/test-developer.agent.md similarity index 96% rename from .github/agents/test-developer.md rename to .github/agents/test-developer.agent.md index a802a4f..42f3996 100644 --- a/.github/agents/test-developer.md +++ b/.github/agents/test-developer.agent.md @@ -1,6 +1,9 @@ --- -name: Test Developer -description: Writes unit and integration tests following AAA pattern - clear documentation of what's tested and proved +name: test-developer +description: > + Writes unit and integration tests following AAA pattern - clear documentation + of what's tested and proved. +user-invocable: true --- # Test Developer - SpdxModel diff --git a/.gitignore b/.gitignore index 6509060..46082ea 100644 --- a/.gitignore +++ b/.gitignore @@ -85,6 +85,7 @@ npm-debug.log __pycache__/ *.py[cod] *$py.class +.venv/ # Generated documentation docs/**/*.html diff --git a/AGENTS.md b/AGENTS.md index e165c7f..e978170 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,25 +19,33 @@ quality checks and guidelines throughout your work. ## 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 in literate style -- **Test Developer** - Creates unit tests following AAA pattern -- **Code Quality Agent** - Enforces linting, static analysis, and security standards -- **Repo Consistency Agent** - Ensures SpdxModel remains consistent with the +- **implementation** - Orchestrator agent that manages quality implementations + through a formal RESEARCH → DEVELOPMENT → QUALITY state machine workflow +- **developer** - General-purpose software development agent that applies + appropriate standards based on the work being performed +- **quality** - Quality assurance agent that grades developer work against DEMA + Consulting standards and Continuous Compliance practices +- **code-review** - Agent for performing formal reviews using standardized + review processes +- **repo-consistency** - Ensures SpdxModel remains consistent with the [TemplateDotNetLibrary](https://github.com/demaconsulting/TemplateDotNetLibrary) template patterns +- **requirements** - Develops requirements and ensures test coverage linkage +- **technical-writer** - Creates accurate documentation following regulatory best practices +- **test-developer** - Creates unit tests following AAA pattern ## Agent Selection Guide -- Fix a bug → **Software Developer** -- Add a new feature → **Requirements Agent** → **Software Developer** → **Test Developer** -- Write a test → **Test Developer** -- Fix linting or static analysis issues → **Code Quality Agent** -- Update documentation → **Technical Writer** -- Add or update requirements → **Requirements Agent** -- Ensure test coverage linkage in `requirements.yaml` → **Requirements Agent** -- Run security scanning or address CodeQL alerts → **Code Quality Agent** -- Propagate template changes → **Repo Consistency Agent** +- Fix a bug → **developer** +- Add a new feature (complex) → **implementation** (orchestrates research→development→quality) +- Add a new feature (simple) → **developer** → **test-developer** +- Write a test → **test-developer** +- Fix linting or static analysis issues → **quality** +- Update documentation → **technical-writer** +- Add or update requirements → **requirements** +- Ensure test coverage linkage in `requirements.yaml` → **requirements** +- Run security scanning or address CodeQL alerts → **quality** +- Propagate template changes → **repo-consistency** +- Formal code review → **code-review** ## Tech Stack @@ -129,9 +137,8 @@ dotnet test --configuration Release dotnet format # Run all linters -npx cspell lint "**/*.md" -npx markdownlint-cli2 "**/*.md" -yamllint . +./lint.sh # Linux/macOS +lint.bat # Windows ``` ## Agent Log Files diff --git a/lint.bat b/lint.bat index ea8aab0..7a84968 100644 --- a/lint.bat +++ b/lint.bat @@ -1,20 +1,40 @@ @echo off -REM Run all linters for SpdxModel (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 --silent -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 --quiet --disable-pip-version-check + +REM Run spell check +call npx cspell --no-progress --no-color --quiet "**/*.{md,yaml,yml,json,cs,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 code formatting check 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 56c3bf0..c2548c4 100755 --- a/lint.sh +++ b/lint.sh @@ -1,18 +1,35 @@ -#!/usr/bin/env bash -# Run all linters for SpdxModel +#!/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 --silent -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 --quiet --disable-pip-version-check -echo "🎨 Checking code formatting..." -dotnet format --verify-no-changes +# Run spell check +npx cspell --no-progress --no-color --quiet "**/*.{md,yaml,yml,json,cs,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 code formatting check +dotnet format --verify-no-changes || lint_error=1 + +exit $lint_error 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 bf104fd822368d9003c5f28a14121892bbaecb49 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 31 Mar 2026 00:43:14 +0000 Subject: [PATCH 04/15] Remove SpdxModel-specific agents and align AGENTS.md with template pattern Agent-Logs-Url: https://github.com/demaconsulting/SpdxModel/sessions/c0925b40-34b4-4a8f-be77-fbfefc521131 Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --- .github/agents/requirements.agent.md | 77 ------------- .github/agents/technical-writer.agent.md | 69 ------------ .github/agents/test-developer.agent.md | 135 ----------------------- AGENTS.md | 69 ++++++------ 4 files changed, 33 insertions(+), 317 deletions(-) delete mode 100644 .github/agents/requirements.agent.md delete mode 100644 .github/agents/technical-writer.agent.md delete mode 100644 .github/agents/test-developer.agent.md diff --git a/.github/agents/requirements.agent.md b/.github/agents/requirements.agent.md deleted file mode 100644 index b7395d1..0000000 --- a/.github/agents/requirements.agent.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -name: requirements -description: > - Develops requirements and ensures appropriate test coverage - knows which - requirements need unit/integration/self-validation tests. -user-invocable: true ---- - -# Requirements Agent - SpdxModel - -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 -- Differentiating requirements from design details - -## Responsibilities - -### Writing Good Requirements - -- Focus on **what** the system must do, not **how** it does it -- Requirements describe observable behavior or characteristics -- Design details (implementation choices) are NOT requirements -- Use clear, testable language with measurable acceptance criteria -- Each requirement should be traceable to test evidence - -### Test Coverage Strategy - -- **All requirements MUST be linked to tests** - this is enforced in CI -- **Not all tests need to be linked to requirements** - tests may exist for: - - Exploring corner cases - - Testing design decisions - - Failure-testing scenarios - - Implementation validation beyond requirement scope -- **Unit tests**: For library functionality and internal component behavior - -### Test Source Filters - -Test links can include a source filter prefix to restrict which test results count as evidence. This is essential -for platform and framework requirements - **never remove these filters**. - -- `windows@TestName` - proves the test passed on a Windows platform -- `ubuntu@TestName` - proves the test passed on a Linux (Ubuntu) platform -- `net8.0@TestName` - proves the test passed under the .NET 8 runtime -- `net9.0@TestName` - proves the test passed under the .NET 9 runtime -- `net10.0@TestName` - proves the test passed under the .NET 10 runtime - -Without the source filter, any matching test result satisfies the requirement regardless of which platform or -framework produced it. Removing a filter invalidates the evidence for platform/framework requirements. - -### 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` - -## Defer To - -- **Software Developer Agent**: For implementing self-validation tests -- **Test Developer Agent**: For implementing unit and integration tests -- **Technical Writer Agent**: For documentation of requirements and processes -- **Code Quality Agent**: For verifying test quality and enforcement - -## Don't - -- Mix requirements with implementation details -- Create requirements without test linkage -- Expect all tests to be linked to requirements (some tests exist for other purposes) -- Change code directly (delegate to developer agents) diff --git a/.github/agents/technical-writer.agent.md b/.github/agents/technical-writer.agent.md deleted file mode 100644 index eff2c4d..0000000 --- a/.github/agents/technical-writer.agent.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -name: technical-writer -description: > - Ensures documentation is accurate and complete - knowledgeable about - regulatory documentation and special document types. -user-invocable: true ---- - -# Technical Writer - SpdxModel - -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 - -### SpdxModel-Specific Rules - -#### Markdown Style - -- **All markdown files**: Use reference-style links `[text][ref]` with `[ref]: url` at document end -- **Exceptions**: - - **README.md**: Use absolute URLs in the links (shipped in NuGet package) - - **AI agent markdown files** (`.github/agents/*.md`): Use inline links `[text](url)` so URLs are visible in agent context -- Max 120 characters per line -- Lists require blank lines (MD032) - -#### Linting Requirements - -- **markdownlint**: Style and structure compliance -- **cspell**: Spelling (add technical terms to `.cspell.json`) -- **yamllint**: YAML file validation - -### Regulatory Documentation - -For documents requiring regulatory compliance: - -- Clear purpose and scope sections -- Appropriate detail level for audience -- Traceability to requirements where applicable - -## Defer To - -- **Requirements Agent**: For requirements.yaml content and test linkage -- **Software Developer Agent**: For code examples -- **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 deleted file mode 100644 index 42f3996..0000000 --- a/.github/agents/test-developer.agent.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -name: test-developer -description: > - Writes unit and integration tests following AAA pattern - clear documentation - of what's tested and proved. -user-invocable: true ---- - -# Test Developer - SpdxModel - -Develop comprehensive unit tests following best practices. - -## When to Invoke This Agent - -Invoke the test-developer for: - -- Creating unit tests for individual components -- 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 runtime -- `net9.0@TestName` - proves the test passed under the .NET 9 runtime -- `net10.0@TestName` - proves the test passed under the .NET 10 runtime - -Removing a source filter means a test result from any environment can satisfy the requirement, which invalidates -the evidence-based proof that the library works on a specific platform or framework. - -### SpdxModel-Specific - -- Unit tests live in `test/` directory -- Use MSTest V4 testing framework -- Follow existing naming conventions in the test suite - -### MSTest V4 Best Practices - -Common anti-patterns to avoid (not exhaustive): - -1. **Avoid Assertions in Catch Blocks (MSTEST0058)** - Instead of wrapping code in try/catch and asserting in the - catch block, use `Assert.ThrowsExactly()`: - - ```csharp - var ex = Assert.ThrowsExactly(() => SomeWork()); - Assert.Contains("Some message", ex.Message); - ``` - -2. **Avoid using Assert.IsTrue / Assert.IsFalse for equality checks** - Use `Assert.AreEqual` / - `Assert.AreNotEqual` instead, as it provides better failure messages: - - ```csharp - // ❌ Bad: Assert.IsTrue(result == expected); - // ✅ Good: Assert.AreEqual(expected, result); - ``` - -3. **Avoid non-public test classes and methods** - Test classes and `[TestMethod]` methods must be `public` or - they will be silently ignored: - - ```csharp - // ❌ Bad: internal class MyTests - // ✅ Good: public class MyTests - ``` - -4. **Avoid Assert.IsTrue(collection.Count == N)** - Use `Assert.HasCount` for count assertions: - - ```csharp - // ❌ Bad: Assert.IsTrue(collection.Count == 3); - // ✅ Good: Assert.HasCount(3, collection); - ``` - -## Defer To - -- **Requirements Agent**: For test strategy and coverage requirements -- **Software Developer Agent**: For 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 diff --git a/AGENTS.md b/AGENTS.md index e978170..c42a697 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,35 +17,42 @@ Before performing any work, agents must read and apply the relevant standards fr 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 -- **implementation** - Orchestrator agent that manages quality implementations - through a formal RESEARCH → DEVELOPMENT → QUALITY state machine workflow +- **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 RESEARCH → DEVELOPMENT → QUALITY state machine workflow - **quality** - Quality assurance agent that grades developer work against DEMA Consulting standards and Continuous Compliance practices -- **code-review** - Agent for performing formal reviews using standardized - review processes - **repo-consistency** - Ensures SpdxModel remains consistent with the - [TemplateDotNetLibrary](https://github.com/demaconsulting/TemplateDotNetLibrary) template patterns -- **requirements** - Develops requirements and ensures test coverage linkage -- **technical-writer** - Creates accurate documentation following regulatory best practices -- **test-developer** - Creates unit tests following AAA pattern - -## Agent Selection Guide - -- Fix a bug → **developer** -- Add a new feature (complex) → **implementation** (orchestrates research→development→quality) -- Add a new feature (simple) → **developer** → **test-developer** -- Write a test → **test-developer** -- Fix linting or static analysis issues → **quality** -- Update documentation → **technical-writer** -- Add or update requirements → **requirements** -- Ensure test coverage linkage in `requirements.yaml` → **requirements** -- Run security scanning or address CodeQL alerts → **quality** -- Propagate template changes → **repo-consistency** -- Formal code review → **code-review** + [TemplateDotNetLibrary][template] template patterns and best practices + +## Quality Gate Enforcement (ALL Agents Must Verify) + +Configuration files and scripts are self-documenting with their design intent and +modification policies in header comments. + +1. **Linting Standards**: `./lint.sh` (Unix) or `lint.bat` (Windows) - comprehensive linting suite +2. **Build Quality**: Zero warnings (`TreatWarningsAsErrors=true`) +3. **Static Analysis**: SonarCloud/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 ## Tech Stack @@ -141,24 +148,14 @@ dotnet format lint.bat # Windows ``` -## Agent Log Files +## Agent Report Files -Upon completion, agents should create a log 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 - Follow-up items, open questions, or TODOs -Agent logs are stored in `.agent-logs/` which is excluded from git (via `.gitignore`) and excluded from linting. - -## Agent Report Files - -When agents need to write report files to communicate with each other or the user, follow these guidelines: +Store agent logs in the `.agent-logs/` folder so they are ignored via `.gitignore` and excluded from linting and commits. -- **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 +[template]: https://github.com/demaconsulting/TemplateDotNetLibrary From 9847315a900aaca58beac30f47d90e3ad36ca12d Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 31 Mar 2026 00:50:10 +0000 Subject: [PATCH 05/15] Align AGENTS.md more closely with NuGetCacheTool template pattern Agent-Logs-Url: https://github.com/demaconsulting/SpdxModel/sessions/2dee4720-8818-4e0d-84aa-86a41277be8a Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --- AGENTS.md | 42 ++---------------------------------------- 1 file changed, 2 insertions(+), 40 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index c42a697..a69ae01 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -40,7 +40,7 @@ Delegate to specialized agents only for specific scenarios: - **quality** - Quality assurance agent that grades developer work against DEMA Consulting standards and Continuous Compliance practices - **repo-consistency** - Ensures SpdxModel remains consistent with the - [TemplateDotNetLibrary][template] template patterns and best practices + TemplateDotNetLibrary template patterns and best practices ## Quality Gate Enforcement (ALL Agents Must Verify) @@ -53,6 +53,7 @@ modification policies in header comments. 4. **Requirements Traceability**: `dotnet reqstream --enforce` passing 5. **Test Coverage**: All requirements linked to passing tests 6. **Documentation Currency**: All docs current and generated +7. **File Review Status**: All reviewable files have current reviews ## Tech Stack @@ -87,25 +88,6 @@ evidence. This is critical for platform and framework requirements - **do not re Without the source filter, a test result from any platform/framework satisfies the requirement. Adding the filter ensures the CI evidence comes specifically from the required environment. -## Testing - -- **Test Naming**: `ClassName_MethodUnderTest_Scenario_ExpectedBehavior` for unit tests -- **Test Framework**: Uses MSTest for unit testing -- **Code Coverage**: Maintain high code coverage for library APIs - -## Code Style - -- **XML Docs**: On ALL members (public/internal/private) with spaces after `///` in summaries -- **Namespace**: File-scoped namespaces only -- **Using Statements**: Top of file only (no nested using declarations except for IDisposable) -- **String Formatting**: Use interpolated strings ($"") for clarity - -## Project Structure - -- **`src/DemaConsulting.SpdxModel/`**: Library source code -- **`test/DemaConsulting.SpdxModel.Tests/`**: Unit tests -- **`DemaConsulting.SpdxModel.sln`**: Visual Studio solution file - ## Build and Test ```bash @@ -116,13 +98,6 @@ dotnet build --configuration Release dotnet test --configuration Release ``` -## Documentation - -- **User Guide**: `docs/guide/` -- **Requirements**: `requirements.yaml` -> auto-generated docs -- **Build Notes**: Auto-generated via BuildMark -- **Trace Matrix**: Auto-generated via ReqStream - ## Markdown Link Style - **AI agent markdown files** (`.github/agents/*.md`): Use inline links `[text](url)` so URLs are @@ -137,17 +112,6 @@ dotnet test --configuration Release - **CodeQL**: Security scanning - **SonarCloud**: Code quality analysis -## Common Tasks - -```bash -# Format code -dotnet format - -# Run all linters -./lint.sh # Linux/macOS -lint.bat # Windows -``` - ## Agent Report Files Upon completion, create a report file at `.agent-logs/[agent-name]-[subject]-[unique-id].md` that includes: @@ -157,5 +121,3 @@ Upon completion, create a report file at `.agent-logs/[agent-name]-[subject]-[un - Follow-up items, open questions, or TODOs Store agent logs in the `.agent-logs/` folder so they are ignored via `.gitignore` and excluded from linting and commits. - -[template]: https://github.com/demaconsulting/TemplateDotNetLibrary From ca112db68c3a44c75bf13fc7a800a5d6ab9c4e75 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 31 Mar 2026 00:59:13 +0000 Subject: [PATCH 06/15] Sync agent files, AGENTS.md, and config with TemplateDotNetTool Agent-Logs-Url: https://github.com/demaconsulting/SpdxModel/sessions/b8d46c38-93ff-4275-9499-f51d5df46506 Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --- .github/agents/developer.agent.md | 27 +------ .github/agents/quality.agent.md | 42 ++++++----- .github/agents/repo-consistency.agent.md | 24 ++---- .github/standards/reqstream-usage.md | 1 + .gitignore | 2 + AGENTS.md | 94 +++++++++++++++++++++++- lint.bat | 2 +- lint.sh | 2 +- 8 files changed, 132 insertions(+), 62 deletions(-) diff --git a/.github/agents/developer.agent.md b/.github/agents/developer.agent.md index d383fa8..955f9e9 100644 --- a/.github/agents/developer.agent.md +++ b/.github/agents/developer.agent.md @@ -6,11 +6,11 @@ description: > user-invocable: true --- -# Developer Agent - SpdxModel +# Developer Agent Perform software development tasks by determining and applying appropriate DEMA Consulting standards from `.github/standards/`. -## Standards-Based Workflow +# 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 @@ -18,28 +18,7 @@ Perform software development tasks by determining and applying appropriate DEMA 4. **Execute work** following standards requirements and quality checks 5. **Generate completion report** with results and compliance status -## SpdxModel-Specific Rules - -- **XML Docs**: On ALL members (public/internal/private) with spaces after `///` -- **Namespace**: File-scoped namespaces only -- **Using Statements**: Top of file only -- **String Formatting**: Use interpolated strings ($"") for clarity - -## Defer To - -- **Requirements Agent**: For new requirement creation and test strategy -- **Test Developer Agent**: For unit and integration tests -- **Technical Writer Agent**: For documentation updates -- **Code Quality Agent**: For linting, formatting, and static analysis - -## Don't - -- Write code without explanatory comments -- Create large monolithic functions -- Skip XML documentation -- Ignore the literate programming style - -## Reporting +# Reporting Upon completion create a summary in `.agent-logs/[agent-name]-[subject]-[unique-id].md` of the project consisting of: diff --git a/.github/agents/quality.agent.md b/.github/agents/quality.agent.md index 6bb2c31..8ecdad8 100644 --- a/.github/agents/quality.agent.md +++ b/.github/agents/quality.agent.md @@ -6,22 +6,22 @@ description: > user-invocable: true --- -# Quality Agent - SpdxModel +# Quality Agent Grade and validate software development work by ensuring compliance with DEMA Consulting standards and Continuous Compliance practices. -## Standards-Based Quality Assessment +# 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 and language tools +4. **Validate tool compliance** using ReqStream, ReviewMark, and language tools 5. **Generate quality assessment report** with findings and recommendations -### Requirements Compliance +## Requirements Compliance - [ ] Were requirements updated to reflect functional changes? - [ ] Were new requirements created for new features? @@ -30,7 +30,7 @@ This assessment is a quality control system of the project and MUST be performed - [ ] Does ReqStream enforcement pass without errors? - [ ] Is requirements traceability maintained to tests? -### Design Documentation Compliance +## Design Documentation Compliance - [ ] Were design documents updated for architectural changes? - [ ] Were new design artifacts created for new components? @@ -38,7 +38,7 @@ This assessment is a quality control system of the project and MUST be performed - [ ] Is system/subsystem/unit categorization maintained? - [ ] Is design-to-implementation traceability preserved? -### Code Quality Compliance +## Code Quality Compliance - [ ] Are language-specific standards followed (from applicable standards files)? - [ ] Are quality checks from standards files satisfied? @@ -46,7 +46,7 @@ This assessment is a quality control system of the project and MUST be performed - [ ] Is appropriate separation of concerns maintained? - [ ] Was language-specific tooling executed and passing? -### Testing Compliance +## Testing Compliance - [ ] Were tests created/updated for all functional changes? - [ ] Is test coverage maintained for all requirements? @@ -54,15 +54,28 @@ This assessment is a quality control system of the project and MUST be performed - [ ] Does test categorization align with code structure? - [ ] Do all tests pass without failures? -### Documentation Compliance +## 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 +## Process Compliance - [ ] Was Continuous Compliance workflow followed? - [ ] Did all quality gates execute successfully? @@ -70,15 +83,7 @@ This assessment is a quality control system of the project and MUST be performed - [ ] Were standards consistently applied across work? - [ ] Was compliance evidence generated and preserved? -## SpdxModel-Specific Quality Gates (ALL Must Pass) - -1. **Build**: Zero warnings (`TreatWarningsAsErrors=true`) -2. **Linting**: `./lint.sh` (Linux/macOS) or `lint.bat` (Windows) -3. **Static Analysis**: Microsoft.CodeAnalysis.NetAnalyzers, SonarAnalyzer.CSharp -4. **Requirements Traceability**: `dotnet reqstream --requirements requirements.yaml --tests "artifacts/**/*.trx" --enforce` -5. **Tests**: All unit tests passing - -## Reporting +# Reporting Upon completion create a summary in `.agent-logs/[agent-name]-[subject]-[unique-id].md` of the project consisting of: @@ -101,6 +106,7 @@ of the project consisting of: - **Design Documentation**: - [Summary] - **Code Quality**: - [Summary] - **Testing Compliance**: - [Summary] +- **Review Management**: - [Summary] - **Documentation**: - [Summary] - **Process Compliance**: - [Summary] diff --git a/.github/agents/repo-consistency.agent.md b/.github/agents/repo-consistency.agent.md index 4e62871..cbf3e18 100644 --- a/.github/agents/repo-consistency.agent.md +++ b/.github/agents/repo-consistency.agent.md @@ -1,22 +1,22 @@ --- name: repo-consistency description: > - Ensures SpdxModel remains consistent with the TemplateDotNetLibrary + Ensures SpdxModel remains consistent with the TemplateDotNetTool template patterns and best practices. user-invocable: true --- -# Repo Consistency Agent - SpdxModel +# Repo Consistency Agent -Maintain consistency between SpdxModel and the TemplateDotNetLibrary template at -. +Maintain consistency between downstream projects and the TemplateDotNetTool template, ensuring repositories +benefit from template evolution while respecting project-specific customizations. -## Consistency Workflow (MANDATORY) +# Consistency Workflow (MANDATORY) **CRITICAL**: This agent MUST follow these steps systematically to ensure proper template consistency analysis: 1. **Fetch Recent Template Changes**: Use GitHub search to fetch the 20 most recently merged PRs - (`is:pr is:merged sort:updated-desc`) from + (`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 @@ -30,15 +30,7 @@ Maintain consistency between SpdxModel and the TemplateDotNetLibrary template at - **Intelligent Customization Respect**: Distinguish valid customizations from unintentional drift - **Incremental Template Adoption**: Support phased adoption of template improvements based on project capacity -## What NOT to Flag - -- Project-specific naming (SpdxModel package IDs, repository URLs, etc.) -- SpdxModel-specific spell check exceptions in `.cspell.json` (e.g. spdx, sbom, etc.) -- Workflow variations for SpdxModel-specific needs -- Additional requirements or features beyond the template -- SpdxModel-specific dependencies (e.g. System.Text.Json) - -## Don't Do These Things +# 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 @@ -48,7 +40,7 @@ Maintain consistency between SpdxModel and the TemplateDotNetLibrary template at - **Never skip validation** of preserved functionality after template alignment - **Never assume all template patterns apply universally** (assess project-specific needs) -## Reporting +# Reporting Upon completion create a summary in `.agent-logs/[agent-name]-[subject]-[unique-id].md` of the project consisting of: diff --git a/.github/standards/reqstream-usage.md b/.github/standards/reqstream-usage.md index b1b47e8..8ec267b 100644 --- a/.github/standards/reqstream-usage.md +++ b/.github/standards/reqstream-usage.md @@ -140,6 +140,7 @@ Before submitting requirements, verify: - [ ] Platform-specific requirements use source filters (`platform@TestName`) - [ ] Requirements specify observable behavior (WHAT), not implementation (HOW) - [ ] Comprehensive justification explains business/regulatory need +- [ ] Files organized under `docs/reqstream/` following naming patterns - [ ] Valid YAML syntax passes yamllint validation - [ ] ReqStream enforcement passes: `dotnet reqstream --enforce` - [ ] Test result formats compatible (TRX, JUnit XML) diff --git a/.gitignore b/.gitignore index 46082ea..95e4bdd 100644 --- a/.gitignore +++ b/.gitignore @@ -98,6 +98,8 @@ docs/quality/codeql-quality.md docs/quality/sonar-quality.md docs/buildnotes.md docs/buildnotes/versions.md +docs/code_review_plan/plan.md +docs/code_review_report/report.md # Test results TestResults/ diff --git a/AGENTS.md b/AGENTS.md index a69ae01..f00d758 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -36,11 +36,11 @@ Delegate to specialized agents only for specific scenarios: - **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 RESEARCH → DEVELOPMENT → QUALITY state machine workflow + 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 SpdxModel remains consistent with the - TemplateDotNetLibrary template patterns and best practices + TemplateDotNetTool template patterns and best practices ## Quality Gate Enforcement (ALL Agents Must Verify) @@ -55,6 +55,96 @@ modification policies in header comments. 6. **Documentation Currency**: All docs current and generated 7. **File Review Status**: All reviewable files have current reviews +## Continuous Compliance Overview + +This repository follows the DEMA Consulting Continuous Compliance + approach, which enforces quality and +compliance gates on every CI/CD run instead of as a last-mile activity. + +### Core Principles + +- **Requirements Traceability**: Every requirement MUST link to passing tests +- **Quality Gates**: All quality checks must pass before merge +- **Documentation Currency**: All docs auto-generated and kept current +- **Automated Evidence**: Full audit trail generated with every build + +## Required Compliance Tools + +### Linting Tools (ALL Must Pass) + +- **markdownlint-cli2**: Markdown style and formatting enforcement +- **cspell**: Spell-checking across all text files (use `.cspell.json` for technical terms) +- **yamllint**: YAML structure and formatting validation +- **Language-specific linters**: Based on repository technology stack + +### Quality Analysis + +- **SonarCloud**: Code quality and security analysis +- **CodeQL**: Security vulnerability scanning (produces SARIF output) +- **Static analyzers**: Microsoft.CodeAnalysis.NetAnalyzers, SonarAnalyzer.CSharp, etc. + +### Requirements & Compliance + +- **ReqStream**: Requirements traceability enforcement (`dotnet reqstream --enforce`) +- **ReviewMark**: File review status enforcement +- **BuildMark**: Tool version documentation +- **VersionMark**: Version tracking across CI/CD jobs + +## Key Configuration Files + +### Essential Files (Repository-Specific) + +- **`lint.sh` / `lint.bat`** - Cross-platform comprehensive linting scripts +- **`.editorconfig`** - Code formatting rules +- **`.cspell.json`** - Spell-check configuration and technical term dictionary +- **`.markdownlint-cli2.jsonc`** - Markdown linting rules +- **`.yamllint.yaml`** - YAML linting configuration +- **`nuget.config`** - NuGet package sources +- **`package.json`** - Node.js dependencies for linting tools + +### Compliance Files + +- **`requirements.yaml`** - Root requirements file with includes +- **`.reviewmark.yaml`** - File review definitions and tracking +- CI/CD pipeline files with quality gate enforcement + +## Continuous Compliance Workflow + +### CI/CD Pipeline Stages (Standard) + +1. **Lint**: `./lint.sh` or `lint.bat` - comprehensive linting suite +2. **Build**: Compile with warnings as errors +3. **Analyze**: SonarCloud, CodeQL security scanning +4. **Test**: Execute all tests, generate coverage reports +5. **Document**: Generate requirements reports, trace matrix, build notes +6. **Enforce**: Requirements traceability, file review status +7. **Publish**: Generate final documentation (Pandoc → PDF) + +### Quality Gate Enforcement + +All stages must pass before merge. Pipeline fails immediately on: + +- Any linting errors +- Build warnings or errors +- Security vulnerabilities (CodeQL) +- Requirements without test coverage +- Outdated file reviews +- Missing documentation + +## Continuous Compliance Requirements + +This repository follows continuous compliance practices from DEMA Consulting +Continuous Compliance . + +### Core Requirements Traceability Rules + +- **ALL requirements MUST be linked to tests** - Enforced in CI via `dotnet reqstream --enforce` +- **NOT all tests need requirement links** - Tests may exist for corner cases, design validation, failure scenarios +- **Source filters are critical** - Platform/framework requirements need specific test evidence + +For detailed requirements format, test linkage patterns, and ReqStream +integration, call the @developer agent with requirements management context. + ## Tech Stack - C# 12, .NET 8.0/9.0/10.0, dotnet CLI, NuGet diff --git a/lint.bat b/lint.bat index 7a84968..1fa5972 100644 --- a/lint.bat +++ b/lint.bat @@ -33,7 +33,7 @@ REM Run yamllint check yamllint . if errorlevel 1 set "LINT_ERROR=1" -REM Run code formatting check +REM Run .NET formatting check (verifies no changes are needed) dotnet format --verify-no-changes if errorlevel 1 set "LINT_ERROR=1" diff --git a/lint.sh b/lint.sh index c2548c4..b778299 100755 --- a/lint.sh +++ b/lint.sh @@ -29,7 +29,7 @@ npx markdownlint-cli2 "**/*.md" || lint_error=1 # Run yamllint check yamllint . || lint_error=1 -# Run code formatting check +# Run .NET formatting check (verifies no changes are needed) dotnet format --verify-no-changes || lint_error=1 exit $lint_error From 8c2ef82a80219cb4b2f7481e5d38bd8dd344aafc Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 31 Mar 2026 01:15:52 +0000 Subject: [PATCH 07/15] Plan all pending changes across lint scripts, standards, agents, and build.yaml Agent-Logs-Url: https://github.com/demaconsulting/SpdxModel/sessions/11b07f51-94a2-449f-9d04-d7bc4a018628 Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --- .cspell.json | 124 ---------------- .cspell.yaml | 140 +++++++++++++++++++ .github/standards/technical-documentation.md | 2 +- .markdownlint-cli2.jsonc | 18 --- .markdownlint-cli2.yaml | 53 +++++++ .yamllint.yaml | 1 - AGENTS.md | 8 +- 7 files changed, 198 insertions(+), 148 deletions(-) delete mode 100644 .cspell.json create mode 100644 .cspell.yaml delete mode 100644 .markdownlint-cli2.jsonc create mode 100644 .markdownlint-cli2.yaml diff --git a/.cspell.json b/.cspell.json deleted file mode 100644 index d94f91f..0000000 --- a/.cspell.json +++ /dev/null @@ -1,124 +0,0 @@ -{ - "version": "0.2", - "language": "en", - "words": [ - "Alsos", - "Anson", - "Blockquotes", - "BuildMark", - "Checkmarx", - "CodeQL", - "Cyper", - "DEMACONSULTINGNUGETKEY", - "Dema", - "DemaConsulting", - "Dependabot", - "DOAP", - "Doap", - "Gidget", - "hotspots", - "LINQ", - "NOASSERTION", - "NTIA", - "Neko", - "Ntia", - "NuGet", - "OpenCover", - "Protecode", - "Pylint", - "Qube", - "ReqStream", - "reviewmark", - "ReviewMark", - "code_quality", - "code_review_plan", - "code_review_report", - "requirements_doc", - "requirements_report", - "trace_matrix", - "Sarif", - "SarifMark", - "SBOM", - "Semgrep", - "SonarCloud", - "SonarMark", - "SonarQube", - "SPDX", - "SPDXID", - "SPDXJSON", - "SpdxModel", - "TMPL", - "Trivy", - "Weasyprint", - "acmecorp", - "acmenator", - "buildmark", - "buildnotes", - "camelcase", - "copilot", - "cspell", - "csproj", - "dbproj", - "dcterms", - "demaconsulting", - "dependabot", - "deserializer", - "doctitle", - "dotnet", - "editorconfig", - "filepart", - "fsproj", - "gitattributes", - "ibiqlik", - "maintainer", - "markdownlint", - "mermaid", - "mstest", - "myterm", - "nameof", - "ncipollo", - "nuget", - "nupkg", - "opencover", - "pagetitle", - "pandoc", - "reqstream", - "sbom", - "semver", - "serializer", - "slnx", - "snupkg", - "sonarmark", - "sonarscanner", - "spdx", - "streetsidesoftware", - "templatetool", - "testname", - "tracematrix", - "triaging", - "trx", - "vbproj", - "vcxproj", - "versionmark", - "weasyprint", - "workflow", - "workflows", - "yamllint" - ], - "ignorePaths": [ - "node_modules", - ".git", - ".agent-logs", - "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..6708ed2 --- /dev/null +++ b/.cspell.yaml @@ -0,0 +1,140 @@ +--- +# 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: + - acmecorp + - acmenator + - Alsos + - Anson + - Blockquotes + - buildmark + - BuildMark + - build_notes + - camelcase + - Checkmarx + - CodeQL + - code_quality + - code_review_plan + - code_review_report + - copilot + - cspell + - csproj + - Cyper + - dbproj + - dcterms + - Dema + - demaconsulting + - DemaConsulting + - DEMACONSULTINGNUGETKEY + - Dependabot + - dependabot + - deserializer + - DOAP + - Doap + - doctitle + - dotnet + - editorconfig + - filepart + - fsproj + - Gidget + - gitattributes + - hotspots + - ibiqlik + - LINQ + - maintainer + - markdownlint + - mermaid + - mstest + - myterm + - nameof + - ncipollo + - Neko + - NOASSERTION + - NTIA + - Ntia + - NuGet + - nuget + - nupkg + - OpenCover + - opencover + - pagetitle + - pandoc + - Propagatable + - Protecode + - Pylint + - Qube + - reqstream + - ReqStream + - requirements_doc + - requirements_report + - reviewmark + - ReviewMark + - Sarif + - SarifMark + - SBOM + - sbom + - Semgrep + - semver + - serializer + - slnx + - snupkg + - SonarCloud + - sonarmark + - SonarMark + - SonarQube + - sonarscanner + - SPDX + - spdx + - SPDXID + - SPDXJSON + - SpdxModel + - streetsidesoftware + - templatetool + - testname + - TMPL + - trace_matrix + - tracematrix + - triaging + - Trivy + - trx + - vbproj + - vcxproj + - versionmark + - Weasyprint + - weasyprint + - workflow + - workflows + - yamllint + +# Exclude common build artifacts, dependencies, and vendored third-party code +ignorePaths: + - "**/.git/**" + - "**/node_modules/**" + - "**/.venv/**" + - "**/thirdparty/**" + - "**/third-party/**" + - "**/3rd-party/**" + - "**/AGENT_REPORT_*.md" + - "**/.agent-logs/**" + - "**/bin/**" + - "**/obj/**" + - "*.nupkg" + - "*.snupkg" + - "*.dll" + - "*.exe" + - "*.trx" + - "*.spdx.json" + - package-lock.json + - yarn.lock diff --git a/.github/standards/technical-documentation.md b/.github/standards/technical-documentation.md index 0b50665..53c3aa7 100644 --- a/.github/standards/technical-documentation.md +++ b/.github/standards/technical-documentation.md @@ -89,7 +89,7 @@ Write technical documentation for clarity and compliance verification: # Markdown Format Requirements Markdown documentation in this repository must follow the formatting standards -defined in `.markdownlint-cli2.jsonc` (subject to any exclusions configured there) +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. diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc deleted file mode 100644 index 6fbe8ba..0000000 --- a/.markdownlint-cli2.jsonc +++ /dev/null @@ -1,18 +0,0 @@ -{ - "noBanner": true, - "noProgress": true, - "config": { - "default": true, - "MD003": { "style": "atx" }, - "MD007": { "indent": 2 }, - "MD013": { "line_length": 120 }, - "MD025": false, - "MD033": false, - "MD041": false - }, - "ignores": [ - "node_modules", - ".agent-logs", - "**/AGENT_REPORT_*.md" - ] -} diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml new file mode 100644 index 0000000..4532ba3 --- /dev/null +++ b/.markdownlint-cli2.yaml @@ -0,0 +1,53 @@ +--- +# 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 + +noBanner: true + +# Disable the progress indicator on stdout +noProgress: true + +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" + - "**/.agent-logs/**" diff --git a/.yamllint.yaml b/.yamllint.yaml index c5fb81a..4fbc811 100644 --- a/.yamllint.yaml +++ b/.yamllint.yaml @@ -27,7 +27,6 @@ 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 f00d758..c032a7f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -73,7 +73,7 @@ compliance gates on every CI/CD run instead of as a last-mile activity. ### Linting Tools (ALL Must Pass) - **markdownlint-cli2**: Markdown style and formatting enforcement -- **cspell**: Spell-checking across all text files (use `.cspell.json` for technical terms) +- **cspell**: Spell-checking across all text files (use `.cspell.yaml` for technical terms) - **yamllint**: YAML structure and formatting validation - **Language-specific linters**: Based on repository technology stack @@ -96,8 +96,8 @@ compliance gates on every CI/CD run instead of as a last-mile activity. - **`lint.sh` / `lint.bat`** - Cross-platform comprehensive linting scripts - **`.editorconfig`** - Code formatting rules -- **`.cspell.json`** - Spell-check configuration and technical term dictionary -- **`.markdownlint-cli2.jsonc`** - Markdown linting rules +- **`.cspell.yaml`** - Spell-check configuration and technical term dictionary +- **`.markdownlint-cli2.yaml`** - Markdown linting rules - **`.yamllint.yaml`** - YAML linting configuration - **`nuget.config`** - NuGet package sources - **`package.json`** - Node.js dependencies for linting tools @@ -153,7 +153,7 @@ integration, call the @developer agent with requirements management context. - **`requirements.yaml`** - All requirements with test linkage (enforced via `dotnet reqstream --enforce`) - **`.editorconfig`** - Code style (file-scoped namespaces, 4-space indent, UTF-8, LF endings) -- **`.cspell.json`, `.markdownlint-cli2.jsonc`, `.yamllint.yaml`** - Linting configs +- **`.cspell.yaml`, `.markdownlint-cli2.yaml`, `.yamllint.yaml`** - Linting configs ## Requirements From 64aa6cedb10d35de635dcd77fe81acbd0c67e20d Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 31 Mar 2026 01:18:24 +0000 Subject: [PATCH 08/15] Make lint scripts, standards, agents, and build.yaml match template exactly Agent-Logs-Url: https://github.com/demaconsulting/SpdxModel/sessions/11b07f51-94a2-449f-9d04-d7bc4a018628 Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --- .cspell.yaml | 1 + .github/agents/repo-consistency.agent.md | 2 +- .github/standards/reqstream-usage.md | 8 +- .github/standards/reviewmark-usage.md | 20 +++-- .github/standards/technical-documentation.md | 37 +++++--- .github/workflows/build.yaml | 94 ++++++++++++++++---- lint.bat | 2 +- lint.sh | 2 +- 8 files changed, 124 insertions(+), 42 deletions(-) diff --git a/.cspell.yaml b/.cspell.yaml index 6708ed2..5ee6003 100644 --- a/.cspell.yaml +++ b/.cspell.yaml @@ -22,6 +22,7 @@ words: - buildmark - BuildMark - build_notes + - buildnotes - camelcase - Checkmarx - CodeQL diff --git a/.github/agents/repo-consistency.agent.md b/.github/agents/repo-consistency.agent.md index cbf3e18..dfaf702 100644 --- a/.github/agents/repo-consistency.agent.md +++ b/.github/agents/repo-consistency.agent.md @@ -1,7 +1,7 @@ --- name: repo-consistency description: > - Ensures SpdxModel remains consistent with the TemplateDotNetTool + Ensures downstream repositories remain consistent with the TemplateDotNetTool template patterns and best practices. user-invocable: true --- diff --git a/.github/standards/reqstream-usage.md b/.github/standards/reqstream-usage.md index 8ec267b..3f99929 100644 --- a/.github/standards/reqstream-usage.md +++ b/.github/standards/reqstream-usage.md @@ -66,7 +66,7 @@ sections: Use meaningful IDs following `Project-Section-ShortDesc` pattern: -- **Good**: `SpdxModel-Core-DisplayHelp` +- **Good**: `TemplateTool-Core-DisplayHelp` - **Bad**: `REQ-042` (requires lookup to understand) # Requirement Best Practices @@ -117,18 +117,18 @@ dotnet reqstream \ # Generate requirements report dotnet reqstream \ --requirements requirements.yaml \ - --report docs/requirements/requirements.md + --report docs/requirements_doc/requirements.md # Generate justifications report dotnet reqstream \ --requirements requirements.yaml \ - --justifications docs/justifications/justifications.md + --justifications docs/requirements_doc/justifications.md # Generate trace matrix dotnet reqstream \ --requirements requirements.yaml \ --tests "artifacts/**/*.trx" \ - --matrix docs/tracematrix/tracematrix.md + --matrix docs/requirements_report/trace_matrix.md ``` # Quality Checks diff --git a/.github/standards/reviewmark-usage.md b/.github/standards/reviewmark-usage.md index aa715f7..bdabd1d 100644 --- a/.github/standards/reviewmark-usage.md +++ b/.github/standards/reviewmark-usage.md @@ -35,7 +35,15 @@ evidence-source: # Named review-sets grouping related files reviews: - - id: SpdxModel-AllRequirements + - 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" @@ -53,7 +61,7 @@ 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**: `SpdxModel-System` +- **Example**: `TemplateTool-System` ## [Product]-Design Review @@ -61,7 +69,7 @@ Reviews architectural and design consistency: - **Files**: System-level requirements, platform requirements, all design documents - **Purpose**: Ensures design completeness and architectural coherence -- **Example**: `SpdxModel-Design` +- **Example**: `MyProduct-Design` ## [Product]-AllRequirements Review @@ -69,7 +77,7 @@ Reviews requirements quality and traceability: - **Files**: All requirement files including root `requirements.yaml` - **Purpose**: Validates requirements structure, IDs, justifications, and test linkage -- **Example**: `SpdxModel-AllRequirements` +- **Example**: `MyProduct-AllRequirements` ## [Product]-[Unit] Review @@ -77,7 +85,7 @@ Reviews individual software unit implementation: - **Files**: Unit requirements, design documents, source code, unit tests - **Purpose**: Validates unit meets requirements and is properly implemented -- **Example**: `SpdxModel-SpdxDocument`, `SpdxModel-SpdxPackage` +- **Example**: `MyProduct-PasswordValidator`, `MyProduct-ConfigParser` ## [Product]-[Subsystem] Review @@ -85,7 +93,7 @@ Reviews subsystem architecture and interfaces: - **Files**: Subsystem requirements, design documents, integration tests (usually no source code) - **Purpose**: Validates subsystem behavior and interface compliance -- **Example**: `SpdxModel-IO`, `SpdxModel-Validation` +- **Example**: `MyProduct-Authentication`, `MyProduct-DataLayer` # ReviewMark Commands diff --git a/.github/standards/technical-documentation.md b/.github/standards/technical-documentation.md index 53c3aa7..f09ee83 100644 --- a/.github/standards/technical-documentation.md +++ b/.github/standards/technical-documentation.md @@ -25,18 +25,30 @@ consistency and tool compatibility: ```text docs/ build_notes.md # Generated by BuildMark - buildnotes/ # Auto-generated build notes + build_notes/ # Auto-generated build notes versions.md # Generated by VersionMark - guide/ # User-facing documentation - introduction.md # User guide overview - {section}.md # User guide sections - requirements/ # Auto-generated requirements reports + 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/ # Auto-generated justifications reports justifications.md # Generated by ReqStream - tracematrix/ # Auto-generated trace matrices - tracematrix.md # Generated by ReqStream - quality/ # Auto-generated quality reports + 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) @@ -110,9 +122,9 @@ for consistency and professional presentation: **NEVER modify auto-generated markdown files** because changes will be overwritten and break compliance automation: -- **Read-Only Files**: Generated reports under `docs/requirements/`, - `docs/justifications/`, `docs/tracematrix/`, and `docs/quality/` are - regenerated on every build +- **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 @@ -155,5 +167,6 @@ Before submitting technical documentation, verify: - [ ] Content follows clear and concise writing guidelines with specific examples - [ ] No modifications made to auto-generated markdown files in compliance folders - [ ] README.md includes all required sections with absolute URLs and concrete examples +- [ ] Documentation integrated into ReviewMark review-sets for formal review - [ ] Links validated and external references accessible - [ ] Content synchronized with current code implementation and requirements diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index 4bc4451..865b0a6 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -19,7 +19,7 @@ jobs: contents: read steps: # === INSTALL DEPENDENCIES === - # This section installs all required dependencies and tools for quality checks. + # This section installs all required dependencies for quality checks. # Downstream projects: Add any additional dependency installations here. - name: Checkout @@ -34,6 +34,16 @@ jobs: run: > dotnet tool restore + - name: Setup Node.js + uses: actions/setup-node@v6 + with: + node-version: 'lts/*' + + - name: Setup Python + uses: actions/setup-python@v6 + with: + python-version: '3.x' + # === CAPTURE TOOL VERSIONS === # This section captures the versions of all tools used in the build process. # Downstream projects: Add any additional tools to capture here. @@ -63,21 +73,9 @@ jobs: # This section runs the linting and quality checks for the project. # Downstream projects: Add any additional quality check steps here. - - name: Run markdown linter - uses: DavidAnson/markdownlint-cli2-action@v22 - with: - globs: '**/*.md' - - - name: Run spell checker - uses: streetsidesoftware/cspell-action@v8 - with: - files: '**/*.{md,cs}' - incremental_files_only: false - - - name: Run YAML linter - uses: ibiqlik/action-yamllint@v3 - with: - config_file: .yamllint.yaml + - name: Run linters + shell: bash + run: bash ./lint.sh # === UPLOAD ARTIFACTS === # This section uploads all generated artifacts for use by downstream jobs. @@ -356,7 +354,7 @@ jobs: echo "Capturing tool versions..." dotnet versionmark --capture --job-id "build-docs" \ --output "artifacts/versionmark-build-docs.json" -- \ - dotnet git node npm pandoc weasyprint sarifmark sonarmark reqstream buildmark versionmark + dotnet git node npm pandoc weasyprint sarifmark sonarmark reqstream buildmark versionmark reviewmark echo "✓ Tool versions captured" # === CAPTURE OTS SELF-VALIDATION RESULTS === @@ -394,6 +392,12 @@ jobs: --validate --results artifacts/sonarmark-self-validation.trx + - name: Run ReviewMark self-validation + run: > + dotnet reviewmark + --validate + --results artifacts/reviewmark-self-validation.trx + # === GENERATE MARKDOWN REPORTS === # This section generates all markdown reports from various tools and sources. # Downstream projects: Add any additional markdown report generation steps here. @@ -441,6 +445,28 @@ jobs: echo "=== SonarCloud Quality Report ===" cat docs/quality/sonar-quality.md + - name: Generate Review Plan and Review Report with ReviewMark + shell: bash + # TODO: Add --enforce once reviews branch is populated with review evidence PDFs and index.json + run: > + dotnet reviewmark + --plan docs/code_review_plan/plan.md + --plan-depth 1 + --report docs/code_review_report/report.md + --report-depth 1 + + - name: Display Review Plan + shell: bash + run: | + echo "=== Review Plan ===" + cat docs/code_review_plan/plan.md + + - name: Display Review Report + shell: bash + run: | + echo "=== Review Report ===" + cat docs/code_review_report/report.md + - name: Generate Build Notes with BuildMark shell: bash env: @@ -535,6 +561,26 @@ jobs: --metadata date="$(date +'%Y-%m-%d')" --output docs/tracematrix/tracematrix.html + - 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/code_review_report/definition.yaml + --filter node_modules/.bin/mermaid-filter.cmd + --metadata version="${{ inputs.version }}" + --metadata date="$(date +'%Y-%m-%d')" + --output docs/code_review_report/report.html + # === GENERATE PDF DOCUMENTS WITH WEASYPRINT === # This section converts HTML documents to PDF using Weasyprint. # Downstream projects: Add any additional Weasyprint PDF generation steps here. @@ -581,6 +627,20 @@ jobs: docs/tracematrix/tracematrix.html "docs/SpdxModel Trace Matrix.pdf" + - name: Generate Review Plan PDF with Weasyprint + run: > + dotnet weasyprint + --pdf-variant pdf/a-3u + docs/code_review_plan/plan.html + "docs/SpdxModel Review Plan.pdf" + + - name: Generate Review Report PDF with Weasyprint + run: > + dotnet weasyprint + --pdf-variant pdf/a-3u + docs/code_review_report/report.html + "docs/SpdxModel Review Report.pdf" + # === UPLOAD ARTIFACTS === # This section uploads all generated documentation artifacts. # Downstream projects: Add any additional artifact uploads here. diff --git a/lint.bat b/lint.bat index 1fa5972..5d9c0f5 100644 --- a/lint.bat +++ b/lint.bat @@ -22,7 +22,7 @@ call .venv\Scripts\activate.bat pip install -r pip-requirements.txt --quiet --disable-pip-version-check REM Run spell check -call npx cspell --no-progress --no-color --quiet "**/*.{md,yaml,yml,json,cs,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 b778299..0e8dfc8 100755 --- a/lint.sh +++ b/lint.sh @@ -21,7 +21,7 @@ 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,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 From 168cd4127b24f8f8fc2d8b91ed7916cf03e6b925 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 31 Mar 2026 01:27:18 +0000 Subject: [PATCH 09/15] Apply TemplateDotNetTool PR#65 docs folder renames and add review docs Agent-Logs-Url: https://github.com/demaconsulting/SpdxModel/sessions/ed2c444d-6168-4016-9a7f-8a76c680b17f Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --- .cspell.yaml | 1 - .github/workflows/build.yaml | 65 +++++++------------ .github/workflows/release.yaml | 6 +- .gitignore | 14 ++-- docs/build_notes/definition.yaml | 12 ++++ .../introduction.md | 0 docs/{buildnotes => build_notes}/title.txt | 0 docs/buildnotes/definition.yaml | 16 ----- 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 | 33 ++++++++++ docs/code_review_report/title.txt | 13 ++++ docs/justifications/definition.yaml | 15 ----- docs/justifications/introduction.md | 30 --------- docs/justifications/title.txt | 16 ----- docs/quality/definition.yaml | 16 ----- docs/requirements/definition.yaml | 15 ----- 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 | 15 ----- 29 files changed, 195 insertions(+), 175 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/.cspell.yaml b/.cspell.yaml index 5ee6003..6708ed2 100644 --- a/.cspell.yaml +++ b/.cspell.yaml @@ -22,7 +22,6 @@ words: - buildmark - BuildMark - build_notes - - buildnotes - camelcase - Checkmarx - CodeQL diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index 865b0a6..f931b6a 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -407,16 +407,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 "SpdxModel CodeQL Analysis" --report-depth 1 @@ -424,7 +424,7 @@ jobs: shell: bash run: | echo "=== CodeQL Quality Report ===" - cat docs/quality/codeql-quality.md + cat docs/code_quality/codeql-quality.md - name: Generate SonarCloud Quality Report shell: bash @@ -436,14 +436,14 @@ jobs: --project-key demaconsulting_SpdxModel --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 @@ -474,20 +474,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" @@ -495,7 +495,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. @@ -505,11 +505,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 User Guide HTML with Pandoc shell: bash @@ -525,41 +525,31 @@ jobs: shell: bash run: > dotnet pandoc - --defaults docs/quality/definition.yaml + --defaults docs/code_quality/definition.yaml --filter node_modules/.bin/mermaid-filter.cmd --metadata version="${{ inputs.version }}" --metadata date="$(date +'%Y-%m-%d')" - --output docs/quality/quality.html + --output docs/code_quality/quality.html - name: Generate Requirements HTML with Pandoc shell: bash run: > dotnet pandoc - --defaults docs/requirements/definition.yaml + --defaults docs/requirements_doc/definition.yaml --filter node_modules/.bin/mermaid-filter.cmd --metadata version="${{ inputs.version }}" --metadata date="$(date +'%Y-%m-%d')" - --output docs/requirements/requirements.html - - - name: Generate Requirements Justifications HTML with Pandoc - shell: bash - run: > - dotnet pandoc - --defaults docs/justifications/definition.yaml - --filter node_modules/.bin/mermaid-filter.cmd - --metadata version="${{ inputs.version }}" - --metadata date="$(date +'%Y-%m-%d')" - --output docs/justifications/justifications.html + --output docs/requirements_doc/requirements.html - name: Generate Trace Matrix HTML with Pandoc shell: bash run: > dotnet pandoc - --defaults docs/tracematrix/definition.yaml + --defaults docs/requirements_report/definition.yaml --filter node_modules/.bin/mermaid-filter.cmd --metadata version="${{ inputs.version }}" --metadata date="$(date +'%Y-%m-%d')" - --output docs/tracematrix/tracematrix.html + --output docs/requirements_report/trace_matrix.html - name: Generate Review Plan HTML with Pandoc shell: bash @@ -589,7 +579,7 @@ jobs: run: > dotnet weasyprint --pdf-variant pdf/a-3u - docs/buildnotes/buildnotes.html + docs/build_notes/buildnotes.html "docs/SpdxModel Build Notes.pdf" - name: Generate User Guide PDF with Weasyprint @@ -603,28 +593,21 @@ jobs: run: > dotnet weasyprint --pdf-variant pdf/a-3u - docs/quality/quality.html + docs/code_quality/quality.html "docs/SpdxModel 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/SpdxModel Requirements.pdf" - - name: Generate Justifications PDF with Weasyprint - run: > - dotnet weasyprint - --pdf-variant pdf/a-3u - docs/justifications/justifications.html - "docs/SpdxModel Requirements Justifications.pdf" - - name: Generate Trace Matrix PDF with Weasyprint run: > dotnet weasyprint --pdf-variant pdf/a-3u - docs/tracematrix/tracematrix.html + docs/requirements_report/trace_matrix.html "docs/SpdxModel Trace Matrix.pdf" - name: Generate Review Plan PDF with Weasyprint @@ -651,4 +634,4 @@ jobs: name: documents path: | docs/*.pdf - docs/buildnotes.md + docs/build_notes.md diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index d3cb7ab..7f3d9e7 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -64,10 +64,10 @@ jobs: name: documents path: artifacts - - name: Move buildnotes.md to root + - name: Move build_notes.md to root run: | set -e - mv artifacts/buildnotes.md buildnotes.md + mv artifacts/build_notes.md build_notes.md - name: Create GitHub Release if: inputs.publish == 'release' || inputs.publish == 'publish' @@ -75,7 +75,7 @@ jobs: with: tag: ${{ inputs.version }} artifacts: artifacts/* - bodyFile: buildnotes.md + bodyFile: build_notes.md generateReleaseNotes: false - name: Publish to NuGet.org diff --git a/.gitignore b/.gitignore index 95e4bdd..8a718cd 100644 --- a/.gitignore +++ b/.gitignore @@ -91,13 +91,13 @@ __pycache__/ docs/**/*.html docs/**/*.pdf !docs/template/** -docs/requirements/requirements.md -docs/justifications/justifications.md -docs/tracematrix/tracematrix.md -docs/quality/codeql-quality.md -docs/quality/sonar-quality.md -docs/buildnotes.md -docs/buildnotes/versions.md +docs/requirements_doc/requirements.md +docs/requirements_doc/justifications.md +docs/requirements_report/trace_matrix.md +docs/code_quality/codeql-quality.md +docs/code_quality/sonar-quality.md +docs/build_notes.md +docs/build_notes/versions.md docs/code_review_plan/plan.md docs/code_review_report/report.md 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 7eb0c4c..0000000 --- a/docs/buildnotes/definition.yaml +++ /dev/null @@ -1,16 +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..2cfb085 --- /dev/null +++ b/docs/code_review_plan/introduction.md @@ -0,0 +1,33 @@ +# Introduction + +This document contains the review plan for the SpdxModel project. + +## Purpose + +This review plan provides a comprehensive overview of all files requiring formal review +in the SpdxModel 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 SpdxModel +- 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..227b7ca --- /dev/null +++ b/docs/code_review_plan/title.txt @@ -0,0 +1,13 @@ +--- +title: SpdxModel Review Plan +subtitle: File Review Plan for the SpdxModel Library +author: DEMA Consulting +description: File Review Plan for the SpdxModel Library +lang: en-US +keywords: + - SpdxModel + - Review Plan + - File Reviews + - .NET + - Library +--- 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..e834541 --- /dev/null +++ b/docs/code_review_report/introduction.md @@ -0,0 +1,33 @@ +# Introduction + +This document contains the review report for the SpdxModel 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 SpdxModel 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 SpdxModel +- 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..029a5d6 --- /dev/null +++ b/docs/code_review_report/title.txt @@ -0,0 +1,13 @@ +--- +title: SpdxModel Review Report +subtitle: File Review Report for the SpdxModel Library +author: DEMA Consulting +description: File Review Report for the SpdxModel Library +lang: en-US +keywords: + - SpdxModel + - Review Report + - File Reviews + - .NET + - Library +--- diff --git a/docs/justifications/definition.yaml b/docs/justifications/definition.yaml deleted file mode 100644 index f197d59..0000000 --- a/docs/justifications/definition.yaml +++ /dev/null @@ -1,15 +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 93a2bd3..0000000 --- a/docs/justifications/introduction.md +++ /dev/null @@ -1,30 +0,0 @@ -# Introduction - -This document provides justifications for the requirements of the SpdxModel library, explaining -the rationale and purpose behind each requirement. - -## Purpose - -The purpose of this document is to: - -- Document the rationale behind each requirement -- Explain why each requirement exists and its importance -- Support stakeholder understanding of project scope and design decisions -- Provide context for compliance and audit activities - -## Scope - -This justifications document covers: - -- All functional requirements for SPDX element support -- Quality requirements for platform and API design -- The reasoning behind requirement priorities and scope - -## How to Read This Document - -Each requirement is presented with: - -- **Requirement ID**: Unique identifier for the requirement -- **Requirement Title**: Brief description of what the requirement mandates -- **Justification**: Detailed explanation of why the requirement exists, its importance, - and how it contributes to the library's overall purpose diff --git a/docs/justifications/title.txt b/docs/justifications/title.txt deleted file mode 100644 index db0cbbe..0000000 --- a/docs/justifications/title.txt +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: SpdxModel Library -subtitle: Requirements Justifications -author: DEMA Consulting -description: Requirements justifications for the SpdxModel C# library documenting the rationale behind each requirement -lang: en-US -keywords: - - SpdxModel - - Requirements - - Justifications - - C# - - .NET - - SPDX - - SBOM - - Software Bill of Materials ---- diff --git a/docs/quality/definition.yaml b/docs/quality/definition.yaml deleted file mode 100644 index 65420a4..0000000 --- a/docs/quality/definition.yaml +++ /dev/null @@ -1,16 +0,0 @@ ---- -resource-path: - - docs/quality - - docs/template - -input-files: - - docs/quality/title.txt - - docs/quality/introduction.md - - docs/quality/codeql-quality.md - - docs/quality/sonar-quality.md - -template: template.html - -table-of-contents: true - -number-sections: true diff --git a/docs/requirements/definition.yaml b/docs/requirements/definition.yaml deleted file mode 100644 index 8f22e65..0000000 --- a/docs/requirements/definition.yaml +++ /dev/null @@ -1,15 +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 98c8447..0000000 --- a/docs/tracematrix/definition.yaml +++ /dev/null @@ -1,15 +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 From 2546d7e04a32bf2b643187a3dcfc744b687c4410 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 31 Mar 2026 01:29:16 +0000 Subject: [PATCH 10/15] Fix release.yaml: use build_notes.md directly from artifacts (no copy step) Agent-Logs-Url: https://github.com/demaconsulting/SpdxModel/sessions/0a4e2a39-989c-4bea-8157-86cb41c62ebc Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --- .github/workflows/release.yaml | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index 7f3d9e7..fe3fb50 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -64,18 +64,13 @@ jobs: name: documents path: artifacts - - name: Move build_notes.md to root - run: | - set -e - mv artifacts/build_notes.md build_notes.md - - name: Create GitHub Release if: inputs.publish == 'release' || inputs.publish == 'publish' uses: ncipollo/release-action@v1 with: tag: ${{ inputs.version }} artifacts: artifacts/* - bodyFile: build_notes.md + bodyFile: artifacts/build_notes.md generateReleaseNotes: false - name: Publish to NuGet.org From e9c5603a1660a679b52505b03b02f5d843c4ef3c Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 31 Mar 2026 01:38:48 +0000 Subject: [PATCH 11/15] Fix .versionmark.yaml: add reviewmark entry and update regex patterns for pre-release versions Agent-Logs-Url: https://github.com/demaconsulting/SpdxModel/sessions/00a82df9-1511-4ecf-bc8a-9d77fd87b7e0 Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --- .versionmark.yaml | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/.versionmark.yaml b/.versionmark.yaml index b8bf259..6fa4e84 100644 --- a/.versionmark.yaml +++ b/.versionmark.yaml @@ -26,39 +26,44 @@ tools: # SonarScanner for .NET (from dotnet tool list) dotnet-sonarscanner: command: dotnet tool list - regex: '(?i)dotnet-sonarscanner\s+(?\d+\.\d+\.\d+)' + regex: '(?i)dotnet-sonarscanner\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)' # Pandoc (DemaConsulting.PandocTool from dotnet tool list) pandoc: command: dotnet tool list - regex: '(?i)demaconsulting\.pandoctool\s+(?\d+\.\d+\.\d+)' + regex: '(?i)demaconsulting\.pandoctool\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)' # WeasyPrint (DemaConsulting.WeasyPrintTool from dotnet tool list) weasyprint: command: dotnet tool list - regex: '(?i)demaconsulting\.weasyprinttool\s+(?\d+\.\d+\.\d+)' + regex: '(?i)demaconsulting\.weasyprinttool\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)' # SarifMark (DemaConsulting.SarifMark from dotnet tool list) sarifmark: command: dotnet tool list - regex: '(?i)demaconsulting\.sarifmark\s+(?\d+\.\d+\.\d+)' + regex: '(?i)demaconsulting\.sarifmark\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)' # SonarMark (DemaConsulting.SonarMark from dotnet tool list) sonarmark: command: dotnet tool list - regex: '(?i)demaconsulting\.sonarmark\s+(?\d+\.\d+\.\d+)' + regex: '(?i)demaconsulting\.sonarmark\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)' # ReqStream (DemaConsulting.ReqStream from dotnet tool list) reqstream: command: dotnet tool list - regex: '(?i)demaconsulting\.reqstream\s+(?\d+\.\d+\.\d+)' + regex: '(?i)demaconsulting\.reqstream\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)' # BuildMark (DemaConsulting.BuildMark from dotnet tool list) buildmark: command: dotnet tool list - regex: '(?i)demaconsulting\.buildmark\s+(?\d+\.\d+\.\d+)' + regex: '(?i)demaconsulting\.buildmark\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)' # VersionMark (DemaConsulting.VersionMark from dotnet tool list) versionmark: command: dotnet tool list - regex: '(?i)demaconsulting\.versionmark\s+(?\d+\.\d+\.\d+)' + regex: '(?i)demaconsulting\.versionmark\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)' + + # ReviewMark (DemaConsulting.ReviewMark from dotnet tool list) + reviewmark: + command: dotnet tool list + regex: '(?i)demaconsulting\.reviewmark\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)' From bcf0813519c1ef7e688bfc4c8edaee703eb9dc79 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 31 Mar 2026 01:45:14 +0000 Subject: [PATCH 12/15] Rename docs/guide to docs/user_guide and guide.md to introduction.md Agent-Logs-Url: https://github.com/demaconsulting/SpdxModel/sessions/ccd865f3-57d0-4c62-a172-bd9121c86dd2 Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --- .github/workflows/build.yaml | 6 +++--- docs/{guide => user_guide}/definition.yaml | 6 +++--- docs/{guide/guide.md => user_guide/introduction.md} | 0 docs/{guide => user_guide}/title.txt | 0 4 files changed, 6 insertions(+), 6 deletions(-) rename docs/{guide => user_guide}/definition.yaml (59%) rename docs/{guide/guide.md => user_guide/introduction.md} (100%) rename docs/{guide => user_guide}/title.txt (100%) diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index f931b6a..64e7b44 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -515,11 +515,11 @@ jobs: shell: bash run: > dotnet pandoc - --defaults docs/guide/definition.yaml + --defaults docs/user_guide/definition.yaml --filter node_modules/.bin/mermaid-filter.cmd --metadata version="${{ inputs.version }}" --metadata date="$(date +'%Y-%m-%d')" - --output docs/guide/guide.html + --output docs/user_guide/introduction.html - name: Generate Code Quality HTML with Pandoc shell: bash @@ -586,7 +586,7 @@ jobs: run: > dotnet weasyprint --pdf-variant pdf/a-3u - docs/guide/guide.html + docs/user_guide/introduction.html "docs/SpdxModel User Guide.pdf" - name: Generate Code Quality PDF with Weasyprint diff --git a/docs/guide/definition.yaml b/docs/user_guide/definition.yaml similarity index 59% rename from docs/guide/definition.yaml rename to docs/user_guide/definition.yaml index 07533af..3a61568 100644 --- a/docs/guide/definition.yaml +++ b/docs/user_guide/definition.yaml @@ -1,11 +1,11 @@ --- resource-path: - - docs/guide + - docs/user_guide - docs/template input-files: - - docs/guide/title.txt - - docs/guide/guide.md + - docs/user_guide/title.txt + - docs/user_guide/introduction.md template: template.html diff --git a/docs/guide/guide.md b/docs/user_guide/introduction.md similarity index 100% rename from docs/guide/guide.md rename to docs/user_guide/introduction.md diff --git a/docs/guide/title.txt b/docs/user_guide/title.txt similarity index 100% rename from docs/guide/title.txt rename to docs/user_guide/title.txt From d5d20dfae95ae1b49e2bc645c9c8b3901ba093ab Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 31 Mar 2026 01:47:17 +0000 Subject: [PATCH 13/15] Add cspell and markdownlint-cli2 as pinned devDependencies in package.json Agent-Logs-Url: https://github.com/demaconsulting/SpdxModel/sessions/242e437d-e0b1-4f6d-80df-d13fd8792631 Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --- package.json | 2 ++ 1 file changed, 2 insertions(+) diff --git a/package.json b/package.json index 9487fa5..a57dc1f 100644 --- a/package.json +++ b/package.json @@ -2,6 +2,8 @@ "private": true, "devDependencies": { "@mermaid-js/mermaid-cli": "11.12.0", + "cspell": "9.7.0", + "markdownlint-cli2": "0.21.0", "mermaid-filter": "1.4.7" } } From 30f5f9a1b461299df0b2f390bd502c1d75b79a86 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 31 Mar 2026 02:00:22 +0000 Subject: [PATCH 14/15] Update .config/dotnet-tools.json to match TemplateDotNetTool (add reviewmark, bump versions) Agent-Logs-Url: https://github.com/demaconsulting/SpdxModel/sessions/516a18d7-9901-407d-b7e0-2405cc41aa9e Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --- .config/dotnet-tools.json | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json index 8019fdb..cc121c5 100644 --- a/.config/dotnet-tools.json +++ b/.config/dotnet-tools.json @@ -9,7 +9,7 @@ ] }, "demaconsulting.pandoctool": { - "version": "3.9.0", + "version": "3.9.0.2", "commands": [ "pandoc" ] @@ -20,35 +20,41 @@ "weasyprint" ] }, - "demaconsulting.sonarmark": { + "demaconsulting.sarifmark": { "version": "1.2.0", "commands": [ - "sonarmark" + "sarifmark" ] }, - "demaconsulting.sarifmark": { - "version": "1.2.0", + "demaconsulting.sonarmark": { + "version": "1.3.0", "commands": [ - "sarifmark" + "sonarmark" ] }, "demaconsulting.reqstream": { - "version": "1.4.1", + "version": "1.5.0", "commands": [ "reqstream" ] }, "demaconsulting.buildmark": { - "version": "0.4.0", + "version": "0.4.1", "commands": [ "buildmark" ] }, "demaconsulting.versionmark": { - "version": "1.0.0", + "version": "1.1.0", "commands": [ "versionmark" ] + }, + "demaconsulting.reviewmark": { + "version": "0.2.0", + "commands": [ + "reviewmark" + ] } } } \ No newline at end of file From 76f3832a141c5e5fc0da21793e309f3c92a86c2b Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 31 Mar 2026 02:10:44 +0000 Subject: [PATCH 15/15] Add basic .reviewmark.yaml for SpdxModel Agent-Logs-Url: https://github.com/demaconsulting/SpdxModel/sessions/6f1d2f66-65ae-4449-895e-41a6fde5eebb Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --- .reviewmark.yaml | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 .reviewmark.yaml diff --git a/.reviewmark.yaml b/.reviewmark.yaml new file mode 100644 index 0000000..31bb85a --- /dev/null +++ b/.reviewmark.yaml @@ -0,0 +1,24 @@ +--- +# 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 + - "!**/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/SpdxModel/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: []