docs: reorganize design and reqstream into system-name subfolders; sync template files

.github/agents/developer.agent.md

@@ -16,7 +16,8 @@ Perform software development tasks by determining and applying appropriate DEMA
 2. **Read relevant standards** from `.github/standards/` as defined in AGENTS.md based on work performed
 3. **Apply loaded standards** throughout development process
 4. **Execute work** following standards requirements and quality checks
-5. **Generate completion report** with results and compliance status
+5. **Lint fixes** follow the linting process before performing quality gates
+6. **Generate completion report** with results and compliance status
 
 # Reporting
 

.github/agents/implementation.agent.md

@@ -28,7 +28,7 @@ counting how many retries have occurred.
 
 Call the built-in explore sub-agent with:
 
-- **context**: the user's request and any current quality findings
+- **context**: the user's request + any previous quality findings + retry context
 - **goal**: analyze the implementation state and develop a plan to implement the request
 
 Once the explore sub-agent finishes, transition to the DEVELOPMENT state.
@@ -37,7 +37,7 @@ Once the explore sub-agent finishes, transition to the DEVELOPMENT state.
 
 Call the developer sub-agent with:
 
-- **context** the user's request and the current implementation plan
+- **context** the user's request + research plan + specific quality issues to address (if retry)
 - **goal** implement the user's request and any identified quality fixes
 
 Once the developer sub-agent finishes:
@@ -49,7 +49,7 @@ Once the developer sub-agent finishes:
 
 Call the quality sub-agent with:
 
-- **context** the user's request and the current implementation report
+- **context** the user's request + development summary + files changed + previous issues (if any)
 - **goal** check the quality of the work performed for any issues
 
 Once the quality sub-agent finishes:
@@ -73,7 +73,7 @@ of the project consisting of:
 ## State Machine Execution
 
 - **Research Results**: [Summary of explore agent findings]
-- **Development Results**: [Summary of developer agent results]  
+- **Development Results**: [Summary of developer agent results]
 - **Quality Results**: [Summary of quality agent results]
 - **State Transitions**: [Log of state changes and decisions]
 
@@ -86,7 +86,7 @@ of the project consisting of:
 ## Final Status
 
 - **Implementation Success**: [Overall completion status]
-- **Quality Compliance**: [Final quality validation status]  
+- **Quality Compliance**: [Final quality validation status]
 - **Issues Resolved**: [Problems encountered and resolution attempts]
 ```
 

.github/agents/quality.agent.md

@@ -26,6 +26,13 @@ This assessment is a quality control system of the project and MUST be performed
 Upon completion create a summary in `.agent-logs/{agent-name}-{subject}-{unique-id}.md`
 of the project consisting of:
 
+The **Result** field MUST reflect the quality validation outcome for orchestrator decision-making:
+
+- **Result: SUCCEEDED** - Only when Overall Grade is PASS (all compliance requirements met)
+- **Result: FAILED** - When Overall Grade is FAIL or NEEDS_WORK (compliance failures present)
+
+This ensures orchestrators properly halt workflows when quality gates fail.
+
 ```markdown
 # Quality Assessment Report
 
@@ -98,6 +105,13 @@ of the project consisting of:
 - Do README.md files use absolute URLs and include concrete examples? (PASS|FAIL|N/A) - [Evidence]
 - Is documentation integrated into ReviewMark review-sets for formal review? (PASS|FAIL|N/A) - [Evidence]
 
+## Software Item Completeness: (PASS|FAIL|N/A)
+
+- Does every identified software unit have its own requirements file? (PASS|FAIL|N/A) - [Evidence]
+- Does every identified software unit have its own design document? (PASS|FAIL|N/A) - [Evidence]
+- Does every identified subsystem have its own requirements file? (PASS|FAIL|N/A) - [Evidence]
+- Does every identified subsystem have its own design document? (PASS|FAIL|N/A) - [Evidence]
+
 ## Process Compliance: (PASS|FAIL|N/A)
 
 - Was Continuous Compliance workflow followed? (PASS|FAIL|N/A) - [Evidence]

