diff --git a/src/.github/agents/template-sync.agent.md b/src/.github/agents/template-sync.agent.md index 44d29ff..c013503 100644 --- a/src/.github/agents/template-sync.agent.md +++ b/src/.github/agents/template-sync.agent.md @@ -31,8 +31,15 @@ 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}`) + (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 + (`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: @@ -42,15 +49,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; 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` - - 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 + - **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 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: `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. @@ -69,6 +99,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 diff --git a/src/.github/standards/cpp-language.md b/src/.github/standards/cpp-language.md index bab95df..8ed4316 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 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/ @@ -28,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 db6290d..a1761bf 100644 --- a/src/.github/standards/cpp-testing.md +++ b/src/.github/standards/cpp-testing.md @@ -13,13 +13,14 @@ 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/ -└── {system_name}/ +└── {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 635cb6d..156edfd 100644 --- a/src/.github/standards/design-documentation.md +++ b/src/.github/standards/design-documentation.md @@ -28,7 +28,10 @@ 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, 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) @@ -56,6 +59,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}/**/*.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 +70,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}/**/*.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 95d36a1..2371164 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 @@ -35,62 +35,66 @@ 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 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 -```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 -``` +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. -# OTS Software Requirements +Valid section nestings (names in `{braces}` are placeholders): + +```text +{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) +└── {PackageName} Requirements # requirements for one shared package +``` -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: +Each file implements one path through this tree: ```yaml sections: - - title: OTS Software Requirements + - title: '{SystemName} Requirements' sections: - - title: System.Text.Json + - title: '{SubsystemName} Requirements' 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) @@ -145,13 +149,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/reviewmark-usage.md b/src/.github/standards/reviewmark-usage.md index 990d707..4921a55 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**: 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**: 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) @@ -110,12 +112,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 +128,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 +144,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,45 +159,47 @@ 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**: - - 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}` -## `{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` - - 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 (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) @@ -208,7 +212,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..444928c 100644 --- a/src/.github/standards/software-items.md +++ b/src/.github/standards/software-items.md @@ -40,13 +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, 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 + +## 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. Examples covering all three forms: + +- `{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 @@ -94,8 +107,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 diff --git a/src/.github/standards/verification-documentation.md b/src/.github/standards/verification-documentation.md index 8dc4408..d29da5f 100644 --- a/src/.github/standards/verification-documentation.md +++ b/src/.github/standards/verification-documentation.md @@ -28,7 +28,10 @@ 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}...]/{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) @@ -53,6 +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}/**/*.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 +69,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}/**/*.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 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