From 052669ff767ec139c37d39802697effb0f6e87a2 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 24 Mar 2026 13:18:09 +0000 Subject: [PATCH 1/4] Initial plan From c4bdd5f7e86831c4939ae3ff24a9797fcfcb5777 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 24 Mar 2026 13:29:08 +0000 Subject: [PATCH 2/4] Update repo-consistency agent to latest template version Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> Agent-Logs-Url: https://github.com/demaconsulting/VersionMark/sessions/58f62a5f-de80-44aa-a3ba-9f17084cf2ba --- .github/agents/repo-consistency-agent.md | 150 ----------------------- .github/agents/repo-consistency.agent.md | 39 ++++++ 2 files changed, 39 insertions(+), 150 deletions(-) delete mode 100644 .github/agents/repo-consistency-agent.md create mode 100644 .github/agents/repo-consistency.agent.md diff --git a/.github/agents/repo-consistency-agent.md b/.github/agents/repo-consistency-agent.md deleted file mode 100644 index 3f289af..0000000 --- a/.github/agents/repo-consistency-agent.md +++ /dev/null @@ -1,150 +0,0 @@ ---- -name: Repo Consistency Agent -description: Ensures downstream repositories remain consistent with the TemplateDotNetTool template patterns and best practices ---- - -# Repo Consistency Agent - Template DotNet Tool - -Maintain consistency between downstream projects and the TemplateDotNetTool template at . - -## When to Invoke This Agent - -Invoke the repo-consistency-agent for: - -- Periodic reviews of downstream repositories based on this template -- Checking if downstream projects follow the latest template patterns -- Identifying drift from template standards -- Recommending updates to bring projects back in sync with template - -**Note**: This agent should NOT be invoked for the TemplateDotNetTool repository itself (), -as that would try to ensure the repository is consistent with itself (implicitly a no-op). - -## Responsibilities - -### Consistency Checks - -The agent reviews the following areas for consistency with the template: - -#### GitHub Configuration - -- **Issue Templates**: `.github/ISSUE_TEMPLATE/` files (bug_report.yml, feature_request.yml, config.yml) -- **Pull Request Template**: `.github/pull_request_template.md` -- **Workflow Patterns**: General structure of `.github/workflows/` (build.yaml, build_on_push.yaml, release.yaml) - - Note: Some projects may need workflow deviations for specific requirements - -#### Agent Configuration - -- **Agent Definitions**: `.github/agents/` directory structure -- **Agent Documentation**: `AGENTS.md` file listing available agents - -#### Code Structure and Patterns - -- **Context Parsing**: `Context.cs` pattern for command-line argument handling -- **Self-Validation**: `Validation.cs` pattern for built-in tests -- **Program Entry**: `Program.cs` pattern with version/help/validation routing -- **Standard Arguments**: Support for `-v`, `--version`, `-?`, `-h`, `--help`, `--silent`, `--validate`, `--results`, `--log` - -#### Documentation - -- **README Structure**: Follows template README.md pattern (badges, features, installation, - usage, structure, CI/CD, documentation, license) -- **Standard Files**: Presence and structure of: - - `CONTRIBUTING.md` - - `CODE_OF_CONDUCT.md` - - `SECURITY.md` - - `LICENSE` - -#### Quality Configuration - -- **Linting Rules**: `.cspell.json`, `.markdownlint-cli2.jsonc`, `.yamllint.yaml` - - Note: Spelling exceptions will be repository-specific -- **Editor Config**: `.editorconfig` settings (file-scoped namespaces, 4-space indent, UTF-8+BOM, LF endings) -- **Code Style**: C# code style rules and analyzer configuration - -#### Project Configuration - -- **csproj Sections**: Key sections in .csproj files: - - NuGet Tool Package Configuration - - Symbol Package Configuration - - Code Quality Configuration (TreatWarningsAsErrors, GenerateDocumentationFile, etc.) - - SBOM Configuration - - Common package references (DemaConsulting.TestResults, Microsoft.SourceLink.GitHub, analyzers) - -#### Documentation Generation - -- **Document Structure**: `docs/` directory with: - - `guide/` (user guide) - - `requirements/` (auto-generated) - - `justifications/` (auto-generated) - - `tracematrix/` (auto-generated) - - `buildnotes/` (auto-generated) - - `quality/` (auto-generated) -- **Definition Files**: `definition.yaml` files for document generation - -### Tracking Template Evolution - -To ensure downstream projects benefit from recent template improvements, review recent pull requests -merged into the template repository: - -1. **List Recent PRs**: Retrieve recently merged PRs from `demaconsulting/TemplateDotNetTool` - - Review the last 10-20 PRs to identify template improvements - -2. **Identify Propagatable Changes**: For each PR, determine if changes should apply to downstream - projects: - - Focus on structural changes (workflows, agents, configurations) over content-specific changes - - Note changes to `.github/`, linting configurations, project patterns, and documentation - structure - -3. **Check Downstream Application**: Verify if identified changes exist in the downstream project: - - Check if similar files/patterns exist in downstream - - Compare file contents between template and downstream project - - Look for similar PR titles or commit messages in downstream repository history - -4. **Recommend Missing Updates**: For changes not yet applied, include them in the consistency - review with: - - Description of the template change (reference PR number) - - Explanation of benefits for the downstream project - - Specific files or patterns that need updating - -This technique ensures downstream projects don't miss important template improvements and helps -maintain long-term consistency. - -### Review Process - -1. **Identify Differences**: Compare downstream repository structure with template -2. **Assess Impact**: Determine if differences are intentional variations or drift -3. **Recommend Updates**: Suggest specific files or patterns that should be updated -4. **Respect Customizations**: Recognize valid project-specific customizations - -### What NOT to Flag - -- Project-specific naming (tool names, package IDs, repository URLs) -- Project-specific spell check exceptions in `.cspell.json` -- Workflow variations for specific project needs -- Additional requirements or features beyond the template -- Project-specific dependencies - -## Defer To - -- **Software Developer Agent**: For implementing code changes recommended by consistency check -- **Technical Writer Agent**: For updating documentation to match template -- **Requirements Agent**: For updating requirements.yaml -- **Test Developer Agent**: For updating test patterns -- **Code Quality Agent**: For applying linting and code style changes - -## Usage Pattern - -This agent is typically invoked on downstream repositories (not on TemplateDotNetTool itself): - -1. Clone or access the downstream repository -2. Invoke repo-consistency-agent to review consistency with the TemplateDotNetTool template () -3. Review agent recommendations -4. Apply relevant changes using appropriate specialized agents -5. Test changes to ensure they don't break existing functionality - -## Key Principles - -- **Template Evolution**: As the template evolves, this agent helps downstream projects stay current -- **Respect Customization**: Not all differences are problems - some are valid customizations -- **Incremental Adoption**: Downstream projects can adopt template changes incrementally -- **Documentation**: When recommending changes, explain why they align with best practices diff --git a/.github/agents/repo-consistency.agent.md b/.github/agents/repo-consistency.agent.md new file mode 100644 index 0000000..8591e2f --- /dev/null +++ b/.github/agents/repo-consistency.agent.md @@ -0,0 +1,39 @@ +--- +name: repo-consistency +description: Ensures downstream repositories remain consistent with the TemplateDotNetTool template patterns and best practices. +tools: [read, search, edit, execute, github, agent] +user-invocable: true +--- + +# Repo Consistency Agent + +Maintain consistency between downstream projects and the TemplateDotNetTool template, ensuring repositories +benefit from template evolution while respecting project-specific customizations. + +## Reporting + +If detailed documentation of consistency analysis is needed, create a report using the filename pattern +`AGENT_REPORT_consistency_[repo_name].md` (e.g., `AGENT_REPORT_consistency_MyTool.md`) to document +consistency gaps, template evolution updates, and recommended changes for the specific repository. + +## Consistency Steps + +1. Fetch the 20 most recently merged PRs (`is:pr is:merged sort:updated-desc`) from +2. Determine the intent of the template pull requests (what changes were performed to which files) +3. Apply missing changes to this repository's files (if appropriate and with translation) + +## 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) + +## Key Principles + +- **Evolutionary Consistency**: Template improvements should enhance downstream projects systematically +- **Intelligent Customization Respect**: Distinguished valid customizations from unintentional drift +- **Incremental Template Adoption**: Support phased adoption of template improvements based on project capacity From 033223f2033113c5ec9fb4160e949ad609e5ca48 Mon Sep 17 00:00:00 2001 From: Copilot Date: Tue, 24 Mar 2026 13:39:37 +0000 Subject: [PATCH 3/4] Apply template consistency changes from TemplateDotNetTool PRs #55-#74 - Add .gitattributes to enforce LF line endings for consistent reviewmark fingerprints (PR #71) - Convert .cspell.json to .cspell.yaml format with updated ignorePaths and word list policy comments (PRs #61, #63, #64, #65) - Convert .markdownlint-cli2.jsonc to .markdownlint-cli2.yaml format with updated ignores including thirdparty paths (PRs #61, #64) - Update .yamllint.yaml with improved header comments and thirdparty paths in ignore section (PR #64) - Rename agent files from *-agent.md to *.agent.md convention (PR #61) - Update agent frontmatter: add tools field and user-invocable: true, update name and description to match template (PRs #61, #73) - Update AGENTS.md: add spell check word list policy section (PR #63) - Update CONTRIBUTING.md: update spell check section with policy (PR #63) - Rename docs directories to match template naming convention (PR #65, #67): buildnotes -> build_notes, quality -> code_quality, requirements -> requirements_doc, justifications -> removed (merged into requirements_doc), tracematrix -> requirements_report, reviewplan -> code_review_plan, reviewreport -> code_review_report - Update definition.yaml files in all renamed docs directories - Update build.yaml to use new docs directory paths and remove separate justifications document generation (now merged into requirements_doc) - Update release.yaml for renamed build_notes.md - Update requirements.yaml comment to reference new docs paths --- .cspell.json | 91 ---------------- .cspell.yaml | 103 ++++++++++++++++++ .gitattributes | 7 ++ ...quality-agent.md => code-quality.agent.md} | 6 +- ...e-review-agent.md => code-review.agent.md} | 6 +- ...rements-agent.md => requirements.agent.md} | 6 +- ...veloper.md => software-developer.agent.md} | 6 +- ...al-writer.md => technical-writer.agent.md} | 6 +- ...t-developer.md => test-developer.agent.md} | 6 +- .github/workflows/build.yaml | 85 ++++++--------- .github/workflows/release.yaml | 4 +- .markdownlint-cli2.jsonc | 15 --- .markdownlint-cli2.yaml | 47 ++++++++ .yamllint.yaml | 22 +++- AGENTS.md | 12 +- CONTRIBUTING.md | 14 +-- docs/build_notes/definition.yaml | 12 ++ .../introduction.md | 0 docs/{buildnotes => build_notes}/title.txt | 0 docs/buildnotes/definition.yaml | 12 -- docs/code_quality/definition.yaml | 12 ++ .../{quality => code_quality}/introduction.md | 0 docs/{quality => code_quality}/title.txt | 0 docs/code_review_plan/definition.yaml | 11 ++ .../introduction.md | 0 .../title.txt | 0 docs/code_review_report/definition.yaml | 11 ++ .../introduction.md | 0 .../title.txt | 0 docs/justifications/definition.yaml | 11 -- docs/justifications/introduction.md | 29 ----- docs/justifications/title.txt | 13 --- docs/quality/definition.yaml | 12 -- docs/requirements/definition.yaml | 11 -- docs/requirements_doc/definition.yaml | 12 ++ .../introduction.md | 0 .../title.txt | 0 docs/requirements_report/definition.yaml | 11 ++ .../introduction.md | 0 .../title.txt | 0 docs/reviewplan/definition.yaml | 11 -- docs/reviewreport/definition.yaml | 11 -- docs/tracematrix/definition.yaml | 11 -- requirements.yaml | 2 +- 44 files changed, 324 insertions(+), 304 deletions(-) delete mode 100644 .cspell.json create mode 100644 .cspell.yaml create mode 100644 .gitattributes rename .github/agents/{code-quality-agent.md => code-quality.agent.md} (93%) rename .github/agents/{code-review-agent.md => code-review.agent.md} (93%) rename .github/agents/{requirements-agent.md => requirements.agent.md} (96%) rename .github/agents/{software-developer.md => software-developer.agent.md} (93%) rename .github/agents/{technical-writer.md => technical-writer.agent.md} (93%) rename .github/agents/{test-developer.md => test-developer.agent.md} (97%) delete mode 100644 .markdownlint-cli2.jsonc create mode 100644 .markdownlint-cli2.yaml 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 rename docs/{reviewplan => code_review_plan}/introduction.md (100%) rename docs/{reviewplan => code_review_plan}/title.txt (100%) create mode 100644 docs/code_review_report/definition.yaml rename docs/{reviewreport => code_review_report}/introduction.md (100%) rename docs/{reviewreport => code_review_report}/title.txt (100%) 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/reviewplan/definition.yaml delete mode 100644 docs/reviewreport/definition.yaml delete mode 100644 docs/tracematrix/definition.yaml diff --git a/.cspell.json b/.cspell.json deleted file mode 100644 index 2323c45..0000000 --- a/.cspell.json +++ /dev/null @@ -1,91 +0,0 @@ -{ - "version": "0.2", - "language": "en", - "words": [ - "Anson", - "Blockquotes", - "buildmark", - "BuildMark", - "buildnotes", - "camelcase", - "Checkmarx", - "CodeQL", - "copilot", - "cspell", - "csproj", - "dbproj", - "dcterms", - "Dema", - "demaconsulting", - "DEMACONSULTINGNUGETKEY", - "Dependabot", - "dependabot", - "doctitle", - "dotnet", - "editorconfig", - "filepart", - "fsproj", - "Gidget", - "gitattributes", - "ibiqlik", - "LINQ", - "maintainer", - "markdownlint", - "mermaid", - "msbuild", - "mstest", - "myterm", - "ncipollo", - "nuget", - "nupkg", - "opencover", - "pagetitle", - "pandoc", - "Pylint", - "Qube", - "reqstream", - "ReqStream", - "reviewmark", - "ReviewMark", - "Sarif", - "SarifMark", - "SBOM", - "Semgrep", - "semver", - "slnx", - "snupkg", - "sonarmark", - "SonarMark", - "SonarQube", - "spdx", - "streetsidesoftware", - "versionmark", - "testname", - "TMPL", - "tracematrix", - "triaging", - "Trivy", - "trx", - "vbproj", - "vcxproj", - "versionmark", - "VersionMark", - "Weasyprint", - "yamllint" - ], - "ignorePaths": [ - "node_modules", - ".git", - "bin", - "obj", - "*.nupkg", - "*.snupkg", - "*.dll", - "*.exe", - "*.trx", - "*.spdx.json", - "package-lock.json", - "yarn.lock", - "AGENT_REPORT_*.md" - ] -} diff --git a/.cspell.yaml b/.cspell.yaml new file mode 100644 index 0000000..d41635b --- /dev/null +++ b/.cspell.yaml @@ -0,0 +1,103 @@ +--- +# Spell-Checking +# +# PURPOSE: +# - Maintain professional documentation and code quality +# - Catch spelling errors before publication +# - Support consistent technical terminology usage +# - Misspelled words should be fixed in the source +# - NEVER add a misspelled word to the 'words' list +# - PROPOSE only genuine technical terms/names as needed + +version: "0.2" +language: en + +# Project-specific technical terms and tool names +words: + - Anson + - Blockquotes + - buildmark + - BuildMark + - build_notes + - camelcase + - Checkmarx + - CodeQL + - code_quality + - code_review_plan + - code_review_report + - copilot + - cspell + - csproj + - dbproj + - dcterms + - Dema + - demaconsulting + - DEMACONSULTINGNUGETKEY + - Dependabot + - dependabot + - doctitle + - dotnet + - editorconfig + - filepart + - fsproj + - Gidget + - gitattributes + - ibiqlik + - LINQ + - maintainer + - markdownlint + - mermaid + - msbuild + - mstest + - ncipollo + - nuget + - nupkg + - opencover + - pagetitle + - pandoc + - Propagatable + - Pylint + - Qube + - reqstream + - ReqStream + - requirements_doc + - requirements_report + - reviewmark + - ReviewMark + - Sarif + - SarifMark + - SBOM + - Semgrep + - semver + - slnx + - snupkg + - sonarmark + - SonarMark + - SonarQube + - spdx + - streetsidesoftware + - testname + - TMPL + - trace_matrix + - triaging + - Trivy + - trx + - vbproj + - vcxproj + - versionmark + - VersionMark + - Weasyprint + - yamllint + +# Exclude common build artifacts, dependencies, and vendored third-party code +ignorePaths: + - "**/.git/**" + - "**/node_modules/**" + - "**/.venv/**" + - "**/thirdparty/**" + - "**/third-party/**" + - "**/3rd-party/**" + - "**/AGENT_REPORT_*.md" + - "**/bin/**" + - "**/obj/**" + - package-lock.json diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..2f09872 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,7 @@ +# Set default behavior: normalize line endings to LF on checkout for all text files. +# This ensures consistent SHA256 fingerprints for reviewmark across all platforms. +* text=auto eol=lf + +# Windows batch files require CRLF line endings to function correctly. +*.bat text eol=crlf +*.cmd text eol=crlf diff --git a/.github/agents/code-quality-agent.md b/.github/agents/code-quality.agent.md similarity index 93% rename from .github/agents/code-quality-agent.md rename to .github/agents/code-quality.agent.md index 263cfe1..f21459f 100644 --- a/.github/agents/code-quality-agent.md +++ b/.github/agents/code-quality.agent.md @@ -1,6 +1,8 @@ --- -name: Code Quality Agent -description: Ensures code quality through linting and static analysis - responsible for security, maintainability, and correctness +name: code-quality +description: Ensures code quality through comprehensive linting and static analysis. +tools: [read, search, edit, execute, github, agent] +user-invocable: true --- # Code Quality Agent - VersionMark diff --git a/.github/agents/code-review-agent.md b/.github/agents/code-review.agent.md similarity index 93% rename from .github/agents/code-review-agent.md rename to .github/agents/code-review.agent.md index 297d64f..5113a27 100644 --- a/.github/agents/code-review-agent.md +++ b/.github/agents/code-review.agent.md @@ -1,6 +1,8 @@ --- -name: Code Review Agent -description: Assists in performing formal file reviews - knows how to elaborate review-sets and perform structured review checks +name: code-review +description: Assists in performing formal file reviews. +tools: [read, search, edit, execute, github, web, agent] +user-invocable: true --- # Code Review Agent - VersionMark diff --git a/.github/agents/requirements-agent.md b/.github/agents/requirements.agent.md similarity index 96% rename from .github/agents/requirements-agent.md rename to .github/agents/requirements.agent.md index 8babb7e..061eaa9 100644 --- a/.github/agents/requirements-agent.md +++ b/.github/agents/requirements.agent.md @@ -1,6 +1,8 @@ --- -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. +tools: [read, search, edit, execute, github, web, agent] +user-invocable: true --- # Requirements Agent - VersionMark diff --git a/.github/agents/software-developer.md b/.github/agents/software-developer.agent.md similarity index 93% rename from .github/agents/software-developer.md rename to .github/agents/software-developer.agent.md index 191c6b0..3ebafb8 100644 --- a/.github/agents/software-developer.md +++ b/.github/agents/software-developer.agent.md @@ -1,6 +1,8 @@ --- -name: Software Developer -description: Writes production code and self-validation tests - targets design-for-testability and literate programming style +name: software-developer +description: Writes production code and self-validation tests. +tools: [read, search, edit, execute, github, agent] +user-invocable: true --- # Software Developer - VersionMark diff --git a/.github/agents/technical-writer.md b/.github/agents/technical-writer.agent.md similarity index 93% rename from .github/agents/technical-writer.md rename to .github/agents/technical-writer.agent.md index 40ced15..56149cb 100644 --- a/.github/agents/technical-writer.md +++ b/.github/agents/technical-writer.agent.md @@ -1,6 +1,8 @@ --- -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. +tools: [read, search, edit, execute, github, agent] +user-invocable: true --- # Technical Writer - VersionMark diff --git a/.github/agents/test-developer.md b/.github/agents/test-developer.agent.md similarity index 97% rename from .github/agents/test-developer.md rename to .github/agents/test-developer.agent.md index e90725f..5ed1dff 100644 --- a/.github/agents/test-developer.md +++ b/.github/agents/test-developer.agent.md @@ -1,6 +1,8 @@ --- -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. +tools: [read, search, edit, execute, github, agent] +user-invocable: true --- # Test Developer - VersionMark diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index 866f7af..7a8c326 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -446,16 +446,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 "VersionMark CodeQL Analysis" --report-depth 1 @@ -463,7 +463,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 @@ -475,36 +475,36 @@ jobs: --project-key demaconsulting_VersionMark --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 run: > dotnet reviewmark --definition .reviewmark.yaml - --plan docs/reviewplan/review-plan.md + --plan docs/code_review_plan/review-plan.md --plan-depth 1 - --report docs/reviewreport/review-report.md + --report docs/code_review_report/review-report.md --report-depth 1 - name: Display Review Plan shell: bash run: | echo "=== Review Plan ===" - cat docs/reviewplan/review-plan.md + cat docs/code_review_plan/review-plan.md - name: Display Review Report shell: bash run: | echo "=== Review Report ===" - cat docs/reviewreport/review-report.md + cat docs/code_review_report/review-report.md - name: Generate Build Notes with BuildMark shell: bash @@ -513,20 +513,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..." - versionmark --publish --report docs/buildnotes/versions.md --report-depth 1 \ + versionmark --publish --report docs/build_notes/versions.md --report-depth 1 \ -- "artifacts/**/versionmark-*.json" echo "✓ Tool versions published" @@ -534,7 +534,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. @@ -544,11 +544,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 # === GENERATE PDF DOCUMENTS WITH WEASYPRINT === # This section converts HTML documents to PDF using Weasyprint. @@ -558,7 +558,7 @@ jobs: run: > dotnet weasyprint --pdf-variant pdf/a-3u - docs/buildnotes/buildnotes.html + docs/build_notes/buildnotes.html "docs/VersionMark Build Notes.pdf" - name: Generate Design HTML with Pandoc @@ -599,102 +599,85 @@ 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 Code Quality PDF with Weasyprint run: > dotnet weasyprint --pdf-variant pdf/a-3u - docs/quality/quality.html + docs/code_quality/quality.html "docs/VersionMark Code Quality.pdf" - name: Generate Requirements HTML with Pandoc shell: bash run: > dotnet pandoc - --defaults docs/requirements/definition.yaml + --defaults docs/requirements_doc/definition.yaml --filter node_modules/.bin/mermaid-filter.cmd --metadata version="${{ inputs.version }}" --metadata date="$(date +'%Y-%m-%d')" - --output docs/requirements/requirements.html + --output docs/requirements_doc/requirements.html - name: Generate Requirements PDF with Weasyprint run: > dotnet weasyprint --pdf-variant pdf/a-3u - docs/requirements/requirements.html + docs/requirements_doc/requirements.html "docs/VersionMark Requirements.pdf" - - 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 - - - name: Generate Requirements Justifications PDF with Weasyprint - run: > - dotnet weasyprint - --pdf-variant pdf/a-3u - docs/justifications/justifications.html - "docs/VersionMark Requirements Justifications.pdf" - - 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 Trace Matrix PDF with Weasyprint run: > dotnet weasyprint --pdf-variant pdf/a-3u - docs/tracematrix/tracematrix.html + docs/requirements_report/trace_matrix.html "docs/VersionMark Trace Matrix.pdf" - name: Generate Review Plan HTML with Pandoc shell: bash run: > dotnet pandoc - --defaults docs/reviewplan/definition.yaml + --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/reviewplan/review-plan.html + --output docs/code_review_plan/review-plan.html - name: Generate Review Plan PDF with Weasyprint run: > dotnet weasyprint --pdf-variant pdf/a-3u - docs/reviewplan/review-plan.html + docs/code_review_plan/review-plan.html "docs/VersionMark Review Plan.pdf" - name: Generate Review Report HTML with Pandoc shell: bash run: > dotnet pandoc - --defaults docs/reviewreport/definition.yaml + --defaults docs/code_review_report/definition.yaml --filter node_modules/.bin/mermaid-filter.cmd --metadata version="${{ inputs.version }}" --metadata date="$(date +'%Y-%m-%d')" - --output docs/reviewreport/review-report.html + --output docs/code_review_report/review-report.html - name: Generate Review Report PDF with Weasyprint run: > dotnet weasyprint --pdf-variant pdf/a-3u - docs/reviewreport/review-report.html + docs/code_review_report/review-report.html "docs/VersionMark Review Report.pdf" # === UPLOAD ARTIFACTS === @@ -707,4 +690,4 @@ jobs: name: documents path: | docs/*.pdf - docs/buildnotes.md + docs/build_notes.md diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index 9a81642..b019d74 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -63,10 +63,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 buildnotes.md - name: Create GitHub Release if: inputs.publish == 'release' || inputs.publish == 'publish' diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc deleted file mode 100644 index a46ee1a..0000000 --- a/.markdownlint-cli2.jsonc +++ /dev/null @@ -1,15 +0,0 @@ -{ - "config": { - "default": true, - "MD003": { "style": "atx" }, - "MD007": { "indent": 2 }, - "MD013": { "line_length": 120 }, - "MD025": false, - "MD033": false, - "MD041": false - }, - "ignores": [ - "node_modules", - "**/AGENT_REPORT_*.md" - ] -} diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml new file mode 100644 index 0000000..04f1f80 --- /dev/null +++ b/.markdownlint-cli2.yaml @@ -0,0 +1,47 @@ +--- +# Markdown Linting Standards +# +# PURPOSE: +# - Maintain professional technical documentation standards +# - Ensure consistent formatting for readability and maintenance +# - Support automated documentation generation and publishing +# +# DO NOT MODIFY: These rules represent coding standards +# - If files fail linting, fix the files to meet these standards +# - Do not relax rules to accommodate existing non-compliant files +# - Consistency across repositories is critical for documentation quality + +config: + # Enable all default rules + default: true + + # Require ATX-style headers (# Header) instead of Setext-style + MD003: + style: atx + + # Set consistent indentation for nested lists + MD007: + indent: 2 + + # Allow longer lines for URLs and technical content + MD013: + line_length: 120 + + # Allow multiple top-level headers per document + MD025: false + + # Allow inline HTML for enhanced documentation + MD033: false + + # Allow documents without top-level header (for fragments) + MD041: false + +# Exclude common build artifacts, dependencies, and vendored third-party code +ignores: + - "**/.git/**" + - "**/node_modules/**" + - "**/.venv/**" + - "**/thirdparty/**" + - "**/third-party/**" + - "**/3rd-party/**" + - "**/AGENT_REPORT_*.md" diff --git a/.yamllint.yaml b/.yamllint.yaml index 9ceba9e..4ad71b3 100644 --- a/.yamllint.yaml +++ b/.yamllint.yaml @@ -1,9 +1,27 @@ --- -# yamllint configuration for VersionMark -# This configuration defines the rules for YAML file linting +# YAML Linting Standards +# +# PURPOSE: +# - Maintain consistent code quality and readability standards +# - Support CI/CD workflows with reliable YAML parsing +# - Ensure professional documentation and configuration files +# +# DO NOT MODIFY: These rules represent coding standards +# - If files fail linting, fix the files to meet these standards +# - Do not relax rules to accommodate existing non-compliant files +# - Consistency across repositories is critical for maintainability extends: default +# Exclude common build artifacts, dependencies, and vendored third-party code +ignore: | + .git/ + node_modules/ + .venv/ + thirdparty/ + third-party/ + 3rd-party/ + rules: # Allow 'on:' in GitHub Actions workflows (not a boolean value) truthy: diff --git a/AGENTS.md b/AGENTS.md index 6a63e9c..dd6654c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -48,7 +48,17 @@ VersionMark is a tool that: - **`.versionmark.yaml`** - Configuration defining tools to capture and how to extract versions - **`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 + +## Spell check word list policy + +**Never** add a word to the `.cspell.yaml` word list in order to silence a spell-checking failure. +Doing so defeats the purpose of spell-checking and reduces the quality of the repository. + +- If cspell flags a word that is **misspelled**, fix the spelling in the source file. +- If cspell flags a word that is a **genuine technical term** (tool name, project identifier, etc.) and is + spelled correctly, raise a **proposal** (e.g. comment in a pull request) explaining why the word + should be added. The proposal must be reviewed and approved before the word is added to the list. ## Requirements diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7baab0d..0624d2a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -187,15 +187,13 @@ All markdown files must follow these rules (enforced by markdownlint): ### Spell Checking -All files are spell-checked using cspell. Add project-specific terms to `.cspell.json`: +All files are spell-checked using cspell. **Never** add a word to the `.cspell.yaml` word list in order to silence a +spell-checking failure. Doing so defeats the purpose of spell-checking and reduces the quality of the repository. -```json -{ - "words": [ - "myterm" - ] -} -``` +- If cspell flags a word that is **misspelled**, fix the spelling in the source file. +- If cspell flags a word that is a **genuine technical term** (tool name, project identifier, etc.) and is spelled + correctly, raise a **proposal** (e.g. comment in a pull request) explaining why the word should be added. The + proposal must be reviewed and approved before the word is added to the list. ## Quality Checks diff --git a/docs/build_notes/definition.yaml b/docs/build_notes/definition.yaml new file mode 100644 index 0000000..207a375 --- /dev/null +++ b/docs/build_notes/definition.yaml @@ -0,0 +1,12 @@ +--- +resource-path: + - docs/build_notes + - docs/template +input-files: + - docs/build_notes/title.txt + - docs/build_notes/introduction.md + - docs/build_notes.md + - docs/build_notes/versions.md +template: template.html +table-of-contents: true +number-sections: true diff --git a/docs/buildnotes/introduction.md b/docs/build_notes/introduction.md similarity index 100% rename from docs/buildnotes/introduction.md rename to docs/build_notes/introduction.md diff --git a/docs/buildnotes/title.txt b/docs/build_notes/title.txt similarity index 100% rename from docs/buildnotes/title.txt rename to docs/build_notes/title.txt diff --git a/docs/buildnotes/definition.yaml b/docs/buildnotes/definition.yaml deleted file mode 100644 index 62699f2..0000000 --- a/docs/buildnotes/definition.yaml +++ /dev/null @@ -1,12 +0,0 @@ ---- -resource-path: - - docs/buildnotes - - docs/template -input-files: - - docs/buildnotes/title.txt - - docs/buildnotes/introduction.md - - docs/buildnotes.md - - docs/buildnotes/versions.md -template: template.html -table-of-contents: true -number-sections: true diff --git a/docs/code_quality/definition.yaml b/docs/code_quality/definition.yaml new file mode 100644 index 0000000..68c58f2 --- /dev/null +++ b/docs/code_quality/definition.yaml @@ -0,0 +1,12 @@ +--- +resource-path: + - docs/code_quality + - docs/template +input-files: + - docs/code_quality/title.txt + - docs/code_quality/introduction.md + - docs/code_quality/codeql-quality.md + - docs/code_quality/sonar-quality.md +template: template.html +table-of-contents: true +number-sections: true diff --git a/docs/quality/introduction.md b/docs/code_quality/introduction.md similarity index 100% rename from docs/quality/introduction.md rename to docs/code_quality/introduction.md diff --git a/docs/quality/title.txt b/docs/code_quality/title.txt similarity index 100% rename from docs/quality/title.txt rename to docs/code_quality/title.txt diff --git a/docs/code_review_plan/definition.yaml b/docs/code_review_plan/definition.yaml new file mode 100644 index 0000000..c425a53 --- /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/review-plan.md +template: template.html +table-of-contents: true +number-sections: true diff --git a/docs/reviewplan/introduction.md b/docs/code_review_plan/introduction.md similarity index 100% rename from docs/reviewplan/introduction.md rename to docs/code_review_plan/introduction.md diff --git a/docs/reviewplan/title.txt b/docs/code_review_plan/title.txt similarity index 100% rename from docs/reviewplan/title.txt rename to docs/code_review_plan/title.txt diff --git a/docs/code_review_report/definition.yaml b/docs/code_review_report/definition.yaml new file mode 100644 index 0000000..b71155d --- /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/review-report.md +template: template.html +table-of-contents: true +number-sections: true diff --git a/docs/reviewreport/introduction.md b/docs/code_review_report/introduction.md similarity index 100% rename from docs/reviewreport/introduction.md rename to docs/code_review_report/introduction.md diff --git a/docs/reviewreport/title.txt b/docs/code_review_report/title.txt similarity index 100% rename from docs/reviewreport/title.txt rename to docs/code_review_report/title.txt diff --git a/docs/justifications/definition.yaml b/docs/justifications/definition.yaml deleted file mode 100644 index d0bbbee..0000000 --- a/docs/justifications/definition.yaml +++ /dev/null @@ -1,11 +0,0 @@ ---- -resource-path: - - docs/justifications - - docs/template -input-files: - - docs/justifications/title.txt - - docs/justifications/introduction.md - - docs/justifications/justifications.md -template: template.html -table-of-contents: true -number-sections: true diff --git a/docs/justifications/introduction.md b/docs/justifications/introduction.md deleted file mode 100644 index baa145d..0000000 --- a/docs/justifications/introduction.md +++ /dev/null @@ -1,29 +0,0 @@ -# Introduction - -This document contains the justifications for the requirements of the VersionMark project. - -## Purpose - -This justifications document provides the rationale behind each requirement in the VersionMark -project. Each requirement justification explains why the requirement exists, what problem it -solves, and how it contributes to the overall value of the tool. - -## Scope - -This document covers justifications for: - -- Command-line interface requirements -- Self-validation framework requirements -- Test result output requirements -- Logging requirements -- Platform support requirements -- Documentation generation requirements - -## Audience - -This document is intended for: - -- Software developers understanding design decisions -- Quality assurance teams reviewing requirement rationale -- Project stakeholders evaluating project scope -- Compliance and audit teams reviewing requirements traceability diff --git a/docs/justifications/title.txt b/docs/justifications/title.txt deleted file mode 100644 index 15adfc0..0000000 --- a/docs/justifications/title.txt +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: VersionMark Requirements Justifications -subtitle: Requirements Justifications for the VersionMark -author: DEMA Consulting -description: Requirements Justifications for the VersionMark -lang: en-US -keywords: - - VersionMark - - Requirements - - Justifications - - .NET - - Documentation ---- diff --git a/docs/quality/definition.yaml b/docs/quality/definition.yaml deleted file mode 100644 index 1b63510..0000000 --- a/docs/quality/definition.yaml +++ /dev/null @@ -1,12 +0,0 @@ ---- -resource-path: - - docs/quality - - docs/template -input-files: - - docs/quality/title.txt - - docs/quality/introduction.md - - docs/quality/codeql-quality.md - - docs/quality/sonar-quality.md -template: template.html -table-of-contents: true -number-sections: true diff --git a/docs/requirements/definition.yaml b/docs/requirements/definition.yaml deleted file mode 100644 index a0f3371..0000000 --- a/docs/requirements/definition.yaml +++ /dev/null @@ -1,11 +0,0 @@ ---- -resource-path: - - docs/requirements - - docs/template -input-files: - - docs/requirements/title.txt - - docs/requirements/introduction.md - - docs/requirements/requirements.md -template: template.html -table-of-contents: true -number-sections: true diff --git a/docs/requirements_doc/definition.yaml b/docs/requirements_doc/definition.yaml new file mode 100644 index 0000000..0f4ccd2 --- /dev/null +++ b/docs/requirements_doc/definition.yaml @@ -0,0 +1,12 @@ +--- +resource-path: + - docs/requirements_doc + - docs/template +input-files: + - docs/requirements_doc/title.txt + - docs/requirements_doc/introduction.md + - docs/requirements_doc/requirements.md + - docs/requirements_doc/justifications.md +template: template.html +table-of-contents: true +number-sections: true diff --git a/docs/requirements/introduction.md b/docs/requirements_doc/introduction.md similarity index 100% rename from docs/requirements/introduction.md rename to docs/requirements_doc/introduction.md diff --git a/docs/requirements/title.txt b/docs/requirements_doc/title.txt similarity index 100% rename from docs/requirements/title.txt rename to docs/requirements_doc/title.txt diff --git a/docs/requirements_report/definition.yaml b/docs/requirements_report/definition.yaml new file mode 100644 index 0000000..918a645 --- /dev/null +++ b/docs/requirements_report/definition.yaml @@ -0,0 +1,11 @@ +--- +resource-path: + - docs/requirements_report + - docs/template +input-files: + - docs/requirements_report/title.txt + - docs/requirements_report/introduction.md + - docs/requirements_report/trace_matrix.md +template: template.html +table-of-contents: true +number-sections: true diff --git a/docs/tracematrix/introduction.md b/docs/requirements_report/introduction.md similarity index 100% rename from docs/tracematrix/introduction.md rename to docs/requirements_report/introduction.md diff --git a/docs/tracematrix/title.txt b/docs/requirements_report/title.txt similarity index 100% rename from docs/tracematrix/title.txt rename to docs/requirements_report/title.txt diff --git a/docs/reviewplan/definition.yaml b/docs/reviewplan/definition.yaml deleted file mode 100644 index 362a390..0000000 --- a/docs/reviewplan/definition.yaml +++ /dev/null @@ -1,11 +0,0 @@ ---- -resource-path: - - docs/reviewplan - - docs/template -input-files: - - docs/reviewplan/title.txt - - docs/reviewplan/introduction.md - - docs/reviewplan/review-plan.md -template: template.html -table-of-contents: true -number-sections: true diff --git a/docs/reviewreport/definition.yaml b/docs/reviewreport/definition.yaml deleted file mode 100644 index 671c73e..0000000 --- a/docs/reviewreport/definition.yaml +++ /dev/null @@ -1,11 +0,0 @@ ---- -resource-path: - - docs/reviewreport - - docs/template -input-files: - - docs/reviewreport/title.txt - - docs/reviewreport/introduction.md - - docs/reviewreport/review-report.md -template: template.html -table-of-contents: true -number-sections: true diff --git a/docs/tracematrix/definition.yaml b/docs/tracematrix/definition.yaml deleted file mode 100644 index ba93d57..0000000 --- a/docs/tracematrix/definition.yaml +++ /dev/null @@ -1,11 +0,0 @@ ---- -resource-path: - - docs/tracematrix - - docs/template -input-files: - - docs/tracematrix/title.txt - - docs/tracematrix/introduction.md - - docs/tracematrix/tracematrix.md -template: template.html -table-of-contents: true -number-sections: true diff --git a/requirements.yaml b/requirements.yaml index 6fc1d15..3488ccc 100644 --- a/requirements.yaml +++ b/requirements.yaml @@ -2,7 +2,7 @@ # VersionMark Requirements # # This file defines the requirements for the VersionMark tool. -# Requirements are verified through tests and documented in docs/requirements/ and docs/tracematrix/. +# Requirements are verified through tests and documented in docs/requirements_doc/ and docs/requirements_report/. includes: - docs/reqstream/command-line.yaml From 380bb02876337fc18676eecd21084e82086e267a Mon Sep 17 00:00:00 2001 From: Copilot Date: Tue, 24 Mar 2026 13:41:37 +0000 Subject: [PATCH 4/4] Fix agent file references to old lint config file names Update references from .cspell.json/.markdownlint-cli2.jsonc to the new .cspell.yaml/.markdownlint-cli2.yaml YAML format config files in: - code-quality.agent.md - technical-writer.agent.md --- .github/agents/code-quality.agent.md | 4 ++-- .github/agents/technical-writer.agent.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/agents/code-quality.agent.md b/.github/agents/code-quality.agent.md index f21459f..9bebd68 100644 --- a/.github/agents/code-quality.agent.md +++ b/.github/agents/code-quality.agent.md @@ -33,8 +33,8 @@ Ensure the project is: 1. **Build**: Zero warnings (TreatWarningsAsErrors=true) 2. **Linting**: - - markdownlint (`.markdownlint-cli2.jsonc`) - - cspell (`.cspell.json`) + - markdownlint (`.markdownlint-cli2.yaml`) + - cspell (`.cspell.yaml`) - yamllint (`.yamllint.yaml`) - dotnet format (`.editorconfig`) 3. **Static Analysis**: diff --git a/.github/agents/technical-writer.agent.md b/.github/agents/technical-writer.agent.md index 56149cb..d35570f 100644 --- a/.github/agents/technical-writer.agent.md +++ b/.github/agents/technical-writer.agent.md @@ -43,7 +43,7 @@ Invoke the technical-writer for: #### Linting Requirements - **markdownlint**: Style and structure compliance -- **cspell**: Spelling (add technical terms to `.cspell.json`) +- **cspell**: Spelling (add technical terms to `.cspell.yaml`) - **yamllint**: YAML file validation ### Regulatory Documentation