Agent updates next

.cspell.yaml

@@ -42,6 +42,7 @@ ignorePaths:
   - "**/thirdparty/**"
   - "**/third-party/**"
   - "**/3rd-party/**"
+  - "**/generated/**"
   - "**/AGENT_REPORT_*.md"
   - "**/.agent-logs/**"
   - "**/bin/**"

.fileassert.yaml

@@ -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/TemplateDotNetLibrary Build Notes.pdf"
+      - pattern: "docs/generated/TemplateDotNetLibrary 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/TemplateDotNetLibrary Code Quality.pdf"
+      - pattern: "docs/generated/TemplateDotNetLibrary 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/TemplateDotNetLibrary Review Plan.pdf"
+      - pattern: "docs/generated/TemplateDotNetLibrary 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/TemplateDotNetLibrary Review Report.pdf"
+      - pattern: "docs/generated/TemplateDotNetLibrary 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/TemplateDotNetLibrary Software Design.pdf"
+      - pattern: "docs/generated/TemplateDotNetLibrary Software Design.pdf"
         count: 1
         pdf:
           metadata:
@@ -180,7 +180,7 @@ tests:
     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 +192,7 @@ tests:
     description: "User Guide PDF was generated by WeasyPrint"
     tags: [user-guide]
     files:
-      - pattern: "docs/TemplateDotNetLibrary User Guide.pdf"
+      - pattern: "docs/generated/TemplateDotNetLibrary User Guide.pdf"
         count: 1
         pdf:
           metadata:
@@ -214,7 +214,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 +226,7 @@ tests:
     description: "Requirements PDF was generated by WeasyPrint"
     tags: [requirements]
     files:
-      - pattern: "docs/TemplateDotNetLibrary Requirements.pdf"
+      - pattern: "docs/generated/TemplateDotNetLibrary Requirements.pdf"
         count: 1
         pdf:
           metadata:
@@ -248,7 +248,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 +260,7 @@ tests:
     description: "Trace Matrix PDF was generated by WeasyPrint"
     tags: [requirements]
     files:
-      - pattern: "docs/TemplateDotNetLibrary Trace Matrix.pdf"
+      - pattern: "docs/generated/TemplateDotNetLibrary Trace Matrix.pdf"
         count: 1
         pdf:
           metadata:

.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/standards/coding-principles.md

@@ -25,6 +25,29 @@ All code MUST follow literate programming principles:
   and compliance verification
 - **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

.github/standards/csharp-language.md

@@ -16,25 +16,57 @@ Read these standards first before applying this standard:
 
 - **Source Files**: `**/*.cs`
 
-# Literate Coding Example
+# API Documentation and Literate Coding Example
+
+The example below demonstrates good XmlDoc API documentation combined with
+literate coding comments.
 
 ```csharp
-// Validate input parameters to prevent downstream errors
-if (string.IsNullOrEmpty(input))
+/// <summary>
+///     Converts a raw sensor reading into a validated measurement ready for downstream consumers.
+/// </summary>
+/// <remarks>
+///     Clamping is preferred over throwing on out-of-range values because sensor drift at
+///     range boundaries is expected; clamping produces a usable result where rejection would
+///     discard valid near-boundary readings. Stateless and thread-safe; the calibration
+///     profile is read but never modified.
+/// </remarks>
+/// <param name="reading">Raw sensor value. Must be finite (NaN and infinities are rejected).</param>
+/// <param name="calibration">Calibration profile providing offset and range. Must not be null.</param>
+/// <returns>Corrected value clamped to [calibration.Minimum, calibration.Maximum].</returns>
+/// <exception cref="ArgumentException">Thrown when <paramref name="reading"/> is NaN or infinite.</exception>
+/// <exception cref="ArgumentNullException">Thrown when <paramref name="calibration"/> is null.</exception>
+public double ProcessReading(double reading, CalibrationProfile calibration)
 {
-    throw new ArgumentException("Input cannot be null or empty", nameof(input));
-}
-
-// Transform input data using the configured processing pipeline
-var processedData = ProcessingPipeline.Transform(input);
+    // Reject invalid inputs before any calculation - non-finite readings cannot be
+    // corrected, and a null calibration profile provides no offset or range to apply
+    if (!double.IsFinite(reading))
+        throw new ArgumentException("Reading must be a finite number.", nameof(reading));
+    ArgumentNullException.ThrowIfNull(calibration);
 
-// Apply business rules and validation logic
-var validatedResults = BusinessRuleEngine.ValidateAndProcess(processedData);
+    // Apply the calibration offset to convert raw counts to physical units
+    var corrected = reading + calibration.Offset;
 
-// Return formatted results matching the expected output contract
-return OutputFormatter.Format(validatedResults);
+    // Clamp to the operational range so consumers can rely on the documented contract
+    return Math.Clamp(corrected, calibration.Minimum, calibration.Maximum);
+}
 ```
 
