fix: reclassify FileAssert from OTS to Shared Package and fix test names

FileAssert cannot treat its own published package as an OTS item. Per the
software-items standard, a package produced by the same program consumed in
CI is a Shared Package. Additionally, the self-validation test names
FileAssert_Exists and FileAssert_Contains no longer exist; they were renamed
to FileAssert_File and FileAssert_Text when validation was refactored into
per-assertion-type files.

Changes:
- Move docs/reqstream/ots/fileassert.yaml to docs/reqstream/shared/
- Rename requirement ID from FileAssert-OTS-FileAssert to
  FileAssert-Shared-FileAssert with tag [shared]
- Replace FileAssert_Exists and FileAssert_Contains with FileAssert_File,
  FileAssert_Text, FileAssert_Html, and FileAssert_Pdf to cover the assertion
  types actually used by this project
- Move design and verification docs from ots/ to shared/ folders
- Add shared.md overview documents for design and verification sections
- Update docs/design/ots.md to remove FileAssert and add clarifying note
- Update docs/verification/ots.md to remove FileAssert references
- Update both definition.yaml files for correct document assembly
- Update docs/design/introduction.md to document Shared Package artifacts
- Update .reviewmark.yaml review set from FileAssert-OTS-FileAssert to
  FileAssert-Shared-FileAssert with corrected paths
- Update requirements.yaml include path

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: 2 people

.reviewmark.yaml

@@ -335,13 +335,13 @@ reviews:
       - "docs/design/ots/buildmark.md"                               # OTS design
       - "docs/verification/ots/buildmark.md"                         # OTS verification
 
-  # FileAssert-OTS-FileAssert Review
-  - id: FileAssert-OTS-FileAssert
-    title: Review FileAssert OTS FileAssert Requirements and Verification
+  # FileAssert-Shared-FileAssert Review
+  - id: FileAssert-Shared-FileAssert
+    title: Review FileAssert Shared Package FileAssert Requirements and Verification
     paths:
-      - "docs/reqstream/ots/fileassert.yaml"                         # OTS requirements
-      - "docs/design/ots/fileassert.md"                              # OTS design
-      - "docs/verification/ots/fileassert.md"                        # OTS verification
+      - "docs/reqstream/shared/fileassert.yaml"                      # Shared Package requirements
+      - "docs/design/shared/fileassert.md"                           # Shared Package design
+      - "docs/verification/shared/fileassert.md"                     # Shared Package verification
 
   # FileAssert-OTS-Pandoc Review
   - id: FileAssert-OTS-Pandoc

docs/design/definition.yaml

@@ -29,7 +29,6 @@ input-files:
   - docs/design/file-assert/ots-dependencies.md
   - docs/design/ots.md
   - docs/design/ots/buildmark.md
-  - docs/design/ots/fileassert.md
   - docs/design/ots/pandoc.md
   - docs/design/ots/reqstream.md
   - docs/design/ots/reviewmark.md
@@ -38,6 +37,8 @@ input-files:
   - docs/design/ots/versionmark.md
   - docs/design/ots/weasyprint.md
   - docs/design/ots/xunit.md
+  - docs/design/shared.md
+  - docs/design/shared/fileassert.md
 template: template.html
 table-of-contents: true
 number-sections: true

docs/design/introduction.md

@@ -149,6 +149,14 @@ FileAssert integrates the third-party library; their artifacts sit parallel to s
 - Design: `docs/design/ots/{ots-name}.md`
 - Verification: `docs/verification/ots/{ots-name}.md`
 