.github/standards/design-documentation.md

@@ -23,12 +23,13 @@ design to implementation:
 
 ```text
 docs/design/
-├── introduction.md             # Design overview with software structure
-├── system.md                   # System-level design documentation
-├── {subsystem-name}/           # Subsystem design documents (kebab-case folder names)
-│   ├── {subsystem-name}.md     # Subsystem overview and design
-│   └── {unit-name}.md          # Unit-level design documents
-└── {unit-name}.md              # Top-level unit design documents (if not in subsystem)
+├── introduction.md              # Design overview with software structure
+└── {system-name}/               # System-level design folder (one per system)
+    ├── {system-name}.md         # System-level design documentation
+    ├── {subsystem-name}/        # Subsystem design documents (kebab-case folder names)
+    │   ├── {subsystem-name}.md  # Subsystem overview and design
+    │   └── {unit-name}.md       # Unit-level design documents
+    └── {unit-name}.md           # Top-level unit design documents (if not in subsystem)
 ```
 
 ## introduction.md (MANDATORY)
@@ -56,13 +57,16 @@ to understand these classifications before creating this section.
 Example format:
 
 ```text
-ProjectName (System)
+Project1Name (System)
 ├── ComponentA (Subsystem)
 │   ├── ClassX (Unit)
 │   └── ClassY (Unit)
 ├── ComponentB (Subsystem)
 │   └── ClassZ (Unit)
 └── UtilityClass (Unit)
+
+Project2Name (System)
+└── HelperClass (Unit)
 ```
 
 ### Folder Layout Section (MANDATORY)
@@ -73,34 +77,39 @@ mirror the software structure, with file paths and brief descriptions.
 Example format:
 
 ```text
-src/ProjectName/
+src/Project1Name/
 ├── ComponentA/
-│   ├── ClassX.cs               — brief description
-│   └── ClassY.cs               — brief description
+│   ├── ClassX.cs               — Core business logic handler
+│   └── ClassY.cs               — Data validation service
 ├── ComponentB/
-│   └── ClassZ.cs               — brief description
-└── UtilityClass.cs             — brief description
+│   └── ClassZ.cs               — Integration interface
+└── UtilityClass.cs             — Common utility functions
+
+src/Project2Name/
+└── HelperClass.cs              — Helper functions
 ```
 
-## system.md (MANDATORY)
+## System Design Documentation (MANDATORY)
 
-The `system.md` file contains system-level design documentation including:
+For each system identified in the repository:
 
-- System architecture and major components
-- External interfaces and dependencies
-- Data flow and control flow
-- System-wide design constraints and decisions
-- Integration patterns and communication protocols
+- Create a kebab-case folder matching the system name
+- Include `{system-name}.md` with system-level design documentation such as:
+  - System architecture and major components
+  - External interfaces and dependencies
+  - Data flow and control flow
+  - System-wide design constraints and decisions
+  - Integration patterns and communication protocols
 
 ## Subsystem and Unit Design Documents
 
 For each subsystem identified in the software structure:
 
 - Create a kebab-case folder matching the subsystem name (enables automated tooling)
 - Include `{subsystem-name}.md` with subsystem overview and design
-- Include unit design documents for complex units within the subsystem
+- Include unit design documents for ALL units within the subsystem
 
-For significant units requiring detailed design:
+For every unit identified in the software structure:
 
 - Document data models, algorithms, and key methods
 - Describe interactions with other units
@@ -124,19 +133,21 @@ implementation specification for formal code review:
 - **Implementation Detail**: Provide sufficient detail for code review and implementation
 - **Architectural Clarity**: Clearly define component boundaries and interfaces
 - **Traceability**: Link to requirements where applicable using ReqStream patterns
-- **Concrete Examples**: Use actual class names, method signatures, and data structures
-- **Current Information**: Keep synchronized with code changes and refactoring
+
+# Mermaid Diagram Integration
+
+Use Mermaid diagrams to supplement text descriptions (diagrams must not replace text content).
 
 # Quality Checks
 
 Before submitting design documentation, verify:
 
 - [ ] `introduction.md` includes both Software Structure and Folder Layout sections
 - [ ] Software structure correctly categorizes items as System/Subsystem/Unit per `software-items.md`