+Key qualities demonstrated above:
+
+- **`<summary>`** is a brief one-liner explaining *what* the method does
+- **`<remarks>`** sits directly after summary and carries the extended intent —
+  *why* it exists, design decisions, thread-safety, and side-effect disclosures
+- **`<param>` tags** state constraints (finite, non-null) so callers know what
+  is valid without reading the body
+- **`<returns>`** documents the boundary guarantee so consumers can rely on the
+  contract
+- **`<exception>` tags** name every thrown exception and the condition that
+  triggers each one
+- **Inline block comments** follow the Literate Coding principles from
+  `coding-principles.md`, separating logical steps so reviewers can verify each
+  step against design intent
+
 # Code Formatting
 
 - **Format entire solution**: `dotnet format`

.github/standards/design-documentation.md

@@ -108,6 +108,13 @@ src/Project2Name/
 └── HelperClass.cs              - Helper functions
 ```
 
+### References Section (RECOMMENDED)
+
+If the design references external documents (standards, specifications), include
+a `## References` section in `introduction.md`. This is the **only** place in the
+design document collection where a References section should appear — do not add
+one to any other design file.
+
 ### Companion Artifact Structure (RECOMMENDED)
 
 Include a brief note explaining that each software item has parallel artifacts
@@ -168,6 +175,9 @@ 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
+- **Verbal Cross-References**: Reference other parts of the design by name (e.g.,
+  "See *Parser Design* for more details") — do not use markdown hyperlinks, which
+  break in compiled PDFs
 
 # Mermaid Diagram Integration
 

.github/standards/reqstream-usage.md

@@ -104,16 +104,16 @@ dotnet reqstream --requirements requirements.yaml --lint
 
 # Generate requirements document for compliance record
 dotnet reqstream --requirements requirements.yaml \
-  --report docs/requirements_doc/requirements.md
+  --report docs/requirements_doc/generated/requirements.md
 
 # Generate justifications document for compliance record
 dotnet reqstream --requirements requirements.yaml \
-  --justifications docs/requirements_doc/justifications.md
+  --justifications docs/requirements_doc/generated/justifications.md
 
 # Generate trace matrix proving each requirement is covered by passing tests
 dotnet reqstream --requirements requirements.yaml \
   --tests "artifacts/**/*.trx" \
-  --matrix docs/requirements_report/trace_matrix.md
+  --matrix docs/requirements_report/generated/trace_matrix.md
 ```
 
 # Quality Checks

.github/standards/requirements-principles.md

@@ -29,6 +29,10 @@ implementation code.
 - **Valid**: "The parser shall report the line number of the first syntax error."
 - **Not a requirement (design decision)**: "The parser shall use a `TokenStream` class."
 
+A unit may use its own name freely — that is identity, not HOW. What is
+forbidden is describing *internal construction*: class names, method signatures,
+algorithms, or data structures.
+
 # Requirements at Every Level (MANDATORY)
 
 Every identified subsystem and unit MUST have its own requirements file because

.github/standards/reviewmark-usage.md

@@ -20,7 +20,7 @@ review, organizes them into review-sets, and generates review plans and reports.
 
 - **Lint Configuration**: `dotnet reviewmark --lint`
 - **Elaborate Review-Set**: `dotnet reviewmark --elaborate {review-set}`
-- **Generate Plan**: `dotnet reviewmark --plan docs/code_review_plan/plan.md --enforce`
+- **Generate Plan**: `dotnet reviewmark --plan docs/code_review_plan/generated/plan.md --enforce`
 
 > **Note**: `--enforce` causes the plan to fail with a non-zero exit code if any repository
 > files are not covered by a review-set. Uncovered files indicate a gap in review-set
@@ -31,7 +31,8 @@ review, organizes them into review-sets, and generates review plans and reports.
 Required repository items for ReviewMark operation:
 
 - `.reviewmark.yaml` - Configuration for review-sets, file-patterns, and review evidence-source.
-- `docs/code_review_plan/` - Review planning artifacts
+- `docs/code_review_plan/generated/` - Generated review plan (build output, do not edit)
+- `docs/code_review_report/generated/` - Generated review report (build output, do not edit)
 
 # Review Definition Structure