Sync compliance docs and lint templates with TemplateDotNetLibrary PR #67

docs/file-reviews.md

@@ -64,26 +64,30 @@ files require review and how to group them into named review-sets.
 # Patterns identifying all files that require review.
 # Processed in order; prefix a pattern with '!' to exclude.
 needs-review:
-  - "**/*.cs"
-  - "**/*.yaml"
-  - "!**/obj/**"           # exclude build output
-  - "!src/Generated/**"   # exclude auto-generated files
+  - "**/*.cs"                    # All C# source and test files
+  - "docs/design/**/*.md"        # Design documentation
+  - "docs/reqstream/**/*.yaml"   # Requirements files only
+  - "!**/obj/**"                 # exclude build output
+  - "!**/bin/**"                 # exclude binary output
 
 # Source of review evidence - see ReviewMark user guide.
 evidence-source:
   type: none
 
 reviews:
-  - id: Core-Logic
-    title: Review of core business logic
+  - id: MyProduct-PasswordValidator
+    title: Password Validator Unit Review
     paths:
-      - "src/Core/**/*.cs"
-      - "src/Core/**/*.yaml"
-      - "!src/Core/Generated/**"
-  - id: Security-Layer
-    title: Review of authentication and authorization
+      - "docs/reqstream/auth-passwordvalidator-class.yaml"
+      - "docs/design/password-validation.md"
+      - "src/Auth/PasswordValidator.cs"
+      - "test/Auth/PasswordValidatorTests.cs"
+
+  - id: MyProduct-AllRequirements
+    title: All Requirements Review
     paths:
-      - "src/Auth/**/*.cs"
+      - "requirements.yaml"
+      - "docs/reqstream/**/*.yaml"
 ```
 
 ### Key Fields
@@ -120,9 +124,8 @@ In a CI/CD pipeline, map repository secrets to those environment variables:
     REVIEWMARK_TOKEN: ${{ secrets.REVIEW_TOKEN }}
   run: >
     dotnet reviewmark
-    --definition .reviewmark.yaml
-    --plan docs/reviewplan/review-plan.md
-    --report docs/reviewreport/review-report.md
+    --plan docs/code_review_plan/plan.md
+    --report docs/code_review_report/report.md
     --enforce
 ```
 
@@ -134,32 +137,32 @@ produces one PDF release artifact and contains a hand-authored `introduction.md`
 
 | Folder | PDF Produced | Hand-authored files |
 | :----- | :----------- | :------------------ |
-| `docs/reviewplan/` | Review Plan PDF | `introduction.md`, `definition.yaml` |
-| `docs/reviewreport/` | Review Report PDF | `introduction.md`, `definition.yaml` |
+| `docs/code_review_plan/` | Review Plan PDF | `introduction.md`, `definition.yaml` |
+| `docs/code_review_report/` | Review Report PDF | `introduction.md`, `definition.yaml` |
 
-The generated markdown files (`review-plan.md`, `review-report.md`) are written by ReviewMark on
+The generated markdown files (`plan.md`, `report.md`) are written by ReviewMark on
 each CI/CD run and must **not** be committed — they are always regenerated from the current state of
 the repository.
 
 ```
 docs/
-  reviewplan/
+  code_review_plan/
     introduction.md       # hand-authored introduction for the Review Plan PDF
     definition.yaml       # Pandoc definition for the Review Plan document
-    review-plan.md        # generated by ReviewMark --plan (not committed)
-  reviewreport/
+    plan.md               # generated by ReviewMark --plan (not committed)
+  code_review_report/
     introduction.md       # hand-authored introduction for the Review Report PDF
     definition.yaml       # Pandoc definition for the Review Report document
-    review-report.md      # generated by ReviewMark --report (not committed)
+    report.md             # generated by ReviewMark --report (not committed)
 ```
 
 ### Pandoc definition.yaml examples
 
 ```yaml
-# docs/reviewplan/definition.yaml
+# docs/code_review_plan/definition.yaml
 input-files:
-  - docs/reviewplan/introduction.md
-  - docs/reviewplan/review-plan.md
+  - docs/code_review_plan/introduction.md
+  - docs/code_review_plan/plan.md
 template: docs/template/template.html
 css: docs/template/template.css
 standalone: true
@@ -170,10 +173,10 @@ metadata:
 ```
 
 ```yaml
-# docs/reviewreport/definition.yaml
+# docs/code_review_report/definition.yaml
 input-files:
-  - docs/reviewreport/introduction.md
-  - docs/reviewreport/review-report.md
+  - docs/code_review_report/introduction.md
+  - docs/code_review_report/report.md
 template: docs/template/template.html
 css: docs/template/template.css
 standalone: true
@@ -189,10 +192,9 @@ ReviewMark runs in the document generation job after all source files are in the
 
 ```bash
 dotnet reviewmark \
