Update agents and template, then review cleanups and validation fixes.

[Malcolmnixon]

Pull Request

Description

This pull request updates agent/template guidance and documentation standards, and now also includes targeted review-driven fixes to keep CI validation aligned with generated document metadata and path contracts.

In addition to the previously described template/standards cleanups, the PR now includes:

• A GlobMatcher fix to ensure rooted non-wildcard matches are returned as fully qualified paths (Path.GetFullPath(...)), preserving the documented absolute-path contract.
• .fileassert.yaml PDF Subject checks corrected to match Pandoc title.txt metadata values with case-sensitive comparisons and template expectations (for Build Notes, Design, Verification, User Guide, and Trace Matrix).
• Removed UK English spellings (artefacts, behaviour, centralises, unrecognised) from the .cspell.yaml allow-list to enforce the repository's US English spelling policy.

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 and all tests pass: pwsh ./build.ps1
• Code produces zero warnings

Code Quality

• New code has appropriate XML documentation comments
• Static analyzer warnings have been addressed

Quality Checks

Please run the following checks before submitting:

• All linters pass: pwsh ./lint.ps1

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 docs/ documentation (if applicable)
• Added code examples for new features (if applicable)
• Updated requirements.yaml (if applicable)

Additional Notes

The .fileassert.yaml updates were validated against the repository's Pandoc metadata docs/**/title.txt files and checked against the template repository expectations with case-sensitive matching.

The .cspell.yaml cleanup removes UK spellings that were only present in the allow-list itself and not used anywhere in the codebase, ensuring cspell will flag accidental UK spellings going forward.

[Copilot]

Pull request overview

This PR updates the repository’s agent instructions and documentation/standards to improve consistency and template-driven regeneration, alongside a few small test/code doc cleanups and build-script adjustments.

Changes:

• Refines the template-sync agent workflow (classification via docs/design/introduction.md, stricter “Recreate” rules, richer reporting).
• Normalizes and restructures standards + design/verification/requirements (ReqStream) documents for consistency and clarity.
• Minor C# test/doc updates and a build script change to restore/build/test with TRX output.

Reviewed changes

