Add verification documentation, update agents, and switch to xUnit.

.cspell.yaml

@@ -18,6 +18,7 @@ words:
   - Dema
   - fileassert
   - mstest
+  - xunit
   - netstandard
   - Newtonsoft
   - pandoc

.fileassert.yaml

@@ -1,7 +1,7 @@
 ---
 # FileAssert document validation tests for NuGetCaching.
 # Tests are tagged by document group to allow per-group execution during the build pipeline.
-# Tags: build-notes, code-quality, code-review, design, user-guide, requirements.
+# Tags: build-notes, code-quality, code-review, design, verification, user-guide, requirements.
 #
 # NOTE: build-notes through user-guide tests provide OTS evidence for Pandoc and WeasyPrint
 # and run before ReqStream. The requirements tests run after ReqStream and validate the
@@ -15,7 +15,7 @@ tests:
     description: "Build Notes HTML was generated by Pandoc"
     tags: [build-notes]
     files:
-      - pattern: "docs/build_notes/build_notes.html"
+      - pattern: "docs/build_notes/generated/build_notes.html"
         count: 1
         html:
           - query: "//head/title"
@@ -27,7 +27,7 @@ tests:
     description: "Build Notes PDF was generated by WeasyPrint"
     tags: [build-notes]
     files:
-      - pattern: "docs/NuGetCaching Build Notes.pdf"
+      - pattern: "docs/generated/NuGetCaching Build Notes.pdf"
         count: 1
         pdf:
           metadata:
@@ -48,7 +48,7 @@ tests:
     description: "Code Quality HTML was generated by Pandoc"
     tags: [code-quality]
     files:
-      - pattern: "docs/code_quality/quality.html"
+      - pattern: "docs/code_quality/generated/quality.html"
         count: 1
         html:
           - query: "//head/title"
@@ -60,7 +60,7 @@ tests:
     description: "Code Quality PDF was generated by WeasyPrint"
     tags: [code-quality]
     files:
-      - pattern: "docs/NuGetCaching Code Quality.pdf"
+      - pattern: "docs/generated/NuGetCaching Code Quality.pdf"
         count: 1
         pdf:
           metadata:
@@ -81,7 +81,7 @@ tests:
     description: "Code Review Plan HTML was generated by Pandoc"
     tags: [code-review]
     files:
-      - pattern: "docs/code_review_plan/plan.html"
+      - pattern: "docs/code_review_plan/generated/plan.html"
         count: 1
         html:
           - query: "//head/title"
@@ -93,7 +93,7 @@ tests:
     description: "Code Review Plan PDF was generated by WeasyPrint"
     tags: [code-review]
     files:
-      - pattern: "docs/NuGetCaching Review Plan.pdf"
+      - pattern: "docs/generated/NuGetCaching Review Plan.pdf"
         count: 1
         pdf:
           metadata:
@@ -114,7 +114,7 @@ tests:
     description: "Code Review Report HTML was generated by Pandoc"
     tags: [code-review]
     files:
-      - pattern: "docs/code_review_report/report.html"
+      - pattern: "docs/code_review_report/generated/report.html"
         count: 1
         html:
           - query: "//head/title"
@@ -126,7 +126,7 @@ tests:
     description: "Code Review Report PDF was generated by WeasyPrint"
     tags: [code-review]
     files:
-      - pattern: "docs/NuGetCaching Review Report.pdf"
+      - pattern: "docs/generated/NuGetCaching Review Report.pdf"
         count: 1
         pdf:
           metadata:
@@ -147,7 +147,7 @@ tests:
     description: "Design HTML was generated by Pandoc"
     tags: [design]
     files:
-      - pattern: "docs/design/design.html"
+      - pattern: "docs/design/generated/design.html"
         count: 1
         html:
           - query: "//head/title"
@@ -159,7 +159,7 @@ tests:
     description: "Design PDF was generated by WeasyPrint"
     tags: [design]
     files:
-      - pattern: "docs/NuGetCaching Software Design.pdf"
+      - pattern: "docs/generated/NuGetCaching Software Design.pdf"
         count: 1
         pdf:
           metadata:
