Fix AGENTS.md gaps vs template, update technical-documentation.md pat…

…hs, fix .cspell.json pattern

Agent-Logs-Url: https://github.com/demaconsulting/BuildMark/sessions/d10b0427-1ebb-4771-9ec1-223de918aa66

Co-authored-by: Malcolmnixon <1863707+Malcolmnixon@users.noreply.github.com>

.cspell.json

@@ -49,6 +49,7 @@
     "reviewmark",
     "ReviewMark",
     "SarifMark",
+    "Sarif",
     "SBOM",
     "sbom",
     "Semgrep",
@@ -86,6 +87,6 @@
     "package-lock.json",
     "yarn.lock",
     "AGENT_REPORT_*.md",
-    "**/.agent-logs/**"
+    ".agent-logs/**"
   ]
 }

.github/standards/technical-documentation.md

@@ -24,31 +24,23 @@ consistency and tool compatibility:
 
 ```text
 docs/
-  build_notes.md               # Generated by BuildMark
-  build_notes/                 # Auto-generated build notes
+  buildnotes/                  # Auto-generated build notes
+    introduction.md            # Collection introduction
     versions.md                # Generated by VersionMark
-  code_review_plan/            # Auto-generated review plans
-    plan.md                    # Generated by ReviewMark
-  code_review_report/          # Auto-generated review reports
-    report.md                  # Generated by ReviewMark
-  design/                      # Design documentation
-    introduction.md            # Design overview
-    system.md                  # System architecture
-    {component}.md             # Component-specific designs
-  reqstream/                   # Requirements source files
-    {project}-system.yaml      # System requirements
-    platform-requirements.yaml # Platform requirements
-    subsystem-{name}.yaml      # Subsystem requirements
-    unit-{name}.yaml           # Unit requirements
-    ots-{name}.yaml            # OTS requirements
-  requirements_doc/            # Auto-generated requirements reports
-    requirements.md            # Generated by ReqStream
+  guide/                       # User guide documentation
+    guide.md                   # User guide content
+  justifications/              # Auto-generated justifications
+    introduction.md            # Collection introduction
     justifications.md          # Generated by ReqStream
-  requirements_report/         # Auto-generated trace matrices
+  quality/                     # Auto-generated code quality reports
+    introduction.md            # Collection introduction
+  requirements/                # Auto-generated requirements reports
+    introduction.md            # Collection introduction
+    requirements.md            # Generated by ReqStream
+  tracematrix/                 # Auto-generated trace matrices
+    introduction.md            # Collection introduction
     trace_matrix.md            # Generated by ReqStream
-  user_guide/                  # User-facing documentation
-    introduction.md            # User guide overview
-    {section}.md               # User guide sections
+  template/                    # Design and template documentation
 ```
 
 # Pandoc Document Structure (MANDATORY)
@@ -122,9 +114,9 @@ for consistency and professional presentation:
 **NEVER modify auto-generated markdown files** because changes will be
 overwritten and break compliance automation:
 
-- **Read-Only Files**: Generated reports under `docs/requirements_doc/`,
-  `docs/requirements_report/`, `docs/code_review_plan/`, and
-  `docs/code_review_report/` are regenerated on every build
+- **Read-Only Files**: Generated reports under `docs/requirements/`,
+  `docs/justifications/`, `docs/tracematrix/`, `docs/quality/`, and
+  `docs/buildnotes/` are regenerated on every build
 - **Source Modification**: Update source files (requirements YAML, code
   comments) instead of generated output
 - **Tool Integration**: Generated content integrates with CI/CD pipelines and

AGENTS.md

@@ -27,6 +27,7 @@ Delegate to specialized agents only for specific scenarios:
 - **Formal bug resolution** (complex debugging, systematic fixes) → Call the `@implementation` agent
 - **Formal reviews** (compliance verification, detailed analysis) → Call @code-review agent
 - **Template consistency** (downstream repository alignment) → Call @repo-consistency agent
+- **Production code and self-validation tests** → Call **software-developer** agent
 - **Requirements management** → Call **Requirements Agent**
 - **Documentation updates** → Call **Technical Writer**
 - **Unit/integration tests** → Call **Test Developer**
@@ -43,10 +44,115 @@ Delegate to specialized agents only for specific scenarios:
   Consulting standards and Continuous Compliance practices
 - **repo-consistency** - Ensures BuildMark remains consistent with the
   TemplateDotNetTool template patterns and best practices
+- **software-developer** - Writes production code and self-validation tests - targets
+  design-for-testability and literate programming style
 - **Requirements Agent** - Develops requirements and ensures test coverage linkage
 - **Technical Writer** - Creates accurate documentation following regulatory best practices
 - **Test Developer** - Creates unit and integration tests following AAA pattern
 