-- [ ] Folder layout matches actual source code organization
-- [ ] `system.md` provides comprehensive system-level design
+- [ ] Folder layout mirrors software structure organization
+- [ ] Design documents provide sufficient detail for code review
+- [ ] System documentation provides comprehensive system-level design
 - [ ] Subsystem documentation folders use kebab-case names while mirroring source subsystem names and structure
-- [ ] Design documents contain sufficient implementation detail
 - [ ] All documents follow technical documentation formatting standards
 - [ ] Content is current with implementation and requirements
 - [ ] Documents are integrated into ReviewMark review-sets for formal review

.github/standards/reqstream-usage.md

@@ -30,15 +30,17 @@ the source code structure because reviewers need clear navigation from
 requirements to design to implementation:
 
 ```text
-requirements.yaml                  # Root file (includes only)
+requirements.yaml                   # Root file (includes only)
 docs/reqstream/
-├── system.yaml                    # System-level requirements
-├── platform-requirements.yaml     # Platform support requirements
-├── {subsystem-name}/              # Subsystem requirements (kebab-case folders)
-│   └── {subsystem-name}.yaml      # Requirements for this subsystem
-├── {unit-name}.yaml               # Unit requirements (for top-level units)
-└── ots/                           # OTS software item requirements
-    └── {ots-name}.yaml            # Requirements for OTS components
+├── {system-name}/                  # System-level requirements folder (one per system)
+│   ├── {system-name}.yaml          # System-level requirements
+│   ├── platform-requirements.yaml  # Platform support requirements
+│   ├── {subsystem-name}/           # Subsystem requirements (kebab-case folders)
+│   │   ├── {subsystem-name}.yaml   # Requirements for this subsystem
+│   │   └── {unit-name}.yaml        # Requirements for units within this subsystem
+│   └── {unit-name}.yaml            # Requirements for top-level units (outside subsystems)
+└── ots/                            # OTS software items folder
+    └── {ots-name}.yaml             # Requirements for OTS components
 ```
 
 The folder structure MUST mirror the source code organization to maintain
@@ -62,7 +64,7 @@ for compliance auditing.
 sections:
   - title: Functional Requirements
     requirements:
-      - id: Project-Subsystem-Feature
+      - id: System-Subsystem-Feature
         title: The system shall perform the required function.
         justification: |
           Business rationale explaining why this requirement exists.
@@ -88,15 +90,15 @@ sections:
     sections:
       - title: System.Text.Json
         requirements:
-          - id: Project-SystemTextJson-ReadJson
+          - id: TemplateTool-SystemTextJson-ReadJson
             title: System.Text.Json shall be able to read JSON files.
             tests:
               - JsonReaderTests.TestReadValidJson
 ```
 
 # Semantic IDs (MANDATORY)
 
-Use meaningful IDs following `Project-Section-ShortDesc` pattern because
+Use meaningful IDs following `System-Section-ShortDesc` pattern because
 auditors need to understand requirements without cross-referencing:
 
 - **Good**: `TemplateTool-Core-DisplayHelp`
@@ -127,12 +129,6 @@ dotnet reqstream \
   --requirements requirements.yaml \
   --lint
 
-# Enforce requirements traceability (use in CI/CD)
-dotnet reqstream \
-  --requirements requirements.yaml \
-  --tests "artifacts/**/*.trx" \
-  --enforce
-
 # Generate requirements report
 dotnet reqstream \
   --requirements requirements.yaml \
@@ -154,7 +150,7 @@ dotnet reqstream \
 
 Before submitting requirements, verify:
 
-- [ ] All requirements have semantic IDs (`Project-Section-Feature` pattern)
+- [ ] All requirements have semantic IDs (`System-Section-Feature` pattern)
 - [ ] Every requirement links to at least one passing test
 - [ ] Platform-specific requirements use source filters (`platform@TestName`)
 - [ ] Requirements specify observable behavior (WHAT), not implementation (HOW)