-  --definition .reviewmark.yaml \
-  --plan docs/reviewplan/review-plan.md \
+  --plan docs/code_review_plan/plan.md \
   --plan-depth 1 \
-  --report docs/reviewreport/review-report.md \
+  --report docs/code_review_report/report.md \
   --report-depth 1 \
   --enforce
 ```
@@ -206,41 +208,40 @@ so the review plan is available to diagnose coverage gaps.
 - name: Generate Review Documents
   run: >
     dotnet reviewmark
-    --definition .reviewmark.yaml
-    --plan docs/reviewplan/review-plan.md
+    --plan docs/code_review_plan/plan.md
     --plan-depth 1
-    --report docs/reviewreport/review-report.md
+    --report docs/code_review_report/report.md
     --report-depth 1
     --enforce
 
 - name: Generate Review Plan HTML
   run: >
     dotnet pandoc
-    --defaults docs/reviewplan/definition.yaml
+    --defaults docs/code_review_plan/definition.yaml
     --metadata version="${{ inputs.version }}"
     --metadata date="$(date +'%Y-%m-%d')"
-    --output docs/reviewplan/review-plan.html
+    --output docs/code_review_plan/plan.html
 
 - name: Generate Review Plan PDF
   run: >
     dotnet weasyprint
     --pdf-variant pdf/a-3u
-    docs/reviewplan/review-plan.html
+    docs/code_review_plan/plan.html
     "docs/MyProject Review Plan.pdf"
 
 - name: Generate Review Report HTML
   run: >
     dotnet pandoc
-    --defaults docs/reviewreport/definition.yaml
+    --defaults docs/code_review_report/definition.yaml
     --metadata version="${{ inputs.version }}"
     --metadata date="$(date +'%Y-%m-%d')"
-    --output docs/reviewreport/review-report.html
+    --output docs/code_review_report/report.html
 
 - name: Generate Review Report PDF
   run: >
     dotnet weasyprint
     --pdf-variant pdf/a-3u
-    docs/reviewreport/review-report.html
+    docs/code_review_report/report.html
     "docs/MyProject Review Report.pdf"
 ```
 
@@ -451,6 +452,63 @@ Software unit reviews are appropriate when design-requirements specify the preci
 a single class, enabling a reviewer — human or AI — to verify each requirement against its
 direct implementation and tests without noise from unrelated files.
 
+### Standard Review-Set Patterns
+
+Projects following DEMA Consulting standards use a set of named review-set types that agents and
+reviewers can recognize and rely upon:
+
++----------------------+------------------------------+----------------------------------------------------------+
+| Review-Set Type      | ID Pattern                   | Contents                                                 |
++======================+==============================+==========================================================+
+| **System**           | `[Project]-System`           | System-level requirements, design introduction,          |
+|                      |                              | system design documents, integration tests               |
++----------------------+------------------------------+----------------------------------------------------------+
+| **Design**           | `[Product]-Design`           | System-level requirements, platform requirements,        |
+|                      |                              | all design documents                                     |
++----------------------+------------------------------+----------------------------------------------------------+
+| **All Requirements** | `[Product]-AllRequirements`  | All requirement files including root                     |
+|                      |                              | `requirements.yaml`                                      |
++----------------------+------------------------------+----------------------------------------------------------+
+| **Unit**             | `[Product]-[Unit]`           | Unit requirements, design documents, source code,        |
+|                      |                              | unit tests                                               |
++----------------------+------------------------------+----------------------------------------------------------+
+
+A typical project would have one System review, one Design review, one AllRequirements review, and
+one Unit review per software unit (class). This structure gives reviewers — and review agents — a
+predictable set of entry points into the codebase:
+
+```yaml
+reviews:
+  - id: MyProduct-System
+    title: System Integration Review
+    paths:
+      - "docs/reqstream/myproduct-system.yaml"
+      - "docs/design/introduction.md"
+      - "docs/design/system.md"
+      - "tests/**/IntegrationTests.cs"
+
+  - id: MyProduct-Design
+    title: Architecture and Design Review
+    paths:
+      - "docs/reqstream/myproduct-system.yaml"
+      - "docs/reqstream/platform-requirements.yaml"
+      - "docs/design/**/*.md"
+
+  - id: MyProduct-AllRequirements
+    title: All Requirements Review
+    paths:
+      - "requirements.yaml"
+      - "docs/reqstream/**/*.yaml"
+
+  - id: MyProduct-MyComponent
+    title: MyComponent Unit Review
+    paths:
+      - "docs/reqstream/unit-mycomponent.yaml"
+      - "docs/design/mycomponent.md"
+      - "src/MyComponent.cs"
+      - "tests/MyComponentTests.cs"
+```
+
 ### Using ReviewMark with AI Review Agents
 
 The `.reviewmark.yaml` configuration makes the file grouping explicit and machine-readable, which