+## Quality Gate Enforcement (ALL Agents Must Verify)
+
+Configuration files and scripts are self-documenting with their design intent and
+modification policies in header comments.
+
+1. **Linting Standards**: `./lint.sh` (Unix) or `lint.bat` (Windows) - comprehensive linting suite
+2. **Build Quality**: Zero warnings (`TreatWarningsAsErrors=true`)
+3. **Static Analysis**: SonarQube/CodeQL passing with no blockers
+4. **Requirements Traceability**: `dotnet reqstream --enforce` passing
+5. **Test Coverage**: All requirements linked to passing tests
+6. **Documentation Currency**: All docs current and generated
+7. **File Review Status**: All reviewable files have current reviews
+
+## Continuous Compliance Overview
+
+This repository follows the DEMA Consulting Continuous Compliance
+<https://github.com/demaconsulting/ContinuousCompliance> approach, which enforces quality and
+compliance gates on every CI/CD run instead of as a last-mile activity.
+
+### Core Principles
+
+- **Requirements Traceability**: Every requirement MUST link to passing tests
+- **Quality Gates**: All quality checks must pass before merge
+- **Documentation Currency**: All docs auto-generated and kept current
+- **Automated Evidence**: Full audit trail generated with every build
+
+## Required Compliance Tools
+
+### Linting Tools (ALL Must Pass)
+
+- **markdownlint-cli2**: Markdown style and formatting enforcement
+- **cspell**: Spell-checking across all text files (use `.cspell.json` for technical terms)
+- **yamllint**: YAML structure and formatting validation
+- **Language-specific linters**: Based on repository technology stack
+
+### Quality Analysis
+
+- **SonarQube/SonarCloud**: Code quality and security analysis
+- **CodeQL**: Security vulnerability scanning (produces SARIF output)
+- **Static analyzers**: Microsoft.CodeAnalysis.NetAnalyzers, SonarAnalyzer.CSharp, etc.
+
+### Requirements & Compliance
+
+- **ReqStream**: Requirements traceability enforcement (`dotnet reqstream --enforce`)
+- **ReviewMark**: File review status enforcement
+- **BuildMark**: Tool version documentation
+- **VersionMark**: Version tracking across CI/CD jobs
+
+## Key Configuration Files
+
+### Essential Files (Repository-Specific)
+
+- **`lint.sh` / `lint.bat`** - Cross-platform comprehensive linting scripts
+- **`.editorconfig`** - Code formatting rules
+- **`.cspell.json`** - Spell-check configuration and technical term dictionary
+- **`.markdownlint-cli2.jsonc`** - Markdown linting rules
+- **`.yamllint.yaml`** - YAML linting configuration
+- **`package.json`** - Node.js dependencies for linting tools
+
+### Compliance Files
+
+- **`requirements.yaml`** - Root requirements file with includes
+- **`.reviewmark.yaml`** - File review definitions and tracking
+- CI/CD pipeline files with quality gate enforcement
+
+## Continuous Compliance Workflow
+
+### CI/CD Pipeline Stages (Standard)
+
+1. **Lint**: `./lint.sh` or `lint.bat` - comprehensive linting suite
+2. **Build**: Compile with warnings as errors
+3. **Analyze**: SonarQube/SonarCloud, CodeQL security scanning
+4. **Test**: Execute all tests, generate coverage reports
+5. **Validate**: Tool self-validation tests
+6. **Document**: Generate requirements reports, trace matrix, build notes
+7. **Enforce**: Requirements traceability, file review status
+8. **Publish**: Generate final documentation (Pandoc → PDF)
+
+### Quality Gate Enforcement
+
+All stages must pass before merge. Pipeline fails immediately on:
+
+- Any linting errors
+- Build warnings or errors
+- Security vulnerabilities (CodeQL)
+- Requirements without test coverage
+- Outdated file reviews
+- Missing documentation
+
+## Continuous Compliance Requirements
+
+This repository follows continuous compliance practices from DEMA Consulting
+Continuous Compliance <https://github.com/demaconsulting/ContinuousCompliance>.
+
+### Core Requirements Traceability Rules
+
+- **ALL requirements MUST be linked to tests** - Enforced in CI via `dotnet reqstream --enforce`
+- **NOT all tests need requirement links** - Tests may exist for corner cases, design validation, failure scenarios
+- **Source filters are critical** - Platform/framework requirements need specific test evidence
+
+For detailed requirements format, test linkage patterns, and ReqStream
+integration, see the Requirements and Test Source Filters sections below.
+
 ## Tech Stack
 
 - C# (latest), .NET 8.0/9.0/10.0, MSTest, dotnet CLI, NuGet