Cleanups from template-sync and reviews.

[Malcolmnixon]

This pull request updates standards, agent instructions, and documentation structure to support the new "Shared Package" category alongside existing System, Subsystem, Unit, and OTS classifications. It also introduces a new Template Sync agent for auditing and synchronizing repository structure with a canonical template. The changes ensure that Shared Packages are consistently integrated into requirements, design, and verification artifacts, and that compliance and quality checks reflect these updates.

Support for Shared Packages in Standards and Documentation:

• Updated all relevant standards files (software-items.md, reqstream-usage.md, design-documentation.md) to include "Shared Package" as a first-class software item, with specific folder and file organization for requirements, design, and verification artifacts. [1] [2] [3] [4]

Template Sync Agent Introduction:

• Added .github/agents/template-sync.agent.md, defining an orchestrator agent for auditing and synchronizing repository structure and content with a canonical template, supporting Audit, Sync, Scaffold, and Recreate modes.

Improvements to Quality and Compliance Checks:

• Refined compliance checklists in .github/agents/quality.agent.md to account for Shared Packages, clarify requirements/design/testing expectations, and add repository structure compliance (including parallel artifact tree checks and template conformance).

Enhancements to Developer Workflow:

• Updated developer agent instructions to ensure new files are created from template counterparts when available, with placeholder and heading adjustments for consistency.

Clarification and Expansion of Documentation Structure:

• Expanded design documentation standards to require explicit handling and documentation of Shared Packages and OTS items, including new mandatory sections and folder structures for both.

These updates collectively improve traceability, compliance, and maintainability by ensuring Shared Packages are treated consistently across the repository and by introducing tooling to keep repository structure aligned with standards and templates.

[Copilot]

Pull request overview

This pull request updates repository standards, requirements/design/verification documentation, and agent guidance to support an expanded software-item model (including Shared Packages) and to improve traceability/compliance automation. It also tightens CLI/tool documentation and tests around exit codes, error reporting, and cross-platform behavior.

Changes:

• Extend standards and documentation structures to account for Shared Packages and add an orchestrator agent for template auditing/sync (template-sync).
• Improve requirements/design/verification artifacts (including new OTS integration design docs) and update traceability mappings to renamed integration tests.
• Minor product/test refinements: add exit-code assertions to unit tests and make invalid log-path integration test cross-platform.

Reviewed changes

