Pre-release quality: fix formatting, sync documentation, restructure user guide, and port template improvements

[Copilot]

Pull Request

Description

Pre-release sweep to fix code formatting violations, sync documentation with actual tool behavior, restructure the user guide heading hierarchy, and port structural improvements from TemplateDotNetTool.

Code formatting

• Remove trailing whitespace in ValidateDiagram.cs, ValidateHash.cs, ValidateToMarkdown.cs (caught by dotnet format)

Documentation accuracy

• docs/spdx-tool-command-line.md: Add 4 missing CLI options (-l/--log, -s/--silent, --validate, -r/--result); fix diagram command to include [tools] param
• README.md: Update self-validation example — old names (AddPackage) → current (SpdxTool_AddPackage), add 5 missing tests (Validate, Diagram, Hash, Ntia, ToMarkdown)
• CONTRIBUTING.md: Remove reference to non-existent CHANGELOG.md; project uses auto-generated build notes
• Fix Github → GitHub typo in docs/spdx-tool-github-ci.md
• Update GitHub Actions versions in doc examples to match actual workflows (setup-dotnet@v4→v5, checkout@v4→v6)

User guide restructure (docs/guide/guide.md)

• Consolidate Introduction to contain only Purpose and Scope subsections (title comes from title.txt for PDF compilation)
• Merge Key Features content into Purpose paragraph (removed redundant ## Key Features subsection)
• Simplify Scope to a concise description (Pandoc auto-generates TOC via table-of-contents: true, so the section-by-section bullet list was redundant)
• Update self-validation report example with current test names (SpdxTool_* prefix) and all 13 tests

Port improvements from TemplateDotNetTool (PRs #24, #27, #32)

• PR template: "All tests pass" → "All unit tests pass", added self-validation tests checklist item, simplified yamllint command to yamllint .
• CONTRIBUTING.md: Separated unit tests and self-validation tests into distinct subsections with --configuration Release and --framework net10.0 flags
• Test .csproj: Reorganized with section comments (Build Configuration, Test Framework Dependencies, Code Analysis Dependencies, Project References) matching TemplateDotNetTool pattern

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Code quality improvement

Related Issues

Pre-Submission Checklist

Before submitting this pull request, ensure you have completed the following:

Build and Test

• Code builds successfully: dotnet build --configuration Release
• All unit tests pass: dotnet test --configuration Release
• Self-validation tests pass:
  dotnet run --project src/DemaConsulting.SpdxTool --configuration Release --framework net10.0
--no-build -- --validate
• Code produces zero warnings

Code Quality

• Code formatting is correct: dotnet format --verify-no-changes
• New code has appropriate XML documentation comments
• Static analyzer warnings have been addressed

Quality Checks

Please run the following checks before submitting:

• Spell checker passes: cspell "**/*.{md,cs}"
• Markdown linter passes: markdownlint "**/*.md"
• YAML linter passes: yamllint .

Testing

• Added unit tests for new functionality
• Updated existing tests if behavior changed
• All tests follow the AAA (Arrange, Act, Assert) pattern
• Test coverage is maintained or improved

Documentation

• Updated README.md (if applicable)
• Updated ARCHITECTURE.md (if applicable)
• Added code examples for new features (if applicable)
• Updated requirements.yaml (if applicable)

Additional Notes

No behavioral changes. Self-validation (13/13) and unit tests (96/96) all pass. CodeQL reports 0 alerts.

Reviewed TemplateDotNetTool PRs #16–#37. Most improvements were already present in SpdxTool. Ported remaining applicable changes from PRs #24, #27, and #32. PRs not applicable: #18 (SafePathCombine utility doesn't exist in SpdxTool), #35 (test source filters — SpdxTool has no requirements.yaml), #37 (agent file changes).

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Malcolmnixon]

@copilot An additional release-cleanup task is to update the heading-structure of the user guide. The guide has all its headings under one Title-like root heading. This isn't needed for documents compiled to PDF as the title is populated from title.txt. Additionally Pandoc automatically creates a Table of Contents so the guide doesn't need its own navigation table in Markdown, and should start with an Introduction section containing a Purpose and Scope, and then the critical sections of the document should also be root-level markdown sections.

[Copilot]

@copilot An additional release-cleanup task is to update the heading-structure of the user guide. The guide has all its headings under one Title-like root heading. This isn't needed for documents comp...

Done in c968da6. Changes to docs/guide/guide.md:

• Consolidated Introduction to contain only Purpose and Scope subsections
• Merged Key Features content into Purpose as a paragraph (removed the separate ## Key Features subsection)
• Simplified Scope to a concise one-liner since Pandoc auto-generates the TOC from table-of-contents: true in definition.yaml
• Updated the self-validation report example with current test names (SpdxTool_* prefix) and all 13 tests

All major sections (Installation, Command-Line Usage, Core Commands, etc.) remain as root-level # headings.

[Malcolmnixon]

@copilot Please re-run the Repo Consistency agent to review the last 10-20 PRs of https://github.com/demaconsulting/TemplateDotNetTool and merge in any improvements.

[Copilot]

@copilot Please re-run the Repo Consistency agent to review the last 10-20 PRs of https://github.com/demaconsulting/TemplateDotNetTool and merge in any improvements.

Reviewed the last 20 merged PRs from TemplateDotNetTool (#16–#37). Most improvements were already present in SpdxTool (build script unit tests, markdownlint MD025 disable, version tracking, build-docs reorganization, agent report exclusions, package-lock.json in .gitignore).

Ported the remaining applicable changes in 40c05bd:

• PR Summary should list tools separately from shipping packages #24: PR template — "All tests pass" → "All unit tests pass", added self-validation checklist item. CONTRIBUTING.md — separated unit tests and self-validation tests into distinct subsections with --configuration Release and --framework net10.0 flags.
• PR Add support for running workflow from URL #27: PR template — simplified yamllint command to yamllint . (config file handles glob).
• PR Add 'get-version' command. #32: Test .csproj — reorganized with section comments (Build Configuration, Test Framework Dependencies, Code Analysis Dependencies, Project References) and moved GenerateDocumentationFile to Test Project Configuration group, matching template layout.

PRs not applicable: #18 (SafePathCombine — SpdxTool doesn't have this utility), #35 (test source filters — SpdxTool has no requirements.yaml), #37 (agent files — not accessible).