@@ -174,13 +174,46 @@ tests:
           text:
             - contains: "Design"
 
+  # --- VERIFICATION DOCUMENT ---
+
+  - name: Pandoc_VerificationHtml
+    description: "Verification HTML was generated by Pandoc"
+    tags: [verification]
+    files:
+      - pattern: "docs/verification/generated/verification.html"
+        count: 1
+        html:
+          - query: "//head/title"
+            count: 1
+        text:
+          - contains: "Verification"
+
+  - name: WeasyPrint_VerificationPdf
+    description: "Verification PDF was generated by WeasyPrint"
+    tags: [verification]
+    files:
+      - pattern: "docs/generated/NuGetCaching Verification Design.pdf"
+        count: 1
+        pdf:
+          metadata:
+            - field: "Title"
+              contains: "Verification"
+            - field: "Author"
+              contains: "DEMA Consulting"
+            - field: "Subject"
+              contains: "Verification design document"
+          pages:
+            min: 3
+          text:
+            - contains: "Verification"
+
   # --- USER GUIDE ---
 
   - name: Pandoc_UserGuideHtml
     description: "User Guide HTML was generated by Pandoc"
     tags: [user-guide]
     files:
-      - pattern: "docs/user_guide/user_guide.html"
+      - pattern: "docs/user_guide/generated/user_guide.html"
         count: 1
         html:
           - query: "//head/title"
@@ -192,7 +225,7 @@ tests:
     description: "User Guide PDF was generated by WeasyPrint"
     tags: [user-guide]
     files:
-      - pattern: "docs/NuGetCaching User Guide.pdf"
+      - pattern: "docs/generated/NuGetCaching User Guide.pdf"
         count: 1
         pdf:
           metadata:
@@ -214,7 +247,7 @@ tests:
     description: "Requirements HTML was generated by Pandoc"
     tags: [requirements]
     files:
-      - pattern: "docs/requirements_doc/requirements.html"
+      - pattern: "docs/requirements_doc/generated/requirements.html"
         count: 1
         html:
           - query: "//head/title"
@@ -226,7 +259,7 @@ tests:
     description: "Requirements PDF was generated by WeasyPrint"
     tags: [requirements]
     files:
-      - pattern: "docs/NuGetCaching Requirements.pdf"
+      - pattern: "docs/generated/NuGetCaching Requirements.pdf"
         count: 1
         pdf:
           metadata:
@@ -248,7 +281,7 @@ tests:
     description: "Trace Matrix HTML was generated by Pandoc"
     tags: [requirements]
     files:
-      - pattern: "docs/requirements_report/trace_matrix.html"
+      - pattern: "docs/requirements_report/generated/trace_matrix.html"
         count: 1
         html:
           - query: "//head/title"
@@ -260,7 +293,7 @@ tests:
     description: "Trace Matrix PDF was generated by WeasyPrint"
     tags: [requirements]
     files:
-      - pattern: "docs/NuGetCaching Trace Matrix.pdf"
+      - pattern: "docs/generated/NuGetCaching Trace Matrix.pdf"
         count: 1
         pdf:
           metadata:

.github/agents/developer.agent.md

@@ -21,7 +21,7 @@ Perform software development tasks by determining and applying appropriate stand
 5. **Formatting**: Run `pwsh ./fix.ps1` to silently apply all
    available auto-fixers (dotnet format, markdown, YAML) before committing
 6. **Build and test** (code changes only): Run `pwsh ./build.ps1` and confirm it
-   passes — report FAILED if the build or any tests fail
+   passes - report FAILED if the build or any tests fail
 7. **Generate completion report** per the AGENTS.md reporting requirements - save to
    `.agent-logs/{agent-name}-{subject}-{unique-id}.md` and return the summary to the caller
 

.github/agents/formal-review.agent.md

@@ -20,6 +20,8 @@ Before reviewing, read these standards to inform review judgments:
   hierarchy and categorization review judgments
 - **`design-documentation.md`** - defines mandatory sections, structural conventions,
   and coverage expected at each level; informs all design documentation review judgments
