Clarify OtsSoftwareTests and improve project overview and hierarchy

[Malcolmnixon]

This pull request introduces significant improvements to standards, documentation, and automation for template synchronization and project structure. The main focus is on clarifying the classification of subsystems and units, standardizing file organization, refining requirements file structure, and enhancing automation instructions for template-driven documentation. These changes help ensure consistency, accuracy, and maintainability across the repository.

Template Sync & Automation Enhancements

• Updated template-sync.agent.md to:
  • Pass applicable standards from the standards matrix for each file type to sub-agents.
  • Require consulting docs/design/introduction.md to determine if items are subsystems or units, rather than inferring from folder depth, when selecting templates for docs/design/, docs/verification/, and docs/reqstream/.
  • Overhauled the Recreate mode: now strictly follows the template structure, executes and removes all TEMPLATE-DIRECTIVE blocks, gathers content from all relevant sources, and adds a mandatory self-check for content format compliance.
  • Added a new report field for content format issues when template directives are not followed.

Standards: Subsystem/Unit Classification

• Clarified in design-documentation.md, verification-documentation.md, and reqstream-usage.md that classification of files as subsystems or units must always be determined from docs/design/introduction.md, not from folder depth. [1] [2] [3] [4] [5]

Requirements Documentation Structure

• Rewrote requirements file structure in reqstream-usage.md:
  • Described valid section nestings for system, subsystem, unit, OTS, and shared package requirements.
  • Emphasized that each file implements one path through the requirements tree and must spell out its full ancestry.
  • Provided clear YAML examples and guidance for tags and filtering.
  • Updated the requirements submission checklist for semantic IDs, justifications, and folder structure.

File and Test Organization

• Standardized C++ project folder structure and terminology in cpp-language.md.
• Updated C++ test file naming conventions in cpp-testing.md to use {system_name}_tests/ and {unit_name}_tests.cpp.
• Standardized OTS test project naming and location for all languages in software-items.md and reviewmark-usage.md. [1] [2]

Project Metadata Placeholders

• Expanded the project overview section in AGENTS.md to define canonical placeholders for project-wide metadata (e.g., project name, organization, tagline, languages, technologies).

[Copilot]

Pull request overview

This PR updates the repository’s standards and automation guidance to make documentation structure more consistent and template-driven, with a particular emphasis on (1) correctly classifying subsystem vs. unit artifacts and (2) standardizing OTS test project naming/placement.

Changes:

• Clarifies that subsystem/unit classification must be determined from docs/design/introduction.md (not folder depth) in design/verification/requirements standards and in the template-sync agent.
• Reworks reqstream-usage.md to describe a stricter requirements-section hierarchy and adds tags/filtering guidance and an updated submission checklist.
• Standardizes OTS test project naming/location and adjusts C++ folder/testing structure documentation accordingly.

Reviewed changes

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

Show a summary per file

File	Description
src/AGENTS.md	Expands “Project Overview” metadata keys intended for downstream customization/placeholders.
src/.github/standards/verification-documentation.md	Adds explicit guidance to classify subsystem vs unit via docs/design/introduction.md, not path depth.
src/.github/standards/software-items.md	Clarifies OTS test project naming/location as a fixed repo-level convention.
src/.github/standards/reviewmark-usage.md	Updates OTS review file-path patterns to reflect the standardized OTS test project location.
src/.github/standards/reqstream-usage.md	Rewrites requirements hierarchy/sections guidance, adds tags/filtering section, and updates the checklist.
src/.github/standards/design-documentation.md	Adds the same subsystem-vs-unit classification clarification as verification/design standards.
src/.github/standards/cpp-testing.md	Updates C++ test folder naming convention to {system_name}_tests/.
src/.github/standards/cpp-language.md	Renames/expands the “Header Organization” section into broader C++ project file organization guidance.
src/.github/agents/template-sync.agent.md	Enhances orchestration context (standards matrix + subsystem/unit classification source) and overhauls Recreate mode + reporting.

---

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

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

[Malcolmnixon]

@copilot there are multiple review comments where a {system-name}/**/*.md pattern may be simpler

[Copilot]

@copilot there are multiple review comments where a {system-name}/**/*.md pattern may be simpler

Applied this simplification across the relevant standards notes: path examples now use {system-name}/**/*.md in design and verification guidance. Included in commit 77f896f.

[Copilot]

Pull request overview

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