From ae4a5f74661e38f1d678e6eebb35626bd459b91d Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Thu, 21 May 2026 20:47:40 -0400 Subject: [PATCH 01/23] Clarify one OtsSoftwareTests for the repo --- src/.github/standards/reviewmark-usage.md | 3 ++- src/.github/standards/software-items.md | 6 ++++-- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/src/.github/standards/reviewmark-usage.md b/src/.github/standards/reviewmark-usage.md index 990d707..17952ed 100644 --- a/src/.github/standards/reviewmark-usage.md +++ b/src/.github/standards/reviewmark-usage.md @@ -208,7 +208,8 @@ Reviews OTS item integration design, requirements, and verification evidence: - OTS requirements: `docs/reqstream/ots/{ots-name}.yaml` - OTS integration design: `docs/design/ots/{ots-name}.md` - OTS verification: `docs/verification/ots/{ots-name}.md` - - Tests (if applicable): `test/{OtsSoftwareTests}/...` (cased per language) + - Tests (if applicable): `test/OtsSoftwareTests/...` (C#) or `test/ots_software_tests/...` + (Python/other) — fixed repo-level name, no system prefix ## `Shared-{PackageName}` Review (one per Shared Package) diff --git a/src/.github/standards/software-items.md b/src/.github/standards/software-items.md index 328a08e..07c4013 100644 --- a/src/.github/standards/software-items.md +++ b/src/.github/standards/software-items.md @@ -94,8 +94,10 @@ Choose the appropriate category based on scope and testability: - These folders sit parallel to system folders (not inside any system folder) - System design documentation records which OTS items each system depends on - **OTS test project**: If no other verification evidence is available (e.g., vendor test results, - published compliance reports), a dedicated test project (`OtsSoftwareTests` / `ots_software_tests`, - cased per language) holds OTS integration tests - one test file per OTS item requiring tests. + published compliance reports), a dedicated test project holds OTS integration tests - one test + file per OTS item requiring tests. OTS items are repo-level (not per-system), so the project + uses a fixed repo-level name: `test/OtsSoftwareTests/` (C#) or `test/ots_software_tests/` + (Python/other) — never prefixed with a system or project name. ## Shared Package From 74eca715c434e30e816037d8cb1a99f51d65d634 Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Thu, 21 May 2026 21:03:54 -0400 Subject: [PATCH 02/23] Updates for c++ --- src/.github/standards/cpp-language.md | 7 ++++--- src/.github/standards/cpp-testing.md | 2 +- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/src/.github/standards/cpp-language.md b/src/.github/standards/cpp-language.md index bab95df..0ed512d 100644 --- a/src/.github/standards/cpp-language.md +++ b/src/.github/standards/cpp-language.md @@ -10,10 +10,11 @@ Read these standards first before applying this standard: - **`coding-principles.md`** - Universal coding principles and quality gates -# Header Organization +# File Organization -Public headers live under `include/` mirroring the `src/` folder structure. -Internal headers stay alongside their source files in `src/`: +C++ projects use three parallel top-level folders — `include/` (public API), +`src/` (implementation), and `test/` (verification) — all mirroring the same +system/subsystem/unit hierarchy: ```text include/ diff --git a/src/.github/standards/cpp-testing.md b/src/.github/standards/cpp-testing.md index db6290d..12eb060 100644 --- a/src/.github/standards/cpp-testing.md +++ b/src/.github/standards/cpp-testing.md @@ -17,7 +17,7 @@ Test files mirror the source tree under a `test/` root: ```text test/ -└── {system_name}/ +└── {system_name}_tests/ └── {subsystem_name}/ └── {unit_name}_tests.cpp # unit tests for src/{system_name}/{subsystem_name}/{unit_name}.cpp ``` From d9820879e4a1bf80b90dd49fc9d4266c75887ecf Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Thu, 21 May 2026 22:37:36 -0400 Subject: [PATCH 03/23] Improvements around Recreate --- src/.github/agents/template-sync.agent.md | 27 +++++++++++++++++++---- 1 file changed, 23 insertions(+), 4 deletions(-) diff --git a/src/.github/agents/template-sync.agent.md b/src/.github/agents/template-sync.agent.md index 44d29ff..4e9d632 100644 --- a/src/.github/agents/template-sync.agent.md +++ b/src/.github/agents/template-sync.agent.md @@ -42,10 +42,27 @@ For each group intersecting the requested scope, call a sub-agent with: - **Scaffold** - fetch `repository-map.md` from the template URL in `AGENTS.md` to identify files that should exist but don't; for each, fetch the template, populate all sections, write the file; run `pwsh ./fix.ps1` - - **Recreate** - read the existing file in full, then fetch the template; use - full semantic understanding to map old content onto template sections, - splitting or consolidating as needed; create extra sections for any content - that has no template home; write the rebuilt file; run `pwsh ./fix.ps1` + - **Recreate** - read the existing file in full, then fetch the template; + the template is the **sole authority** for both structure and format — + old content must be reformatted to match, not merely relocated: + - Map each piece of old content to the best-fit template section using + full semantic understanding, splitting or consolidating as needed + - Reformat content within each section to match the template's prescribed + style; HTML comments inside sections describe **how** content must be + formatted (e.g. paragraph blocks, bullet lists, no sub-headings) + - Old sub-headings, tables, or other structures that conflict with the + template format must be converted, preserving the factual content + (e.g. per-scenario sub-headings → bold-name paragraph blocks) + - Only if content has no reasonable template home, append it in an + extra section at the end + - **Before writing**: do a mandatory self-check — for every section that + has an HTML comment in the template, explicitly state what format the + comment requires, then verify the drafted content matches that format + exactly (e.g. if the comment says "no sub-headings", confirm there are + no `###` headings inside that section; if it says "bold-name paragraph + blocks", confirm each entry is `**Name**: prose` with no sub-heading); + fix any mismatches before writing the file + - Write the rebuilt file; run `pwsh ./fix.ps1` - When writing any section: HTML comments and TODO placeholders in the template are instructions - always resolve them to real content; infer from README, related files, sibling docs, and path; if confident write directly; if @@ -69,6 +86,8 @@ Collect sub-agent results and assemble the final report. - **Template**: {template path} - **Missing sections**: {list or "none"} - **Heading depth issues**: {list or "none"} +- **Content format issues**: {list of sections where intra-section content did not + match the template comment's prescribed format, or "none"} *(Recreate only)* - **Action**: (Reported | Sections added | Created | Rebuilt | No template found) ## Summary From 2b23f76822963bc44474d9bca7553e54e890a66e Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Fri, 22 May 2026 06:50:31 -0400 Subject: [PATCH 04/23] Imrpovements to handling requirements nesting. --- src/.github/agents/template-sync.agent.md | 56 +++++++++++++---------- src/.github/standards/reqstream-usage.md | 39 ++++++++++++++++ 2 files changed, 71 insertions(+), 24 deletions(-) diff --git a/src/.github/agents/template-sync.agent.md b/src/.github/agents/template-sync.agent.md index 4e9d632..b345f70 100644 --- a/src/.github/agents/template-sync.agent.md +++ b/src/.github/agents/template-sync.agent.md @@ -31,6 +31,8 @@ For each group intersecting the requested scope, call a sub-agent with: - **context**: - Group scope and template URL from the `# Reference Template` section in `AGENTS.md` + - Applicable standards from the `# Standards Application` matrix in `AGENTS.md` + for the file types in the group scope - Project-specific names substitute for placeholders at matching path depth (e.g. `SystemName` → `{SystemName}`, `system-name` → `{system-name}`) - If a template counterpart cannot be fetched, skip the file and report it @@ -42,32 +44,38 @@ For each group intersecting the requested scope, call a sub-agent with: - **Scaffold** - fetch `repository-map.md` from the template URL in `AGENTS.md` to identify files that should exist but don't; for each, fetch the template, populate all sections, write the file; run `pwsh ./fix.ps1` - - **Recreate** - read the existing file in full, then fetch the template; - the template is the **sole authority** for both structure and format — - old content must be reformatted to match, not merely relocated: - - Map each piece of old content to the best-fit template section using - full semantic understanding, splitting or consolidating as needed - - Reformat content within each section to match the template's prescribed - style; HTML comments inside sections describe **how** content must be - formatted (e.g. paragraph blocks, bullet lists, no sub-headings) - - Old sub-headings, tables, or other structures that conflict with the - template format must be converted, preserving the factual content - (e.g. per-scenario sub-headings → bold-name paragraph blocks) - - Only if content has no reasonable template home, append it in an - extra section at the end + - **Recreate** - fetch the template and use it as the blueprint for a + freshly authored document: + - Work through the template section by section; for each section, find + any `TEMPLATE-DIRECTIVE` blocks (both `` + in markdown and `# ` in YAML) — execute + each directive (read specified standards, apply structural guidance, + substitute content), then **remove the directive block entirely** from + the output; gather the relevant technical details from all available + sources — the old file, README, related docs, sibling files, and any + other repo context — to populate that section correctly; the old file's + structure and headings are irrelevant; only its factual content is mined + as a source + - **Gap-check**: after all template sections are filled, scan the old + file once more for any technical information not yet captured; if + found, preserve it by appending new relevant sections at the end - **Before writing**: do a mandatory self-check — for every section that - has an HTML comment in the template, explicitly state what format the - comment requires, then verify the drafted content matches that format - exactly (e.g. if the comment says "no sub-headings", confirm there are - no `###` headings inside that section; if it says "bold-name paragraph - blocks", confirm each entry is `**Name**: prose` with no sub-heading); - fix any mismatches before writing the file + has a `TEMPLATE-DIRECTIVE` block in the template, explicitly state what + format the directive requires, then verify the drafted content matches + that format exactly (e.g. if the directive says "no sub-headings", + confirm there are no `###` headings inside that section; if it says + "bold-name paragraph blocks", confirm each entry is `**Name**: prose` + with no sub-heading); fix any mismatches before writing the file - Write the rebuilt file; run `pwsh ./fix.ps1` - - When writing any section: HTML comments and TODO placeholders in the template - are instructions - always resolve them to real content; infer from README, - related files, sibling docs, and path; if confident write directly; if - ambiguous offer 2–3 concrete options and ask the user; keep asking until they - answer - never leave a TODO unless the user explicitly requests it + - When writing any section: `TEMPLATE-DIRECTIVE` blocks are directives — + execute them (read specified standards, apply structural guidance, substitute + content) and **remove the block entirely** from the written file; inline + `TODO:` placeholders in YAML string values (e.g. `title:`, `justification:`) + are content placeholders — always resolve them to real content; infer from + README, related files, sibling docs, and path; if confident write directly; + if ambiguous offer 2–3 concrete options and ask the user; keep asking until + they answer - never leave a TODO or TEMPLATE-DIRECTIVE in the output unless + the user explicitly requests it Collect sub-agent results and assemble the final report. diff --git a/src/.github/standards/reqstream-usage.md b/src/.github/standards/reqstream-usage.md index 95d36a1..a713358 100644 --- a/src/.github/standards/reqstream-usage.md +++ b/src/.github/standards/reqstream-usage.md @@ -58,6 +58,45 @@ sections: - windows@PlatformSpecificTest # Only test runs on Windows count as evidence ``` +# Local System/Subsystem/Unit Requirements + +Use nested sections to mirror the system/subsystem/unit hierarchy because ReqStream +does not infer nesting from folder structure — the section hierarchy in the YAML is +the document hierarchy. Identical section title paths across included files are +automatically merged by ReqStream. + +**Subsystem file** (`docs/reqstream/{system-name}/{subsystem-name}.yaml`): + +```yaml +sections: + - title: '{SystemName} Requirements' + sections: + - title: '{SubsystemName} Requirements' + requirements: + - id: SystemName-SubsystemName-Feature + title: The {SubsystemName} shall perform the required function. + children: + - SystemName-SubsystemName-UnitName-Feature + tests: + - SubsystemName_Functionality_Scenario_ExpectedBehavior +``` + +**Unit file** (`docs/reqstream/{system-name}/{subsystem-name}/{unit-name}.yaml`): + +```yaml +sections: + - title: '{SystemName} Requirements' + sections: + - title: '{SubsystemName} Requirements' + sections: + - title: '{UnitName} Requirements' + requirements: + - id: SystemName-SubsystemName-UnitName-Feature + title: '{UnitName} shall perform the required function.' + tests: + - UnitName_MethodUnderTest_Scenario_ExpectedBehavior +``` + # OTS Software Requirements Use nested sections in `docs/reqstream/ots/` because ReqStream renders the `ots/` From da0c15b4678038fca58b387e28c487bb5fa6afd7 Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Fri, 22 May 2026 11:14:22 -0400 Subject: [PATCH 05/23] More agent fixes around hierarchy. --- src/.github/agents/template-sync.agent.md | 5 + src/.github/standards/design-documentation.md | 10 +- src/.github/standards/reqstream-usage.md | 129 ++++++------------ .../standards/verification-documentation.md | 10 +- 4 files changed, 64 insertions(+), 90 deletions(-) diff --git a/src/.github/agents/template-sync.agent.md b/src/.github/agents/template-sync.agent.md index b345f70..fc5c62a 100644 --- a/src/.github/agents/template-sync.agent.md +++ b/src/.github/agents/template-sync.agent.md @@ -35,6 +35,11 @@ For each group intersecting the requested scope, call a sub-agent with: for the file types in the group scope - Project-specific names substitute for placeholders at matching path depth (e.g. `SystemName` → `{SystemName}`, `system-name` → `{system-name}`) + - For files within `{system-name}/` subtrees in `docs/design/`, `docs/verification/`, + and `docs/reqstream/`: consult `docs/design/introduction.md` to determine whether + each item is a subsystem or unit, then select the appropriate template + (`subsystem-name.*` or `unit-name.*`) regardless of the item's folder depth — + do not infer item type from path depth alone - If a template counterpart cannot be fetched, skip the file and report it - **goal**: - Based on the given mode: diff --git a/src/.github/standards/design-documentation.md b/src/.github/standards/design-documentation.md index 635cb6d..1fd9893 100644 --- a/src/.github/standards/design-documentation.md +++ b/src/.github/standards/design-documentation.md @@ -56,6 +56,9 @@ write "N/A - {justification}" rather than removing any section: # Subsystem Design (MANDATORY) Place `{subsystem-name}.md` in the **parent** folder; create `{subsystem-name}/` for children. +**Important**: A file at `{system-name}/{name}.md` may be either a subsystem or a unit. Always +determine the correct classification from `docs/design/introduction.md` — folder depth does not +determine classification. All sections mandatory; write "N/A - {justification}" rather than removing any section: - **Overview**: responsibility, boundaries, contained units @@ -64,8 +67,11 @@ All sections mandatory; write "N/A - {justification}" rather than removing any s # Unit Design (MANDATORY) -Place `{unit-name}.md` in the **parent** folder. All sections mandatory; -write "N/A - {justification}" rather than removing any section: +Place `{unit-name}.md` in the **parent** folder. +**Important**: A file at `{system-name}/{name}.md` may be either a subsystem or a unit. Always +determine the correct classification from `docs/design/introduction.md` — folder depth does not +determine classification. +All sections mandatory; write "N/A - {justification}" rather than removing any section: - **Purpose**: single responsibility - **Data Model**: fields, properties, types, invariants (IEC 62304 §5.4.2) diff --git a/src/.github/standards/reqstream-usage.md b/src/.github/standards/reqstream-usage.md index a713358..0b30dfa 100644 --- a/src/.github/standards/reqstream-usage.md +++ b/src/.github/standards/reqstream-usage.md @@ -35,101 +35,62 @@ docs/reqstream/ └── {package-name}.yaml # Requirements for Shared Package dependencies ``` -Local items have matching relative paths across `docs/reqstream/`, `docs/design/`, and -`docs/verification/`. OTS items appear in `docs/reqstream/ots/`, `docs/design/ots/`, and -`docs/verification/ots/`. Shared Packages appear in `docs/reqstream/shared/`, -`docs/design/shared/`, and `docs/verification/shared/`. +Local items have matching paths across `docs/reqstream/`, `docs/design/`, and `docs/verification/`. # Requirements File Format -```yaml -sections: - - title: Functional Requirements - requirements: - - id: System-Component-Feature # Used as-is in all reports - make it readable - title: The system shall perform the required function. - justification: | - Business rationale and any regulatory references. - # ReqStream extracts this field into the justifications report (--justifications) - children: # ReqStream validates this decomposition chain - - ChildSystem-Feature-Behavior # Downward links only (see requirements-principles.md) - tests: # ReqStream matches these by method name in test results - - TestMethodName - - windows@PlatformSpecificTest # Only test runs on Windows count as evidence -``` - -# Local System/Subsystem/Unit Requirements +Each file adds requirements at exactly one level of the hierarchy. The file spells out +its full ancestry as nested `{ItemName} Requirements` sections down to that level, then +places requirements there. ReqStream merges identical section title paths across included +files automatically. Always determine item classification from `docs/design/introduction.md` - +folder depth does not determine whether an item is a subsystem or unit. -Use nested sections to mirror the system/subsystem/unit hierarchy because ReqStream -does not infer nesting from folder structure — the section hierarchy in the YAML is -the document hierarchy. Identical section title paths across included files are -automatically merged by ReqStream. +Valid section nestings (names in `{braces}` are placeholders): -**Subsystem file** (`docs/reqstream/{system-name}/{subsystem-name}.yaml`): - -```yaml -sections: - - title: '{SystemName} Requirements' - sections: - - title: '{SubsystemName} Requirements' - requirements: - - id: SystemName-SubsystemName-Feature - title: The {SubsystemName} shall perform the required function. - children: - - SystemName-SubsystemName-UnitName-Feature - tests: - - SubsystemName_Functionality_Scenario_ExpectedBehavior +```text +{System} Requirements # system-level requirements +├── {Subsystem} Requirements # root subsystem requirements +│ ├── {Subsystem} Requirements # nested subsystem (may recurse) +│ │ └── {Unit} Requirements # unit under a nested subsystem +│ └── {Unit} Requirements # unit under a root subsystem +└── {Unit} Requirements # unit directly under the system +OTS Software Requirements # OTS root section (fixed title) +└── {OtsName} Requirements # requirements for one OTS item +Shared Package Requirements # shared package root section (fixed title) +└── {PackageName} Requirements # requirements for one shared package ``` -**Unit file** (`docs/reqstream/{system-name}/{subsystem-name}/{unit-name}.yaml`): +Each file implements one path through this tree: ```yaml sections: - title: '{SystemName} Requirements' sections: - title: '{SubsystemName} Requirements' - sections: - - title: '{UnitName} Requirements' - requirements: - - id: SystemName-SubsystemName-UnitName-Feature - title: '{UnitName} shall perform the required function.' - tests: - - UnitName_MethodUnderTest_Scenario_ExpectedBehavior -``` - -# OTS Software Requirements - -Use nested sections in `docs/reqstream/ots/` because ReqStream renders the `ots/` -subtree as a distinct section in generated reports, separate from local -system requirements: - -```yaml -sections: - - title: OTS Software Requirements - sections: - - title: System.Text.Json requirements: - - id: SystemTextJson-Core-ReadJson - title: System.Text.Json shall be able to read JSON files. - tests: - - JsonReaderTests.TestReadValidJson + - id: System-Subsystem-Feature # Used as-is in all reports - make it readable + title: The subsystem shall perform the required function. + justification: | # ReqStream extracts this into the justifications report (--justifications) + Business rationale and any regulatory references. + tags: # Optional: categorize for filtering with --filter + - security + children: # Optional: ReqStream validates this decomposition chain + - System-Subsystem-Unit-Feat # Downward links only (see requirements-principles.md) + tests: # ReqStream matches these by method name in test results + - TestMethodName + - windows@PlatformSpecificTest # Only test runs on Windows count as evidence ``` -# Shared Package Requirements +# Tags (OPTIONAL) -Use nested sections in `docs/reqstream/shared/` - ReqStream renders the `shared/` -subtree as a distinct section in reports, separate from local and OTS requirements: +Tags are free-form - no mandatory vocabulary. Common tags: `security`, `safety`, `performance`, +`compliance`, `reliability`, `critical`. Use `--filter` to selectively export or enforce subsets +(OR logic across comma-separated tags): -```yaml -sections: - - title: Shared Package Requirements - sections: - - title: MyOrg.SharedLibrary - requirements: - - id: SharedLibrary-Core-ParseConfig - title: MyOrg.SharedLibrary shall parse configuration files. - tests: - - SharedLibraryIntegrationTests.TestParseValidConfig +```bash +dotnet reqstream --requirements requirements.yaml \ + --filter security,critical \ + --report docs/requirements_doc/generated/security_requirements.md ``` # Semantic IDs (MANDATORY) @@ -184,13 +145,9 @@ dotnet reqstream --requirements requirements.yaml \ Before submitting requirements, verify: -- [ ] All requirements have semantic IDs (`System-Section-Feature` pattern) -- [ ] Every requirement links to at least one passing test +- [ ] All requirements have semantic IDs (`System-Component-Feature` pattern) +- [ ] Every requirement has a justification explaining business/regulatory need +- [ ] Every requirement links to at least one test - [ ] Platform-specific requirements use source filters (`platform@TestName`) -- [ ] Comprehensive justification explains business/regulatory need -- [ ] Files organized under `docs/reqstream/` following the folder structure pattern above -- [ ] All documentation folders use kebab-case names matching source code structure -- [ ] OTS requirements placed in `ots/` subfolder -- [ ] Shared Package requirements placed in `shared/` subfolder -- [ ] Valid YAML syntax passes yamllint validation -- [ ] Test result formats compatible (TRX, JUnit XML) +- [ ] All files and folders use kebab-case names matching source code structure +- [ ] All files are organized under `docs/reqstream/` following the folder structure above diff --git a/src/.github/standards/verification-documentation.md b/src/.github/standards/verification-documentation.md index 8dc4408..f3d950e 100644 --- a/src/.github/standards/verification-documentation.md +++ b/src/.github/standards/verification-documentation.md @@ -53,6 +53,9 @@ write "N/A - {justification}" rather than removing any section: # Subsystem Verification Design (MANDATORY) Place `{subsystem-name}.md` in the **parent** folder; create `{subsystem-name}/` for children. +**Important**: A file at `{system-name}/{name}.md` may be either a subsystem or a unit. Always +determine the correct classification from `docs/design/introduction.md` — folder depth does not +determine classification. All sections mandatory; write "N/A - {justification}" rather than removing any section: - **Verification Strategy**: integration test approach and mocking at subsystem boundary @@ -63,8 +66,11 @@ All sections mandatory; write "N/A - {justification}" rather than removing any s # Unit Verification Design (MANDATORY) -Place `{unit-name}.md` in the **parent** folder. All sections mandatory; -write "N/A - {justification}" rather than removing any section: +Place `{unit-name}.md` in the **parent** folder. +**Important**: A file at `{system-name}/{name}.md` may be either a subsystem or a unit. Always +determine the correct classification from `docs/design/introduction.md` — folder depth does not +determine classification. +All sections mandatory; write "N/A - {justification}" rather than removing any section: - **Verification Approach**: what is mocked/stubbed and why; injected vs. real dependencies - **Test Environment**: any environment setup beyond the standard test runner From ee66722f35a54d8cb9c805c5524a17ed51d0fbc3 Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Sat, 23 May 2026 17:09:55 -0400 Subject: [PATCH 06/23] Improvements around project overview. --- src/AGENTS.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/src/AGENTS.md b/src/AGENTS.md index 211f942..8492a3c 100644 --- a/src/AGENTS.md +++ b/src/AGENTS.md @@ -1,12 +1,16 @@ # Project Overview > **Downstream customization required**: Replace the `TODO` values below with -> values specific to the target repository. - -- **name**: TODO -- **description**: TODO -- **languages**: TODO -- **technologies**: TODO +> values specific to the target repository. These values are the canonical source +> for project-wide template placeholders used throughout the repository. + +- **project-name**: TODO — repository/project name (e.g., `ReqStream`) +- **organization**: TODO — organization name for document authorship (e.g., `DEMA Consulting`) +- **project-tagline**: TODO — brief one-line description of what the project does + (e.g., `A .NET CLI tool for requirements traceability`) +- **description**: TODO — full project description, may be multiple sentences +- **languages**: TODO — programming languages used (e.g., `C#`, `C++`) +- **technologies**: TODO — key technologies and frameworks (e.g., `.NET`, `CMake`) # Project Structure From 2bfac7f0e1a8fd28c202a0dace4a92f8721b8760 Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Sat, 23 May 2026 20:57:05 -0400 Subject: [PATCH 07/23] More placeholder standardization. --- src/.github/standards/reqstream-usage.md | 16 ++++++------ src/.github/standards/reviewmark-usage.md | 30 +++++++++++------------ 2 files changed, 23 insertions(+), 23 deletions(-) diff --git a/src/.github/standards/reqstream-usage.md b/src/.github/standards/reqstream-usage.md index 0b30dfa..88479db 100644 --- a/src/.github/standards/reqstream-usage.md +++ b/src/.github/standards/reqstream-usage.md @@ -25,8 +25,8 @@ docs/reqstream/ │ ├── platform-requirements.yaml # Platform support requirements │ ├── {subsystem-name}.yaml # Subsystem requirements │ ├── {subsystem-name}/ # Subsystem folder (kebab-case); may nest recursively -│ │ ├── {child-subsystem}.yaml # Child subsystem requirements -│ │ ├── {child-subsystem}/ # Child subsystem folder +│ │ ├── {subsystem-name}.yaml # Child subsystem requirements +│ │ ├── {subsystem-name}/ # Child subsystem folder │ │ └── {unit-name}.yaml # Unit requirements │ └── {unit-name}.yaml # System-level unit requirements ├── ots/ # OTS items appear as a distinct section in reports @@ -48,12 +48,12 @@ folder depth does not determine whether an item is a subsystem or unit. Valid section nestings (names in `{braces}` are placeholders): ```text -{System} Requirements # system-level requirements -├── {Subsystem} Requirements # root subsystem requirements -│ ├── {Subsystem} Requirements # nested subsystem (may recurse) -│ │ └── {Unit} Requirements # unit under a nested subsystem -│ └── {Unit} Requirements # unit under a root subsystem -└── {Unit} Requirements # unit directly under the system +{SystemName} Requirements # system-level requirements +├── {SubsystemName} Requirements # root subsystem requirements +│ ├── {SubsystemName} Requirements # nested subsystem (may recurse) +│ │ └── {UnitName} Requirements # unit under a nested subsystem +│ └── {UnitName} Requirements # unit under a root subsystem +└── {UnitName} Requirements # unit directly under the system OTS Software Requirements # OTS root section (fixed title) └── {OtsName} Requirements # requirements for one OTS item Shared Package Requirements # shared package root section (fixed title) diff --git a/src/.github/standards/reviewmark-usage.md b/src/.github/standards/reviewmark-usage.md index 17952ed..c7c7fc8 100644 --- a/src/.github/standards/reviewmark-usage.md +++ b/src/.github/standards/reviewmark-usage.md @@ -91,9 +91,9 @@ When constructing review-sets, follow these principles to maintain manageable sc Organize review-sets using these standard patterns to ensure comprehensive coverage while keeping each review manageable in scope: -**Naming conventions**: See `software-items.md` - kebab-case placeholders -(e.g., `{system-name}`) are always kebab-case; cased placeholders -(e.g., `{SystemName}`) follow your language's convention. +**Naming conventions**: File path placeholders are kebab-case (e.g., `{system-name}`). +Review-set name placeholders are always PascalCase (e.g., `{SystemName}`) regardless +of the project's source language. ## `Purpose` Review (only one per repository) @@ -110,12 +110,12 @@ Reviews user-facing capabilities and system promises: - Design introduction: `docs/design/introduction.md` - System design: `docs/design/{system-name}.md` -## `{System}-Architecture` Review (one per system) +## `{SystemName}-Architecture` Review (one per system) Reviews system architecture and operational validation: - **Purpose**: Proves that the system is designed and tested to satisfy its requirements -- **Title**: "Review that {System} Architecture Satisfies Requirements" +- **Title**: "Review that {SystemName} Architecture Satisfies Requirements" - **Scope**: Excludes subsystem and unit files, relying on system-level design to describe what subsystems and units it uses - **File Path Patterns**: @@ -126,12 +126,12 @@ Reviews system architecture and operational validation: - System verification design: `docs/verification/{system-name}.md` - System integration tests: `test/{SystemName}.Tests/{SystemName}Tests.{ext}` -## `{System}-Design` Review (one per system) +## `{SystemName}-Design` Review (one per system) Reviews architectural and design consistency: - **Purpose**: Proves the system design is consistent and complete -- **Title**: "Review that {System} Design is Consistent and Complete" +- **Title**: "Review that {SystemName} Design is Consistent and Complete" - **Scope**: Only brings in top-level requirements and relies on brevity of design documentation - **File Path Patterns**: - System requirements: `docs/reqstream/{system-name}.yaml` @@ -142,12 +142,12 @@ Reviews architectural and design consistency: - OTS overview: `docs/design/ots.md` _(only if OTS items exist)_ - Shared Package overview: `docs/design/shared.md` _(only if Shared Package items exist)_ -## `{System}-Verification` Review (one per system) +## `{SystemName}-Verification` Review (one per system) Reviews verification completeness and consistency: - **Purpose**: Proves the system verification design is consistent and covers all requirements -- **Title**: "Review that {System} Verification is Consistent and Complete" +- **Title**: "Review that {SystemName} Verification is Consistent and Complete" - **Scope**: Only brings in top-level requirements and all verification docs for the system - **File Path Patterns**: - System requirements: `docs/reqstream/{system-name}.yaml` @@ -157,24 +157,24 @@ Reviews verification completeness and consistency: - OTS overview: `docs/verification/ots.md` _(only if OTS items exist)_ - Shared Package overview: `docs/verification/shared.md` _(only if Shared Package items exist)_ -## `{System}-AllRequirements` Review (one per system) +## `{SystemName}-AllRequirements` Review (one per system) Reviews requirements quality and traceability: - **Purpose**: Proves the requirements are consistent and complete -- **Title**: "Review that All {System} Requirements are Complete" +- **Title**: "Review that All {SystemName} Requirements are Complete" - **Scope**: Only brings in requirements files to keep review manageable - **File Path Patterns**: - Root requirements: `requirements.yaml` - System requirements: `docs/reqstream/{system-name}.yaml` - Subsystem/unit requirements: `docs/reqstream/{system-name}/**/*.yaml` -## `{System}-{Subsystem[-Child...]}` Review (one per subsystem at any depth) +## `{SystemName}-{SubsystemName}[-{SubsystemName}...]` Review (one per subsystem at any depth) Reviews subsystem architecture and interfaces: - **Purpose**: Proves that the subsystem is designed and tested to satisfy its requirements -- **Title**: "Review that {System} {Subsystem} Satisfies Subsystem Requirements" +- **Title**: "Review that {SystemName} {SubsystemName} Satisfies Subsystem Requirements" - **Scope**: Excludes units under the subsystem, relying on subsystem design to describe what units it uses - **File Path Patterns**: @@ -183,12 +183,12 @@ Reviews subsystem architecture and interfaces: - Verification design: `docs/verification/{system-name}/.../{subsystem-name}.md` - Tests: `test/{SystemName}.Tests/.../{SubsystemName}/{SubsystemName}Tests.{ext}` -## `{System}-{Subsystem[-Child...]}-{Unit}` Review (one per unit) +## `{SystemName}-{SubsystemName}[-{SubsystemName}...]-{UnitName}` Review (one per unit) Reviews individual software unit implementation: - **Purpose**: Proves the unit is designed, implemented, and tested to satisfy its requirements -- **Title**: "Review that {System} {Subsystem} {Unit} Implementation is Correct" +- **Title**: "Review that {SystemName} {SubsystemName} {UnitName} Implementation is Correct" - **Scope**: Complete unit review including all artifacts - **File Path Patterns**: - Requirements: `docs/reqstream/{system-name}/.../{unit-name}.yaml` From 8fd67a49e0777ea8baf9d32836cc07e85997cf9a Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Sat, 23 May 2026 21:37:32 -0400 Subject: [PATCH 08/23] Updates to standardize on nesting pattern. --- src/.github/standards/cpp-language.md | 2 ++ src/.github/standards/cpp-testing.md | 2 +- src/.github/standards/design-documentation.md | 3 ++- src/.github/standards/reqstream-usage.md | 3 ++- src/.github/standards/reviewmark-usage.md | 18 +++++++++--------- src/.github/standards/software-items.md | 9 +++++++++ .../standards/verification-documentation.md | 3 ++- 7 files changed, 27 insertions(+), 13 deletions(-) diff --git a/src/.github/standards/cpp-language.md b/src/.github/standards/cpp-language.md index 0ed512d..34d0bb2 100644 --- a/src/.github/standards/cpp-language.md +++ b/src/.github/standards/cpp-language.md @@ -29,6 +29,8 @@ src/ └── {unit_name}_impl.hpp # internal header - not part of the public API ``` +Subsystems may nest to any depth: `{system_name}[/{subsystem_name}...]/{unit_name}.hpp/cpp`. + Protect every header with `#pragma once`. # Naming and Style Conventions diff --git a/src/.github/standards/cpp-testing.md b/src/.github/standards/cpp-testing.md index 12eb060..edd991e 100644 --- a/src/.github/standards/cpp-testing.md +++ b/src/.github/standards/cpp-testing.md @@ -19,7 +19,7 @@ Test files mirror the source tree under a `test/` root: test/ └── {system_name}_tests/ └── {subsystem_name}/ - └── {unit_name}_tests.cpp # unit tests for src/{system_name}/{subsystem_name}/{unit_name}.cpp + └── {unit_name}_tests.cpp # unit tests for src/{system_name}[/{subsystem_name}...]/{unit_name}.cpp ``` # Package Reference diff --git a/src/.github/standards/design-documentation.md b/src/.github/standards/design-documentation.md index 1fd9893..4eb5baa 100644 --- a/src/.github/standards/design-documentation.md +++ b/src/.github/standards/design-documentation.md @@ -28,7 +28,8 @@ docs/design/ └── {package-name}.md # heading depth ## ``` -Subsystems may nest recursively. Each file's heading depth equals its folder depth under `docs/design/`. +Subsystems may nest recursively: `docs/design/{system-name}[/{subsystem-name}...]/{unit-name}.md`. +Each file's heading depth equals its folder depth under `docs/design/`. # introduction.md (MANDATORY) diff --git a/src/.github/standards/reqstream-usage.md b/src/.github/standards/reqstream-usage.md index 88479db..e07d072 100644 --- a/src/.github/standards/reqstream-usage.md +++ b/src/.github/standards/reqstream-usage.md @@ -35,7 +35,8 @@ docs/reqstream/ └── {package-name}.yaml # Requirements for Shared Package dependencies ``` -Local items have matching paths across `docs/reqstream/`, `docs/design/`, and `docs/verification/`. +Local items have matching paths across `docs/reqstream/`, `docs/design/`, and `docs/verification/`: +`{system-name}[/{subsystem-name}...]/{unit-name}.yaml` # Requirements File Format diff --git a/src/.github/standards/reviewmark-usage.md b/src/.github/standards/reviewmark-usage.md index c7c7fc8..cd2efdc 100644 --- a/src/.github/standards/reviewmark-usage.md +++ b/src/.github/standards/reviewmark-usage.md @@ -178,10 +178,10 @@ Reviews subsystem architecture and interfaces: - **Scope**: Excludes units under the subsystem, relying on subsystem design to describe what units it uses - **File Path Patterns**: - - Requirements: `docs/reqstream/{system-name}/.../{subsystem-name}.yaml` - - Design: `docs/design/{system-name}/.../{subsystem-name}.md` - - Verification design: `docs/verification/{system-name}/.../{subsystem-name}.md` - - Tests: `test/{SystemName}.Tests/.../{SubsystemName}/{SubsystemName}Tests.{ext}` + - Requirements: `docs/reqstream/{system-name}[/{subsystem-name}...]/{subsystem-name}.yaml` + - Design: `docs/design/{system-name}[/{subsystem-name}...]/{subsystem-name}.md` + - Verification design: `docs/verification/{system-name}[/{subsystem-name}...]/{subsystem-name}.md` + - Tests: `test/{SystemName}.Tests[/{SubsystemName}...]/{SubsystemName}Tests.{ext}` ## `{SystemName}-{SubsystemName}[-{SubsystemName}...]-{UnitName}` Review (one per unit) @@ -191,11 +191,11 @@ Reviews individual software unit implementation: - **Title**: "Review that {SystemName} {SubsystemName} {UnitName} Implementation is Correct" - **Scope**: Complete unit review including all artifacts - **File Path Patterns**: - - Requirements: `docs/reqstream/{system-name}/.../{unit-name}.yaml` - - Design: `docs/design/{system-name}/.../{unit-name}.md` - - Verification design: `docs/verification/{system-name}/.../{unit-name}.md` - - Source: `src/{SystemName}/.../{UnitName}.{ext}` - - Tests: `test/{SystemName}.Tests/.../{UnitName}Tests.{ext}` + - Requirements: `docs/reqstream/{system-name}[/{subsystem-name}...]/{unit-name}.yaml` + - Design: `docs/design/{system-name}[/{subsystem-name}...]/{unit-name}.md` + - Verification design: `docs/verification/{system-name}[/{subsystem-name}...]/{unit-name}.md` + - Source: `src/{SystemName}[/{SubsystemName}...]/{UnitName}.{ext}` + - Tests: `test/{SystemName}.Tests[/{SubsystemName}...]/{UnitName}Tests.{ext}` ## `OTS-{OtsName}` Review (one per OTS item) diff --git a/src/.github/standards/software-items.md b/src/.github/standards/software-items.md index 07c4013..2b3b486 100644 --- a/src/.github/standards/software-items.md +++ b/src/.github/standards/software-items.md @@ -48,6 +48,15 @@ Two placeholder styles appear in path patterns across these standards: `PascalCase` for C#/Java, `snake_case` for C++/Python - used in source and test file paths +## Nesting Depth Notation + +Subsystems nest to any depth. Patterns use bracket-ellipsis to express this without +enumerating levels — `[/{subsystem-name}...]` in paths, `[-{SubsystemName}...]` in +dash-separated IDs and names. Examples: + +- `docs/design/{system-name}[/{subsystem-name}...]/{unit-name}.md` +- `SystemName[-SubsystemName...]-UnitName-Feature` + # Categorization Guidelines Choose the appropriate category based on scope and testability: diff --git a/src/.github/standards/verification-documentation.md b/src/.github/standards/verification-documentation.md index f3d950e..16e4520 100644 --- a/src/.github/standards/verification-documentation.md +++ b/src/.github/standards/verification-documentation.md @@ -28,7 +28,8 @@ docs/verification/ └── {package-name}.md # heading depth ## ``` -Subsystems may nest recursively. Each file's heading depth equals its folder depth under `docs/verification/`. +Subsystems may nest recursively: `docs/verification/{system-name}[/{subsystem-name}...]/{unit-name}.md`. +Each file's heading depth equals its folder depth under `docs/verification/`. # introduction.md (MANDATORY) From 8c3dc6326b606638cc0d6222f89695b1239cc2db Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Sat, 23 May 2026 21:45:40 -0400 Subject: [PATCH 09/23] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- src/.github/standards/reqstream-usage.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/.github/standards/reqstream-usage.md b/src/.github/standards/reqstream-usage.md index e07d072..986f248 100644 --- a/src/.github/standards/reqstream-usage.md +++ b/src/.github/standards/reqstream-usage.md @@ -35,8 +35,10 @@ docs/reqstream/ └── {package-name}.yaml # Requirements for Shared Package dependencies ``` -Local items have matching paths across `docs/reqstream/`, `docs/design/`, and `docs/verification/`: -`{system-name}[/{subsystem-name}...]/{unit-name}.yaml` +Local items have matching relative paths across `docs/reqstream/`, `docs/design/`, and `docs/verification/`: +- Requirements: `{system-name}[/{subsystem-name}...]/{item-name}.yaml` +- Design: `{system-name}[/{subsystem-name}...]/{item-name}.md` +- Verification: `{system-name}[/{subsystem-name}...]/{item-name}.md` # Requirements File Format From c675b0dbd0f90da067a8467b08b57028a3c36224 Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Sat, 23 May 2026 21:46:22 -0400 Subject: [PATCH 10/23] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- src/.github/standards/design-documentation.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/.github/standards/design-documentation.md b/src/.github/standards/design-documentation.md index 4eb5baa..8623909 100644 --- a/src/.github/standards/design-documentation.md +++ b/src/.github/standards/design-documentation.md @@ -28,7 +28,9 @@ docs/design/ └── {package-name}.md # heading depth ## ``` -Subsystems may nest recursively: `docs/design/{system-name}[/{subsystem-name}...]/{unit-name}.md`. +Subsystems may nest recursively, so nested paths may end in either a subsystem document +(`docs/design/{system-name}[/{subsystem-name}...]/{subsystem-name}.md`) or a unit document +(`docs/design/{system-name}[/{subsystem-name}...]/{unit-name}.md`). Each file's heading depth equals its folder depth under `docs/design/`. # introduction.md (MANDATORY) From 2d6296ad03b96f1d68f2660e3c7e50f0c9d9598d Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Sat, 23 May 2026 21:46:53 -0400 Subject: [PATCH 11/23] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- src/.github/standards/verification-documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/.github/standards/verification-documentation.md b/src/.github/standards/verification-documentation.md index 16e4520..46e0792 100644 --- a/src/.github/standards/verification-documentation.md +++ b/src/.github/standards/verification-documentation.md @@ -28,7 +28,7 @@ docs/verification/ └── {package-name}.md # heading depth ## ``` -Subsystems may nest recursively: `docs/verification/{system-name}[/{subsystem-name}...]/{unit-name}.md`. +Subsystems may nest recursively, for example as `docs/verification/{system-name}[/{subsystem-name}...]/{subsystem-name}.md` or `docs/verification/{system-name}[/{subsystem-name}...]/{unit-name}.md`. Each file's heading depth equals its folder depth under `docs/verification/`. # introduction.md (MANDATORY) From 60fc2527cbc2d3be5ad99a25a7b3e4b1f1bbc888 Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Sat, 23 May 2026 21:52:14 -0400 Subject: [PATCH 12/23] Improve example around nesting of different types of items. --- src/.github/standards/software-items.md | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/src/.github/standards/software-items.md b/src/.github/standards/software-items.md index 2b3b486..70eb555 100644 --- a/src/.github/standards/software-items.md +++ b/src/.github/standards/software-items.md @@ -40,22 +40,26 @@ Categorize all software into six primary groups: # Naming Conventions in File Path Patterns -Two placeholder styles appear in path patterns across these standards: +Three placeholder forms appear in path patterns across these standards: -- **Kebab-case** (`{system-name}`, `{unit-name}`): always kebab-case - - used in documentation and requirements paths -- **Cased** (`{SystemName}`, `{UnitName}`): follow your language's convention - - `PascalCase` for C#/Java, `snake_case` for C++/Python - - used in source and test file paths +- **Kebab-case** (`{system-name}`, `{unit-name}`): always kebab-case — + documentation and requirements file paths +- **PascalCase IDs** (`SystemName`, `UnitName`): always PascalCase — + requirements IDs, review-mark IDs, and other documentation identifiers +- **Language-cased** (`{SystemName}` or `{system_name}`): follow your language's + convention — `PascalCase` for C#/Java, `snake_case` for C++/Python — + source and test file/folder names ## Nesting Depth Notation Subsystems nest to any depth. Patterns use bracket-ellipsis to express this without enumerating levels — `[/{subsystem-name}...]` in paths, `[-{SubsystemName}...]` in -dash-separated IDs and names. Examples: +dash-separated IDs. Examples covering all three forms: -- `docs/design/{system-name}[/{subsystem-name}...]/{unit-name}.md` -- `SystemName[-SubsystemName...]-UnitName-Feature` +- `SystemName[-SubsystemName...]-UnitName-Feature` (PascalCase ID) +- `docs/design/{system-name}[/{subsystem-name}...]/{unit-name}.md` (kebab-case doc path) +- `src/{SystemName}[/{SubsystemName}...]/{UnitName}.cs` (C# source path) +- `src/{system_name}[/{subsystem_name}...]/{unit_name}.cpp` (C++/Python source path) # Categorization Guidelines From 637f804214691445fcda0a6e0de933869d1affbe Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Sat, 23 May 2026 21:54:54 -0400 Subject: [PATCH 13/23] Lint cleanups. --- src/.github/standards/reqstream-usage.md | 1 + src/.github/standards/verification-documentation.md | 4 +++- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/src/.github/standards/reqstream-usage.md b/src/.github/standards/reqstream-usage.md index 986f248..2371164 100644 --- a/src/.github/standards/reqstream-usage.md +++ b/src/.github/standards/reqstream-usage.md @@ -36,6 +36,7 @@ docs/reqstream/ ``` Local items have matching relative paths across `docs/reqstream/`, `docs/design/`, and `docs/verification/`: + - Requirements: `{system-name}[/{subsystem-name}...]/{item-name}.yaml` - Design: `{system-name}[/{subsystem-name}...]/{item-name}.md` - Verification: `{system-name}[/{subsystem-name}...]/{item-name}.md` diff --git a/src/.github/standards/verification-documentation.md b/src/.github/standards/verification-documentation.md index 46e0792..8fd82a3 100644 --- a/src/.github/standards/verification-documentation.md +++ b/src/.github/standards/verification-documentation.md @@ -28,7 +28,9 @@ docs/verification/ └── {package-name}.md # heading depth ## ``` -Subsystems may nest recursively, for example as `docs/verification/{system-name}[/{subsystem-name}...]/{subsystem-name}.md` or `docs/verification/{system-name}[/{subsystem-name}...]/{unit-name}.md`. +Subsystems may nest recursively: +`docs/verification/{system-name}[/{subsystem-name}...]/{subsystem-name}.md` or +`docs/verification/{system-name}[/{subsystem-name}...]/{unit-name}.md`. Each file's heading depth equals its folder depth under `docs/verification/`. # introduction.md (MANDATORY) From 78f08371729b5518021362d7f9598403fda6b521 Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Sat, 23 May 2026 22:29:09 -0400 Subject: [PATCH 14/23] Minor cleanups. --- src/.github/agents/template-sync.agent.md | 2 +- src/.github/standards/cpp-language.md | 6 +++--- src/.github/standards/cpp-testing.md | 3 ++- src/.github/standards/software-items.md | 2 +- 4 files changed, 7 insertions(+), 6 deletions(-) diff --git a/src/.github/agents/template-sync.agent.md b/src/.github/agents/template-sync.agent.md index fc5c62a..c013503 100644 --- a/src/.github/agents/template-sync.agent.md +++ b/src/.github/agents/template-sync.agent.md @@ -34,7 +34,7 @@ For each group intersecting the requested scope, call a sub-agent with: - Applicable standards from the `# Standards Application` matrix in `AGENTS.md` for the file types in the group scope - Project-specific names substitute for placeholders at matching path depth - (e.g. `SystemName` → `{SystemName}`, `system-name` → `{system-name}`) + (e.g. `MySystem` → `{SystemName}`, `my-system` → `{system-name}`) - For files within `{system-name}/` subtrees in `docs/design/`, `docs/verification/`, and `docs/reqstream/`: consult `docs/design/introduction.md` to determine whether each item is a subsystem or unit, then select the appropriate template diff --git a/src/.github/standards/cpp-language.md b/src/.github/standards/cpp-language.md index 34d0bb2..8ed4316 100644 --- a/src/.github/standards/cpp-language.md +++ b/src/.github/standards/cpp-language.md @@ -12,9 +12,9 @@ Read these standards first before applying this standard: # File Organization -C++ projects use three parallel top-level folders — `include/` (public API), -`src/` (implementation), and `test/` (verification) — all mirroring the same -system/subsystem/unit hierarchy: +C++ projects use two parallel top-level folders — `include/` (public API) and +`src/` (implementation) — both mirroring the same system/subsystem/unit hierarchy +(test layout is covered in `cpp-testing.md`): ```text include/ diff --git a/src/.github/standards/cpp-testing.md b/src/.github/standards/cpp-testing.md index edd991e..a1761bf 100644 --- a/src/.github/standards/cpp-testing.md +++ b/src/.github/standards/cpp-testing.md @@ -13,7 +13,8 @@ Read these standards first before applying this standard: # File Organization -Test files mirror the source tree under a `test/` root: +Test files mirror the `src/` tree under `test/`, with `_tests` appended to the +system folder name and each test file name: ```text test/ diff --git a/src/.github/standards/software-items.md b/src/.github/standards/software-items.md index 70eb555..55b89ea 100644 --- a/src/.github/standards/software-items.md +++ b/src/.github/standards/software-items.md @@ -44,7 +44,7 @@ Three placeholder forms appear in path patterns across these standards: - **Kebab-case** (`{system-name}`, `{unit-name}`): always kebab-case — documentation and requirements file paths -- **PascalCase IDs** (`SystemName`, `UnitName`): always PascalCase — +- **PascalCase IDs** (`{SystemName}`, `{UnitName}`): always PascalCase — requirements IDs, review-mark IDs, and other documentation identifiers - **Language-cased** (`{SystemName}` or `{system_name}`): follow your language's convention — `PascalCase` for C#/Java, `snake_case` for C++/Python — From 7c479fd4bd96b76cb04d4ea54cb695ba75672751 Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Sat, 23 May 2026 22:59:04 -0400 Subject: [PATCH 15/23] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- src/.github/standards/software-items.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/.github/standards/software-items.md b/src/.github/standards/software-items.md index 55b89ea..8e4c7de 100644 --- a/src/.github/standards/software-items.md +++ b/src/.github/standards/software-items.md @@ -45,7 +45,7 @@ Three placeholder forms appear in path patterns across these standards: - **Kebab-case** (`{system-name}`, `{unit-name}`): always kebab-case — documentation and requirements file paths - **PascalCase IDs** (`{SystemName}`, `{UnitName}`): always PascalCase — - requirements IDs, review-mark IDs, and other documentation identifiers + requirements IDs, ReviewMark IDs, and other documentation identifiers - **Language-cased** (`{SystemName}` or `{system_name}`): follow your language's convention — `PascalCase` for C#/Java, `snake_case` for C++/Python — source and test file/folder names From 10c3dc39870786c1ab872959b4870084de9fd1c3 Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Sat, 23 May 2026 22:59:53 -0400 Subject: [PATCH 16/23] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- src/.github/standards/software-items.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/.github/standards/software-items.md b/src/.github/standards/software-items.md index 8e4c7de..444928c 100644 --- a/src/.github/standards/software-items.md +++ b/src/.github/standards/software-items.md @@ -56,7 +56,7 @@ Subsystems nest to any depth. Patterns use bracket-ellipsis to express this with enumerating levels — `[/{subsystem-name}...]` in paths, `[-{SubsystemName}...]` in dash-separated IDs. Examples covering all three forms: -- `SystemName[-SubsystemName...]-UnitName-Feature` (PascalCase ID) +- `{SystemName}[-{SubsystemName}...]-{UnitName}-Feature` (PascalCase ID) - `docs/design/{system-name}[/{subsystem-name}...]/{unit-name}.md` (kebab-case doc path) - `src/{SystemName}[/{SubsystemName}...]/{UnitName}.cs` (C# source path) - `src/{system_name}[/{subsystem_name}...]/{unit_name}.cpp` (C++/Python source path) From 08a4ff8b1963c85ab6a77ee5cc1dd1e83e17d13d Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Sat, 23 May 2026 23:15:17 -0400 Subject: [PATCH 17/23] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- src/.github/standards/reviewmark-usage.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/src/.github/standards/reviewmark-usage.md b/src/.github/standards/reviewmark-usage.md index cd2efdc..3cd40b2 100644 --- a/src/.github/standards/reviewmark-usage.md +++ b/src/.github/standards/reviewmark-usage.md @@ -91,9 +91,11 @@ When constructing review-sets, follow these principles to maintain manageable sc Organize review-sets using these standard patterns to ensure comprehensive coverage while keeping each review manageable in scope: -**Naming conventions**: File path placeholders are kebab-case (e.g., `{system-name}`). -Review-set name placeholders are always PascalCase (e.g., `{SystemName}`) regardless -of the project's source language. +**Naming conventions**: Placeholders in documentation, requirements, design, and +verification file paths are kebab-case (e.g., `{system-name}`). Placeholders in +source and test file paths may use the casing conventional for the project's +source language or repository layout (e.g., `{SystemName}`). Review-set name +placeholders are always PascalCase (e.g., `{SystemName}`). ## `Purpose` Review (only one per repository) From b8155fc7e7993e7d9ac168ab08ff70f13dbd4399 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 24 May 2026 03:18:18 +0000 Subject: [PATCH 18/23] docs: rename placeholder to item-name in subsystem design path example Agent-Logs-Url: https://github.com/demaconsulting/Agents/sessions/1bd74ee2-beba-4438-ab52-c02398310155 Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --- src/.github/standards/design-documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/.github/standards/design-documentation.md b/src/.github/standards/design-documentation.md index 8623909..280d233 100644 --- a/src/.github/standards/design-documentation.md +++ b/src/.github/standards/design-documentation.md @@ -59,7 +59,7 @@ write "N/A - {justification}" rather than removing any section: # Subsystem Design (MANDATORY) Place `{subsystem-name}.md` in the **parent** folder; create `{subsystem-name}/` for children. -**Important**: A file at `{system-name}/{name}.md` may be either a subsystem or a unit. Always +**Important**: A file at `{system-name}/{item-name}.md` may be either a subsystem or a unit. Always determine the correct classification from `docs/design/introduction.md` — folder depth does not determine classification. All sections mandatory; write "N/A - {justification}" rather than removing any section: From 499dd152c0c89b50d3ac527081cc2ace81dce3e1 Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Sat, 23 May 2026 23:21:54 -0400 Subject: [PATCH 19/23] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- src/.github/standards/verification-documentation.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/.github/standards/verification-documentation.md b/src/.github/standards/verification-documentation.md index 8fd82a3..58b08d7 100644 --- a/src/.github/standards/verification-documentation.md +++ b/src/.github/standards/verification-documentation.md @@ -70,9 +70,9 @@ All sections mandatory; write "N/A - {justification}" rather than removing any s # Unit Verification Design (MANDATORY) Place `{unit-name}.md` in the **parent** folder. -**Important**: A file at `{system-name}/{name}.md` may be either a subsystem or a unit. Always -determine the correct classification from `docs/design/introduction.md` — folder depth does not -determine classification. +**Important**: A file at `{system-name}[/{subsystem-name}...]/{name}.md` may be either a +subsystem or a unit. Always determine the correct classification from +`docs/design/introduction.md` — folder depth does not determine classification. All sections mandatory; write "N/A - {justification}" rather than removing any section: - **Verification Approach**: what is mocked/stubbed and why; injected vs. real dependencies From f7e47b9f56eb9052ff59a017f4f93f983b39c2a1 Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Sat, 23 May 2026 23:22:28 -0400 Subject: [PATCH 20/23] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- src/.github/standards/verification-documentation.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/.github/standards/verification-documentation.md b/src/.github/standards/verification-documentation.md index 58b08d7..9629c46 100644 --- a/src/.github/standards/verification-documentation.md +++ b/src/.github/standards/verification-documentation.md @@ -56,9 +56,9 @@ write "N/A - {justification}" rather than removing any section: # Subsystem Verification Design (MANDATORY) Place `{subsystem-name}.md` in the **parent** folder; create `{subsystem-name}/` for children. -**Important**: A file at `{system-name}/{name}.md` may be either a subsystem or a unit. Always -determine the correct classification from `docs/design/introduction.md` — folder depth does not -determine classification. +**Important**: A file at `{system-name}[/{subsystem-name}...]/{name}.md` may be either a +subsystem or a unit. Always determine the correct classification from +`docs/design/introduction.md` — folder depth does not determine classification. All sections mandatory; write "N/A - {justification}" rather than removing any section: - **Verification Strategy**: integration test approach and mocking at subsystem boundary From 6c59eaa5ea583d6435372bb3e823cb8df0f99ac4 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 24 May 2026 03:26:11 +0000 Subject: [PATCH 21/23] docs: use glob pattern in subsystem important note Agent-Logs-Url: https://github.com/demaconsulting/Agents/sessions/56a8ea1a-5149-4089-8502-cfd48abce27e Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --- src/.github/standards/design-documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/.github/standards/design-documentation.md b/src/.github/standards/design-documentation.md index 280d233..c842a24 100644 --- a/src/.github/standards/design-documentation.md +++ b/src/.github/standards/design-documentation.md @@ -59,7 +59,7 @@ write "N/A - {justification}" rather than removing any section: # Subsystem Design (MANDATORY) Place `{subsystem-name}.md` in the **parent** folder; create `{subsystem-name}/` for children. -**Important**: A file at `{system-name}/{item-name}.md` may be either a subsystem or a unit. Always +**Important**: A file at `{system-name}/**/*.md` may be either a subsystem or a unit. Always determine the correct classification from `docs/design/introduction.md` — folder depth does not determine classification. All sections mandatory; write "N/A - {justification}" rather than removing any section: From 77f896ff3c3a9bebbd373a598a75716e0d7ced18 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 24 May 2026 03:35:00 +0000 Subject: [PATCH 22/23] docs: use glob path pattern in design and verification notes Agent-Logs-Url: https://github.com/demaconsulting/Agents/sessions/2eda5e19-abc6-4825-aaf3-ec6ccb391723 Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --- src/.github/standards/design-documentation.md | 2 +- src/.github/standards/verification-documentation.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/.github/standards/design-documentation.md b/src/.github/standards/design-documentation.md index c842a24..156edfd 100644 --- a/src/.github/standards/design-documentation.md +++ b/src/.github/standards/design-documentation.md @@ -71,7 +71,7 @@ All sections mandatory; write "N/A - {justification}" rather than removing any s # Unit Design (MANDATORY) Place `{unit-name}.md` in the **parent** folder. -**Important**: A file at `{system-name}/{name}.md` may be either a subsystem or a unit. Always +**Important**: A file at `{system-name}/**/*.md` may be either a subsystem or a unit. Always determine the correct classification from `docs/design/introduction.md` — folder depth does not determine classification. All sections mandatory; write "N/A - {justification}" rather than removing any section: diff --git a/src/.github/standards/verification-documentation.md b/src/.github/standards/verification-documentation.md index 9629c46..d29da5f 100644 --- a/src/.github/standards/verification-documentation.md +++ b/src/.github/standards/verification-documentation.md @@ -56,7 +56,7 @@ write "N/A - {justification}" rather than removing any section: # Subsystem Verification Design (MANDATORY) Place `{subsystem-name}.md` in the **parent** folder; create `{subsystem-name}/` for children. -**Important**: A file at `{system-name}[/{subsystem-name}...]/{name}.md` may be either a +**Important**: A file at `{system-name}/**/*.md` may be either a subsystem or a unit. Always determine the correct classification from `docs/design/introduction.md` — folder depth does not determine classification. All sections mandatory; write "N/A - {justification}" rather than removing any section: @@ -70,7 +70,7 @@ All sections mandatory; write "N/A - {justification}" rather than removing any s # Unit Verification Design (MANDATORY) Place `{unit-name}.md` in the **parent** folder. -**Important**: A file at `{system-name}[/{subsystem-name}...]/{name}.md` may be either a +**Important**: A file at `{system-name}/**/*.md` may be either a subsystem or a unit. Always determine the correct classification from `docs/design/introduction.md` — folder depth does not determine classification. All sections mandatory; write "N/A - {justification}" rather than removing any section: From af22ef72622cfcf2eea37a10ec1c45cc89956c45 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 24 May 2026 03:48:00 +0000 Subject: [PATCH 23/23] docs: clarify ReviewMark unit path patterns with C# and C++ examples Agent-Logs-Url: https://github.com/demaconsulting/Agents/sessions/ce70b3ba-c4f4-4d31-9d8f-66d62197f205 Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com> --- src/.github/standards/reviewmark-usage.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/.github/standards/reviewmark-usage.md b/src/.github/standards/reviewmark-usage.md index 3cd40b2..4921a55 100644 --- a/src/.github/standards/reviewmark-usage.md +++ b/src/.github/standards/reviewmark-usage.md @@ -196,8 +196,10 @@ Reviews individual software unit implementation: - Requirements: `docs/reqstream/{system-name}[/{subsystem-name}...]/{unit-name}.yaml` - Design: `docs/design/{system-name}[/{subsystem-name}...]/{unit-name}.md` - Verification design: `docs/verification/{system-name}[/{subsystem-name}...]/{unit-name}.md` - - Source: `src/{SystemName}[/{SubsystemName}...]/{UnitName}.{ext}` - - Tests: `test/{SystemName}.Tests[/{SubsystemName}...]/{UnitName}Tests.{ext}` + - Source (C# example): `src/{SystemName}[/{SubsystemName}...]/{UnitName}.cs` + - Tests (C# example): `test/{SystemName}.Tests[/{SubsystemName}...]/{UnitName}Tests.cs` + - Source (snake_case C++ example): `src/{system_name}[/{subsystem_name}...]/{unit_name}.cpp` + - Tests (snake_case C++ example): `test/{system_name}_tests[/{subsystem_name}...]/{unit_name}_tests.cpp` ## `OTS-{OtsName}` Review (one per OTS item)