@@ -491,22 +549,16 @@ Shows which files are covered by which review-sets, and flags any files not cove
 ```markdown
 # Review Plan
 
-## Core-Logic
-
-**Title:** Review of core business logic
-
-| File | Status |
-| :--- | :----- |
-| src/Core/Engine.cs | ✅ Covered |
-| src/Core/Parser.cs | ✅ Covered |
-
-## Security-Layer
+## MyProduct-PasswordValidator
 
-**Title:** Review of authentication and authorization
+**Title:** Password Validator Unit Review
 
 | File | Status |
 | :--- | :----- |
-| src/Auth/AuthService.cs | ✅ Covered |
+| docs/reqstream/auth-passwordvalidator-class.yaml | ✅ Covered |
+| docs/design/password-validation.md | ✅ Covered |
+| src/Auth/PasswordValidator.cs | ✅ Covered |
+| test/Auth/PasswordValidatorTests.cs | ✅ Covered |
 
 ## Uncovered Files
 
@@ -524,6 +576,6 @@ Shows the status of each review-set — whether the evidence is current, stale,
 
 | Review | Title | Status |
 | :----- | :---- | :----- |
-| Core-Logic | Review of core business logic | ✅ Current |
-| Security-Layer | Review of authentication and authorization | ⚠️ Stale |
+| MyProduct-PasswordValidator | Password Validator Unit Review | ✅ Current |
+| MyProduct-AllRequirements | All Requirements Review | ⚠️ Stale |
 ```

docs/requirements.md

@@ -16,6 +16,8 @@ The `templates/reqstream` folder provides ready-to-use template files for a new
   .NET local tool manifest
 - [`requirements.yaml`][reqstream-root] — root requirements file that includes all files from
   `docs/reqstream/`
+- [`docs/reqstream/system-example.yaml`][reqstream-system-example] — example software system
+  requirements
 - [`docs/reqstream/subsystem-example.yaml`][reqstream-subsystem-example] — example software subsystem
   requirements
 - [`docs/reqstream/unit-example.yaml`][reqstream-unit-example] — example software unit requirements
@@ -24,17 +26,39 @@ The `templates/reqstream` folder provides ready-to-use template files for a new
 
 [reqstream-dotnet-tools]: https://github.com/demaconsulting/ContinuousCompliance/blob/main/templates/reqstream/.config/dotnet-tools.json
 [reqstream-root]: https://github.com/demaconsulting/ContinuousCompliance/blob/main/templates/reqstream/requirements.yaml
+[reqstream-system-example]: https://github.com/demaconsulting/ContinuousCompliance/blob/main/templates/reqstream/docs/reqstream/system-example.yaml
 [reqstream-subsystem-example]: https://github.com/demaconsulting/ContinuousCompliance/blob/main/templates/reqstream/docs/reqstream/subsystem-example.yaml
 [reqstream-unit-example]: https://github.com/demaconsulting/ContinuousCompliance/blob/main/templates/reqstream/docs/reqstream/unit-example.yaml
 [reqstream-ots-example]: https://github.com/demaconsulting/ContinuousCompliance/blob/main/templates/reqstream/docs/reqstream/ots-example.yaml
 