Copilot reviewed 133 out of 134 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
test/DemaConsulting.DictionaryMark.Tests/Utilities/UtilitiesSubsystemTests.cs	Updates subsystem test summary comment to reflect broader utility coverage.
test/DemaConsulting.DictionaryMark.Tests/Utilities/TemporaryDirectoryTests.cs	Adds “Arrange” comments for AAA clarity.
test/DemaConsulting.DictionaryMark.Tests/IntegrationTests.cs	Documents _dllPath field intent and reuse.
test/DemaConsulting.DictionaryMark.Tests/Helpers/Runner.cs	Expands XML docs describing stdout/stderr capture and timeout behavior.
test/DemaConsulting.DictionaryMark.Tests/Dictionary/DictionaryGeneratorTests.cs	Clarifies Arrange comments for stdout/stderr redirection scenarios.
test/DemaConsulting.DictionaryMark.Tests/Cli/CliSubsystemTests.cs	Tightens log assertion to check version content specifically.
src/DemaConsulting.DictionaryMark/Utilities/GlobMatcher.cs	Adds detailed XML doc remarks for pattern resolution behavior and constraints.
src/DemaConsulting.DictionaryMark/Program.cs	Improves XML docs for dispatch helpers (banner/help/tool logic).
src/DemaConsulting.DictionaryMark/Dictionary/YamlDictionaryLoader.cs	Adds class/method remarks and clarifies exception contract in docs.
src/DemaConsulting.DictionaryMark/Dictionary/MarkdownFormatter.cs	Adds missing XML doc params/returns on private helpers.
src/DemaConsulting.DictionaryMark/Dictionary/DictionaryGenerator.cs	Clarifies context parameter contract in XML docs.
src/DemaConsulting.DictionaryMark/Dictionary/DictionaryEntry.cs	Adds null-argument validation + richer XML docs for invariants.
src/DemaConsulting.DictionaryMark/Dictionary/ConflictDetector.cs	Refines XML docs and adds explicit null exception contract.
src/DemaConsulting.DictionaryMark/Cli/Context.cs	Expands XML doc remarks about factory pattern and parsing responsibilities.
README.md	Improves packaging-safe link guidance, adds a usage example, reorganizes sections.
docs/verification/title.txt	Normalizes Pandoc title metadata formatting/keywords.
docs/verification/ots/weasyprint.md	Rewrites OTS verification content into standardized “approach + scenarios” style.
docs/verification/ots/versionmark.md	Same as above for VersionMark.
docs/verification/ots/test-results.md	Same as above for TestResults.
docs/verification/ots/sonarmark.md	Same as above for SonarMark.
docs/verification/ots/sarifmark.md	Same as above for SarifMark.
docs/verification/ots/reqstream.md	Same as above for ReqStream.
docs/verification/ots/pandoc.md	Same as above for Pandoc.
docs/verification/ots/fileassert.md	Same as above for FileAssert.
docs/verification/ots/buildmark.md	Same as above for BuildMark.
docs/verification/ots.md	Renames/restructures OTS overview and documents verification strategy chain.
docs/verification/dictionary-mark/utilities.md	Rewrites subsystem verification into “approach + scenarios” format.
docs/verification/dictionary-mark/test-helpers.md	Reframes test helpers as N/A verification with transitive evidence statement.
docs/verification/dictionary-mark/self-test.md	Rewrites subsystem verification into “approach + scenarios” format.
docs/verification/dictionary-mark/dictionary/yaml-loader.md	Rewrites unit verification section content and scenario descriptions.
docs/verification/dictionary-mark/dictionary/dictionary-generator.md	Rewrites unit verification section content and scenario descriptions.
docs/verification/dictionary-mark/dictionary/conflict-detector.md	Rewrites unit verification section content and scenario descriptions.
docs/verification/dictionary-mark/dictionary.md	Rewrites dictionary subsystem verification into “approach + scenarios” format.
docs/user_guide/title.txt	Normalizes title metadata formatting/keywords.
docs/user_guide/definition.yaml	Adds additional user guide inputs and simplifies resource-path syntax.
docs/requirements_report/title.txt	Normalizes metadata and keywords for trace matrix collection.
docs/requirements_report/introduction.md	Tightens intro wording and scope statement.
docs/requirements_doc/title.txt	Normalizes metadata and keywords for requirements collection.
docs/requirements_doc/introduction.md	Tightens intro wording and references.
docs/reqstream/ots/yaml-dot-net.yaml	Normalizes header comment and wraps long title text.
docs/reqstream/ots/xunit.yaml	Normalizes header comment and tightens justification text.
docs/reqstream/ots/weasyprint.yaml	Normalizes header comment.
docs/reqstream/ots/versionmark.yaml	Adds an explicit lint requirement for VersionMark and normalizes header.
docs/reqstream/ots/test-results.yaml	Normalizes header comment and wraps long title text.
docs/reqstream/ots/sonarmark.yaml	Normalizes header comment.
docs/reqstream/ots/sarifmark.yaml	Normalizes header comment.
docs/reqstream/ots/reviewmark.yaml	Normalizes header and switches to US spelling (“catalog”).
docs/reqstream/ots/reqstream.yaml	Normalizes header and switches to US spelling (“artifacts”).
docs/reqstream/ots/pandoc.yaml	Normalizes header and strengthens justification to match verification approach.
docs/reqstream/ots/fileassert.yaml	Normalizes header comment.
docs/reqstream/ots/file-system-globbing.yaml	Normalizes header comment.
docs/reqstream/ots/buildmark.yaml	Normalizes header comment.
docs/reqstream/dictionary-mark/utilities/temporary-directory.yaml	Restructures requirement nesting to match “DictionaryMark Requirements” hierarchy.
docs/reqstream/dictionary-mark/utilities/path-helpers.yaml	Same as above for PathHelpers.
docs/reqstream/dictionary-mark/utilities/glob-matcher.yaml	Same as above for GlobMatcher.
docs/reqstream/dictionary-mark/utilities.yaml	Restructures utilities subsystem requirements under root hierarchy.
docs/reqstream/dictionary-mark/self-test.yaml	Restructures SelfTest subsystem requirements under root hierarchy.
docs/reqstream/dictionary-mark/program.yaml	Restructures Program unit requirements under root hierarchy.
docs/reqstream/dictionary-mark/platform-requirements.yaml	Restructures platform requirements and documents test-source filtering intent.
docs/reqstream/dictionary-mark/dictionary/yaml-loader.yaml	Restructures YamlDictionaryLoader unit requirements under root hierarchy.
docs/reqstream/dictionary-mark/dictionary/markdown-formatter.yaml	Restructures MarkdownFormatter unit requirements under root hierarchy.
docs/reqstream/dictionary-mark/dictionary/dictionary-generator.yaml	Restructures DictionaryGenerator unit requirements under root hierarchy.
docs/reqstream/dictionary-mark/dictionary/conflict-detector.yaml	Restructures ConflictDetector unit requirements under root hierarchy.
docs/reqstream/dictionary-mark/dictionary.yaml	Restructures Dictionary subsystem requirements under root hierarchy.
docs/reqstream/dictionary-mark/cli.yaml	Restructures CLI subsystem requirements under root hierarchy.
docs/reqstream/dictionary-mark.yaml	Normalizes system-level header/title wrapping and adds missing child linkage.
docs/design/title.txt	Normalizes Pandoc title metadata formatting/keywords.
docs/design/ots/yaml-dot-net.md	Rewrites OTS integration design content into standardized structure.
docs/design/ots/test-results.md	Rewrites OTS integration design content into standardized structure.
docs/design/ots/file-system-globbing.md	Rewrites OTS integration design content into standardized structure.
docs/design/ots.md	Tightens OTS policy wording and clarifies SBOM/version policy.
docs/design/dictionary-mark/utilities/temporary-directory.md	Rewrites unit design into standardized “Purpose/Data Model/…” structure.
docs/design/dictionary-mark/utilities/path-helpers.md	Rewrites unit design into standardized “Purpose/Data Model/…” structure.
docs/design/dictionary-mark/utilities/glob-matcher.md	Rewrites unit design into standardized “Purpose/Data Model/…” structure.
docs/design/dictionary-mark/utilities.md	Rewrites subsystem design into standardized “Overview/Interfaces/Design” structure.
docs/design/dictionary-mark/dictionary/yaml-loader.md	Rewrites unit design into standardized structure (removes embedded DictionaryEntry model section).
docs/design/dictionary-mark/dictionary/dictionary-generator.md	Rewrites unit design into standardized structure and error-case list.
docs/design/dictionary-mark/dictionary/conflict-detector.md	Rewrites unit design into standardized structure.
docs/design/definition.yaml	Simplifies resource-path and adjusts input-file ordering/inclusion.
docs/code_review_report/title.txt	Normalizes Pandoc title metadata formatting/keywords.
docs/code_review_report/introduction.md	Tightens intro content by removing redundant generation/audience sections.
docs/code_review_report/definition.yaml	Simplifies resource-path syntax.
docs/code_review_plan/title.txt	Normalizes Pandoc title metadata formatting/keywords.
docs/code_review_plan/introduction.md	Tightens intro content by removing redundant generation/audience sections.
docs/code_quality/title.txt	Normalizes Pandoc title metadata formatting/keywords.
docs/code_quality/introduction.md	Tightens purpose/scope and updates reference formatting.
docs/code_quality/definition.yaml	Simplifies resource-path syntax and clarifies generated file provenance.
docs/build_notes/title.txt	Normalizes Pandoc title metadata formatting/keywords.
docs/build_notes/introduction.md	Tightens intro content by removing redundant generation/audience sections.
docs/build_notes/definition.yaml	Simplifies resource-path syntax.
build.ps1	Changes build flow to restore/build/test with TRX output directory.
AGENTS.md	Adds US-English requirement and clarifies structural-audit agent delegation.
.yamlfix.toml	Adds trailing newline/blank line at end of file.
.versionmark.yaml	Normalizes regex scalars (removes unnecessary quotes) and reorders SarifMark/SonarMark entries.
.gitignore	Replaces default VS template ignore list with a repo-specific, simplified ignore set.
.github/standards/verification-documentation.md	Updates verification doc requirements (mandatory sections, classification source, coverage guidance).
.github/standards/testing-principles.md	Removes redundant “standards” header section.
.github/standards/technical-documentation.md	Tightens wording and consolidates formatting rules presentation.
.github/standards/software-items.md	Tightens wording and adds explicit nesting/placeholder guidance.
.github/standards/design-documentation.md	Updates design doc requirements (mandatory sections, classification source, version policy).
.github/standards/csharp-testing.md	Removes redundant “Quality Checks” intro lines.
.github/standards/csharp-language.md	Removes redundant explanatory prose before example.
.github/standards/coding-principles.md	Tightens wording and formatting for core principles/anti-patterns.
.github/agents/template-sync.agent.md	Updates template-sync agent process (classification source, “Recreate” directives, reporting fields).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 136 out of 137 changed files in this pull request and generated 2 comments.

[Malcolmnixon]

@copilot Please check the .fileassert.yaml against the pandoc metadata title.txt files and make sure they're valid. Check against the template repo and the checks are case-sensitive.

[Copilot]

@copilot Please check the .fileassert.yaml against the pandoc metadata title.txt files and make sure they're valid. Check against the template repo and the checks are case-sensitive.

Updated .fileassert.yaml and fixed the case-sensitive PDF Subject checks to align with the Pandoc title.txt metadata and template expectations in commit 7daf3b9.

[Copilot]

Pull request overview

Copilot reviewed 136 out of 137 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 137 out of 138 changed files in this pull request and generated 1 comment.