+- **`verification-documentation.md`** - defines mandatory sections, structural conventions,
+  and coverage expected at each level; informs all verification design review judgments
 
 For review sets that include source code or tests, also consult the relevant
 standards from the selection matrix in AGENTS.md.

.github/agents/lint-fix.agent.md

@@ -36,7 +36,12 @@ submission, not during normal development.
 
 - **markdownlint MD013 (line length)**: Wrap long lines at natural break points,
   after commas, before conjunctions, or at sentence boundaries. Do not break
-  in the middle of a code span or URL.
+  in the middle of a code span or URL. **Pipe-tables that cannot be wrapped
+  without breaking structure** are a special case - convert them to a bullet
+  list if the data reads naturally that way, or rewrite as a
+  [grid table](https://pandoc.org/MANUAL.html#tables) if a tabular layout is
+  essential. Do not get stuck trying to squeeze a wide pipe-table into 120
+  characters.
 
 - **markdownlint other rules**: Apply the specific fix indicated in the output
   (e.g., missing blank lines, heading levels, code fence languages).

.github/pull_request_template.md

@@ -26,21 +26,19 @@ Before submitting this pull request, ensure you have completed the following:
 
 ### Build and Test
 
-- [ ] Code builds successfully: `dotnet build --configuration Release`
-- [ ] All unit tests pass: `dotnet test --configuration Release`
+- [ ] Code builds successfully and all tests pass: `pwsh ./build.ps1`
 - [ ] Code produces zero warnings
 
 ### Code Quality
 
-- [ ] Code formatting is correct: `dotnet format --verify-no-changes`
 - [ ] New code has appropriate XML documentation comments
 - [ ] Static analyzer warnings have been addressed
 
 ### Quality Checks
 
 Please run the following checks before submitting:
 
-- [ ] **All linters pass**: `./lint.sh` (Unix/macOS) or `cmd /c lint.bat` / `./lint.bat` (Windows)
+- [ ] **All linters pass**: `pwsh ./lint.ps1`
 
 ### Testing
 
@@ -52,7 +50,7 @@ Please run the following checks before submitting:
 ### Documentation
 
 - [ ] Updated README.md (if applicable)
-- [ ] Updated ARCHITECTURE.md (if applicable)
+- [ ] Updated docs/ documentation (if applicable)
 - [ ] Added code examples for new features (if applicable)
 - [ ] Updated requirements.yaml (if applicable)
 

.github/standards/coding-principles.md

@@ -20,11 +20,35 @@ All code MUST follow literate programming principles:
   matches design intent without reading the full codebase
 - **Logical Separation**: Complex functions use block comments to separate and
   describe logical steps within the implementation
-- **Public Documentation**: All public interfaces have comprehensive documentation
-  because consumers and auditors rely on interface contracts for integration
-  and compliance verification
+- **Full Symbol Documentation**: ALL symbols have comprehensive documentation
+  because reviewers and auditors must verify every implementation detail, not
+  just the public interface - access-level specifics (public, protected,
+  private, internal, etc.) vary by language; see the language-specific standard
 - **Clarity Over Cleverness**: Code should be immediately understandable by team members
 
+## API Documentation
+
+Good API documentation enables consumers, reviewers, and agents to use an
+interface correctly without reading the implementation:
+
+- **Self-Contained**: Each member's documentation must be fully understandable
+  in isolation - consumers must not need to read the implementation to call it
+  correctly
+- **Intent-Focused**: Explain WHY the member exists and WHAT problem it solves,
+  not just restate the name - this lets reviewers verify the implementation
+  matches design intent
+- **Parameter and Return Contracts**: Document valid ranges, null handling, and
+  boundary cases - agents and consumers rely on these contracts to call the API
+  correctly
+- **Error Conditions**: Document every exception or error code, the condition
+  that triggers it, and how the caller should respond - undocumented errors
+  cannot be handled correctly
+- **Side Effects**: Document I/O, state mutation, resource allocation, or
+  network calls - hidden side effects cause integration bugs that are hard to
+  diagnose
+- **Thread Safety**: State whether the API is safe for concurrent use - missing
+  this forces consumers to read the implementation or risk data races
+
 ## Universal Code Architecture Principles
 
 ### Design Patterns