-The recommended approach is to keep a separate requirements YAML file per software subsystem, unit,
-or OTS component under `docs/reqstream/`, and list them in `requirements.yaml` using the `includes`
-field. This keeps each file focused on one component and makes reviews easier.
+The recommended approach is to keep a separate requirements YAML file per software system, subsystem,
+unit, or OTS component under `docs/reqstream/`, and list them in `requirements.yaml` using the
+`includes` field. A consistent naming convention makes the scope of each file immediately clear:
+
+```text
+docs/reqstream/
+  {project}-system.yaml         # System-level requirements
+  subsystem-{name}.yaml         # Subsystem requirements
+  unit-{name}.yaml              # Software unit (class-level) requirements
+  ots-{component}.yaml          # OTS software item requirements
+```
+
+This keeps each file focused on one component and makes reviews easier.
 
 ## Requirement Classes
 
-Requirements fall into three classes based on the component they describe:
+Requirements fall into four classes based on the component they describe:
+
+### Software System Requirements
+
+System requirements describe the complete deliverable product from the perspective of its external
+users and interfaces. They capture what the system as a whole must do — its observable behaviors,
+qualities, and constraints — without specifying how any individual subsystem or unit implements
+them. System requirements are satisfied when end-to-end or integration tests demonstrate that the
+product meets its stated obligations.
+
+The recommended approach is to keep system-level requirements in a dedicated file (e.g.,
+`docs/reqstream/{project}-system.yaml`) separate from subsystem and unit requirements.
 
 ### Software Subsystem Requirements
 

templates/lint/.cspell.yaml

@@ -32,6 +32,7 @@ ignorePaths:
   - "**/third-party/**"
   - "**/3rd-party/**"
   - "**/AGENT_REPORT_*.md"
+  - "**/.agent-logs/**"
   - "**/bin/**"
   - "**/obj/**"
   - package-lock.json

templates/lint/.gitignore

@@ -1,2 +1,3 @@
 .venv/
 node_modules/
+.agent-logs/

templates/lint/.markdownlint-cli2.yaml

@@ -44,4 +44,4 @@ ignores:
   - "**/thirdparty/**"
   - "**/third-party/**"
   - "**/3rd-party/**"
-  - "**/AGENT_REPORT_*.md"
+  - "**/.agent-logs/**"

templates/lint/lint.bat

@@ -12,17 +12,19 @@ REM - Agents execute this script to identify files needing fixes
 set "LINT_ERROR=0"
 
 REM Install npm dependencies
-call npm install
+call npm install --silent
+if errorlevel 1 set "LINT_ERROR=1"
 
 REM Create Python virtual environment (for yamllint) if missing
 if not exist ".venv\Scripts\activate.bat" (
     python -m venv .venv
 )
 call .venv\Scripts\activate.bat
-pip install -r pip-requirements.txt
+pip install -r pip-requirements.txt --quiet --disable-pip-version-check
+if errorlevel 1 set "LINT_ERROR=1"
 
 REM Run spell check
-call npx cspell --no-progress --no-color "**/*.{md,yaml,yml,json,cs,cpp,hpp,h,txt}"
+call npx cspell --no-progress --no-color --quiet "**/*.{md,yaml,yml,json,cs,cpp,hpp,h,txt}"
 if errorlevel 1 set "LINT_ERROR=1"
 
 REM Run markdownlint check

templates/lint/lint.sh

@@ -11,17 +11,17 @@
 lint_error=0
 
 # Install npm dependencies
-npm install
+npm install --silent || lint_error=1
 
 # Create Python virtual environment (for yamllint)
 if [ ! -d ".venv" ]; then
   python -m venv .venv
 fi
 source .venv/bin/activate
-pip install -r pip-requirements.txt
+pip install -r pip-requirements.txt --quiet --disable-pip-version-check || lint_error=1
 
 # Run spell check
-npx cspell --no-progress --no-color "**/*.{md,yaml,yml,json,cs,cpp,hpp,h,txt}" || lint_error=1
+npx cspell --no-progress --no-color --quiet "**/*.{md,yaml,yml,json,cs,cpp,hpp,h,txt}" || lint_error=1
 
 # Run markdownlint check
 npx markdownlint-cli2 "**/*.md" || lint_error=1