Copilot reviewed 57 out of 58 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
test/DemaConsulting.NuGet.CacheTool.Tests/ProgramTests.cs	Adds exit-code assertions for common Program.Run scenarios.
test/DemaConsulting.NuGet.CacheTool.Tests/IntegrationTests.cs	Renames tests for clarity; makes invalid log path cross-platform; uses SafePathCombine for DLL path.
src/DemaConsulting.NuGet.CacheTool/Program.cs	Adds documentation remarks; clarifies defensive package parsing comment.
requirements.yaml	Reorders/fixes inclusion of the system reqstream root file.
README.md	Adds overview/build instructions; clarifies --results behavior; adds contributing/support links.
docs/verification/ots.md	Expands OTS verification strategy/qualification/regression guidance.
docs/verification/nuget-cache-tool/self-test/validation.md	Adds test environment and acceptance criteria sections.
docs/verification/nuget-cache-tool/self-test/path-helpers.md	Adds test environment and acceptance criteria sections.
docs/verification/nuget-cache-tool/self-test.md	Adds test environment and acceptance criteria sections.
docs/verification/nuget-cache-tool/program.md	Adds test environment/acceptance criteria; fixes requirement coverage mapping.
docs/verification/nuget-cache-tool/cli/context.md	Adds test environment and acceptance criteria sections.
docs/verification/nuget-cache-tool/cli.md	Adds test environment and acceptance criteria sections.
docs/verification/nuget-cache-tool.md	Updates scenario names/mappings; adds acceptance criteria and clarifies system-level limitations.
docs/verification/introduction.md	Updates software structure tree and companion artifact structure text.
docs/user_guide/introduction.md	Clarifies purpose and example usage; adds references section.
docs/requirements_report/title.txt	Renames report title/subtitle/description to “Requirements Traceability Report”.
docs/requirements_report/introduction.md	Adds references section.
docs/requirements_doc/title.txt	Renames requirements doc title.
docs/requirements_doc/introduction.md	Refocuses purpose/scope on traceable requirements record; adds references section.
docs/reqstream/ots/test-results.yaml	Updates linked test names for results-file scenarios.
docs/reqstream/ots/nuget-caching.yaml	Updates linked test names for package-caching scenarios.
docs/reqstream/nuget-cache-tool/self-test/path-helpers.yaml	Generalizes null-argument requirement wording.
docs/reqstream/nuget-cache-tool/self-test.yaml	Adds missing child requirement reference for null-argument handling.
docs/reqstream/nuget-cache-tool/program.yaml	Splits error-output vs error-exit-code; adds invalid package format + self-validation requirements.
docs/reqstream/nuget-cache-tool/cli/context.yaml	Adds explicit stderr error-output requirement and clarifies error-tracking requirement.
docs/reqstream/nuget-cache-tool/cli.yaml	Splits error-output vs error-exit-code requirement; updates mappings/tests.
docs/reqstream/nuget-cache-tool.yaml	Expands system requirements (stderr, exit code, idempotency, path safety, etc.) and updates test mappings.
docs/design/ots/test-results.md	Adds OTS integration design for DemaConsulting.TestResults.
docs/design/ots/nuget-caching.md	Adds OTS integration design for DemaConsulting.NuGet.Caching.
docs/design/ots.md	Adds top-level OTS integration design strategy/policy.
docs/design/nuget-cache-tool/self-test/validation.md	Expands Validation unit design details (data model, key methods, error handling).
docs/design/nuget-cache-tool/self-test/path-helpers.md	Expands PathHelpers unit design details (algorithm and error handling).
docs/design/nuget-cache-tool/self-test.md	Restructures SelfTest design sections; adds interface/design collaboration details.
docs/design/nuget-cache-tool/program.md	Expands Program unit design: data model, key methods, and error handling details.
docs/design/nuget-cache-tool/cli/context.md	Adds detailed Context API/method descriptions and error-handling table.
docs/design/nuget-cache-tool/cli.md	Restructures CLI design sections and clarifies Context API semantics.
docs/design/nuget-cache-tool.md	Expands system design with external interfaces, dependencies, and security constraints.
docs/design/introduction.md	Updates scope and companion artifact structure; adds OTS items to structure.
docs/design/definition.yaml	Adds OTS design docs to Pandoc build inputs/resource paths.
docs/code_review_report/introduction.md	Clarifies scope and adds references section.
docs/code_review_plan/introduction.md	Clarifies scope and adds references section.
docs/code_quality/introduction.md	Clarifies static-analysis scope and adds references section.
docs/build_notes/title.txt	Renames build notes document title.
docs/build_notes/introduction.md	Clarifies build notes scope and adds references section.
AGENTS.md	Adds reference-template section; simplifies standards selection matrix; points to template-sync agent.
.yamllint.yaml	Updates ignore list and rules (truthy + line-length handling).
.markdownlint-cli2.yaml	Reworks markdownlint configuration/ignores and disables MD013/MD041.
.gitignore	Adds ignores for generated/ outputs, OS files, and Rider/VS artifacts.
.github/standards/verification-documentation.md	Updates verification standards for Shared Package + OTS structures and mandatory sections.
.github/standards/technical-documentation.md	Adds explicit guidance about generated/ folders being non-committed build outputs.
.github/standards/software-items.md	Adds Shared Package category and clarifies OTS vs Shared Package artifacts and design expectations.
.github/standards/reviewmark-usage.md	Adds review-set guidance for OTS integration design and Shared Packages; adds verification review guidance.
.github/standards/reqstream-usage.md	Adds shared/ subtree guidance and updates OTS design expectations.
.github/standards/design-documentation.md	Updates design doc folder structure and required sections for OTS/Shared Packages.
.github/agents/template-sync.agent.md	Introduces template-sync orchestrator agent with Audit/Sync/Scaffold/Recreate modes.
.github/agents/software-architect.agent.md	Updates vocabulary to include Shared Package.
.github/agents/quality.agent.md	Updates compliance checklists to include Shared Packages and template conformance.
.github/agents/developer.agent.md	Adds guidance to seed new files from template counterparts when available.

Comments suppressed due to low confidence (1)

docs/verification/nuget-cache-tool.md:143

• The scenario description still uses a hard-coded Unix path (/nonexistent_dir_xyz_abc/invalid.log), but the integration test now constructs an invalid path under the temp directory to work cross-platform. Update this scenario to reflect the actual invalid-path strategy so the verification doc matches the test evidence.

---

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

[Copilot]

Pull request overview

Copilot reviewed 58 out of 59 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (1)

docs/verification/nuget-cache-tool.md:142

• This scenario description still references the old hard-coded Unix path (/nonexistent_dir_xyz_abc/invalid.log), but the integration test now uses a temp-path-based nonexistent subdirectory to be cross-platform. Update the scenario text to match the actual test input (or describe it platform-agnostically) so verification docs remain traceable to the implemented scenario.

[Copilot]

Pull request overview

Copilot reviewed 72 out of 73 changed files in this pull request and generated 6 comments.

[Copilot]

Pull request overview

Copilot reviewed 73 out of 74 changed files in this pull request and generated 2 comments.

[Malcolmnixon]

@copilot CI reported:

File 'D:\a\NuGetCacheTool\NuGetCacheTool\docs/generated/NuGetCacheTool Trace Matrix.pdf' PDF metadata 'Subject' does not contain 'Traceability'

[Copilot]

@copilot CI reported:

File 'D:\a\NuGetCacheTool\NuGetCacheTool\docs/generated/NuGetCacheTool Trace Matrix.pdf' PDF metadata 'Subject' does not contain 'Traceability'

Fixed in 87b87ad. I updated docs/requirements_report/title.txt so the generated Trace Matrix PDF metadata subject now includes Traceability.

[Copilot]

Pull request overview

Copilot reviewed 73 out of 74 changed files in this pull request and generated 1 comment.