+Shared packages (earlier releases of the same program's own packages consumed in CI) have
+integration/usage design docs at `docs/design/shared/{package-name}.md`; their artifacts also
+sit parallel to system and OTS folders:
+
+- Requirements: `docs/reqstream/shared/{package-name}.yaml`
+- Design: `docs/design/shared/{package-name}.md`
+- Verification: `docs/verification/shared/{package-name}.md`
+
 Review-sets: defined in `.reviewmark.yaml`
 
 ## References

docs/design/ots.md

@@ -25,7 +25,6 @@ builds and provides an audit record of which tool version produced each release
 | OTS Item    | Role                                                                         |
 | :---------- | :--------------------------------------------------------------------------- |
 | BuildMark   | Generates build-notes documentation from GitHub Actions metadata             |
-| FileAssert  | Validates generated HTML and PDF documents against acceptance criteria       |
 | Pandoc      | Converts Markdown source documents to HTML for each document collection      |
 | ReqStream   | Enforces requirements traceability against TRX test-result files             |
 | ReviewMark  | Generates review plan and review report from the review configuration        |
@@ -35,12 +34,15 @@ builds and provides an audit record of which tool version produced each release
 | WeasyPrint  | Converts HTML documents to PDF for release artifact archiving                |
 | xUnit       | Discovers, executes, and reports unit tests; produces TRX output             |
 
+> **Note**: FileAssert is not an OTS item for this project. Because this project consumes an
+> earlier released version of its own package in CI, it is classified as a **Shared Package**.
+> See the _Shared Package Integration Design_ section for details.
+
 ## Per-Item Design
 
 Detailed design for each OTS item is provided in the following sections of this document:
 
 - See _BuildMark OTS Design_ for the build-notes generation tool.
-- See _FileAssert OTS Design_ for the document assertion tool.
 - See _Pandoc OTS Design_ for the Markdown-to-HTML conversion tool.
 - See _ReqStream OTS Design_ for the requirements traceability enforcement tool.
 - See _ReviewMark OTS Design_ for the review plan and report generation tool.
@@ -83,7 +85,7 @@ manifest outside of the design artifact set.
 
 OTS items in this project fall into two integration categories:
 
-- **dotnet global tools** (BuildMark, FileAssert, Pandoc, ReqStream, ReviewMark, SarifMark,
+- **dotnet global tools** (BuildMark, Pandoc, ReqStream, ReviewMark, SarifMark,
   SonarMark, VersionMark, WeasyPrint) — installed globally in the CI environment via
   `dotnet tool restore` from `.config/dotnet-tools.json` and invoked as command-line executables
   within GitHub Actions workflow steps. No wrapper code is written; tools are invoked directly

docs/design/shared.md

@@ -0,0 +1,28 @@
+# Shared Package Integration Design
+
+FileAssert uses one shared package from within the same program: an earlier released version of
+itself. This section describes the integration strategy and usage design for this package.
+
+## Integration Strategy
+
+A **Shared Package** is a software package produced by the same program (repository), consumed as
+a pinned released version rather than built from source. Unlike an OTS item, a shared package is
+developed in-house; unlike in-scope source code, the consuming repository references its advertised
+features rather than its internal design.
+
+FileAssert consumes a previous release of itself as a dotnet global tool installed via
+`.config/dotnet-tools.json`. This is a deliberate dogfooding practice: the CI pipeline uses a
+stable released build of the tool to validate the in-development build's documentation outputs,
+while the in-development build is what produces the next release.
+
+## Shared Package Summary
+
+| Package     | Role                                                                         |
+| :---------- | :--------------------------------------------------------------------------- |
+| FileAssert  | Validates generated HTML and PDF documents against acceptance criteria       |
+
+## Per-Package Design
+
+Detailed integration design is provided in the following section of this document:
+
+- See _FileAssert Shared Package Design_ for the document assertion tool.

docs/design/ots/fileassert.md docs/design/shared/fileassert.mddocs/design/ots/fileassert.md renamed to docs/design/shared/fileassert.md

@@ -1,15 +1,16 @@
-## FileAssert OTS Design
+## FileAssert Shared Package Design
 
-DemaConsulting.FileAssert is the tool developed by this project and is also consumed as an OTS
-item within its own CI pipeline to validate the correctness of the documents it generates and to
-produce self-validation evidence.
+DemaConsulting.FileAssert is the tool developed by this project. An earlier released version of it
+is also consumed within this project's own CI pipeline to validate generated documents and to
+produce self-validation evidence. Because this repository uses its own published package, it is
+classified as a **Shared Package** rather than OTS.
 
 ### Purpose
 
 FileAssert validates HTML and PDF documents produced during the build pipeline, asserting that
 each document exists, has a non-trivial size, is structurally valid, and contains expected
 content. Its built-in self-validation suite (`--validate`) is run as a CI step to produce TRX
-test evidence satisfying the `FileAssert-OTS-FileAssert` requirement.
+test evidence satisfying the `FileAssert-Shared-FileAssert` requirement.
 
 FileAssert is chosen because it directly implements the project's own document-assertion
 capability, making its CI use a natural dogfooding exercise that simultaneously validates the
@@ -42,7 +43,7 @@ The project uses the following FileAssert command-line interfaces:
 | `dotnet fileassert --validate --results <trx-file>`          | Runs self-validation and writes TRX results        |
 | `dotnet fileassert --config <file> --results <trx-file>`     | Runs document assertions from a YAML configuration |
 
-The TRX output from `--results` is consumed by ReqStream to satisfy `FileAssert-OTS-FileAssert`.
+The TRX output from `--results` is consumed by ReqStream to satisfy `FileAssert-Shared-FileAssert`.
 
 ### Dependencies
 

docs/reqstream/ots/fileassert.yaml docs/reqstream/shared/fileassert.yamldocs/reqstream/ots/fileassert.yaml renamed to docs/reqstream/shared/fileassert.yaml

@@ -1,28 +1,35 @@
 ---
-# FileAssert OTS Software Requirements
+# FileAssert Shared Package Software Requirements
 #
 # Requirements for the FileAssert document assertion tool functionality.
+# FileAssert is classified as a Shared Package because this repository uses an earlier
+# released version of itself in CI - a project cannot treat its own package as OTS.
 
 sections:
-  - title: OTS Software Requirements
+  - title: Shared Package Software Requirements
     sections:
       - title: FileAssert Requirements
         requirements:
-          - id: FileAssert-OTS-FileAssert
+          - id: FileAssert-Shared-FileAssert
             title: FileAssert shall validate generated documents against acceptance criteria.
             justification: |
               DemaConsulting.FileAssert validates HTML and PDF documents produced during the
               build, asserting that each document exists, is structurally valid, has correct
-              metadata, and contains expected content. It provides OTS evidence for Pandoc and
-              WeasyPrint and independently confirms file assertion is functioning. Self-validation
-              proves the tool itself is operational before ReqStream consumes the results.
-            tags: [ots]
+              metadata, and contains expected content. It provides verification evidence for
+              Pandoc and WeasyPrint and independently confirms file assertion is functioning.
+              Self-validation proves the tool itself is operational before ReqStream consumes
+              the results.
+            tags: [shared]
             # Test IDs below are sourced from the tool's `--validate` self-validation TRX output
             # (artifacts/<tool>-self-validation*.trx in CI). Each ID matches a TestCase Name in
             # the TRX; ReqStream consumes the artifacts/**/*.trx glob.
+            # Tests are selected to cover the specific assertion types used by this project:
+            # file existence (count), text content, HTML structure, and PDF metadata/pages/text.
             tests:
               - FileAssert_VersionDisplay
               - FileAssert_HelpDisplay
               - FileAssert_Results
-              - FileAssert_Exists
-              - FileAssert_Contains
+              - FileAssert_File
+              - FileAssert_Text
+              - FileAssert_Html
+              - FileAssert_Pdf

docs/verification/definition.yaml

@@ -29,7 +29,6 @@ input-files:
   - docs/verification/file-assert/selftest/validation.md
   - docs/verification/ots.md
   - docs/verification/ots/buildmark.md
-  - docs/verification/ots/fileassert.md
   - docs/verification/ots/pandoc.md
   - docs/verification/ots/reqstream.md
   - docs/verification/ots/reviewmark.md
@@ -38,6 +37,8 @@ input-files:
   - docs/verification/ots/versionmark.md
   - docs/verification/ots/weasyprint.md
   - docs/verification/ots/xunit.md
+  - docs/verification/shared.md
+  - docs/verification/shared/fileassert.md
 template: template.html
 table-of-contents: true
 number-sections: true

docs/verification/ots.md

@@ -11,8 +11,8 @@ OTS software items used by FileAssert are verified by one of two complementary a
 depending on the nature of the item:
 
 - **Authored integration tests**: Items whose correct behaviour cannot be inferred purely from
-  pipeline success (xUnit, FileAssert) are verified by named test scenarios that exercise the
-  specific features required by this project. Each scenario identifies a test method, the expected
+  pipeline success (xUnit) are verified by named test scenarios that exercise the specific
+  features required by this project. Each scenario identifies a test method, the expected
   outcome, and the requirement it covers.
 
 - **CI pipeline evidence**: Items whose primary function is to produce artefacts consumed by
@@ -32,10 +32,6 @@ The following evidence is collected and retained for each OTS item:
 - **xUnit**: TRX result files generated by `dotnet test` during CI. Each TRX file is consumed by
   `reqstream --enforce` to confirm that all named test scenarios have a recorded passing result.
 
-- **FileAssert**: The self-validation TRX file (`artifacts/fileassert-self-validation.trx`)
-  produced by `fileassert --validate --results` during CI. This file is also consumed by
-  `reqstream --enforce`.
-
 - **All other OTS items**: A passing CI pipeline run, including Pandoc HTML generation, WeasyPrint
   PDF rendering, FileAssert assertions on every generated document, and `reqstream --enforce` with
   no unmet requirements. The combined CI log and artefacts constitute the qualification record.
@@ -63,9 +59,6 @@ The following OTS software items are used by FileAssert and are verified in this
 - **BuildMark** — generates a markdown build-notes document from GitHub Actions workflow metadata,
   verified by CI pipeline success and downstream document validation.
 
-- **FileAssert** — validates generated HTML and PDF documents for existence, size, structure, and
-  content; verified by self-validation tests and transitive pipeline evidence.
-
 - **Pandoc** — converts Markdown source documents to HTML as part of the documentation build;
   verified by FileAssert assertions on each generated HTML document.