From 94155853c049b5b1808dff10ee0a2e7e53557e2c Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Sat, 11 Jul 2026 10:02:20 -0400 Subject: [PATCH 1/4] Add SysML2 architecture model and remediate documentation compliance gaps - Wire sysml2tools into dotnet-tools.json, .versionmark.yaml, lint.ps1, and the build.yaml design job (render Software Structure diagrams to docs/design/generated before Pandoc HTML generation) - Add docs/sysml2/ model (system + Demo unit) and design-views (Software Structure and TemplateDotNetLibrary views) - Embed rendered SVG diagrams in docs/design/introduction.md and the system/unit design docs - Extensively refactor docs/design/introduction.md to follow the template (Purpose, Scope, Software Structure, Folder Layout, Document Conventions, Companion Artifact Structure, References) - Extensively refactor .reviewmark.yaml with new context blocks and review-sets (Purpose, Decomposition, Architecture, Design, Verification, AllRequirements, Demo, and per-OTS-item sets) - Move system-level design/reqstream/verification docs to top level to match the reference template convention, fix heading depths and mandatory sections in design/verification docs, and add the missing OTS design (docs/design/ots.md + docs/design/ots/*.md) and verification (docs/verification/ots.md) documentation - Remove an unrequested/untraceable NuGet package metadata interface claim from the system design flagged by formal review Verified via dotnet reqstream/versionmark/reviewmark/sysml2tools --lint, markdownlint-cli2, cspell, yamllint, dotnet format, and formal-review agents (gpt-5.4-mini) across all affected review-sets. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .config/dotnet-tools.json | 6 + .cspell.yaml | 1 + .github/agents/developer.agent.md | 9 +- .github/agents/formal-review.agent.md | 13 +- .github/agents/implementation.agent.md | 54 ++-- .github/agents/lint-fix.agent.md | 3 +- .github/agents/planning.agent.md | 134 ++++++++++ .github/agents/quality.agent.md | 92 +++---- .github/agents/software-architect.agent.md | 2 +- .github/agents/template-sync.agent.md | 142 ++++++++++ .github/skills/sysml2tools-query/SKILL.md | 145 +++++++++++ .github/standards/coding-principles.md | 18 +- .github/standards/csharp-language.md | 3 - .github/standards/csharp-testing.md | 2 - .github/standards/design-documentation.md | 242 ++++++------------ .github/standards/reqstream-usage.md | 114 +++++---- .github/standards/reviewmark-usage.md | 235 ++++++++++------- .github/standards/software-items.md | 88 +++++-- .github/standards/sysml2-modeling.md | 232 +++++++++++++++++ .github/standards/technical-documentation.md | 77 +++--- .github/standards/testing-principles.md | 5 - .../standards/verification-documentation.md | 155 +++++------ .github/workflows/build.yaml | 10 +- .reviewmark.yaml | 187 +++++++++----- .versionmark.yaml | 5 + AGENTS.md | 84 +++--- docs/design/definition.yaml | 13 +- docs/design/introduction.md | 54 ++-- docs/design/ots.md | 33 +++ docs/design/ots/buildmark.md | 24 ++ docs/design/ots/fileassert.md | 24 ++ docs/design/ots/pandoc.md | 25 ++ docs/design/ots/reqstream.md | 26 ++ docs/design/ots/reviewmark.md | 31 +++ docs/design/ots/sarifmark.md | 23 ++ docs/design/ots/sonarmark.md | 23 ++ docs/design/ots/versionmark.md | 25 ++ docs/design/ots/weasyprint.md | 22 ++ docs/design/ots/xunit.md | 22 ++ .../template-dot-net-library.md | 64 +++-- docs/design/template-dot-net-library/demo.md | 37 ++- .../template-dot-net-library.yaml | 0 .../model/template-dot-net-library.sysml | 18 ++ .../model/template-dot-net-library/demo.sysml | 11 + docs/sysml2/views/design-views.sysml | 14 + docs/verification/definition.yaml | 3 +- docs/verification/introduction.md | 22 +- docs/verification/ots.md | 28 ++ .../template-dot-net-library.md | 18 +- .../template-dot-net-library/demo.md | 45 ++-- lint.ps1 | 7 +- requirements.yaml | 2 +- 52 files changed, 1895 insertions(+), 777 deletions(-) create mode 100644 .github/agents/planning.agent.md create mode 100644 .github/agents/template-sync.agent.md create mode 100644 .github/skills/sysml2tools-query/SKILL.md create mode 100644 .github/standards/sysml2-modeling.md create mode 100644 docs/design/ots.md create mode 100644 docs/design/ots/buildmark.md create mode 100644 docs/design/ots/fileassert.md create mode 100644 docs/design/ots/pandoc.md create mode 100644 docs/design/ots/reqstream.md create mode 100644 docs/design/ots/reviewmark.md create mode 100644 docs/design/ots/sarifmark.md create mode 100644 docs/design/ots/sonarmark.md create mode 100644 docs/design/ots/versionmark.md create mode 100644 docs/design/ots/weasyprint.md create mode 100644 docs/design/ots/xunit.md rename docs/design/{template-dot-net-library => }/template-dot-net-library.md (56%) rename docs/reqstream/{template-dot-net-library => }/template-dot-net-library.yaml (100%) create mode 100644 docs/sysml2/model/template-dot-net-library.sysml create mode 100644 docs/sysml2/model/template-dot-net-library/demo.sysml create mode 100644 docs/sysml2/views/design-views.sysml create mode 100644 docs/verification/ots.md rename docs/verification/{template-dot-net-library => }/template-dot-net-library.md (75%) diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json index 337f9ec..7ccda75 100644 --- a/.config/dotnet-tools.json +++ b/.config/dotnet-tools.json @@ -61,6 +61,12 @@ "commands": [ "fileassert" ] + }, + "demaconsulting.sysml2tools.tool": { + "version": "0.1.0-beta.5", + "commands": [ + "sysml2tools" + ] } } } \ No newline at end of file diff --git a/.cspell.yaml b/.cspell.yaml index e6115d4..c774d06 100644 --- a/.cspell.yaml +++ b/.cspell.yaml @@ -28,6 +28,7 @@ words: - SARIF - sarifmark - sonarmark + - sysml - versionmark - Weasy - WeasyPrint diff --git a/.github/agents/developer.agent.md b/.github/agents/developer.agent.md index a95c562..5f2b988 100644 --- a/.github/agents/developer.agent.md +++ b/.github/agents/developer.agent.md @@ -14,8 +14,12 @@ Perform software development tasks by determining and applying appropriate stand 2. **Read relevant standards** using the selection matrix in AGENTS.md 3. **Pre-flight verification** before making any changes: - List files that will be created, modified, or deleted + - For each file to be **created**, check whether a counterpart exists in the + template (URL in the `# Reference Template` section of `AGENTS.md`). + If one exists, fetch it as the starting point; adjust placeholder names and heading + depth to match the target path before writing the file - For each modified file, identify which companion artifacts need updating - (requirements, design docs, tests, review-sets) + (requirements, design docs, verification docs, tests, review-sets, README.md, user guides) - Include companion artifact updates in the work plan 4. **Execute work** following standards requirements and quality checks 5. **Formatting**: Run `pwsh ./fix.ps1` to silently apply all @@ -31,8 +35,7 @@ Perform software development tasks by determining and applying appropriate stand # Developer Agent Report **Result**: (SUCCEEDED|FAILED) - -## Work Summary +**Report**: `.agent-logs/developer-{subject}-{unique-id}.md` - **Files Modified**: {List of files created/modified/deleted} - **Languages Detected**: {Languages identified} diff --git a/.github/agents/formal-review.agent.md b/.github/agents/formal-review.agent.md index 7dd8e84..cb78ddf 100644 --- a/.github/agents/formal-review.agent.md +++ b/.github/agents/formal-review.agent.md @@ -31,12 +31,14 @@ standards from the selection matrix in AGENTS.md. 1. Download the review checklist from . If the download fails, report the failure rather than proceeding without the template. -2. Use `dotnet reviewmark --elaborate {review-set}` to get the files to review -3. Review all files holistically, checking for cross-file consistency and - compliance with the review checklist -4. Save the populated review checklist to `.agent-logs/reviews/review-report-{review-set}.md`. +2. Run `dotnet reviewmark --elaborate {review-set}`. Read all files listed under + `## Context` first — these are reference material, not under review — then review + all files listed under `## Files` holistically, using the context to understand + the intended role and scope within the broader system, and checking for cross-file + consistency and compliance with the review checklist. +3. Save the populated review checklist to `.agent-logs/reviews/review-report-{review-set}.md`. This directory holds formal review artifacts, not agent logs. -5. Generate a completion report per the AGENTS.md reporting requirements. +4. Generate a completion report per the AGENTS.md reporting requirements. # Report Template @@ -44,6 +46,7 @@ standards from the selection matrix in AGENTS.md. # Formal Review Report **Result**: (SUCCEEDED|FAILED) +**Report**: `.agent-logs/formal-review-{subject}-{unique-id}.md` ## Review Summary diff --git a/.github/agents/implementation.agent.md b/.github/agents/implementation.agent.md index 7cc0352..d94e880 100644 --- a/.github/agents/implementation.agent.md +++ b/.github/agents/implementation.agent.md @@ -28,36 +28,18 @@ The state-transitions include retrying a limited number of times: ## PLANNING State (start) -Call the **explore** agent as a sub-agent (built-in agent type) with: +Call the **planning** agent as a sub-agent (custom agent from `.github/agents/`) with: - **context**: the user's request + any previous quality findings + retry context -- **goal**: produce a verified implementation plan through these steps: - - 1. Investigate the codebase and develop a concrete implementation plan that - addresses the request - 2. **Identify companion artifact deliverables**: for every code change in the - plan, list the requirements files, design documents, and review-set entries - that must be created or updated - traceability must flow requirements → - design → code, so these are mandatory deliverables, not optional extras - 3. Review the plan for assumptions, weaknesses, and gaps - identify up to 5 - key assumptions and rate each as: - - **VERIFIED**: confirmed by codebase evidence - - **LIKELY**: consistent with codebase patterns but not directly confirmed - - **UNVERIFIED**: not confirmed by any evidence - 4. For any assumption rated UNVERIFIED or LIKELY, attempt to resolve it - through additional investigation and revise the plan to address identified - weaknesses - repeat the critique-and-strengthen cycle up to 2 additional - times if unresolved issues remain, but stop as soon as the plan is stable - 5. List up to 5 risks to the implementation - 6. Assess feasibility: can this be implemented in a single development pass? - 7. State a **recommendation**: GO or INCOMPLETE - GO if the plan is sound, or - INCOMPLETE if critical unknowns remain that only the user can resolve - -Once the explore sub-agent finishes: - -- IF recommendation is INCOMPLETE: Transition to REPORT with Result: INCOMPLETE, +- **goal**: produce a verified implementation plan, or a targeted plan to address + the identified quality issues if this is a retry + +Once the planning sub-agent finishes: + +- IF Result is FAILED: Transition to REPORT with Result: FAILED +- IF Result is INCOMPLETE: Transition to REPORT with Result: INCOMPLETE, listing the unknowns and what CAN be implemented once they are resolved -- OTHERWISE (GO): Transition to DEVELOPMENT +- OTHERWISE (SUCCEEDED): Transition to DEVELOPMENT ## DEVELOPMENT State @@ -76,7 +58,8 @@ Once the developer sub-agent finishes: Call the **quality** agent as a sub-agent (custom agent from `.github/agents/`) with: -- **context**: the user's request + development summary + files changed + previous issues (if any) +- **context**: the user's request + development summary + files changed + planning companion artifact table + + previous issues (if any) - **goal**: check the quality of the work performed for any issues Once the quality sub-agent finishes: @@ -92,6 +75,9 @@ Once the quality sub-agent finishes: this agent may report INCOMPLETE when the request cannot be implemented without information only the user can provide. +For full planning details (assumptions, risks, feasibility), read the planning +report file referenced in the planning agent's response. + Generate the completion report using the template below, then save it to `.agent-logs/{agent-name}-{subject}-{unique-id}.md` per the AGENTS.md reporting requirements, and return the summary to the caller. @@ -102,19 +88,20 @@ requirements, and return the summary to the caller. # Implementation Orchestration Report **Result**: (SUCCEEDED|FAILED|INCOMPLETE) -**Final State**: (PLANNING|DEVELOPMENT|QUALITY|REPORT) +**Report**: `.agent-logs/implementation-{subject}-{unique-id}.md` +**Last Active State**: (PLANNING|DEVELOPMENT|QUALITY) **Retry Count**: ## State Machine Execution -- **Planning Results**: {Implementation plan, assumption ratings, risks, and recommendation} +- **Planning Results**: {Planning report path; plan summary and SUCCEEDED/INCOMPLETE/FAILED result} - **Development Results**: {Summary of developer agent results} - **Quality Results**: {Summary of quality agent results} - **State Transitions**: {Log of state changes and decisions} ## Sub-Agent Coordination -- **Explore Agent (Planning)**: {Plan, assumption verdicts, top risks, GO/INCOMPLETE recommendation} +- **Planning Agent**: {Report file path, SUCCEEDED/INCOMPLETE/FAILED result, plan summary} - **Developer Agent**: {Development status and files modified} - **Quality Agent**: {Validation results and compliance status} @@ -123,4 +110,9 @@ requirements, and return the summary to the caller. - **Implementation Success**: {Overall completion status} - **Quality Compliance**: {Final quality validation status} - **Issues Resolved**: {Problems encountered and resolution attempts} + +## Unknowns (only when Result is INCOMPLETE) + +- **Unresolved Questions**: {List each question the user must answer} +- **What Can Proceed**: {Work that can be done without the missing information} ``` diff --git a/.github/agents/lint-fix.agent.md b/.github/agents/lint-fix.agent.md index 549e751..36d3ca1 100644 --- a/.github/agents/lint-fix.agent.md +++ b/.github/agents/lint-fix.agent.md @@ -68,8 +68,7 @@ submission, not during normal development. # Lint Fix Report **Result**: (SUCCEEDED|FAILED) - -## Summary +**Report**: `.agent-logs/lint-fix-{subject}-{unique-id}.md` - **Iterations**: {Number of fix-loop iterations performed} - **Files Modified**: {List of all files changed} diff --git a/.github/agents/planning.agent.md b/.github/agents/planning.agent.md new file mode 100644 index 0000000..20e75ee --- /dev/null +++ b/.github/agents/planning.agent.md @@ -0,0 +1,134 @@ +--- +name: planning +description: Planning agent that investigates the codebase, develops a verified implementation plan, and identifies all companion artifact deliverables. +user-invocable: true +--- + +# Planning Agent + +Investigate the codebase and produce a verified implementation plan with all +companion artifact deliverables. + +## Step 1 — Load Standards + +Read the relevant standards from `.github/standards/` using the selection matrix +in `AGENTS.md` based on the artifact types in scope for the request (requirements, +design, verification, documentation, code). + +## Step 2 — Investigate and Plan + +Read `docs/design/introduction.md` first (if present), then investigate the +codebase to develop a concrete implementation plan: + +- Identify all files to create, modify, or delete +- Describe the change required for each file + +## Step 3 — Identify Companion Artifact Deliverables + +For each planned change, assess the mandatory companion artifacts below (create/update/N/A +with justification): + +- **Requirements** — functional changes require a requirement entry +- **Design Documentation** — new or changed components require design docs +- **Verification Documentation** — new or changed components require verification docs +- **Tests** — functional changes require test coverage +- **Review Sets** — changes to the software item hierarchy (units or subsystems + added, removed, or reorganized) require review-set updates +- **README.md** — user-facing changes require README updates +- **User Guide** — user-facing features require user guide updates + +## Step 4 — Critique and Strengthen + +Identify up to 5 key assumptions and rate each: + +- **VERIFIED**: confirmed by codebase evidence +- **LIKELY**: consistent with codebase patterns but not directly confirmed +- **UNVERIFIED**: not confirmed by any evidence + +For UNVERIFIED or LIKELY assumptions, investigate further and revise the plan. +Repeat up to 2 more times, stopping when the plan is stable. + +## Step 5 — Risk Assessment + +List up to 5 risks with a brief mitigation for each. + +## Step 6 — Feasibility Assessment + +State whether this can be implemented in a single development pass and any +preconditions that affect feasibility. + +## Step 7 — Recommendation + +- **SUCCEEDED** — the plan is sound and the developer agent can proceed +- **INCOMPLETE** — critical unknowns remain that only the user can resolve; + list each unknown explicitly +- **FAILED** — investigation could not produce a viable plan + +# REPORT Phase + +Save the full analysis to `.agent-logs/planning-{subject}-{unique-id}.md` per +the AGENTS.md reporting requirements. + +Then respond to the caller with ONLY the lean structured summary below. + +# Report Template + +```markdown +# Planning Report + +**Result**: (SUCCEEDED|INCOMPLETE|FAILED) +**Request Summary**: {Brief restatement of the task as understood} +**Report**: `.agent-logs/planning-{subject}-{unique-id}.md` + +## Implementation Plan + +| File | Action | Description | +|------|--------|-------------| +| {path} | create/modify/delete | {what changes and why} | + +## Companion Artifact Deliverables + +| Category | File | Action | +|----------|------|--------| +| Requirements | {path} | create/update/N/A — {justification} | +| Design Documentation | {path} | create/update/N/A — {justification} | +| Verification Documentation | {path} | create/update/N/A — {justification} | +| Tests | {path} | create/update/N/A — {justification} | +| Review Sets | {path} | create/update/N/A — {justification} | +| README.md | {path} | create/update/N/A — {justification} | +| User Guide | {path} | create/update/N/A — {justification} | + +## Assumption Analysis + +| # | Assumption | Rating | Resolution | +|---|-----------|--------|------------| +| 1 | {assumption} | VERIFIED/LIKELY/UNVERIFIED | {resolution or N/A} | + +## Risk Assessment + +1. **[severity]** {risk} — {mitigation} + +## Feasibility Assessment + +{Single-pass or not, and why. Any preconditions.} + +## Unknowns + +{Only present when Result is INCOMPLETE. List each question the user must +resolve before implementation can proceed.} +``` + +# Lean Structured Response (returned to caller) + +```markdown +**Result**: (SUCCEEDED|INCOMPLETE|FAILED) +**Report**: `.agent-logs/planning-{subject}-{unique-id}.md` + +**Plan**: +{Repeat the Implementation Plan table} + +**Companion Artifacts**: +{Repeat the Companion Artifact Deliverables table} + +**Unknowns**: {Only if INCOMPLETE — list questions for the user} +``` diff --git a/.github/agents/quality.agent.md b/.github/agents/quality.agent.md index da467d4..26fd251 100644 --- a/.github/agents/quality.agent.md +++ b/.github/agents/quality.agent.md @@ -13,14 +13,23 @@ Grade and validate software development work by ensuring compliance with project 1. **Analyze the task request AND completed work** to determine scope: identify which artifact categories were changed, and which *should have been changed* given the task - new user-visible features always require requirements, - design, and review-set coverage regardless of whether those files were touched; - test-only additions (corner-case tests, defensive boundary tests, regression - tests) do not require a corresponding requirement + design, verification docs, and README/user guide updates regardless of + whether those files were touched; Review Sets are always in scope when + the software item hierarchy changes (units or subsystems added, removed, or + reorganized); test-only additions (corner-case tests, defensive boundary + tests, regression tests) do not require a corresponding requirement; if a + planning companion artifact table is provided in context, cross-reference it + — any artifact listed as create/update must be covered in the evaluation and + FAIL if the artifact was not produced 2. **Read relevant standards** using the selection matrix in AGENTS.md 3. **Evaluate all in-scope categories** - N/A only when the task genuinely cannot affect a category; if the task introduces new user-visible features or - structural changes then Requirements, Design Documentation, and Review - Management are always in scope and FAIL if the artifacts were not updated + structural changes then Requirements, Design Documentation, and Verification + Documentation are always in scope and FAIL if the artifacts were not updated; + Documentation (README/user guide) is always in scope for user-facing changes + and FAIL if not updated; Review Sets are always in scope when the + software item hierarchy changes (units or subsystems added, removed, or + reorganized) and FAIL if review-sets were not updated 4. **Validate tool compliance** using ReqStream, ReviewMark, and build tools 5. **Generate focused quality report** per the AGENTS.md reporting requirements - save to `.agent-logs/{agent-name}-{subject}-{unique-id}.md` and return the summary to the caller @@ -36,6 +45,7 @@ For each checklist item in the template below, record as `(PASS|FAIL|N/A) - {one # Quality Assessment Report **Result**: (SUCCEEDED|FAILED) +**Report**: `.agent-logs/quality-{subject}-{unique-id}.md` **Overall Grade**: (PASS|FAIL) ## Required Fixes (only when Result is FAILED) @@ -50,25 +60,17 @@ Priority-ordered list of issues that MUST be resolved for the next retry: - **Evaluated**: {List sections assessed and why} - **Skipped**: {One-line per skipped section with reason, e.g., "Design - Documentation: N/A - no design files modified"} + Documentation: N/A - no component behavior, structure, or interface changed"} ## Requirements Compliance: (PASS|FAIL|N/A) -- Were requirements updated to reflect functional changes? -- Were new requirements created for new features? -- Do requirement IDs follow semantic naming standards? -- Do requirement files follow kebab-case naming convention? -- Are requirement files organized under `docs/reqstream/` with proper folder structure? -- Are OTS requirements properly placed in `docs/reqstream/ots/` subfolder? -- Were source filters applied appropriately for platform-specific requirements? -- Is requirements traceability maintained to tests? +- Were requirements created/updated for all functional changes? +- Were source filters applied for platform-specific requirements? +- Is forward traceability from requirements to verification artifacts preserved? ## Design Documentation Compliance: (PASS|FAIL|N/A) -- Were design documents updated for architectural changes? -- Were new design artifacts created for new components? -- Do design folder names use kebab-case convention matching source structure? -- Are design files properly named ({subsystem-name}.md, {unit-name}.md patterns)? +- Were design artifacts created/updated for all new or changed components? - Is `docs/design/introduction.md` present with required Software Structure section? - Are design decisions documented with rationale? - Is system/subsystem/unit categorization maintained? @@ -76,55 +78,57 @@ Priority-ordered list of issues that MUST be resolved for the next retry: ## Code Quality Compliance: (PASS|FAIL|N/A) -- Are language-specific standards followed (from applicable standards files)? -- Are quality checks from standards files satisfied? -- Is code properly categorized (system/subsystem/unit/OTS)? -- Is appropriate separation of concerns maintained? -- Was language-specific build tooling executed and passing? +- Do language-specific quality checks from loaded standards pass? +- Is code properly categorized (system/subsystem/unit/OTS/Shared Package)? +- Does the build pass? ## Testing Compliance: (PASS|FAIL|N/A) - Were tests created/updated for all functional changes? - Is test coverage maintained for all requirements? -- Are testing standards followed (AAA pattern, etc.)? -- Do tests respect software item hierarchy boundaries (System/Subsystem/Unit scope)? +- Do tests respect software item hierarchy boundaries? - Are cross-hierarchy test dependencies documented in design docs? -- Does test categorization align with code structure? -- Do all tests pass without failures? +- Do all tests pass? -## Review Management Compliance: (PASS|FAIL|N/A) +## Verification Documentation Compliance: (PASS|FAIL|N/A) -- Were review-sets updated for structural changes (new/deleted systems, subsystems, or units)? -- Do file patterns follow include-then-exclude approach? +- Were verification documents created/updated for all new or changed components? +- Do verification documents include all mandatory sections (Verification Approach, Test Environment, + Acceptance Criteria, Test Scenarios)? +- Is requirements-to-test coverage tracked via the ReqStream trace matrix (not embedded in verification docs)? + +## Review Sets Compliance: (PASS|FAIL|N/A) + +- Were review-sets updated for structural changes? - Is review scope appropriate for change magnitude? -- Was ReviewMark tooling executed and passing? -- Were review artifacts generated correctly? +- Does ReviewMark pass? ## Documentation Compliance: (PASS|FAIL|N/A) -- Was README.md updated for user-facing changes? -- Were user guides updated for feature changes? +- Were README.md and user guides updated for user-facing changes? - Does API documentation reflect code changes? - Was compliance documentation generated? -- Does documentation follow standards formatting? -- Is documentation organized under `docs/` following standard folder structure? -- Do Pandoc collections include proper `introduction.md` with Purpose and Scope sections? - Are auto-generated markdown files left unmodified? -- Do README.md files use absolute URLs and include concrete examples? -- Is documentation integrated into ReviewMark review-sets for formal review? +- Is documentation integrated into ReviewMark review-sets? ## Software Item Completeness: (PASS|FAIL|N/A) +- Load `software-items.md` before evaluating this section. + - Does every identified software unit have its own requirements file? - Does every identified software unit have its own design document? - Does every identified subsystem have its own requirements file? - Does every identified subsystem have its own design document? +## Repository Structure Compliance: (PASS|FAIL|N/A) + +- Load `repository-map.md` from the template URL in the `# Reference Template` + section of `AGENTS.md` before evaluating this section. + +- Are parallel artifact trees in sync (reqstream/design/verification/src/test)? +- Does the repository conform to the template `repository-map.md`? + ## Process Compliance: (PASS|FAIL|N/A) -- Was Continuous Compliance workflow followed? -- Did all quality gates execute successfully? -- Were appropriate tools used for validation? -- Were standards consistently applied across work? -- Was compliance evidence generated and preserved? +- Was compliance evidence (test results, review artifacts, generated docs) generated and preserved? ``` diff --git a/.github/agents/software-architect.agent.md b/.github/agents/software-architect.agent.md index 494568d..de5efa2 100644 --- a/.github/agents/software-architect.agent.md +++ b/.github/agents/software-architect.agent.md @@ -13,7 +13,7 @@ Interview the user and produce evolving architecture documentation with prioriti # Standards Read `.github/standards/software-items.md` before starting. Use its definitions -(Software Package, System, Subsystem, Unit, OTS) as vocabulary throughout. +(Software Package, System, Subsystem, Unit, OTS, Shared Package) as vocabulary throughout. # Approach diff --git a/.github/agents/template-sync.agent.md b/.github/agents/template-sync.agent.md new file mode 100644 index 0000000..baf5fa8 --- /dev/null +++ b/.github/agents/template-sync.agent.md @@ -0,0 +1,142 @@ +--- +name: template-sync +description: Audits or synchronizes repository files against the canonical template. + Supports four modes - Audit, Sync, Scaffold, and Recreate. +user-invocable: true +--- + +# Template Sync Agent + +This agent is an orchestrator supporting four modes: + +- **Audit** - report structural deviations; no changes +- **Sync** - patch missing sections into existing files +- **Scaffold** - create files that do not yet exist; skip existing files +- **Recreate** - rebuild existing files from the template, migrating old content + +Read the template URL and `repository-map.md` from the `# Reference Template` +section in `AGENTS.md`, then map the requested scope onto the work groups below. +Delegate each group to a sub-agent. + +# Work Groups + +- **Root config files** - all non-collection files at the repository root +- **`docs/sysml2/`** - SysML2 model files and rendered views (root-level flat folder, + not a Pandoc collection) +- **One group per flat `docs/` folder** - e.g. `docs/build_notes/`, `docs/user_guide/` +- **One group for root files in each of `docs/design/`, `docs/verification/`, + `docs/reqstream/`** - e.g. `docs/design/introduction.md` — separate from the + system subtrees beneath them +- **One group per system subtree** in `docs/design/`, `docs/verification/`, `docs/reqstream/` - + each subtree and all its descendants is one group + +# Orchestration + +For Audit mode, call an **explore** sub-agent (built-in) per group. +For Sync, Scaffold, and Recreate modes, call a **general-purpose** sub-agent (built-in) per group. + +For each group intersecting the requested scope, call the appropriate sub-agent with: + +- **context**: + - Group scope and template URL from the `# Reference Template` section in `AGENTS.md` + - Applicable standards from the `# Standards Application` matrix in `AGENTS.md` + for the file types in the group scope + - Project-specific names substitute for placeholders at matching path depth + (e.g. `MySystem` → `{SystemName}`, `my-system` → `{system-name}`) + - For files within `{system-name}/` subtrees in `docs/design/`, `docs/verification/`, + and `docs/reqstream/`: consult `docs/design/introduction.md` to determine whether + each item is a subsystem or unit, then select the appropriate template + (`subsystem-name.*` or `unit-name.*`) regardless of the item's folder depth — + do not infer item type from path depth alone + - If a file has no template counterpart, skip it and report it as + "No template found" — this is not a failure + - If a file appears in `repository-map.md` but its template cannot be fetched, + report Result: FAILED and list the affected files +- **goal**: + - Based on the given mode: + - **Audit** - fetch each template counterpart; compare headings; report missing + sections and depth mismatches; no changes + - **Sync** - as Audit, then insert each missing section; run `pwsh ./fix.ps1` + - **Scaffold** - fetch `repository-map.md` from the template URL in `AGENTS.md` + to identify files that should exist but don't; for each, fetch the template, + populate all sections, write the file; run `pwsh ./fix.ps1` + - **Recreate** - fetch the template and use it as the blueprint for a + freshly authored document: + - Work through the template section by section; for each section, find + any `TEMPLATE-DIRECTIVE` blocks (both `` + in markdown and `# ` in YAML) — execute + each directive (read specified standards, apply structural guidance, + substitute content), then **remove the directive block entirely** from + the output; gather the relevant technical details from all available + sources — the old file, README, related docs, sibling files, and any + other repo context — to populate that section correctly; the old file's + structure and headings are irrelevant; only its factual content is mined + as a source + - **Gap-check**: after all template sections are filled, scan the old + file once more for any technical information not yet captured; if + found, preserve it by appending new relevant sections at the end + - **Before writing**: do a mandatory self-check — for every section that + has a `TEMPLATE-DIRECTIVE` block in the template, explicitly state what + format the directive requires, then verify the drafted content matches + that format exactly (e.g. if the directive says "no sub-headings", + confirm there are no `###` headings inside that section; if it says + "bold-name paragraph blocks", confirm each entry is `**Name**: prose` + with no sub-heading); fix any mismatches before writing the file + - Write the rebuilt file; run `pwsh ./fix.ps1` + - When writing any section: `TEMPLATE-DIRECTIVE` blocks are directives — + execute them (read specified standards, apply structural guidance, substitute + content) and **remove the block entirely** from the written file; inline + `TODO:` placeholders in YAML string values (e.g. `title:`, `justification:`) + are content placeholders — always resolve them to real content; infer from + README, related files, sibling docs, and path; if confident write directly; + if ambiguous, **do not ask interactively** — return the unresolved questions + in the result so the orchestrator can ask the user and re-invoke; never leave + a TODO or TEMPLATE-DIRECTIVE in the output unless the user explicitly requests it + - Return results in this format for each file in the group: + + ```markdown + ### {file-path} + + - **Template**: {template path or "not found"} + - **Missing sections**: {list or "none"} + - **Heading depth issues**: {list or "none"} + - **Content format issues**: {list or "none"} *(Recreate only)* + - **Action**: (Reported | Sections added | Created | Rebuilt | No template found) + - **Unresolved Questions**: {list or "none"} + ``` + +If any sub-agent returns unresolved questions, collect them, ask the user, then +re-invoke the affected sub-agent(s) with the answers before assembling the final report. +If questions remain unresolved after asking the user, report Result: INCOMPLETE. + +Collect sub-agent results and assemble the final report. + +# Report Template + +```markdown +# Template Sync Report + +**Result**: (SUCCEEDED|FAILED|INCOMPLETE) +**Report**: `.agent-logs/template-sync-{subject}-{unique-id}.md` +**Mode**: (Audit|Sync|Scaffold|Recreate) + +## Files + +### {file-path} + +- **Template**: {template path} +- **Missing sections**: {list or "none"} +- **Heading depth issues**: {list or "none"} +- **Content format issues**: {list of sections where intra-section content did not + match the template comment's prescribed format, or "none"} *(Recreate only)* +- **Action**: (Reported | Sections added | Created | Rebuilt | No template found) +- **Unresolved Questions**: {list or "none"} + +## Summary + +- **Conformant**: {count} | **Deviations**: {count} | **Updated**: {count} + +## Unknowns (only when Result is INCOMPLETE) + +- **Unresolved Questions**: {List each placeholder or ambiguity the user must resolve} +``` diff --git a/.github/skills/sysml2tools-query/SKILL.md b/.github/skills/sysml2tools-query/SKILL.md new file mode 100644 index 0000000..f754338 --- /dev/null +++ b/.github/skills/sysml2tools-query/SKILL.md @@ -0,0 +1,145 @@ +--- +name: sysml2tools-query +description: Query this repository's SysML2 architecture model (docs/sysml2/) to understand software structure, purpose, and relationships before deep-diving into source code. Use this when asked to understand the codebase, find which unit implements something, assess the impact of a change, or trace requirements to code. +--- + +# SysML2Tools Query Skill + +This repository models its software structure in SysML2 under `docs/sysml2/`. Prefer +querying this model over grepping/reading source files when you need to understand +*what* a piece of the system is, *why* it exists, or *what it depends on*. + +## Prerequisites + +The `sysml2tools` CLI is a local .NET tool pinned in `.config/dotnet-tools.json`. +Restore it once per session if not already available: + +```pwsh +dotnet tool restore +``` + +## Model files + +- `docs/sysml2/model/{system-name}.sysml` — system-level `part def` only (no subsystems/units + inline). A repository may contain more than one system. +- `docs/sysml2/model/{system-name}/{subsystem-name}.sysml` and + `docs/sysml2/model/{system-name}/{subsystem-name}/{unit-name}.sysml` — one file per + Subsystem/Unit, nested to mirror the same folder depth as that item's companion + `docs/design/`, `docs/reqstream/`, and `docs/verification/` files. +- `docs/sysml2/model/ots.sysml` — off-the-shelf (OTS) dependency parts (present when OTS items + exist). +- `docs/sysml2/model/shared.sysml` — Shared Package parts (present when Shared Package items + exist). +- `docs/sysml2/views/design-views.sysml` — named views rendered for the design document; a + sibling of `model/`, not nested inside it. Not usually needed for query workflows, but + useful to see how diagrams are scoped. + +Always pass all `.sysml` files (or a glob covering them) to every `sysml2tools` +invocation — the model spans multiple files and cross-references between them; files that +reopen the same `package Name { ... }` from different files merge into one namespace +automatically, no `import` required. As of `sysml2tools` 0.1.0-beta.5, every subcommand +(`lint`, `render`, `query`) expands `*`/`**` glob patterns internally and recurses +correctly — pass a single **quoted** glob string and let the tool resolve it, rather than +relying on the shell (quoting works identically in both PowerShell and bash): + +```pwsh +dotnet sysml2tools query list 'docs/sysml2/model/**/*.sysml' +``` + +## Artifact-location metadata + +Every System/Subsystem/Unit `part def` carries named `comment` elements pointing at its +companion artifacts (source, test, design, verification, and — for repositories that still +use ReqStream — requirements file). `query describe` returns every comment attached to +an element, so one query gets you every artifact location for that item without grepping the +source tree: + +```pwsh +dotnet sysml2tools query describe -e {SystemName}::{UnitName} 'docs/sysml2/model/**/*.sysml' +``` + +```text +- Documentation: One-line purpose statement for the unit. +- Comment: Source: src/{Project}/{Subsystem}/{UnitName}.cs +- Comment: Test: test/{Project}.Tests/{Subsystem}/{UnitName}Tests.cs +- Comment: Design: docs/design/{system-name}/{subsystem-name}/{unit-name}.md +- Comment: Verification: docs/verification/{system-name}/{subsystem-name}/{unit-name}.md +- Comment: Requirements: docs/reqstream/{system-name}/{subsystem-name}/{unit-name}.yaml +``` + +Not every item has all five comments — Systems/Subsystems have no `Source` comment, and +units without a dedicated companion doc point at their parent's doc instead (see the +Artifact-Location Comments section of `sysml2-modeling.md` for the full rules). Prefer these +paths over guessing a file location from the unit name; fall back to `grep`/`glob` only when +a comment is missing or the model is stale. + +## Recommended workflow + +1. **Discover the system(s) present** — do not assume a fixed name: + + ```pwsh + dotnet sysml2tools query list --kind "part def" 'docs/sysml2/model/**/*.sysml' + ``` + + Look for the top-level part def with no containing part (or the one with the most + children) to identify each system's qualified name. + +2. **Get the full hierarchy** (subsystems and units) for a system found above: + + ```pwsh + dotnet sysml2tools query describe -e 'docs/sysml2/model/**/*.sysml' + ``` + + `describe` lists direct children and every artifact-location comment; repeat on each + child to walk deeper, or use `query list` to see the full flat inventory. + +3. **Understand a specific unit's purpose and find its files** before opening its source + file — `describe` returns both the purpose `doc` and every `Comment:` artifact-location + line in one call (see Artifact-location metadata above): + + ```pwsh + dotnet sysml2tools query describe -e 'docs/sysml2/model/**/*.sysml' + ``` + +4. **Assess impact before editing a unit** — see what depends on it: + + ```pwsh + dotnet sysml2tools query used-by -e 'docs/sysml2/model/**/*.sysml' + dotnet sysml2tools query impact -e 'docs/sysml2/model/**/*.sysml' + ``` + + Note: this only surfaces structural (typing/containment) references modeled in + `.sysml` — not full call-graph/behavioral dependencies. Confirm actual usage in source + before making impact-sensitive changes. + +5. **Trace requirements** linked to a unit, if modeled: + + ```pwsh + dotnet sysml2tools query requirements -e 'docs/sysml2/model/**/*.sysml' + ``` + +6. **Search by name or kind** when the qualified name is unknown: + + ```pwsh + dotnet sysml2tools query find --name 'docs/sysml2/model/**/*.sysml' + dotnet sysml2tools query list --kind "part def" 'docs/sysml2/model/**/*.sysml' + ``` + +Use `--format json` on any query verb for machine-parsed output. + +## Fallback + +If the model is stale, doesn't yet cover a unit, or a query returns nothing useful, fall +back to `grep`/`glob`/reading source directly. When you finish work that adds or changes a +Unit/Subsystem, update the corresponding `.sysml` model file (including its artifact-location +comments) in the same change (mirrors the existing requirement to keep `docs/design/*.md` and +`docs/reqstream/*.yaml` companion artifacts in sync). See the `sysml2-modeling.md` +standard for full modeling and view-authoring conventions. + +## Validating changes to the model + +Before committing changes to any `.sysml` file, lint it: + +```pwsh +dotnet sysml2tools lint 'docs/sysml2/**/*.sysml' +``` diff --git a/.github/standards/coding-principles.md b/.github/standards/coding-principles.md index 9e67fbb..6797c61 100644 --- a/.github/standards/coding-principles.md +++ b/.github/standards/coding-principles.md @@ -3,11 +3,6 @@ name: Coding Principles description: Follow these standards when developing any software code. --- -# Coding Principles Standards - -This document defines universal coding principles and quality standards for software development within -Continuous Compliance environments. - # Core Principles ## Literate Coding @@ -20,10 +15,9 @@ 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 -- **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 +- **Full Symbol Documentation**: ALL symbols have comprehensive documentation — + not just the public interface, because reviewers and auditors must verify every + implementation detail. Access-level specifics vary by language; see the language-specific standard. - **Clarity Over Cleverness**: Code should be immediately understandable by team members ## API Documentation @@ -79,13 +73,13 @@ interface correctly without reading the implementation: ## Universal Anti-Patterns -- **Skip Literate Coding**: Don't skip literate programming comments - they are required for maintainability -- **Ignore Compiler Warnings**: Don't ignore compiler warnings - they exist for quality enforcement +- **Skip Literate Coding**: Don't skip literate programming comments +- **Ignore Compiler Warnings**: Don't ignore compiler warnings - **Hidden Dependencies**: Don't create untestable code with hidden dependencies - **Hidden Functionality**: Don't implement functionality without requirement traceability because untraced functionality cannot be validated during audits - **Monolithic Functions**: Don't write monolithic functions with multiple responsibilities -- **Overcomplicated Solutions**: Don't make solutions more complex than necessary - favor simplicity and clarity +- **Overcomplicated Solutions**: Don't make solutions more complex than necessary - **Premature Optimization**: Don't optimize for performance before establishing correctness - **Copy-Paste Programming**: Don't duplicate logic - extract common functionality into reusable components - **Magic Numbers**: Don't use unexplained constants - either name them or add clear comments diff --git a/.github/standards/csharp-language.md b/.github/standards/csharp-language.md index 6df39cd..ec05a25 100644 --- a/.github/standards/csharp-language.md +++ b/.github/standards/csharp-language.md @@ -12,9 +12,6 @@ Read these standards first before applying this standard: # API Documentation and Literate Coding Example -The example below demonstrates good XmlDoc API documentation combined with -literate coding comments. - ```csharp /// /// Converts a raw sensor reading into a validated measurement ready for downstream consumers. diff --git a/.github/standards/csharp-testing.md b/.github/standards/csharp-testing.md index 181de02..1f93b72 100644 --- a/.github/standards/csharp-testing.md +++ b/.github/standards/csharp-testing.md @@ -66,8 +66,6 @@ These are non-obvious v3 behaviors that differ from v2 or common assumptions: # Quality Checks -Before submitting C# tests, verify: - - [ ] All tests follow AAA pattern with clear section comments - [ ] Test names follow hierarchical naming pattern above - [ ] Each test verifies single, specific behavior (no shared state between tests) diff --git a/.github/standards/design-documentation.md b/.github/standards/design-documentation.md index 3b448f3..c6f107f 100644 --- a/.github/standards/design-documentation.md +++ b/.github/standards/design-documentation.md @@ -4,196 +4,120 @@ description: Follow these standards when creating design documentation. globs: ["docs/design/**/*.md"] --- -# Design Documentation Standards - -This document defines standards for design documentation within Continuous -Compliance environments, extending the general technical documentation -standards with specific requirements for software design artifacts. - -## Required Standards - -Read these standards first before applying this standard: +# Required Standards - **`technical-documentation.md`** - General technical documentation standards -- **`software-items.md`** - Software categorization (System/Subsystem/Unit/OTS) - -# Core Principles - -Design documentation serves as the bridge between requirements and -implementation, providing detailed technical specifications that enable: - -- **Formal Code Review**: Reviewers can verify implementation matches design -- **Compliance Evidence**: Auditors can trace requirements through design to code -- **Maintenance Support**: Developers can understand system structure and interactions -- **Quality Assurance**: Testing teams can validate against detailed specifications - -# Required Structure and Documents +- **`software-items.md`** - Software categorization (System/Subsystem/Unit/OTS/Shared Package) +- **`sysml2-modeling.md`** - SysML2 model and view conventions feeding the Software Structure + section -Design documentation must be organized under `docs/design/` with folder structure -mirroring source code organization because reviewers need clear navigation from -design to implementation: +# Folder Structure ```text docs/design/ -├── introduction.md # Design overview with software structure -└── {system-name}/ # System-level design folder (one per system) - ├── {system-name}.md # System-level design documentation - ├── {subsystem-name}/ # Subsystem (kebab-case); may nest recursively - │ ├── {subsystem-name}.md # Subsystem overview and design - │ ├── {child-subsystem}/ # Child subsystem (same structure as parent) - │ └── {unit-name}.md # Unit-level design documents - └── {unit-name}.md # Top-level unit design documents (if not in subsystem) +├── introduction.md # heading depth # +├── {system-name}.md # heading depth # +├── {system-name}/ +│ ├── {subsystem-name}.md # heading depth ## +│ ├── {subsystem-name}/ +│ │ └── {unit-name}.md # heading depth ### +│ └── {unit-name}.md # heading depth ## +├── ots.md # heading depth # (if OTS items exist) +├── ots/ +│ └── {ots-name}.md # heading depth ## +├── shared.md # heading depth # (if Shared Packages exist) +└── shared/ + └── {package-name}.md # heading depth ## ``` -## introduction.md (MANDATORY) +All sections in every file are mandatory; write "N/A - {justification}" rather than removing any. +Determine subsystem vs. unit classification from `docs/design/introduction.md` — folder depth does not determine classification. -The `introduction.md` file serves as the design entry point and MUST include -these sections because auditors need clear scope boundaries and architectural -overview: +# introduction.md (MANDATORY) -### Purpose Section +Must include: -Clear statement of the design document's purpose, audience, and regulatory -or compliance drivers. +- **Purpose**: audience and compliance drivers +- **Scope**: items covered and explicitly excluded (no test projects) +- **Software Structure**: diagram(s) rendered from the SysML2 model under `docs/sysml2/`, + per `sysml2-modeling.md` — not a hand-maintained text tree +- **Folder Layout**: text tree showing source folder structure +- **Companion Artifact Structure**: parallel paths for requirements, design, verification, source, tests +- **References** _(if applicable)_: external standards or specifications - only in `introduction.md` -### Scope Section +# System Design (MANDATORY) -Define what software items are covered and what is explicitly excluded. -Design documentation must NOT include test projects, test classes, or test -infrastructure because design documentation documents the architecture of -shipping product code, not ancillary content used to validate it. +Create `{system-name}.md` (`#` heading) and `{system-name}/` folder: -### Software Structure Section (MANDATORY) +- **Architecture**: software items, relationships, and collaboration +- **External Interfaces**: name, direction, format, constraints +- **Dependencies**: OTS and Shared Packages used; cross-reference their design docs +- **Risk Control Measures**: segregation required for risk control (IEC 62304 §5.3.3) +- **Data Flow**: inputs to outputs +- **Design Constraints**: platform, performance, security, regulatory -Include a text-based tree diagram showing the software organization across -System, Subsystem, and Unit levels. Agents MUST read `software-items.md` -to understand these classifications before creating this section. +# Subsystem Design (MANDATORY) -Example format: +Place `{subsystem-name}.md` in the **parent** folder; create `{subsystem-name}/` for children: -```text -Project1Name (System) -├── ComponentA (Subsystem) -│ ├── SubComponentP (Subsystem) -│ │ └── ClassW (Unit) -│ ├── ClassX (Unit) -│ └── ClassY (Unit) -├── ComponentB (Subsystem) -│ └── ClassZ (Unit) -└── UtilityClass (Unit) - -Project2Name (System) -└── HelperClass (Unit) -``` +- **Overview**: responsibility, boundaries, contained units +- **Interfaces**: what it exposes and consumes +- **Design**: how internal units collaborate -### Folder Layout Section (MANDATORY) +# Unit Design (MANDATORY) -Include a text-based tree diagram showing how the source code folders -mirror the software structure, with file paths and brief descriptions. +Place `{unit-name}.md` in the **parent** folder: -Example format: +- **Purpose**: single responsibility +- **Data Model**: fields, properties, types, invariants (IEC 62304 §5.4.2) +- **Key Methods**: name, purpose, algorithm, preconditions, postconditions, parameter types +- **Error Handling**: detection and handling; what is propagated vs. handled locally +- **Dependencies**: other units, subsystems, OTS items, and shared packages used +- **Callers**: units or subsystems that call or consume this unit -```text -src/Project1Name/ -├── ComponentA/ -│ ├── SubComponentP/ -│ │ └── ClassW.cs - Specialized processing engine -│ ├── ClassX.cs - Core business logic handler -│ └── ClassY.cs - Data validation service -├── ComponentB/ -│ └── ClassZ.cs - Integration interface -└── UtilityClass.cs - Common utility functions - -src/Project2Name/ -└── HelperClass.cs - Helper functions -``` +# OTS Integration Design (when OTS items exist) -### References Section (RECOMMENDED) +Create `docs/design/ots.md` (`#` heading) covering the overall OTS integration strategy. -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. +For each OTS item, create `docs/design/ots/{ots-name}.md` (`##` heading) with sections: -### Companion Artifact Structure (RECOMMENDED) +- **Purpose**: why chosen and what it provides to the local system +- **Features Used**: which specific features, APIs, or capabilities are consumed +- **Integration Pattern**: how it is consumed; initialization, configuration, disposal requirements -Include a brief note explaining that each software item has parallel artifacts -across the repository, so agents and reviewers can navigate from any one -artifact to all related files: +# Shared Package Integration Design (when Shared Packages exist) -Example format: +Create `docs/design/shared.md` (`#` heading) covering the overall consumption strategy. -```text -Each software item in the structure above has corresponding artifacts in -parallel directory trees: - -- Requirements: `docs/reqstream/{system}/.../{item}.yaml` (kebab-case) -- Design docs: `docs/design/{system}/.../{item}.md` (kebab-case) -- Verification design: `docs/verification/{system}/.../{item}.md` (kebab-case) -- Source code: `src/{System}/.../{Item}.{ext}` (cased per language - see `software-items.md`) -- Tests: `test/{System}.Tests/.../{Item}Tests.{ext}` (cased per language - see `software-items.md`) -- Review-sets: defined in `.reviewmark.yaml` -``` +For each Shared Package, create `docs/design/shared/{package-name}.md` (`##` heading) with sections: -## System Design Documentation (MANDATORY) - -For each system identified in the repository: - -- Create a kebab-case folder matching the system name -- Include `{system-name}.md` with system-level design documentation such as: - - System architecture and major components - - External interfaces and dependencies - - Data flow and control flow - - System-wide design constraints and decisions - - Integration patterns and communication protocols - -## Subsystem and Unit Design Documents - -For each subsystem identified in the software structure: - -- Create a kebab-case folder matching the subsystem name (enables automated tooling) -- Include `{subsystem-name}.md` with subsystem overview and design -- Include unit design documents for ALL units within the subsystem - -For every unit identified in the software structure: - -- Document data models, algorithms, and key methods -- Describe interactions with other units -- Include sufficient detail for formal code review -- Place in appropriate subsystem folder or at design root level - -# Software Items Integration (CRITICAL) - -Read `software-items.md` before creating design documentation - correct -System/Subsystem/Unit categorization is required for software structure -diagrams and folder layout. +- **Advertised Features Consumed**: which features the local system relies on +- **Integration Pattern**: how the package is referenced, initialized, and consumed +- **Assumptions**: any assumptions the local system makes about the package's behavior # Writing Guidelines -Design documentation must be technical and specific because it serves as the -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 - -Use Mermaid diagrams to supplement text descriptions (diagrams must not replace text content). +- Use Mermaid diagrams to supplement (not replace) text +- Use verbal cross-references ("see _Parser Design_") - not markdown hyperlinks (break in PDF) +- Provide sufficient detail for formal code review +- Do not record version numbers in design documentation — they go stale with dependency updates and + are managed in SBOMs. Version numbers are pinned release versions (e.g., `1.2.3`, `v2.0.1`). + The following are **not** version numbers and are permitted: + - Language/platform standards: `netstandard2.0`, `net10.0`, `C++20`, `C# 12` (stable standard identifiers) + - Protocol standards: `TLS 1.3`, `HTTP/2` (stable specifications) + - Placeholders: `0.0.0` (signals "not yet assigned") # Quality Checks -Before submitting design documentation, verify: - -- [ ] `introduction.md` includes both Software Structure and Folder Layout sections -- [ ] Software structure correctly categorizes items as System/Subsystem/Unit per `software-items.md` -- [ ] Folder layout mirrors software structure organization -- [ ] Design documents provide sufficient detail for code review -- [ ] System documentation provides comprehensive system-level design -- [ ] Subsystem documentation folders use kebab-case names while mirroring source subsystem names and structure -- [ ] All documents follow technical documentation formatting standards -- [ ] Content is current with implementation and requirements -- [ ] Documents are integrated into ReviewMark review-sets for formal review +- [ ] `introduction.md` includes Software Structure, Folder Layout, and Companion Artifact Structure +- [ ] Software structure correctly categorizes items per `software-items.md` +- [ ] Each file's heading depth matches its folder depth +- [ ] All folders use kebab-case mirroring source structure +- [ ] System design includes all mandatory sections (Architecture, External Interfaces, Dependencies, + Risk Control Measures, Data Flow, Design Constraints) +- [ ] Subsystem design includes all mandatory sections (Overview, Interfaces, Design) +- [ ] Unit design includes all mandatory sections (Purpose, Data Model, Key Methods, Error Handling, Dependencies, Callers) +- [ ] Non-applicable mandatory sections contain "N/A - {justification}" +- [ ] `docs/design/ots.md` and `docs/design/ots/{ots-name}.md` exist when OTS items are present +- [ ] `docs/design/shared.md` and `docs/design/shared/{package-name}.md` exist when Shared Packages are present +- [ ] Documents are integrated into ReviewMark review-sets diff --git a/.github/standards/reqstream-usage.md b/.github/standards/reqstream-usage.md index 58b08b4..2371164 100644 --- a/.github/standards/reqstream-usage.md +++ b/.github/standards/reqstream-usage.md @@ -9,7 +9,7 @@ globs: ["requirements.yaml", "docs/reqstream/**/*.yaml"] Read these standards first before applying this standard: - **`requirements-principles.md`** - Requirements principles and unidirectionality -- **`software-items.md`** - Software categorization (System/Subsystem/Unit/OTS) +- **`software-items.md`** - Software categorization (System/Subsystem/Unit/OTS/Shared Package) # Requirements Organization @@ -18,54 +18,83 @@ because ReqStream discovers files via the includes chain in `requirements.yaml` and organizes report output by this hierarchy: ```text -requirements.yaml # Root file (includes only) +requirements.yaml # Root file (includes only) docs/reqstream/ -├── {system-name}/ # System-level requirements folder (one per system) -│ ├── {system-name}.yaml # System-level requirements +├── {system-name}.yaml # System-level requirements +├── {system-name}/ # System folder (one per system) │ ├── platform-requirements.yaml # Platform support requirements -│ ├── {subsystem-name}/ # Subsystem (kebab-case); may nest recursively -│ │ ├── {subsystem-name}.yaml # Requirements for this subsystem -│ │ ├── {child-subsystem}/ # Child subsystem (same structure as parent) -│ │ └── {unit-name}.yaml # Requirements for units within this subsystem -│ └── {unit-name}.yaml # Requirements for top-level units (outside subsystems) -└── ots/ # OTS items appear as a distinct section in reports - └── {ots-name}.yaml # Requirements for OTS components +│ ├── {subsystem-name}.yaml # Subsystem requirements +│ ├── {subsystem-name}/ # Subsystem folder (kebab-case); may nest recursively +│ │ ├── {subsystem-name}.yaml # Child subsystem requirements +│ │ ├── {subsystem-name}/ # Child subsystem folder +│ │ └── {unit-name}.yaml # Unit requirements +│ └── {unit-name}.yaml # System-level unit requirements +├── ots/ # OTS items appear as a distinct section in reports +│ └── {ots-name}.yaml # Requirements for OTS components +└── shared/ # Shared Packages appear as a distinct section in reports + └── {package-name}.yaml # Requirements for Shared Package dependencies ``` +Local items have matching relative paths across `docs/reqstream/`, `docs/design/`, and `docs/verification/`: + +- Requirements: `{system-name}[/{subsystem-name}...]/{item-name}.yaml` +- Design: `{system-name}[/{subsystem-name}...]/{item-name}.md` +- Verification: `{system-name}[/{subsystem-name}...]/{item-name}.md` + # Requirements File Format -```yaml -sections: - - title: Functional Requirements - requirements: - - id: System-Component-Feature # Used as-is in all reports - make it readable - title: The system shall perform the required function. - justification: | - Business rationale and any regulatory references. - # ReqStream extracts this field into the justifications report (--justifications) - children: # ReqStream validates this decomposition chain - - ChildSystem-Feature-Behavior # Downward links only (see requirements-principles.md) - tests: # ReqStream matches these by method name in test results - - TestMethodName - - windows@PlatformSpecificTest # Only test runs on Windows count as evidence -``` +Each file adds requirements at exactly one level of the hierarchy. The file spells out +its full ancestry as nested `{ItemName} Requirements` sections down to that level, then +places requirements there. ReqStream merges identical section title paths across included +files automatically. Always determine item classification from `docs/design/introduction.md` - +folder depth does not determine whether an item is a subsystem or unit. + +Valid section nestings (names in `{braces}` are placeholders): -# OTS Software Requirements +```text +{SystemName} Requirements # system-level requirements +├── {SubsystemName} Requirements # root subsystem requirements +│ ├── {SubsystemName} Requirements # nested subsystem (may recurse) +│ │ └── {UnitName} Requirements # unit under a nested subsystem +│ └── {UnitName} Requirements # unit under a root subsystem +└── {UnitName} Requirements # unit directly under the system +OTS Software Requirements # OTS root section (fixed title) +└── {OtsName} Requirements # requirements for one OTS item +Shared Package Requirements # shared package root section (fixed title) +└── {PackageName} Requirements # requirements for one shared package +``` -Use nested sections in `docs/reqstream/ots/` because ReqStream renders the `ots/` -subtree as a distinct section in generated reports, separate from in-house -system requirements: +Each file implements one path through this tree: ```yaml sections: - - title: OTS Software Requirements + - title: '{SystemName} Requirements' sections: - - title: System.Text.Json + - title: '{SubsystemName} Requirements' requirements: - - id: TemplateTool-SystemTextJson-ReadJson - title: System.Text.Json shall be able to read JSON files. - tests: - - JsonReaderTests.TestReadValidJson + - id: System-Subsystem-Feature # Used as-is in all reports - make it readable + title: The subsystem shall perform the required function. + justification: | # ReqStream extracts this into the justifications report (--justifications) + Business rationale and any regulatory references. + tags: # Optional: categorize for filtering with --filter + - security + children: # Optional: ReqStream validates this decomposition chain + - System-Subsystem-Unit-Feat # Downward links only (see requirements-principles.md) + tests: # ReqStream matches these by method name in test results + - TestMethodName + - windows@PlatformSpecificTest # Only test runs on Windows count as evidence +``` + +# Tags (OPTIONAL) + +Tags are free-form - no mandatory vocabulary. Common tags: `security`, `safety`, `performance`, +`compliance`, `reliability`, `critical`. Use `--filter` to selectively export or enforce subsets +(OR logic across comma-separated tags): + +```bash +dotnet reqstream --requirements requirements.yaml \ + --filter security,critical \ + --report docs/requirements_doc/generated/security_requirements.md ``` # Semantic IDs (MANDATORY) @@ -120,12 +149,9 @@ dotnet reqstream --requirements requirements.yaml \ Before submitting requirements, verify: -- [ ] All requirements have semantic IDs (`System-Section-Feature` pattern) -- [ ] Every requirement links to at least one passing test +- [ ] All requirements have semantic IDs (`System-Component-Feature` pattern) +- [ ] Every requirement has a justification explaining business/regulatory need +- [ ] Every requirement links to at least one test - [ ] Platform-specific requirements use source filters (`platform@TestName`) -- [ ] Comprehensive justification explains business/regulatory need -- [ ] Files organized under `docs/reqstream/` following folder structure patterns -- [ ] Subsystem folders use kebab-case naming matching source code -- [ ] OTS requirements placed in `ots/` subfolder -- [ ] Valid YAML syntax passes yamllint validation -- [ ] Test result formats compatible (TRX, JUnit XML) +- [ ] All files and folders use kebab-case names matching source code structure +- [ ] All files are organized under `docs/reqstream/` following the folder structure above diff --git a/.github/standards/reviewmark-usage.md b/.github/standards/reviewmark-usage.md index 2f778dc..bc73da6 100644 --- a/.github/standards/reviewmark-usage.md +++ b/.github/standards/reviewmark-usage.md @@ -9,7 +9,7 @@ description: Follow these standards when configuring file reviews with ReviewMar Read these standards first before applying this standard: -- **`software-items.md`** - Software categorization (System/Subsystem/Unit/OTS) +- **`software-items.md`** - Software categorization (System/Subsystem/Unit/OTS/Shared Package) ## Purpose @@ -21,169 +21,228 @@ 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/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 -> configuration that should be addressed. + (exits non-zero if any files are uncovered) ## Repository Structure -Required repository items for ReviewMark operation: - - `.reviewmark.yaml` - Configuration for review-sets, file-patterns, and review evidence-source. -- `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 Configure reviews in `.reviewmark.yaml` at repository root: ```yaml -# Patterns identifying all files that require review needs-review: - # Include source code (adjust file extensions for your repo) - - "**/*.cs" # C# source files - - "**/*.cpp" # C++ source files - - "**/*.hpp" # C++ header files - - "!**/bin/**" # Generated source in build outputs - - "!**/obj/**" # Generated source in build intermediates - - # Include requirement files - - "requirements.yaml" # Root requirements file - - "docs/reqstream/**/*.yaml" # Requirements files - - # Include critical documentation files - - "README.md" # Root level README - - "docs/user_guide/**/*.md" # User guide - - "docs/design/**/*.md" # Design documentation - - "docs/verification/**/*.md" # Verification design documentation - -# Source of review evidence + - "**/*.cs" + - "**/*.cpp" + - "**/*.hpp" + - "!**/bin/**" + - "!**/obj/**" + - "requirements.yaml" + - "docs/reqstream/**/*.yaml" + - "docs/sysml2/**/*.sysml" + - "README.md" + - "docs/user_guide/**/*.md" + - "docs/design/**/*.md" + - "docs/verification/**/*.md" + evidence-source: type: none + +context: + - docs/design/introduction.md + +reviews: + - id: Purpose + title: Review that README and User Guide are Coherent and Complete + paths: + - "README.md" + - "docs/user_guide/**/*.md" + - id: Decomposition + title: Review that {SystemName} Decomposition Addresses the Stated Purpose + context: + - "README.md" + - "docs/user_guide/**/*.md" + paths: + - "requirements.yaml" + - "docs/design/introduction.md" ``` -# Review-Set Design Principles +For a complete annotated example with template directives, see `.reviewmark.yaml` in the +reference template (`{template-url}/.reviewmark.yaml` per `AGENTS.md`). -When constructing review-sets, follow these principles to maintain manageable scope and effective compliance evidence: +# Review-Set Design Principles - **Hierarchical Scope**: Higher-level reviews exclude lower-level implementation details, relying instead on design documents to describe what components they use. System reviews exclude subsystem/unit details, subsystem reviews exclude unit source code, only unit reviews include actual implementation. - **Single Focus**: Each review-set proves one specific compliance question (user promises, system architecture, design consistency, etc.) +- **Parent Context**: Unit and subsystem reviews include parent design and requirements as + context so reviewers understand the intended role and scope; see the Context Files section. - **Context Management**: Keep file counts manageable to prevent context overflow while maintaining complete coverage through the hierarchy -# Review-Set Organization +# Context Files -Organize review-sets using these standard patterns to ensure comprehensive coverage -while keeping each review manageable in scope: +Context files are shown to reviewers for orientation but not fingerprinted. Add a top-level +`context:` key for global context (every reviewer) and a per-review-set `context:` between +`title:` and `paths:` for review-specific context. Always include `docs/design/introduction.md` +as global context. -**Naming conventions**: See `software-items.md` - kebab-case placeholders -(e.g., `{system-name}`) are always kebab-case; cased placeholders -(e.g., `{SystemName}`) follow your language's convention. +| Review Type | Context to add | +| :---------- | :------------- | +| `Decomposition` | `README.md`, `docs/user_guide/**/*.md` | +| `{SystemName}-Architecture` | `README.md`, `docs/user_guide/**/*.md` | +| `{SystemName}-Design` | `docs/reqstream/{system-name}.yaml` | +| `{SystemName}-Verification` | `docs/reqstream/{system-name}.yaml` | +| `{SystemName}-AllRequirements` | Parent system design doc + `docs/reqstream/{system-name}.yaml` | +| `{SystemName}-{UnitName}` (direct unit) | Parent system design doc + parent system requirements | +| `{SystemName}-{SubsystemName}` (subsystem) | Parent system design doc + parent system requirements | +| `{SystemName}-{SubsystemName}-{UnitName}` (unit under subsystem) | System + subsystem design docs + requirements | -## `Purpose` Review (only one per repository) +# Review-Set Organization -Reviews user-facing capabilities and system promises: +**Naming conventions**: Placeholders in documentation, requirements, design, and +verification file paths are kebab-case (e.g., `{system-name}`). Placeholders in +source and test file paths may use the casing conventional for the project's +source language or repository layout (e.g., `{SystemName}`). Review-set name +placeholders are always PascalCase (e.g., `{SystemName}`). + +## `Purpose` Review (only one per repository) -- **Purpose**: Proves that the systems provide the capabilities the user is being told about -- **Title**: "Review that Advertised Features Match System Design" -- **Scope**: Excludes subsystem and unit files, relying on system-level design documents - to describe what subsystems and units they use +- **Purpose**: Proves that the user-facing docs are coherent and complete — the north-star for the hierarchy +- **Title**: "Review that README and User Guide are Coherent and Complete" +- **ID**: `Purpose` (no system prefix — one per repository) +- **Scope**: README and user_guide only; no requirements or design files - **File Path Patterns**: - README: `README.md` - User guide: `docs/user_guide/**/*.md` - - System requirements: `docs/reqstream/{system-name}/{system-name}.yaml` - - Design introduction: `docs/design/introduction.md` - - System design: `docs/design/{system-name}/{system-name}.md` -## `{System}-Architecture` Review (one per system) +## `Decomposition` Review (only one per repository) + +- **Purpose**: Proves that the software items tree breakdown logically addresses the user-facing + promise; the structural mirror of the decomposition decision +- **Title**: "Review that {SystemName} Decomposition Addresses the Stated Purpose" +- **ID**: `Decomposition` (no system prefix — one per repository) +- **Scope**: introduction.md (the decomposition narrative), the SysML2 model (the + authoritative structural tree), and requirements.yaml; no system-level detail +- **File Path Patterns**: + - Root requirements: `requirements.yaml` + - Design introduction: `docs/design/introduction.md` + - SysML2 model: `docs/sysml2/**/*.sysml` +- **Context Files**: `README.md`, `docs/user_guide/**/*.md` -Reviews system architecture and operational validation: +## `{SystemName}-Architecture` Review (one per system) - **Purpose**: Proves that the system is designed and tested to satisfy its requirements -- **Title**: "Review that {System} Architecture Satisfies Requirements" +- **Title**: "Review that {SystemName} Architecture Satisfies Requirements" - **Scope**: Excludes subsystem and unit files, relying on system-level design to describe what subsystems and units it uses - **File Path Patterns**: - - System requirements: `docs/reqstream/{system-name}/{system-name}.yaml` + - System requirements: `docs/reqstream/{system-name}.yaml` - Design introduction: `docs/design/introduction.md` - - System design: `docs/design/{system-name}/{system-name}.md` + - System design: `docs/design/{system-name}.md` - Verification introduction: `docs/verification/introduction.md` - - System verification design: `docs/verification/{system-name}/{system-name}.md` + - System verification design: `docs/verification/{system-name}.md` - System integration tests: `test/{SystemName}.Tests/{SystemName}Tests.{ext}` +- **Context Files**: `README.md`, `docs/user_guide/**/*.md` -## `{System}-Design` Review (one per system) - -Reviews architectural and design consistency: +## `{SystemName}-Design` Review (one per system) - **Purpose**: Proves the system design is consistent and complete -- **Title**: "Review that {System} Design is Consistent and Complete" +- **Title**: "Review that {SystemName} Design is Consistent and Complete" - **Scope**: Only brings in top-level requirements and relies on brevity of design documentation +- **Context Files**: `docs/reqstream/{system-name}.yaml` - **File Path Patterns**: - - System requirements: `docs/reqstream/{system-name}/{system-name}.yaml` - Platform requirements: `docs/reqstream/{system-name}/platform-requirements.yaml` - Design introduction: `docs/design/introduction.md` + - System design: `docs/design/{system-name}.md` - System design files: `docs/design/{system-name}/**/*.md` + - OTS overview: `docs/design/ots.md` _(only if OTS items exist)_ + - Shared Package overview: `docs/design/shared.md` _(only if Shared Package items exist)_ -## `{System}-AllRequirements` Review (one per system) +## `{SystemName}-Verification` Review (one per system) -Reviews requirements quality and traceability: +- **Purpose**: Proves the system verification design is consistent and covers all requirements +- **Title**: "Review that {SystemName} Verification is Consistent and Complete" +- **Scope**: Only brings in top-level requirements and all verification docs for the system +- **Context Files**: `docs/reqstream/{system-name}.yaml` +- **File Path Patterns**: + - Verification introduction: `docs/verification/introduction.md` + - System verification: `docs/verification/{system-name}.md` + - System verification files: `docs/verification/{system-name}/**/*.md` + - OTS overview: `docs/verification/ots.md` _(only if OTS items exist)_ + - Shared Package overview: `docs/verification/shared.md` _(only if Shared Package items exist)_ + +## `{SystemName}-AllRequirements` Review (one per system) - **Purpose**: Proves the requirements are consistent and complete -- **Title**: "Review that All {System} Requirements are Complete" +- **Title**: "Review that All {SystemName} Requirements are Complete" - **Scope**: Only brings in requirements files to keep review manageable - **File Path Patterns**: - - Root requirements: `requirements.yaml` - - System requirements: `docs/reqstream/{system-name}/**/*.yaml` - - OTS requirements: `docs/reqstream/ots/**/*.yaml` (if applicable) + - Subsystem/unit requirements: `docs/reqstream/{system-name}/**/*.yaml` +- **Context Files**: `docs/design/{system-name}.md`, `docs/reqstream/{system-name}.yaml` -## `{System}-{Subsystem[-Child...]}` Review (one per subsystem at any depth) - -Reviews subsystem architecture and interfaces: +## `{SystemName}-{SubsystemName}[-{SubsystemName}...]` Review (one per subsystem at any depth) - **Purpose**: Proves that the subsystem is designed and tested to satisfy its requirements -- **Title**: "Review that {System} {Subsystem} Satisfies Subsystem Requirements" +- **Title**: "Review that {SystemName} {SubsystemName} Satisfies Subsystem Requirements" - **Scope**: Excludes units under the subsystem, relying on subsystem design to describe what units it uses - **File Path Patterns**: - - Requirements: `docs/reqstream/{system-name}/.../{subsystem-name}/{subsystem-name}.yaml` - - Design: `docs/design/{system-name}/.../{subsystem-name}/{subsystem-name}.md` - - Verification design: `docs/verification/{system-name}/.../{subsystem-name}/{subsystem-name}.md` - - Tests: `test/{SystemName}.Tests/.../{SubsystemName}/{SubsystemName}Tests.{ext}` - -## `{System}-{Subsystem[-Child...]}-{Unit}` Review (one per unit) + - Requirements: `docs/reqstream/{system-name}[/{subsystem-name}...]/{subsystem-name}.yaml` + - Design: `docs/design/{system-name}[/{subsystem-name}...]/{subsystem-name}.md` + - Verification design: `docs/verification/{system-name}[/{subsystem-name}...]/{subsystem-name}.md` + - Tests: `test/{SystemName}.Tests[/{SubsystemName}...]/{SubsystemName}Tests.{ext}` +- **Context Files**: `docs/design/{system-name}.md`, `docs/reqstream/{system-name}.yaml` -Reviews individual software unit implementation: +## `{SystemName}-{SubsystemName}[-{SubsystemName}...]-{UnitName}` Review (one per unit) - **Purpose**: Proves the unit is designed, implemented, and tested to satisfy its requirements -- **Title**: "Review that {System} {Subsystem} {Unit} Implementation is Correct" +- **Title**: "Review that {SystemName} {SubsystemName} {UnitName} Implementation is Correct" - **Scope**: Complete unit review including all artifacts - **File Path Patterns**: - - Requirements: `docs/reqstream/{system-name}/.../{unit-name}.yaml` - - Design: `docs/design/{system-name}/.../{unit-name}.md` - - Verification design: `docs/verification/{system-name}/.../{unit-name}.md` - - Source: `src/{SystemName}/.../{UnitName}.{ext}` - - Tests: `test/{SystemName}.Tests/.../{UnitName}Tests.{ext}` + - Requirements: `docs/reqstream/{system-name}[/{subsystem-name}...]/{unit-name}.yaml` + - Design: `docs/design/{system-name}[/{subsystem-name}...]/{unit-name}.md` + - Verification design: `docs/verification/{system-name}[/{subsystem-name}...]/{unit-name}.md` + - Source (C# example): `src/{SystemName}[/{SubsystemName}...]/{UnitName}.cs` + - Tests (C# example): `test/{SystemName}.Tests[/{SubsystemName}...]/{UnitName}Tests.cs` + - Source (snake_case C++ example): `src/{system_name}[/{subsystem_name}...]/{unit_name}.cpp` + - Tests (snake_case C++ example): `test/{system_name}_tests[/{subsystem_name}...]/{unit_name}_tests.cpp` +- **Context Files**: Parent system design + requirements; add subsystem design + + requirements for each subsystem level above the unit. + +## `OTS-{OtsName}` Review (one per OTS item) + +- **Purpose**: Proves that the OTS item provides the required functionality and is correctly integrated +- **Title**: "Review that {OtsName} Provides Required Functionality" +- **Scope**: No local source code; review covers integration design, requirements, and verification evidence +- **File Path Patterns**: + - OTS requirements: `docs/reqstream/ots/{ots-name}.yaml` + - OTS integration design: `docs/design/ots/{ots-name}.md` + - OTS verification: `docs/verification/ots/{ots-name}.md` + - Tests (if applicable): `test/OtsSoftwareTests/...` (C#) or `test/ots_software_tests/...` + (Python/other) — fixed repo-level name, no system prefix + +## `Shared-{PackageName}` Review (one per Shared Package) + +- **Purpose**: Proves that the Shared Package provides the required advertised features and is correctly integrated +- **Title**: "Review that {PackageName} Provides Required Features" +- **Scope**: No local source code; review covers integration design, requirements, and verification evidence +- **File Path Patterns**: + - Shared Package requirements: `docs/reqstream/shared/{package-name}.yaml` + - Shared Package integration design: `docs/design/shared/{package-name}.md` + - Shared Package verification: `docs/verification/shared/{package-name}.md` **Note**: File path patterns use `{ext}` as a placeholder for language-specific extensions (`.cs`, `.cpp`/`.hpp`, `.py`, etc.). Adapt to your repository's languages. # Quality Checks -Before submitting ReviewMark configuration, verify: - - [ ] `.reviewmark.yaml` exists at repository root with proper structure - [ ] Review-set organization follows the standard hierarchy patterns -- [ ] Purpose review-set includes README.md, user guide, system requirements, design introduction, and system design files -- [ ] System-level reviews follow hierarchical scope principle (exclude subsystem/unit details) -- [ ] Subsystem reviews follow hierarchical scope principle (exclude unit source code) -- [ ] Only unit reviews include actual source code files -- [ ] Architecture review-sets include system verification design alongside system design -- [ ] Subsystem review-sets include subsystem verification design -- [ ] Unit review-sets include unit verification design - [ ] Each review-set focuses on a single compliance question (single focus principle) - [ ] File patterns use correct glob syntax and match intended files - [ ] Review-set file counts remain manageable (context management principle) +- [ ] Context configured per the Context Files section diff --git a/.github/standards/software-items.md b/.github/standards/software-items.md index 4e5c90e..3514228 100644 --- a/.github/standards/software-items.md +++ b/.github/standards/software-items.md @@ -3,20 +3,16 @@ name: Software Items description: Follow these standards when categorizing software components. --- -# Software Items Definition Standards - -This document defines standards for categorizing software items within -Continuous Compliance environments because proper categorization determines -requirements management approach, testing strategy, and review scope. - # Software Item Categories -Categorize all software into five primary groups: +Categorize all software into six primary groups: - **Software Package**: Distributable unit delivered to end users or dependent systems, containing one software system with all its components. All software - systems are delivered as a software package. When consumed by another system, - our software package is treated as an OTS Software Item by that system. + systems are delivered as a software package. When consumed by a system outside + the producing program, our software package is treated as an OTS Software Item + by that system. When consumed by another repository within the same program, + it is treated as a Shared Package. - **Software System**: Complete deliverable product including all components and external interfaces, contained within a software package - **Software Subsystem**: Major architectural component with well-defined @@ -24,7 +20,11 @@ Categorize all software into five primary groups: - **Software Unit**: Individual class, function, or tightly coupled set of functions that can be tested in isolation - **OTS Software Item**: Third-party component (library, framework, tool, or - published software package) providing functionality not developed in-house + published software package) providing functionality not developed within the program +- **Shared Package**: A software package produced by a different repository within + the same program, consumed as a dependency. Referenced by its advertised features + rather than internal design; traceability to program-level requirements runs + through the top-level project. **Naming**: When names collide in hierarchy, add descriptive suffix to higher-level entity: @@ -34,17 +34,28 @@ Categorize all software into five primary groups: # Naming Conventions in File Path Patterns -Two placeholder styles appear in path patterns across these standards: +Three placeholder forms appear in path patterns across these standards: -- **Kebab-case** (`{system-name}`, `{unit-name}`): always kebab-case - - used in documentation and requirements paths -- **Cased** (`{SystemName}`, `{UnitName}`): follow your language's convention - - `PascalCase` for C#/Java, `snake_case` for C++/Python - - used in source and test file paths +- **Kebab-case** (`{system-name}`, `{unit-name}`): always kebab-case — + documentation and requirements file paths +- **PascalCase IDs** (`{SystemName}`, `{UnitName}`): always PascalCase — + requirements IDs, ReviewMark IDs, and other documentation identifiers +- **Language-cased** (`{SystemName}` or `{system_name}`): follow your language's + convention — `PascalCase` for C#/Java, `snake_case` for C++/Python — + source and test file/folder names -# Categorization Guidelines +## Nesting Depth Notation + +Subsystems nest to any depth. Patterns use bracket-ellipsis to express this without +enumerating levels — `[/{subsystem-name}...]` in paths, `[-{SubsystemName}...]` in +dash-separated IDs. Examples covering all three forms: -Choose the appropriate category based on scope and testability: +- `{SystemName}[-{SubsystemName}...]-{UnitName}-Feature` (PascalCase ID) +- `docs/design/{system-name}[/{subsystem-name}...]/{unit-name}.md` (kebab-case doc path) +- `src/{SystemName}[/{SubsystemName}...]/{UnitName}.cs` (C# source path) +- `src/{system_name}[/{subsystem_name}...]/{unit_name}.cpp` (C++/Python source path) + +# Categorization Guidelines ## Software Package @@ -75,12 +86,37 @@ Choose the appropriate category based on scope and testability: ## OTS Software Item -- External dependency not developed in-house - typically a third-party published +- External dependency from outside the program - typically a third-party published software package (NuGet, npm, etc.), hosted service, or tool -- Our own published software package becomes an OTS item to any system that - consumes it +- A package produced by an unrelated program (inside or outside the organization) + is treated as OTS by any consuming system - Tested through integration tests proving required functionality works - Examples: System.Text.Json, Entity Framework, third-party APIs +- **Artifact locations** (OTS items have no internal design documentation): + - Requirements: `docs/reqstream/ots/{ots-name}.yaml` + - Design: `docs/design/ots/{ots-name}.md` (integration/usage design) + - Verification: `docs/verification/ots/{ots-name}.md` + - These folders sit parallel to system folders (not inside any system folder) +- System design documentation records which OTS items each system depends on +- **OTS test project**: If no other verification evidence is available (e.g., vendor test results, + published compliance reports), a dedicated test project holds OTS integration tests - one test + file per OTS item requiring tests. OTS items are repo-level (not per-system), so the project + uses a fixed repo-level name: `test/OtsSoftwareTests/` (C#) or `test/ots_software_tests/` + (Python/other) — never prefixed with a system or project name. + +## Shared Package + +- A software package produced by a different repository within the same program +- The consuming repository references advertised features, not internal design or source +- Traceability to program-level requirements runs through the top-level project, + not directly between repositories +- Verified through any appropriate approach in the consuming repository - most commonly + downstream integration tests that transitively prove the advertised features are functional +- **Artifact locations** (no internal design documentation in the consuming repository): + - Requirements: `docs/reqstream/shared/{package-name}.yaml` + - Design: `docs/design/shared/{package-name}.md` (integration/usage design) + - Verification: `docs/verification/shared/{package-name}.md` + - These folders sit parallel to system and OTS folders # Software Item Artifact Model @@ -89,7 +125,13 @@ unit - because reviewing any one artifact in isolation cannot determine whether the item is correct, well-designed, and proven to work: - **Requirements** - WHAT the item must do (drives all other artifacts; applies to all item types) -- **Design** - HOW the item satisfies its requirements (in-house items only: system, subsystem, unit) +- **Design** - HOW the item satisfies its requirements (full design for local items: system, + subsystem, unit; integration/usage design for OTS and Shared Package) - **Verification Design** - HOW the requirements will be tested (applies to all item types) -- **Source code** - The implementation of the design (in-house units only) +- **Source code** - The implementation of the design (local units only; not applicable to OTS or Shared Package) - **Tests** - PROOF the item does WHAT it is required to do (applies to all item types) + +Where the repository models its software structure in SysML2, each item's part def carries +`comment` metadata pointing at these same artifact locations (`sourceRef`/`testRef`/ +`designRef`/`verificationRef`/`reqRef`) so agents can query them directly — see +`sysml2-modeling.md`. diff --git a/.github/standards/sysml2-modeling.md b/.github/standards/sysml2-modeling.md new file mode 100644 index 0000000..c5558e1 --- /dev/null +++ b/.github/standards/sysml2-modeling.md @@ -0,0 +1,232 @@ +--- +name: SysML2 Modeling +description: Follow these standards when creating or modifying the SysML2 architecture + model, its rendered views, or the software structure it feeds into design documentation. +globs: ["docs/sysml2/**/*.sysml"] +--- + +# SysML2 Modeling Standard + +## Required Standards + +Read these standards first before applying this standard: + +- **`software-items.md`** - Software categorization (System/Subsystem/Unit/OTS/Shared Package) +- **`design-documentation.md`** - Design document structure that embeds the diagrams this + standard produces + +## Purpose + +The repository's software structure is modeled in SysML2 under `docs/sysml2/` rather than +hand-maintained as prose or an ASCII tree. The model is the authoritative, machine-queryable +source of structure; rendered diagrams and `docs/design/introduction.md`'s narrative are +generated/derived artifacts. AI agents should query the model (see `sysml2tools-query` +skill) before deep-diving into source code to understand what a piece of the system is, +why it exists, and what it depends on. + +## Repository Structure + +```text +docs/sysml2/ +├── model/ +│ ├── {system-name}.sysml # system-level part def only (no subsystems/units inline) +│ ├── {system-name}/ +│ │ ├── {subsystem-name}.sysml # subsystem part def; nests further for sub-subsystems +│ │ └── {subsystem-name}/ +│ │ └── {unit-name}.sysml # one file per unit +│ ├── ots.sysml # OTS dependency parts (optional; if OTS items exist) +│ └── shared.sysml # Shared Package parts (optional; if Shared Packages exist) +└── views/ + └── design-views.sysml # named view usages rendered for the design document +``` + +`docs/sysml2/model/` mirrors the same folder shape as `docs/design/`, `docs/reqstream/`, and +`docs/verification/` — one `.sysml` file per System/Subsystem/Unit, at the same nesting depth +as that item's companion design/requirements/verification files. This keeps each file small +and keeps PRs that touch one unit's model from producing unrelated diffs in unrelated units. +`docs/sysml2/views/` is a sibling of `model/`, not nested inside it, so a single +`docs/sysml2/model/**/*.sysml` glob never needs to exclude view files (`sysml2tools` has no +exclude-glob syntax). + +There is no separate "stable entry point" file — a repository may contain multiple systems, +so no single alias name would generalize. Agents discover the system(s) present by running +`query list --kind "part def"` or `query find` (see the `sysml2tools-query` skill) over +`docs/sysml2/model/**/*.sysml`, not by assuming a fixed name. + +Always pass the full set of `.sysml` files (or an equivalent glob) to every `sysml2tools` +invocation — the model spans multiple files and cross-references between them; files sharing +the same `package Name { ... }` merge into one namespace automatically with no `import` +required, as long as all files are passed together. As of `sysml2tools` 0.1.0-beta.5, +`lint` and `render` both expand `*`/`**` glob patterns internally (recursing correctly into +subdirectories), so pass a single **quoted** glob string (e.g. `'docs/sysml2/**/*.sysml'`) +and let the tool resolve it — do not rely on the shell to expand it, and do not quote-strip +the pattern before it reaches the tool. Quoting keeps the behavior identical across +PowerShell and bash, since neither shell needs to (or reliably does) expand `**` itself. + +## Model Content + +- `{system-name}.sysml` defines one `part def` for the System only, with `part` usages + referencing its direct Subsystems/Units (defined in their own files, see below). +- Each `{subsystem-name}.sysml` / `{unit-name}.sysml` defines exactly one `part def`, with a + `doc /* ... */` comment stating its purpose — mirroring what would otherwise be written as + prose in `docs/design/introduction.md`'s Software Structure section. Subsystem files add + `part` usages for their own direct children (nested subsystems or units), matching the + Software Item Hierarchy in `software-items.md`. +- `ots.sysml` / `shared.sysml` define one `part def` per OTS item / Shared Package, referenced + as `part` usages from the system(s) that depend on them. + +## Artifact-Location Comments + +Every System/Subsystem/Unit `part def` records where its companion artifacts live, as named +`comment` elements — not `attribute`s (attribute values are not surfaced by `sysml2tools query +describe`, even in JSON output; comments are). Comments have zero effect on rendered diagrams +(verified: a part def with several comments attached renders with no extra nodes or size +change) and are fully returned by `query describe`, in declaration order, as +`Comment: ...` summary lines — this is how an agent gets every artifact location for a unit +in a single query, without grepping the source tree. + +Use these comment names, in this order, when applicable to the item: + +```sysml +part def {UnitName} { + doc /* One-line purpose statement. */ + + comment sourceRef /* Source: {path to the unit's source file} */ + comment testRef /* Test: {path to the unit's test file} */ + comment designRef /* Design: {path to the unit's design doc} */ + comment verificationRef /* Verification: {path to the unit's verification doc} */ + comment reqRef /* Requirements: {path to the unit's reqstream file} */ +} +``` + +Not every item has all five: + +- **Systems and Subsystems** have no `sourceRef` (no single source file represents a whole + system or subsystem) — use `testRef` for the subsystem-level test file when one exists. +- **Units without a dedicated companion doc** (e.g. small data-model types documented inline + within their subsystem's design doc rather than in their own file) point `designRef` / + `verificationRef` / `reqRef` at the subsystem-level doc, with a short parenthetical note, + e.g. `/* Design: docs/design/{system}/{subsystem}.md (documented as a supporting value type) */`. +- **Units without a dedicated test file** (exercised only indirectly through another unit's + tests) omit `testRef` entirely rather than pointing at an unrelated test file. +- **OTS items** have no `sourceRef`/`testRef` (no local integration code); use `designRef` + (when the optional design doc exists) / `verificationRef` / `reqRef` only. + +This is prose-searchable metadata only — it is not a substitute for the authoritative +requirements/design/verification artifacts, and it does not replace ReqStream as the +requirements source of truth. (This repository currently keeps requirements traceability in +ReqStream; a future migration to native SysML2 `requirement`/`satisfy` modeling is a separate, +not-yet-scheduled change.) + +## Views (`docs/sysml2/views/design-views.sysml`) + +Views control what gets rendered into diagrams for the design document. Use named `view` +**usages** (not `view def` **definitions**) — `expose` is only valid inside a usage: + +```sysml +package {SystemName} { + view SoftwareStructureView { + expose {SystemName}; // whole package: system + subsystems + units + } + + view {SystemName}View { + expose {SystemName}System; // system def only, not expanded into subsystems + } + + view {SubsystemName}View { + expose {SubsystemName}; // one subsystem def only + } +} +``` + +**Critical distinction** (do not confuse these — this cost significant trial-and-error to +discover): `expose ;` is what scopes a rendered diagram's content (the union of the +named element's containment subtree). `render ;` selects a rendering *style* (e.g. +`asInterconnectionDiagram`) — it has **no effect on scope**. `expose` is only legal inside a named +`view Name { ... }` **usage**; it is a syntax/semantic error inside a `view def Name { ... }` +**definition**. `expose` targets must be `::`-qualified or locally-resolvable names, not +dotted member-access chains (`expose foo.bar;` is invalid — use `expose Bar;`). + +**Naming convention** — one `View` suffix per rendered diagram, no `System`/`Subsystem` +suffix duplication: + +- `SoftwareStructureView` - full detail: every system, subsystem, and unit in one diagram +- `{SystemName}View` - one per system, direct members only (not expanded into subsystems) +- `{SubsystemName}View` - one per subsystem (at any nesting depth), that subsystem's own + members only + +When a repository has multiple systems, `SoftwareStructureView` may expose each system's +package individually (`expose {SystemNameA}; expose {SystemNameB};`) or the whole workspace, +whichever produces a single coherent overview diagram. + +## Diagram Embedding + +Render with a single quoted recursive glob for the model tree, plus the views file +(`sysml2tools` 0.1.0-beta.5+ expands and recurses `**` internally, so no shell-side globbing +or explicit per-file listing is needed): + +```pwsh +dotnet sysml2tools render ` + --output docs/design/generated --format svg ` + 'docs/sysml2/model/**/*.sysml' ` + 'docs/sysml2/views/design-views.sysml' +``` + +With multiple views declared and no `--view` flag, `sysml2tools` renders every declared view +in one invocation, one file per view, using each view's own name as the filename +(`{ViewName}.svg`) — no post-render rename step is needed. + +Embed diagrams in `docs/design/` per this rule: every design doc for an item embeds the +diagram for the narrowest view that still shows that item's own immediate structure — + +- `docs/design/introduction.md` — `SoftwareStructureView.svg` (the full-detail overview) +- `docs/design/{system-name}.md` and every unit doc for a unit directly under the system + (no subsystem parent) — `{SystemName}View.svg` +- `docs/design/{system-name}/{subsystem-name}.md` and every unit doc nested under that + subsystem (at any depth) — `{SubsystemName}View.svg` + +Place the image directly under the file's top-level heading, before its first prose +subsection, e.g. `![{Name} Structure]({ViewName}.svg)`. + +## Build and Lint Integration + +- `sysml2tools lint` belongs in `lint.ps1`'s compliance-tools section, **not** as a separate + step in the CI design-document job — `lint.ps1` gates every later job (including document + generation) transitively, so linting the model there is both earlier and non-duplicated. + Pass a single quoted recursive glob, e.g. `dotnet sysml2tools lint 'docs/sysml2/**/*.sysml'` + — `sysml2tools` (0.1.0-beta.5+) expands and recurses this itself, so no + `Get-ChildItem`/shell-side globbing is needed. +- The CI design-document job renders the views (see the render command above) before running + Pandoc, so generated SVGs exist before HTML generation. Rename/stable-filename workarounds + are unnecessary since view names are stable by definition. Pass the model and views globs as + separate quoted arguments (e.g. `'docs/sysml2/model/**/*.sysml' 'docs/sysml2/views/design-views.sysml'`) + — plain PowerShell (the default shell) is sufficient; no `shell: bash`/`shopt -s globstar` + workaround is needed. +- Add `sysml2tools` to `.config/dotnet-tools.json` (`demaconsulting.sysml2tools.tool`) and to + `.versionmark.yaml`'s captured tool list. + +## Fallback + +If the model is stale, doesn't yet cover an item, or a query returns nothing useful, fall +back to `grep`/`glob`/reading source directly. When work adds or changes a Unit/Subsystem, +update the corresponding `.sysml` model file in the same change — this mirrors the existing +requirement to keep `docs/design/*.md` and `docs/reqstream/*.yaml` companion artifacts in +sync. + +## Quality Checks + +- [ ] Every System/Subsystem/Unit in `docs/design/introduction.md` has a matching `part def` + in its own file under `docs/sysml2/model/`, at the same folder depth as its companion + design/reqstream/verification files, with a purpose `doc` comment +- [ ] Every Unit-level `part def` has `sourceRef`/`testRef`/`designRef`/`verificationRef`/ + `reqRef` comments where applicable (see Artifact-Location Comments for documented + exceptions); System/Subsystem `part def`s have `testRef`/`designRef`/`verificationRef`/ + `reqRef` but no `sourceRef` +- [ ] `docs/sysml2/views/design-views.sysml` uses `view Name { expose ...; }` usages, not + `view def` definitions +- [ ] View names follow the `SoftwareStructureView` / `{SystemName}View` / + `{SubsystemName}View` convention +- [ ] `sysml2tools lint` passes on all `.sysml` files +- [ ] Rendered diagrams are embedded in every design doc per the Diagram Embedding rule +- [ ] `sysml2tools` is present in `lint.ps1`, `.config/dotnet-tools.json`, and + `.versionmark.yaml` diff --git a/.github/standards/technical-documentation.md b/.github/standards/technical-documentation.md index 7ff5b5a..23893bd 100644 --- a/.github/standards/technical-documentation.md +++ b/.github/standards/technical-documentation.md @@ -6,9 +6,6 @@ globs: ["docs/**/*.md", "README.md", "!docs/**/generated/**"] # Technical Documentation Standards -This document defines standards for technical documentation within Continuous -Compliance environments. - # Core Principles Technical documentation serves as compliance evidence and must be structured @@ -40,8 +37,11 @@ docs/{collection}/ Without `title.txt` and `definition.yaml` the pipeline cannot generate the document. When creating a new document collection, create these three files together and use -the existing collections under `docs/` as templates - they share a consistent -structure across all collections. +the existing collections under `docs/` as templates. + +The `generated/` folder is **never committed** to the repository - it is created +locally and in CI by the build pipeline. Do not flag its absence as a conformance +issue. **`title.txt`** - YAML front matter with document metadata. Use the existing files under `docs/` as a pattern and keep fields consistent with the rest of @@ -81,23 +81,34 @@ elsewhere causes duplicate sections in the compiled PDF. ## Document Ordering -List documents in logical reading order in Pandoc configuration because -readers need coherent information flow from general to specific topics. +List documents in logical reading order in `definition.yaml`. + +## Heading Depth Rule (MANDATORY) + +A file's top-level heading depth must equal its folder depth under the document +collection root - this ensures Pandoc can concatenate all files in `definition.yaml` +order and produce a coherent outline with no heading-shift configuration: + +| Folder depth | Top heading | +| --- | --- | +| 0 - collection root | `#` | +| 1 - one subfolder deep | `##` | +| 2 - two subfolders deep | `###` | +| N - N subfolders deep | `#` × (N+1) | + +Internal sections use the next heading level down (e.g. a `##` file uses `###` +for *Overview*, *Interfaces*, etc.). Deeply nested files have fewer heading levels +available - keep internal structure flat to avoid excessive nesting. # Writing Guidelines Write technical documentation for clarity and compliance verification: - **Clear and Concise**: Use direct language and avoid unnecessary complexity. - Regulatory reviewers must understand content quickly. -- **Structured Sections**: Use consistent heading hierarchy and section - organization. Enables automated processing and review. -- **Specific Examples**: Include concrete examples with actual values rather - than placeholders. Supports implementation verification. +- **Structured Sections**: Use consistent heading hierarchy and section organization. +- **Specific Examples**: Include concrete examples with actual values rather than placeholders. - **Current Information**: Keep documentation synchronized with code changes. - Outdated documentation invalidates compliance evidence. -- **Traceable Content**: Link documentation to requirements and implementation - where applicable for audit trails. +- **Traceable Content**: Link documentation to requirements and implementation where applicable. ## References Sections @@ -117,26 +128,16 @@ Instead use **verbal references** - plain prose that identifies the target by na > > Refer to the *System Requirements* document for the full specification. -Verbal references are readable by both AI agents and humans in any rendering environment. - # Markdown Format Requirements -Markdown documentation in this repository must follow the formatting standards -defined in `.markdownlint-cli2.yaml` (subject to any exclusions configured there) -for consistency and professional presentation: - -- **120 Character Line Limit**: Keep lines 120 characters or fewer for readability. - Break long lines naturally at punctuation or logical breaks. -- **No Trailing Whitespace**: Remove all trailing spaces and tabs from line - endings to prevent formatting inconsistencies. -- **Blank Lines Around Headings**: Include a blank line both before and after - each heading to improve document structure and readability. -- **Blank Lines Around Lists**: Include a blank line both before and after - numbered and bullet lists to ensure proper rendering and visual separation. -- **ATX-Style Headers**: Use `#` syntax for headers instead of underline style - for consistency across all documentation. -- **Consistent List Indentation**: Use 2-space indentation for nested list - items to maintain uniform formatting. +Follow `.markdownlint-cli2.yaml` formatting standards: + +- **120 Character Line Limit**: Keep lines 120 characters or fewer; break at punctuation or logical breaks. +- **No Trailing Whitespace**: Remove all trailing spaces and tabs. +- **Blank Lines Around Headings**: Include a blank line before and after each heading. +- **Blank Lines Around Lists**: Include a blank line before and after numbered and bullet lists. +- **ATX-Style Headers**: Use `#` syntax, not underline style. +- **Consistent List Indentation**: Use 2-space indentation for nested list items. # Auto-Generated Content (CRITICAL) @@ -147,8 +148,6 @@ build outputs that are overwritten on every CI run: respective `docs/` sections, or in `docs/generated/` for final release artifacts - **Source Modification**: Update source files (requirements YAML, `.reviewmark.yaml`, tool configuration) instead of generated output -- **Tool Integration**: Generated content integrates with CI/CD pipelines and - manual changes disrupt automation # README.md Best Practices @@ -171,20 +170,12 @@ Structure README.md for both human readers and AI agent processing: - **Code Block Languages**: Specify language for syntax highlighting and tool processing - **Clear Prerequisites**: List exact version requirements and dependencies -## Quality Guidelines - -- **Scannable Structure**: Use bullet points, headings, and short paragraphs -- **Current Examples**: Verify all code examples work with current version -- **Link Validation**: Ensure all external links are accessible and current -- **Consistent Tone**: Professional, helpful tone appropriate for technical audience - # Quality Checks Before submitting technical documentation, verify: - [ ] Documentation organized under `docs/` following standard folder structure - [ ] Pandoc collections include `introduction.md` with Purpose and Scope sections -- [ ] Content follows clear and concise writing guidelines with specific examples - [ ] No modifications made to auto-generated markdown files in compliance folders - [ ] README.md includes all required sections with absolute URLs and concrete examples - [ ] Documentation integrated into ReviewMark review-sets for formal review diff --git a/.github/standards/testing-principles.md b/.github/standards/testing-principles.md index 73974ff..917463e 100644 --- a/.github/standards/testing-principles.md +++ b/.github/standards/testing-principles.md @@ -3,11 +3,6 @@ name: Testing Principles description: Follow these standards when developing any software tests. --- -# Testing Principles Standards - -This document defines universal testing principles and quality standards for test development within -Continuous Compliance environments. - # Test Dependency Boundaries (MANDATORY) Respect software item hierarchy boundaries to ensure review-sets can validate proper architectural scope. diff --git a/.github/standards/verification-documentation.md b/.github/standards/verification-documentation.md index f6f407f..494e40f 100644 --- a/.github/standards/verification-documentation.md +++ b/.github/standards/verification-documentation.md @@ -6,123 +6,96 @@ globs: ["docs/verification/**/*.md"] # Required Standards -Read these standards first before applying this standard: - - **`technical-documentation.md`** - General technical documentation standards -- **`software-items.md`** - Software categorization (System/Subsystem/Unit/OTS) - -# Core Principles - -Verification design is the bridge between requirements and tests - it documents HOW -requirements will be verified, enabling reviewers to confirm test completeness without -reading implementation code. +- **`software-items.md`** - Software categorization (System/Subsystem/Unit/OTS/Shared Package) -# Required Structure and Documents - -Organize under `docs/verification/` mirroring the software item hierarchy: +# Folder Structure ```text docs/verification/ -├── introduction.md # Verification overview -├── {system-name}/ # System-level verification folder (one per system) -│ ├── {system-name}.md # System-level verification design -│ ├── {subsystem-name}/ # Subsystem (kebab-case); may nest recursively -│ │ ├── {subsystem-name}.md # Subsystem verification design -│ │ ├── {child-subsystem}/ # Child subsystem (same structure as parent) -│ │ └── {unit-name}.md # Unit-level verification design documents -│ └── {unit-name}.md # Top-level unit verification documents (if not in subsystem) -└── ots/ # OTS items (one verification file per OTS item) - └── {ots-name}.md # Verification evidence for each OTS item +├── introduction.md # heading depth # +├── {system-name}.md # heading depth # +├── {system-name}/ +│ ├── {subsystem-name}.md # heading depth ## +│ ├── {subsystem-name}/ +│ │ └── {unit-name}.md # heading depth ### +│ └── {unit-name}.md # heading depth ## +├── ots.md # heading depth # (if OTS items exist) +├── ots/ +│ └── {ots-name}.md # heading depth ## +├── shared.md # heading depth # (if Shared Packages exist) +└── shared/ + └── {package-name}.md # heading depth ## ``` -## introduction.md (MANDATORY) +All sections in every file are mandatory; write "N/A - {justification}" rather than removing any. +Determine subsystem vs. unit classification from `docs/design/introduction.md` — folder depth does not determine classification. -Follow the standard `introduction.md` format from `technical-documentation.md`. Scope -covers all software items including OTS items (via self-validation if appropriate). +# introduction.md (MANDATORY) -Include a Companion Artifact Structure note so agents and reviewers can navigate from any -artifact to all related files: +Must include: -```text -In-house items have parallel artifacts in: -- Requirements: `docs/reqstream/{system}/.../{item}.yaml` (kebab-case) -- Design: `docs/design/{system}/.../{item}.md` (kebab-case) -- Verification: `docs/verification/{system}/.../{item}.md` (kebab-case) -- Source: `src/{System}/.../{Item}.{ext}` (cased per language) -- Tests: `test/{System}.Tests/.../{Item}Tests.{ext}` (cased per language) - -OTS items have parallel artifacts in: -- Requirements: `docs/reqstream/ots/{ots-name}.yaml` (kebab-case) -- Verification: `docs/verification/ots/{ots-name}.md` (kebab-case) -- Tests: `test/{OtsName}.Tests/...` (cased per language, if required) - -Review-sets: defined in `.reviewmark.yaml` -``` +- **Purpose**: audience and compliance drivers +- **Scope**: items covered and explicitly excluded (no test projects) +- **Companion Artifact Structure**: parallel paths for requirements, design, verification, source, tests +- **References** _(if applicable)_: external standards or specifications - only in `introduction.md` -If the verification design references external documents (standards, specifications), include -a `## References` section in `introduction.md` only - do not add one to any other verification file. +# System Verification Design (MANDATORY) -## System Verification Design (MANDATORY) +Create `{system-name}.md` (`#` heading) and `{system-name}/` folder: -For each system, create a kebab-case folder and `{system-name}.md` covering: +- **Verification Approach**: test types (unit, integration, end-to-end), framework, project structure +- **Test Environment**: OS, runtime, external services, files, or configuration required +- **Acceptance Criteria**: what constitutes a passing system test (IEC 62304 §5.7.2) +- **Test Scenarios**: named scenarios for each system requirement -- System verification strategy and overall test approach -- Test environments and configuration required -- External interface simulation and test-harness design -- End-to-end and integration test scenarios covering system requirements -- Acceptance criteria and pass/fail conditions at the system boundary -- Coverage mapping of system requirements to system-level test scenarios +# Subsystem Verification Design (MANDATORY) -## Subsystem Verification Design (MANDATORY) +Place `{subsystem-name}.md` in the **parent** folder; create `{subsystem-name}/` for children: -For each subsystem, create a kebab-case folder and `{subsystem-name}.md` covering: +- **Verification Approach**: integration test approach and mocking at subsystem boundary +- **Test Environment**: any environment setup beyond the standard test runner +- **Acceptance Criteria**: what constitutes a passing subsystem test (IEC 62304 §5.5.2) +- **Test Scenarios**: named scenarios including boundary conditions, error paths, and normal operation -- Subsystem verification strategy and integration test approach -- Dependencies that must be mocked or stubbed at the subsystem boundary -- Integration test scenarios covering subsystem requirements -- Coverage mapping of subsystem requirements to subsystem-level test scenarios +# Unit Verification Design (MANDATORY) -## Unit Verification Design (MANDATORY) +Place `{unit-name}.md` in the **parent** folder: -For each unit, create `{unit-name}.md` covering: +- **Verification Approach**: what is mocked/stubbed and why; injected vs. real dependencies +- **Test Environment**: any environment setup beyond the standard test runner +- **Acceptance Criteria**: what constitutes passing unit tests (IEC 62304 §5.5.2) +- **Test Scenarios**: named scenarios including boundary values, error paths, and normal operation -- Verification approach for each unit requirement -- Named test scenarios including boundary conditions, error paths, and normal-operation cases -- Which dependencies are mocked and how they are configured -- Coverage mapping of every unit requirement to at least one named test scenario +# OTS Verification Evidence (when OTS items exist) -## OTS Verification Evidence (when OTS items are used) +Create `docs/verification/ots.md` (`#` heading) covering the overall OTS verification strategy. -For each OTS item, create `docs/verification/ots/{ots-name}.md` covering: +For each OTS item, create `docs/verification/ots/{ots-name}.md` (`##` heading) covering: +verification approach (self-validation, integration tests, vendor evidence). -- The OTS item's required functionality (reference `docs/reqstream/ots/{ots-name}.yaml`) -- Verification of each requirement (using self-validation evidence if appropriate) -- Coverage mapping of OTS requirements to test scenarios +# Shared Package Verification Evidence (when Shared Packages exist) -# Writing Guidelines +Create `docs/verification/shared.md` (`#` heading) covering the overall Shared Package verification strategy. -- **Test Coverage**: Map every requirement to at least one named test scenario so - reviewers can verify completeness without reading test code -- **Scenario Clarity**: Name each scenario clearly - "Valid input returns parsed result" not "Test 1" -- **Boundary Conditions**: Call out boundary values, error inputs, and edge cases explicitly -- **Isolation Strategy**: Describe what is mocked or stubbed and why at each level -- **Traceability**: Link to requirements where applicable using ReqStream patterns -- **Verbal Cross-References**: Reference other documents by name - do not use markdown - hyperlinks, which break in compiled PDFs +For each Shared Package, create `docs/verification/shared/{package-name}.md` (`##` heading) covering: +verification approach. + +# Writing Guidelines -Mermaid diagrams may supplement text descriptions where test flow benefits from visual -representation, but must not replace text content. +- Name scenarios clearly ("Valid input returns parsed result", not "Test 1") +- Use verbal cross-references - not markdown hyperlinks (break in PDF) +- Use Mermaid diagrams to supplement (not replace) text # Quality Checks -Before submitting verification documentation, verify: - -- [ ] Every requirement at each level is mapped to at least one named test scenario -- [ ] System verification documents cover end-to-end and integration scenarios -- [ ] Subsystem verification documents identify mocked boundaries and integration scenarios -- [ ] Unit verification documents identify individual scenarios including boundary and error paths -- [ ] Subsystem documentation folders use kebab-case names mirroring the source subsystem structure -- [ ] All documents follow technical documentation formatting standards -- [ ] Content is current with requirements and test implementation -- [ ] Every OTS item has `docs/verification/ots/{ots-name}.md` with requirement coverage -- [ ] Documents are integrated into ReviewMark review-sets for formal review +- [ ] `introduction.md` includes Companion Artifact Structure +- [ ] Each file's heading depth matches its folder depth +- [ ] All folders use kebab-case mirroring source structure +- [ ] Each system/subsystem/unit file includes all mandatory sections (Verification Approach, + Test Environment, Acceptance Criteria, Test Scenarios) +- [ ] Non-applicable mandatory sections contain "N/A - {justification}" +- [ ] Requirements-to-test coverage is tracked via the ReqStream trace matrix, not in these documents +- [ ] `docs/verification/ots.md` and `docs/verification/ots/{ots-name}.md` exist when OTS items are present +- [ ] `docs/verification/shared.md` and `docs/verification/shared/{package-name}.md` exist when Shared Packages are present +- [ ] Documents are integrated into ReviewMark review-sets diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index 5ec5c09..5140bf1 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -356,7 +356,7 @@ jobs: dotnet versionmark --capture --job-id "build-docs" \ --output "artifacts/versionmark-build-docs.json" -- \ dotnet git node npm pandoc weasyprint sarifmark sonarmark reqstream \ - buildmark versionmark reviewmark fileassert + buildmark versionmark reviewmark fileassert sysml2tools echo "✓ Tool versions captured" # === PREPARE DOCUMENT OUTPUT === @@ -615,6 +615,14 @@ jobs: shell: bash run: mkdir -p docs/design/generated + - name: Render Software Structure diagrams with SysML2Tools + shell: pwsh + run: > + dotnet sysml2tools render + --output docs/design/generated --format svg + 'docs/sysml2/model/**/*.sysml' + 'docs/sysml2/views/design-views.sysml' + - name: Generate Design HTML with Pandoc shell: bash run: > diff --git a/.reviewmark.yaml b/.reviewmark.yaml index 629bd8b..a8b3de0 100644 --- a/.reviewmark.yaml +++ b/.reviewmark.yaml @@ -11,11 +11,12 @@ needs-review: - "**/*.cs" # All C# source and test files - "docs/reqstream/**/*.yaml" # Requirements files - "docs/design/**/*.md" # Design documentation files - - "docs/verification/**/*.md" # Verification documentation files - - "docs/user_guide/**/*.md" # User guide documentation + - "docs/verification/**/*.md" # Verification documentation files + - "docs/user_guide/**/*.md" # User guide documentation + - "docs/sysml2/**/*.sysml" # SysML2 architecture model - "!**/obj/**" # Exclude build output - "!**/bin/**" # Exclude build output - - "!node_modules/**" # Exclude npm dependencies + - "!node_modules/**" # Exclude npm dependencies - "!**/.venv/**" # Exclude Python virtual environment # Evidence source: review data and index.json are located in the 'reviews' branch @@ -26,113 +27,169 @@ evidence-source: type: url location: https://raw.githubusercontent.com/demaconsulting/TemplateDotNetLibrary/reviews/index.json +# Global context shown to every reviewer for orientation (not fingerprinted). +context: + - docs/design/introduction.md + # Review sets following hierarchical scope principles. # Each review-set focuses on a single compliance question with manageable file counts. reviews: - # Purpose + # Purpose Review (only one per repository) - id: Purpose - title: Review of user-facing capabilities and system promises + title: Review that README and User Guide are Coherent and Complete + context: + - "!docs/design/introduction.md" # exclude design intro from user-facing review paths: + - "README.md" # project readme + - "docs/user_guide/**/*.md" # user guide + + # Decomposition Review (only one per repository) + - id: Decomposition + title: Review that TemplateDotNetLibrary Decomposition Addresses the Stated Purpose + context: - "README.md" - "docs/user_guide/**/*.md" - - "docs/reqstream/template-dot-net-library/template-dot-net-library.yaml" - - "docs/design/introduction.md" - - "docs/design/template-dot-net-library/template-dot-net-library.md" + paths: + - "requirements.yaml" # root requirements file + - "docs/design/introduction.md" # design introduction + - "docs/sysml2/**/*.sysml" # SysML2 model (authoritative structure) - # TemplateDotNetLibrary - Specials + # TemplateDotNetLibrary-Architecture Review (one per system) - id: TemplateDotNetLibrary-Architecture - title: Review of Template DotNet Library system architecture and operational validation + title: Review that TemplateDotNetLibrary Architecture Satisfies Requirements + context: + - "README.md" + - "docs/user_guide/**/*.md" paths: - - "docs/reqstream/template-dot-net-library/template-dot-net-library.yaml" - - "docs/design/introduction.md" - - "docs/design/template-dot-net-library/template-dot-net-library.md" - - "docs/verification/introduction.md" - - "docs/verification/template-dot-net-library/template-dot-net-library.md" - - "test/DemaConsulting.TemplateDotNetLibrary.Tests/TemplateDotNetLibraryTests.cs" - + - "docs/reqstream/template-dot-net-library.yaml" # system requirements + - "docs/design/introduction.md" # design introduction + - "docs/design/template-dot-net-library.md" # system design + - "docs/verification/introduction.md" # verification introduction + - "docs/verification/template-dot-net-library.md" # system verification + - "test/DemaConsulting.TemplateDotNetLibrary.Tests/TemplateDotNetLibraryTests.cs" # integration tests + + # TemplateDotNetLibrary-Design Review (one per system) - id: TemplateDotNetLibrary-Design - title: Review of Template DotNet Library architectural and design consistency + title: Review that TemplateDotNetLibrary Design is Consistent and Complete + context: + - "docs/reqstream/template-dot-net-library.yaml" + paths: + - "docs/reqstream/template-dot-net-library/platform-requirements.yaml" # platform requirements + - "docs/design/introduction.md" # design introduction + - "docs/design/template-dot-net-library.md" # system design + - "docs/design/template-dot-net-library/**/*.md" # all system design documents + - "docs/design/ots.md" # OTS overview + + # TemplateDotNetLibrary-Verification Review (one per system) + - id: TemplateDotNetLibrary-Verification + title: Review that TemplateDotNetLibrary Verification is Consistent and Complete + context: + - "docs/reqstream/template-dot-net-library.yaml" paths: - - "docs/reqstream/template-dot-net-library/template-dot-net-library.yaml" - - "docs/reqstream/template-dot-net-library/platform-requirements.yaml" - - "docs/design/introduction.md" - - "docs/design/template-dot-net-library/**/*.md" - - "docs/verification/introduction.md" + - "docs/verification/introduction.md" # verification introduction + - "docs/verification/template-dot-net-library.md" # system verification + - "docs/verification/template-dot-net-library/**/*.md" # all verification documents + - "docs/verification/ots.md" # OTS overview + # TemplateDotNetLibrary-AllRequirements Review (one per system) - id: TemplateDotNetLibrary-AllRequirements - title: Review of Template DotNet Library requirements quality and traceability + title: Review that All TemplateDotNetLibrary Requirements are Complete + context: + - "docs/design/template-dot-net-library.md" + - "docs/reqstream/template-dot-net-library.yaml" paths: - - "requirements.yaml" - - "docs/reqstream/template-dot-net-library/**/*.yaml" - - "docs/reqstream/ots/*.yaml" + - "requirements.yaml" # root requirements file + - "docs/reqstream/**/*.yaml" # all requirements files - # TemplateDotNetLibrary - Demo + # TemplateDotNetLibrary-Demo Review (one per unit) - id: TemplateDotNetLibrary-Demo - title: Review of Demo Unit Implementation + title: Review that TemplateDotNetLibrary Demo Implementation is Correct + context: + - "docs/design/template-dot-net-library.md" + - "docs/reqstream/template-dot-net-library.yaml" paths: - - "docs/reqstream/template-dot-net-library/demo.yaml" - - "docs/design/template-dot-net-library/demo.md" - - "docs/verification/template-dot-net-library/demo.md" - - "src/DemaConsulting.TemplateDotNetLibrary/Demo.cs" - - "test/DemaConsulting.TemplateDotNetLibrary.Tests/DemoTests.cs" + - "docs/reqstream/template-dot-net-library/demo.yaml" # unit requirements + - "docs/design/template-dot-net-library/demo.md" # unit design + - "docs/verification/template-dot-net-library/demo.md" # unit verification + - "src/DemaConsulting.TemplateDotNetLibrary/Demo.cs" # unit source + - "test/DemaConsulting.TemplateDotNetLibrary.Tests/DemoTests.cs" # unit tests - # OTS Items + # OTS-BuildMark Review (one per OTS item) - id: OTS-BuildMark - title: Review of BuildMark OTS verification evidence + title: Review that BuildMark Provides Required Functionality paths: - - "docs/reqstream/ots/buildmark.yaml" - - "docs/verification/ots/buildmark.md" + - "docs/reqstream/ots/buildmark.yaml" # OTS requirements + - "docs/design/ots/buildmark.md" # OTS integration design + - "docs/verification/ots/buildmark.md" # OTS verification + # OTS-FileAssert Review (one per OTS item) - id: OTS-FileAssert - title: Review of FileAssert OTS verification evidence + title: Review that FileAssert Provides Required Functionality paths: - - "docs/reqstream/ots/fileassert.yaml" - - "docs/verification/ots/fileassert.md" + - "docs/reqstream/ots/fileassert.yaml" # OTS requirements + - "docs/design/ots/fileassert.md" # OTS integration design + - "docs/verification/ots/fileassert.md" # OTS verification + # OTS-Pandoc Review (one per OTS item) - id: OTS-Pandoc - title: Review of Pandoc OTS verification evidence + title: Review that Pandoc Provides Required Functionality paths: - - "docs/reqstream/ots/pandoc.yaml" - - "docs/verification/ots/pandoc.md" + - "docs/reqstream/ots/pandoc.yaml" # OTS requirements + - "docs/design/ots/pandoc.md" # OTS integration design + - "docs/verification/ots/pandoc.md" # OTS verification + # OTS-ReqStream Review (one per OTS item) - id: OTS-ReqStream - title: Review of ReqStream OTS verification evidence + title: Review that ReqStream Provides Required Functionality paths: - - "docs/reqstream/ots/reqstream.yaml" - - "docs/verification/ots/reqstream.md" + - "docs/reqstream/ots/reqstream.yaml" # OTS requirements + - "docs/design/ots/reqstream.md" # OTS integration design + - "docs/verification/ots/reqstream.md" # OTS verification + # OTS-ReviewMark Review (one per OTS item) - id: OTS-ReviewMark - title: Review of ReviewMark OTS verification evidence + title: Review that ReviewMark Provides Required Functionality paths: - - "docs/reqstream/ots/reviewmark.yaml" - - "docs/verification/ots/reviewmark.md" + - "docs/reqstream/ots/reviewmark.yaml" # OTS requirements + - "docs/design/ots/reviewmark.md" # OTS integration design + - "docs/verification/ots/reviewmark.md" # OTS verification + # OTS-SarifMark Review (one per OTS item) - id: OTS-SarifMark - title: Review of SarifMark OTS verification evidence + title: Review that SarifMark Provides Required Functionality paths: - - "docs/reqstream/ots/sarifmark.yaml" - - "docs/verification/ots/sarifmark.md" + - "docs/reqstream/ots/sarifmark.yaml" # OTS requirements + - "docs/design/ots/sarifmark.md" # OTS integration design + - "docs/verification/ots/sarifmark.md" # OTS verification + # OTS-SonarMark Review (one per OTS item) - id: OTS-SonarMark - title: Review of SonarMark OTS verification evidence + title: Review that SonarMark Provides Required Functionality paths: - - "docs/reqstream/ots/sonarmark.yaml" - - "docs/verification/ots/sonarmark.md" + - "docs/reqstream/ots/sonarmark.yaml" # OTS requirements + - "docs/design/ots/sonarmark.md" # OTS integration design + - "docs/verification/ots/sonarmark.md" # OTS verification + # OTS-VersionMark Review (one per OTS item) - id: OTS-VersionMark - title: Review of VersionMark OTS verification evidence + title: Review that VersionMark Provides Required Functionality paths: - - "docs/reqstream/ots/versionmark.yaml" - - "docs/verification/ots/versionmark.md" + - "docs/reqstream/ots/versionmark.yaml" # OTS requirements + - "docs/design/ots/versionmark.md" # OTS integration design + - "docs/verification/ots/versionmark.md" # OTS verification + # OTS-WeasyPrint Review (one per OTS item) - id: OTS-WeasyPrint - title: Review of WeasyPrint OTS verification evidence + title: Review that WeasyPrint Provides Required Functionality paths: - - "docs/reqstream/ots/weasyprint.yaml" - - "docs/verification/ots/weasyprint.md" + - "docs/reqstream/ots/weasyprint.yaml" # OTS requirements + - "docs/design/ots/weasyprint.md" # OTS integration design + - "docs/verification/ots/weasyprint.md" # OTS verification + # OTS-xUnit Review (one per OTS item) - id: OTS-xUnit - title: Review of xUnit OTS verification evidence + title: Review that xUnit Provides Required Functionality paths: - - "docs/reqstream/ots/xunit.yaml" - - "docs/verification/ots/xunit.md" + - "docs/reqstream/ots/xunit.yaml" # OTS requirements + - "docs/design/ots/xunit.md" # OTS integration design + - "docs/verification/ots/xunit.md" # OTS verification diff --git a/.versionmark.yaml b/.versionmark.yaml index 9275778..0074ac8 100644 --- a/.versionmark.yaml +++ b/.versionmark.yaml @@ -72,3 +72,8 @@ tools: fileassert: command: dotnet tool list regex: '(?i)demaconsulting\.fileassert\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)' + + # sysml2tools (DemaConsulting.Sysml2Tools.Tool from dotnet tool list) + sysml2tools: + command: dotnet tool list + regex: '(?i)demaconsulting\.sysml2tools\.tool\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)' diff --git a/AGENTS.md b/AGENTS.md index 7a629b5..cf5e111 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,12 +1,16 @@ # Project Overview > **Downstream customization required**: Replace the `TODO` values below with -> values specific to the target repository. +> values specific to the target repository. These values are the canonical source +> for project-wide template placeholders used throughout the repository. -- **name**: TODO -- **description**: TODO -- **languages**: TODO -- **technologies**: TODO +- **project-name**: TODO — repository/project name (e.g., `ReqStream`) +- **organization**: TODO — organization name for document authorship (e.g., `DEMA Consulting`) +- **project-tagline**: TODO — document subtitle; 4–8 words, noun phrase, no period + (e.g., `Requirements traceability for .NET projects`) +- **description**: TODO — full project description, may be multiple sentences +- **languages**: TODO — programming languages used (e.g., `C#`, `C++`) +- **technologies**: TODO — key technologies and frameworks (e.g., `.NET`, `CMake`) # Project Structure @@ -23,6 +27,7 @@ │ ├── requirements_doc/ │ ├── requirements_report/ │ ├── reqstream/ +│ ├── sysml2/ │ ├── user_guide/ │ └── verification/ ├── src/ @@ -31,12 +36,27 @@ └── {test-project}/ ``` +# Language and Spelling (ALL Agents) + +Always use **US English** spelling in all output (code, comments, documentation, +commit messages, and reports). + +# Reference Template + +This repository follows a reference template for structure and file conventions. + +- **template-url**: `https://github.com/demaconsulting/Agents/raw/refs/heads/template` +- **Repository map**: `{template-url}/repository-map.md` +- **Template files**: `{template-url}/{file-path}` for files described in the map + # Codebase Navigation (ALL Agents) -When working with source code, design, or requirements artifacts, read -`docs/design/introduction.md` first. It provides the software structure, -folder layout, and companion artifact locations. Use it as the primary map -before searching the filesystem. +When working with source code, design, or requirements artifacts, query the SysML2 +architecture model under `docs/sysml2/` first (see the `sysml2tools-query` skill) to +understand software structure, purpose, and relationships. Fall back to +`docs/design/introduction.md` for the human-facing narrative, folder layout, and +companion artifact locations, and use it as the primary map when the model doesn't +yet cover something. # Key Configuration Files @@ -51,6 +71,7 @@ before searching the filesystem. - **`package.json`** - Node.js dependencies for formatting tools - **`requirements.yaml`** - Root requirements file with includes - **`pip-requirements.txt`** - Python dependencies for yamllint and yamlfix +- **`docs/sysml2/`** - SysML2 architecture model; authoritative source for software structure - **`fix.ps1`** - Applies all auto-fixers silently (dotnet format, markdown, YAML). Always exits 0. - **`build.ps1`** - Builds the solution and runs all tests. @@ -59,17 +80,16 @@ before searching the filesystem. Before performing any work, agents must read and apply the relevant standards from `.github/standards/`. Use this matrix to determine which to load: -| Work involves... | Load these standards | -|----------------------|------------------------------------------------------------------------------------| -| Any code | `coding-principles.md` | -| C# code | `coding-principles.md`, `csharp-language.md` | -| Any tests | `testing-principles.md` | -| C# tests | `testing-principles.md`, `csharp-testing.md` | -| Requirements | `requirements-principles.md`, `software-items.md`, `reqstream-usage.md` | -| Design docs | `software-items.md`, `design-documentation.md`, `technical-documentation.md` | -| Verification docs | `software-items.md`, `verification-documentation.md`, `technical-documentation.md` | -| Review configuration | `software-items.md`, `reviewmark-usage.md` | -| Any documentation | `technical-documentation.md` | +- **Any code**: `coding-principles.md` +- **C# code**: `coding-principles.md`, `csharp-language.md` +- **Any tests**: `testing-principles.md` +- **C# tests**: `testing-principles.md`, `csharp-testing.md` +- **Requirements**: `requirements-principles.md`, `software-items.md`, `reqstream-usage.md` +- **Design docs**: `software-items.md`, `design-documentation.md`, `technical-documentation.md` +- **Verification docs**: `software-items.md`, `verification-documentation.md`, `technical-documentation.md` +- **Review configuration**: `software-items.md`, `reviewmark-usage.md` +- **Software structure**: `sysml2-modeling.md` +- **Any documentation**: `technical-documentation.md` Load only the standards relevant to your specific task scope. @@ -79,11 +99,15 @@ The default agent should handle simple, straightforward tasks directly. Delegate to specialized agents only for specific scenarios: - **Pre-PR lint cleanup** (fix all lint issues before pull request) → Call the lint-fix agent -- **Light development work** (small fixes, simple features) → Call the developer agent +- **Scoped fixes with no new user-visible behavior** (PR review comments, doc + corrections, known bug fixes with defined root cause) → Call the developer agent - **Light quality checking** (basic validation) → Call the quality agent -- **Formal feature implementation** (complex, multi-step) → Call the implementation agent -- **Formal bug resolution** (complex debugging, systematic fixes) → Call the implementation agent +- **Any change introducing new user-visible behavior** (features, enhancements, + new commands or options) → Call the implementation agent +- **Formal bug resolution** (complex debugging, unknown root cause) → Call the implementation agent - **Formal reviews** (compliance verification, detailed analysis) → Call the formal-review agent +- **Structural audit**: (repository layout vs. template) → Call the template-sync agent +- **Implementation planning only** (review a plan before committing to implementation) → Call the planning agent # Agent Reporting (Specialized Agents Must Follow) @@ -92,21 +116,21 @@ Specialized agents MUST generate a completion report: 1. Save to `.agent-logs/{agent-name}-{subject}-{unique-id}.md` where `{subject}` is a kebab-case task summary (max 5 words) and `{unique-id}` is a short unique suffix (e.g., 8-char hex or timestamp) -2. Start with `**Result**: (SUCCEEDED|FAILED)` as the first metadata field +2. Start with `**Result**: (SUCCEEDED|FAILED|INCOMPLETE)` as the first metadata field 3. Include the agent-specific report sections defined in each agent's prompt 4. Return the summary to the caller Result semantics for orchestrator decision-making: -- **SUCCEEDED**: Work completed and all applicable quality gates met +- **SUCCEEDED**: Work completed and all quality gates applicable to that agent's scope met - **FAILED**: Work could not be completed or quality gates not met - **INCOMPLETE**: Work cannot proceed without information only the user can - provide (implementation agent only) + provide (implementation, planning, and template-sync agents) # Formatting (After Making Changes) After making changes, run the auto-fix pass. This applies all available fixers -silently and **always exits 0** — agents do not need to respond to its output. +silently and **always exits 0** - agents do not need to respond to its output. ```pwsh pwsh ./fix.ps1 @@ -114,17 +138,17 @@ pwsh ./fix.ps1 This automatically handles: `dotnet format`, markdown formatting, and YAML formatting. Full lint compliance is a **pre-PR responsibility**, not an agent -responsibility — invoke the lint-fix agent once before submitting a pull request. +responsibility - invoke the lint-fix agent once before submitting a pull request. ## CI Quality Tools CI runs `lint.ps1` which checks: markdownlint-cli2, cspell, yamllint, dotnet format, -reqstream, versionmark, and reviewmark. +reqstream, versionmark, reviewmark, and sysml2tools. # Scope Discipline (ALL Agents Must Follow) - **No generated file access**: Files inside any `generated/` folder are build - outputs — do not read, lint, or modify them + outputs - do not read, lint, or modify them - **Minimum necessary changes**: Only modify files directly required by the task - **No speculative refactoring**: Do not refactor code adjacent to the change unless the task explicitly requests it diff --git a/docs/design/definition.yaml b/docs/design/definition.yaml index 3263656..a98a693 100644 --- a/docs/design/definition.yaml +++ b/docs/design/definition.yaml @@ -5,8 +5,19 @@ resource-path: input-files: - docs/design/title.txt - docs/design/introduction.md - - docs/design/template-dot-net-library/template-dot-net-library.md + - docs/design/template-dot-net-library.md - docs/design/template-dot-net-library/demo.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 + - docs/design/ots/sarifmark.md + - docs/design/ots/sonarmark.md + - docs/design/ots/versionmark.md + - docs/design/ots/weasyprint.md + - docs/design/ots/xunit.md template: template.html table-of-contents: true number-sections: true diff --git a/docs/design/introduction.md b/docs/design/introduction.md index 2dd07d4..1f5d758 100644 --- a/docs/design/introduction.md +++ b/docs/design/introduction.md @@ -27,6 +27,19 @@ software items, specifically: - **TemplateDotNetLibrary (System)** — The complete .NET library template system - **Demo (Unit)** — Demonstration greeting class providing example functionality +The following OTS items are also covered: + +- **BuildMark** — build-notes documentation tool +- **FileAssert** — document assertion tool +- **Pandoc** — Markdown-to-HTML conversion tool +- **ReqStream** — requirements traceability tool +- **ReviewMark** — file review enforcement tool +- **SarifMark** — SARIF report conversion tool +- **SonarMark** — SonarCloud quality report tool +- **VersionMark** — tool-version documentation tool +- **WeasyPrint** — HTML-to-PDF conversion tool +- **xUnit** — unit-testing framework + Version applicability: This design applies to all versions of the Template DotNet Library. The following topics are explicitly excluded from this design documentation: @@ -39,37 +52,18 @@ The following topics are explicitly excluded from this design documentation: ## Software Structure -The following tree diagram shows how the Template DotNet Library software items are organized -across System, Subsystem, and Unit levels according to software-items classification standards: +The software structure is modeled in SysML2 under `docs/sysml2/` and rendered to the +diagram below by SysML2Tools as part of the build pipeline. AI agents should query the +SysML2 model directly (see the `sysml2tools-query` skill) rather than parsing this +diagram or the prose below. -```text -TemplateDotNetLibrary (System) -└── Demo (Unit) -``` +![Software Structure](SoftwareStructureView.svg) This template demonstrates a minimal system structure with no subsystems — it contains only the `Demo` unit directly under the system level. In more complex implementations, subsystems would organize related units and provide architectural boundaries with well-defined interfaces and responsibilities. -## Companion Artifact Structure - -Each software item has corresponding artifacts in parallel directory trees: - -```text -TemplateDotNetLibrary (System) -└── Demo (Unit) -``` - -Each software item has artifacts in these parallel locations: - -- Requirements: `docs/reqstream/{system}/.../{item}.yaml` (kebab-case) -- Design docs: `docs/design/{system}/.../{item}.md` (kebab-case) -- Verification design: `docs/verification/{system}/.../{item}.md` (kebab-case) -- Source code: `src/{System}/.../{Item}.cs` (PascalCase for C#) -- Tests: `test/{System}.Tests/.../{Item}Tests.cs` (PascalCase for C#) -- Review-sets: defined in `.reviewmark.yaml` - ## Folder Layout The source code folder structure mirrors the software structure organization, with file paths @@ -94,6 +88,18 @@ Throughout this document: methods/algorithms, and interactions with other units. - Text tables are used in preference to diagrams, which may not render in all PDF viewers. +## Companion Artifact Structure + +Each software item has corresponding artifacts in parallel directory trees: + +- Requirements: `docs/reqstream/{system}/.../{item}.yaml` (kebab-case) +- Design docs: `docs/design/{system}/.../{item}.md` (kebab-case) +- Verification design: `docs/verification/{system}/.../{item}.md` (kebab-case) +- Source code: `src/{System}/.../{Item}.cs` (PascalCase for C#) +- Tests: `test/{System}.Tests/.../{Item}Tests.cs` (PascalCase for C#) +- SysML2 model: `docs/sysml2/model/{system}/.../{item}.sysml` (kebab-case) +- Review-sets: defined in `.reviewmark.yaml` + ## References - [REF-1] Template DotNet Library User Guide () diff --git a/docs/design/ots.md b/docs/design/ots.md new file mode 100644 index 0000000..adf128f --- /dev/null +++ b/docs/design/ots.md @@ -0,0 +1,33 @@ +# OTS Integration Design + +This document describes the overall Off-The-Shelf (OTS) integration strategy for the Template +DotNet Library repository. + +## Overview + +The Template DotNet Library itself has zero runtime NuGet dependencies — the `Demo` unit is +implemented exclusively against the .NET Base Class Library. All OTS items listed below are +build-time and quality-pipeline tools, not runtime library dependencies. Each OTS item provides one +stage of the documentation, requirements-traceability, testing, and quality-reporting pipeline +invoked by `build.ps1`, `lint.ps1`, and the `.github/workflows/build.yaml` CI workflow. None of +these tools are linked into, or shipped with, the compiled NuGet package. + +## OTS Items + +| OTS Item | Purpose | +|-------------|----------------------------------------------------------------------| +| BuildMark | Generates build-notes documentation from GitHub Actions metadata | +| FileAssert | Validates generated documents (HTML/PDF) against acceptance criteria | +| Pandoc | Converts Markdown documentation to HTML | +| ReqStream | Enforces requirements-to-test traceability | +| ReviewMark | Enforces file review coverage and currency | +| SarifMark | Converts CodeQL SARIF results into a markdown report | +| SonarMark | Generates a SonarCloud quality report | +| VersionMark | Captures and publishes tool-version information | +| WeasyPrint | Converts HTML documentation to PDF | +| xUnit | Discovers and executes unit and integration tests | + +Each item's individual design document (`docs/design/ots/{ots-name}.md`) records its Purpose, +Features Used, and Integration Pattern. Each item's requirements and verification evidence are +recorded in `docs/reqstream/ots/{ots-name}.yaml` and `docs/verification/ots/{ots-name}.md` +respectively. diff --git a/docs/design/ots/buildmark.md b/docs/design/ots/buildmark.md new file mode 100644 index 0000000..e7eb3b4 --- /dev/null +++ b/docs/design/ots/buildmark.md @@ -0,0 +1,24 @@ +## BuildMark + +### Purpose + +DemaConsulting.BuildMark is used to generate build-notes documentation from GitHub Actions +metadata. It was chosen because it queries the GitHub API directly, giving the pipeline a +single source of truth for workflow-run details (commits, issues, pull requests) without +requiring hand-maintained release notes. + +### Features Used + +- Markdown build-notes report generation from GitHub Actions workflow-run metadata +- Git integration for reading version tags and commit history +- Issue tracking integration for including linked GitHub issues and pull requests +- Rules-based routing of items into report sections +- Known-issues reporting (inclusion of open bugs in the generated report) + +### Integration Pattern + +BuildMark is invoked as a `dotnet tool` (`dotnet buildmark`) from the `.github/workflows/build.yaml` +CI workflow during the build-docs job to produce +`docs/build_notes/generated/build_notes.md`. It is a stateless CLI invocation — each run reads +its inputs, writes its markdown output, and exits; there is no initialization, configuration +object, or disposal step beyond the command-line arguments supplied on each invocation. diff --git a/docs/design/ots/fileassert.md b/docs/design/ots/fileassert.md new file mode 100644 index 0000000..cf9cfe3 --- /dev/null +++ b/docs/design/ots/fileassert.md @@ -0,0 +1,24 @@ +## FileAssert + +### Purpose + +DemaConsulting.FileAssert is used to validate generated documents (HTML and PDF) produced during +the documentation build, asserting that each document exists and contains expected content. It +was chosen because it provides a single declarative mechanism for confirming that Pandoc and +WeasyPrint produced meaningful, correctly formed output at every stage of the pipeline. + +### Features Used + +- File-existence assertions (glob-pattern based) +- Text-content assertions (`contains`) against generated HTML and PDF files +- TRX test-results generation (`--results`) so FileAssert's own self-validation and its + document-assertion runs both feed ReqStream traceability + +### Integration Pattern + +FileAssert is invoked as a `dotnet tool` (`dotnet fileassert`) from +`.github/workflows/build.yaml` after each Pandoc/WeasyPrint conversion step (Build Notes, Code +Quality, Review Plan, Review Report, Design, Verification, and User Guide documents), and via +`.fileassert.yaml` for its self-validation configuration. It is a stateless CLI invocation — +each run reads a configuration/target file, asserts, and exits with a pass/fail code; there is +no initialization, long-lived configuration object, or disposal step. diff --git a/docs/design/ots/pandoc.md b/docs/design/ots/pandoc.md new file mode 100644 index 0000000..16a3ee8 --- /dev/null +++ b/docs/design/ots/pandoc.md @@ -0,0 +1,25 @@ +## Pandoc + +### Purpose + +Pandoc (via DemaConsulting.PandocTool) is used to convert Markdown source documentation to HTML +as part of the documentation build pipeline. It was chosen as a widely adopted, well-tested +document converter that reliably renders Markdown, tables, and diagrams into standards-compliant +HTML. + +### Features Used + +- Markdown-to-HTML conversion for Build Notes, Code Quality, Review Plan, Review Report, Design, + Verification, and User Guide documents +- Table-of-contents generation (`table-of-contents: true`) +- Section numbering (`number-sections: true`) +- Custom HTML templating (`template.html`) and resource-path resolution for embedded images + +### Integration Pattern + +Pandoc is invoked as a `dotnet tool` (`dotnet pandoc`) from `.github/workflows/build.yaml`, +driven by the `definition.yaml` manifest files under each `docs/*` folder (e.g. +`docs/design/definition.yaml`, `docs/verification/definition.yaml`) that list the ordered +`input-files` to concatenate and convert. It is a stateless CLI invocation per document type — +each run reads a manifest, produces one HTML file, and exits; there is no initialization, +configuration object, or disposal step beyond the manifest file supplied on each invocation. diff --git a/docs/design/ots/reqstream.md b/docs/design/ots/reqstream.md new file mode 100644 index 0000000..e72e9cd --- /dev/null +++ b/docs/design/ots/reqstream.md @@ -0,0 +1,26 @@ +## ReqStream + +### Purpose + +DemaConsulting.ReqStream is used to enforce that every requirement in `requirements.yaml` is +linked to passing test evidence. It was chosen because it provides both structural linting of +requirements files and enforcement-mode traceability checking, making incomplete or unproven +requirements a build-breaking condition rather than a manual review task. + +### Features Used + +- Requirements-file loading and parsing (`requirements.yaml` and its `includes`) +- Trace-matrix generation linking requirements to TRX test-result evidence +- Requirements report and justifications document export to markdown +- Tag-based requirement filtering +- Enforcement mode (`--enforce`), which exits non-zero when any requirement lacks test evidence +- Lint mode (`--lint`), which checks requirements YAML files for structural and semantic issues + +### Integration Pattern + +ReqStream is invoked as a `dotnet tool` from two places: `lint.ps1` runs +`dotnet reqstream --lint --requirements requirements.yaml` as an early-detection lint gate, and +`.github/workflows/build.yaml` runs `dotnet reqstream --enforce` with all accumulated TRX +test-evidence files to generate `requirements.md`, `justifications.md`, and `trace_matrix.md`. +It is a stateless CLI invocation — each run reads `requirements.yaml` and TRX files, writes its +reports, and exits; there is no initialization, configuration object, or disposal step. diff --git a/docs/design/ots/reviewmark.md b/docs/design/ots/reviewmark.md new file mode 100644 index 0000000..d9b415d --- /dev/null +++ b/docs/design/ots/reviewmark.md @@ -0,0 +1,31 @@ +## ReviewMark + +### Purpose + +DemaConsulting.ReviewMark is used to manage file-review status enforcement. It was chosen because +it turns the informal practice of "review before merge" into an enforceable, structured process: +review-sets, review evidence, and review currency are all tracked and machine-checkable rather +than relying on manual sign-off. + +### Features Used + +- Review-plan generation (`--plan`) from `.reviewmark.yaml` review-set definitions +- Review-report generation (`--report`) documenting review coverage and currency against the + evidence store +- Evidence-index scanning (`--index`) of PDF review evidence into an `index.json` catalogue +- Enforcement mode (`--enforce`), which exits non-zero when files in a review-set are not current +- Elaboration mode (`--elaborate`), which prints a review-set's ID, fingerprint, and file list for + agent consumption +- Lint mode (`--lint`), which validates `.reviewmark.yaml` for structural and semantic issues +- Working-directory override (`--dir`) + +### Integration Pattern + +ReviewMark is invoked as a `dotnet tool` from three places: `lint.ps1` runs +`dotnet reviewmark --lint` as an early-detection configuration check, and +`.github/workflows/build.yaml` runs ReviewMark to generate +`docs/code_review_plan/generated/plan.md` and `docs/code_review_report/generated/report.md`, and +to enforce review currency against the evidence store published on the repository's `reviews` +branch. It is a stateless CLI invocation — each run reads `.reviewmark.yaml` and the evidence +source, produces its output or exit code, and exits; there is no initialization, configuration +object, or disposal step. diff --git a/docs/design/ots/sarifmark.md b/docs/design/ots/sarifmark.md new file mode 100644 index 0000000..6610c99 --- /dev/null +++ b/docs/design/ots/sarifmark.md @@ -0,0 +1,23 @@ +## SarifMark + +### Purpose + +DemaConsulting.SarifMark is used to convert CodeQL SARIF scan results into a human-readable +markdown report. It was chosen because it lets the pipeline surface static-analysis findings as +part of the standard build-artifact documentation set, alongside SonarMark's cloud-hosted quality +data, rather than requiring reviewers to open the SARIF file separately. + +### Features Used + +- SARIF-file reading of CodeQL code-scanning output +- Markdown report generation summarizing SARIF findings +- Enforcement mode, which returns a non-zero exit code when the SARIF input contains reported + issues + +### Integration Pattern + +SarifMark is invoked as a `dotnet tool` (`dotnet sarifmark`) from `.github/workflows/build.yaml` +after the CodeQL scanning step, both to generate `docs/code_quality/generated/codeql-quality.md` +and to enforce a clean result. It is a stateless CLI invocation — each run reads a SARIF file, +writes its markdown report or returns an exit code, and exits; there is no initialization, +configuration object, or disposal step. diff --git a/docs/design/ots/sonarmark.md b/docs/design/ots/sonarmark.md new file mode 100644 index 0000000..a403b19 --- /dev/null +++ b/docs/design/ots/sonarmark.md @@ -0,0 +1,23 @@ +## SonarMark + +### Purpose + +DemaConsulting.SonarMark is used to retrieve quality-gate and metrics data from SonarCloud and +render it as a markdown report. It was chosen because it lets the pipeline include SonarCloud's +quality-gate status, issues, and hot-spots directly in the release artifact documentation set, +next to SarifMark's CodeQL report. + +### Features Used + +- Quality-gate status retrieval from the SonarCloud API +- Issues retrieval from the SonarCloud API +- Hot-spots retrieval from the SonarCloud API +- Markdown report generation combining quality-gate, issues, and hot-spots data + +### Integration Pattern + +SonarMark is invoked as a `dotnet tool` (`dotnet sonarmark`) from `.github/workflows/build.yaml` +after the SonarCloud analysis step, to generate `docs/code_quality/generated/sonar-quality.md`. +It is a stateless CLI invocation — each run queries the live SonarCloud API, writes its markdown +report, and exits; there is no initialization, configuration object, or disposal step beyond the +project key and authentication token supplied on each invocation. diff --git a/docs/design/ots/versionmark.md b/docs/design/ots/versionmark.md new file mode 100644 index 0000000..5b85802 --- /dev/null +++ b/docs/design/ots/versionmark.md @@ -0,0 +1,25 @@ +## VersionMark + +### Purpose + +DemaConsulting.VersionMark is used to capture and publish version metadata for each `dotnet tool` +used in the pipeline. It was chosen because pinned build-tool versions must be visible in the +release artifacts for compliance auditing, without hand-maintaining a versions list that would go +stale as tools are updated. + +### Features Used + +- Version capture (`--capture`) of tool-version JSON files per CI job +- Version publishing (`--publish`) combining captured JSON files into a versions markdown report +- Lint mode (`--lint`), which validates the `.versionmark.yaml` configuration for structural and + semantic errors + +### Integration Pattern + +VersionMark is invoked as a `dotnet tool` from three places: `lint.ps1` runs +`dotnet versionmark --lint` as an early-detection configuration check; each CI job in +`.github/workflows/build.yaml` runs `dotnet versionmark --capture` to record the versions of tools +used in that job; and the build-docs job runs `dotnet versionmark --publish` to produce +`docs/build_notes/generated/versions.md`, included in the Build Notes document. It is a stateless +CLI invocation — each run reads its configuration/input files, writes its output, and exits; there +is no initialization, long-lived configuration object, or disposal step. diff --git a/docs/design/ots/weasyprint.md b/docs/design/ots/weasyprint.md new file mode 100644 index 0000000..5863910 --- /dev/null +++ b/docs/design/ots/weasyprint.md @@ -0,0 +1,22 @@ +## WeasyPrint + +### Purpose + +DemaConsulting.WeasyPrintTool is used to convert HTML documents to PDF as part of the +documentation build pipeline. It was chosen as a standards-compliant HTML/CSS-to-PDF renderer +that produces consistent, printable PDF/A release artifacts from the same HTML that Pandoc +generates. + +### Features Used + +- HTML-to-PDF conversion for Build Notes, Code Quality, Review Plan, Review Report, Design, + Verification, and User Guide documents +- PDF page-count and content rendering suitable for FileAssert validation of rendered text + +### Integration Pattern + +WeasyPrint is invoked as a `dotnet tool` (`dotnet weasyprint`) from +`.github/workflows/build.yaml` immediately after each corresponding Pandoc HTML-conversion step, +producing the final PDF release artifacts. It is a stateless CLI invocation — each run reads one +HTML file, writes one PDF file, and exits; there is no initialization, configuration object, or +disposal step beyond the input/output file paths supplied on each invocation. diff --git a/docs/design/ots/xunit.md b/docs/design/ots/xunit.md new file mode 100644 index 0000000..270a746 --- /dev/null +++ b/docs/design/ots/xunit.md @@ -0,0 +1,22 @@ +## xUnit + +### Purpose + +xUnit v3 (`xunit.v3` and `xunit.runner.visualstudio`) is used as the unit-testing framework for +the Template DotNet Library. It was chosen as the standard, widely supported .NET test framework +that discovers and executes `[Fact]`/`[Theory]` test methods and produces TRX results consumable +by downstream tooling. + +### Features Used + +- Test discovery and execution of `[Fact]`-annotated test methods in + `DemaConsulting.TemplateDotNetLibrary.Tests` +- TRX result-file generation, consumed by ReqStream for requirements-to-test traceability + +### Integration Pattern + +xUnit is invoked indirectly through `dotnet test` in `build.ps1` and in the test jobs of +`.github/workflows/build.yaml`; there is no direct CLI invocation of an `xunit` tool by name. +It is a stateless test-run invocation — each run discovers tests in the compiled test assembly, +executes them, writes TRX output, and exits; there is no initialization, configuration object, or +disposal step beyond the standard .NET test-project configuration (`.csproj` test SDK settings). diff --git a/docs/design/template-dot-net-library/template-dot-net-library.md b/docs/design/template-dot-net-library.md similarity index 56% rename from docs/design/template-dot-net-library/template-dot-net-library.md rename to docs/design/template-dot-net-library.md index aee080b..c5eb4a6 100644 --- a/docs/design/template-dot-net-library/template-dot-net-library.md +++ b/docs/design/template-dot-net-library.md @@ -2,32 +2,22 @@ This document provides the system-level design for the Template DotNet Library. -## System Architecture +![Template DotNet Library Structure](TemplateDotNetLibraryView.svg) + +## Architecture The Template DotNet Library is a minimal .NET library template demonstrating DEMA Consulting best practices. The system consists of: - **Demo Unit**: Simple greeting functionality demonstrating library patterns -## External Interfaces - -### Dependencies - -**Runtime Dependencies:** - -- **.NET Runtime**: Provides core framework functionality +There are no subsystems and no relationships between software items beyond the system exposing +the `Demo` unit directly through its public API; see _Demo Unit Design_ for the unit's internal +collaboration (none — `Demo` is a self-contained leaf class). -**Build and Quality Tooling:** - -- **xUnit v3**: Unit testing framework for verification -- **ReqStream**: Requirements traceability enforcement -- **ReviewMark**: File review management -- **BuildMark/VersionMark**: Build and version documentation -- **SonarMark/SarifMark**: Quality analysis integration - -### Public API +## External Interfaces -The system exposes: +The system exposes the following public API to external consumers: - **Demo()**: Default constructor; initializes the instance with the default prefix `"Hello"` - **Demo(string prefix)**: Custom-prefix constructor; initializes the instance with the specified @@ -37,7 +27,37 @@ The system exposes: - **Demo.DemoMethod(string name)**: Returns a greeting string in the format `{prefix}, {name}!`. Throws `ArgumentNullException` if `name` is null; throws `ArgumentException` if `name` is an empty string. -- Package metadata and documentation for NuGet distribution + +| Interface | Direction | Format | Constraints | +|--------------------------------|------------------|-------------------------------|------------------------------| +| `Demo()` | Inbound | Constructor call | None; always succeeds | +| `Demo(string prefix)` | Inbound | Constructor call | `prefix` non-null, non-empty | +| `Demo.Prefix` | Outbound | `string` property read | None; always succeeds | +| `Demo.DemoMethod(string name)` | Inbound/Outbound | Method call / `string` return | `name` non-null, non-empty | + +## Dependencies + +The Template DotNet Library has zero runtime NuGet dependencies — it is implemented exclusively +against the .NET Base Class Library. The following OTS items are used for building and verifying +this system (not consumed at runtime); see _OTS Integration Design_ (`docs/design/ots.md`) and +each item's dedicated design document for details: + +- **BuildMark** — generates build-notes documentation; see _BuildMark Design_ +- **FileAssert** — validates generated documents against acceptance criteria; see + _FileAssert Design_ +- **Pandoc** — converts Markdown documentation to HTML; see _Pandoc Design_ +- **ReqStream** — enforces requirements-to-test traceability; see _ReqStream Design_ +- **ReviewMark** — enforces file review coverage and currency; see _ReviewMark Design_ +- **SarifMark** — converts CodeQL SARIF results to markdown; see _SarifMark Design_ +- **SonarMark** — generates SonarCloud quality reports; see _SonarMark Design_ +- **VersionMark** — captures and publishes tool-version information; see _VersionMark Design_ +- **WeasyPrint** — converts HTML documentation to PDF; see _WeasyPrint Design_ +- **xUnit** — executes unit and integration tests; see _xUnit Design_ + +## Risk Control Measures + +N/A - Template DotNet Library is a demonstration template with no safety-critical functionality +requiring risk control measures (IEC 62304 §5.3.3). ## Data Flow @@ -56,14 +76,14 @@ The system exposes: 3. **Processing**: Simple string formatting combining stored prefix and supplied name 4. **Output**: Formatted greeting string in the format `{prefix}, {name}!` -## System Constraints +## Design Constraints - **Simplicity**: Minimal functionality to serve as template - **Compliance**: All functionality must be traceable to requirements - **Quality**: Zero warnings, full test coverage, complete documentation - **Portability**: Compatible across supported .NET platforms -## Platform Support +### Platform Support The library targets the following frameworks, enabling broad compatibility across modern .NET runtimes and legacy environments: @@ -85,7 +105,7 @@ Portability is achieved by restricting the implementation exclusively to Base Cl APIs available across all target frameworks. No platform-specific native interop, OS-specific APIs, or framework-version-specific features are used. -## Integration Patterns +### Integration Patterns - **NuGet Packaging**: Standard .NET library packaging and distribution - **CI/CD Integration**: Automated build, test, and quality validation diff --git a/docs/design/template-dot-net-library/demo.md b/docs/design/template-dot-net-library/demo.md index e414c2e..63c7b92 100644 --- a/docs/design/template-dot-net-library/demo.md +++ b/docs/design/template-dot-net-library/demo.md @@ -1,29 +1,31 @@ -# Demo +## Demo + +![Template DotNet Library Structure](TemplateDotNetLibraryView.svg) The `Demo` class is the sole software unit in the Template DotNet Library. It serves as a demonstration of how a DEMA Consulting .NET library class should be structured, documented, and tested. -## Overview +### Purpose `Demo` is a simple greeting class that constructs a greeting string by combining a configurable prefix with a caller-supplied name. It has no external dependencies and performs no I/O. Instances are immutable after construction and are therefore safe for concurrent access. -## Data Model +### Data Model | Field | Type | Description | |-----------------|----------------|--------------------------------------------------| | `_prefix` | `string` | The greeting prefix stored at construction time. | | `DefaultPrefix` | `const string` | The default greeting prefix (`"Hello"`). | -## Methods +### Key Methods -### Demo() +#### Demo() Default constructor. Delegates to `Demo(string prefix)` with `DefaultPrefix` as the argument. -### Demo(string prefix) +#### Demo(string prefix) Custom-prefix constructor. Validates that `prefix` is non-null and non-empty using `ArgumentException.ThrowIfNullOrEmpty`, then stores it in `_prefix`. @@ -33,7 +35,7 @@ Custom-prefix constructor. Validates that `prefix` is non-null and non-empty usi - `ArgumentNullException` — when `prefix` is `null` - `ArgumentException` — when `prefix` is an empty string -### DemoMethod(string name) +#### DemoMethod(string name) Returns a greeting string in the format `"{prefix}, {name}!"`. Validates that `name` is non-null and non-empty using `ArgumentException.ThrowIfNullOrEmpty`. @@ -45,11 +47,26 @@ non-null and non-empty using `ArgumentException.ThrowIfNullOrEmpty`. **Returns:** A `string` in the format `"{prefix}, {name}!"`. -### Prefix +#### Prefix Read-only property that exposes `_prefix` to callers. -## Interactions +### Error Handling + +Both the custom-prefix constructor and `DemoMethod` validate their string arguments using +`ArgumentException.ThrowIfNullOrEmpty`, which throws `ArgumentNullException` when the argument is +`null` and `ArgumentException` when the argument is an empty string. `Demo` performs no local +error handling or recovery — validation failures are detected at the point of entry and the +resulting exception propagates directly to the caller uncaught. There is no internal state to +roll back because invalid arguments are rejected before any field is assigned. + +### Dependencies + +N/A - Demo has no dependencies beyond the .NET base class library. + +### Callers `Demo` has no interactions with other units. It is a self-contained leaf class with no -dependencies beyond the .NET base class library. +dependencies beyond the .NET base class library. It is a public API entry point: it is invoked +externally by consumers of the Template DotNet Library package, not by any other unit within +this system. diff --git a/docs/reqstream/template-dot-net-library/template-dot-net-library.yaml b/docs/reqstream/template-dot-net-library.yaml similarity index 100% rename from docs/reqstream/template-dot-net-library/template-dot-net-library.yaml rename to docs/reqstream/template-dot-net-library.yaml diff --git a/docs/sysml2/model/template-dot-net-library.sysml b/docs/sysml2/model/template-dot-net-library.sysml new file mode 100644 index 0000000..bd06dc7 --- /dev/null +++ b/docs/sysml2/model/template-dot-net-library.sysml @@ -0,0 +1,18 @@ +package TemplateDotNetLibrary { + doc + /* + * TemplateDotNetLibrary is a .NET library template demonstrating DEMA Consulting + * best practices for structuring, documenting, and testing a DotNet library. + */ + + part def TemplateDotNetLibrarySystem { + doc /* The Template DotNet Library system as a whole. */ + + comment testRef /* Test: test/DemaConsulting.TemplateDotNetLibrary.Tests/TemplateDotNetLibraryTests.cs */ + comment designRef /* Design: docs/design/template-dot-net-library.md */ + comment verificationRef /* Verification: docs/verification/template-dot-net-library.md */ + comment reqRef /* Requirements: docs/reqstream/template-dot-net-library.yaml */ + + part demo : Demo; + } +} diff --git a/docs/sysml2/model/template-dot-net-library/demo.sysml b/docs/sysml2/model/template-dot-net-library/demo.sysml new file mode 100644 index 0000000..d2aa621 --- /dev/null +++ b/docs/sysml2/model/template-dot-net-library/demo.sysml @@ -0,0 +1,11 @@ +package TemplateDotNetLibrary { + part def Demo { + doc /* Demonstration greeting class showing how a DEMA Consulting .NET library class should be structured, documented, and tested. */ + + comment sourceRef /* Source: src/DemaConsulting.TemplateDotNetLibrary/Demo.cs */ + comment testRef /* Test: test/DemaConsulting.TemplateDotNetLibrary.Tests/DemoTests.cs */ + comment designRef /* Design: docs/design/template-dot-net-library/demo.md */ + comment verificationRef /* Verification: docs/verification/template-dot-net-library/demo.md */ + comment reqRef /* Requirements: docs/reqstream/template-dot-net-library/demo.yaml */ + } +} diff --git a/docs/sysml2/views/design-views.sysml b/docs/sysml2/views/design-views.sysml new file mode 100644 index 0000000..2d7f30d --- /dev/null +++ b/docs/sysml2/views/design-views.sysml @@ -0,0 +1,14 @@ +// Views rendered into docs/design/generated/ for the Design document. +// Reopens the TemplateDotNetLibrary package so each 'expose' statement can reference +// its target part def directly. Per SysML2Tools syntax, 'expose' is only valid +// inside a named 'view' usage (not a 'view def' definition), and it - not +// 'render' - is what scopes the rendered diagram content. +package TemplateDotNetLibrary { + view SoftwareStructureView { + expose TemplateDotNetLibrary; + } + + view TemplateDotNetLibraryView { + expose TemplateDotNetLibrarySystem; + } +} diff --git a/docs/verification/definition.yaml b/docs/verification/definition.yaml index b8b2bff..37f6b43 100644 --- a/docs/verification/definition.yaml +++ b/docs/verification/definition.yaml @@ -5,8 +5,9 @@ resource-path: input-files: - docs/verification/title.txt - docs/verification/introduction.md - - docs/verification/template-dot-net-library/template-dot-net-library.md + - docs/verification/template-dot-net-library.md - docs/verification/template-dot-net-library/demo.md + - docs/verification/ots.md - docs/verification/ots/buildmark.md - docs/verification/ots/fileassert.md - docs/verification/ots/pandoc.md diff --git a/docs/verification/introduction.md b/docs/verification/introduction.md index 4dc8f59..311e63e 100644 --- a/docs/verification/introduction.md +++ b/docs/verification/introduction.md @@ -51,26 +51,8 @@ The following topics are explicitly excluded from this verification documentatio ## Companion Artifact Structure -Each software item in the structure below has corresponding artifacts in parallel directory trees: - -```text -TemplateDotNetLibrary (System) -└── Demo (Unit) - -OTS Items -├── BuildMark -├── FileAssert -├── Pandoc -├── ReqStream -├── ReviewMark -├── SarifMark -├── SonarMark -├── VersionMark -├── WeasyPrint -└── xUnit -``` - -In-house items have artifacts in these parallel locations: +Each software item covered by this document has corresponding artifacts in parallel directory +trees. In-house items have artifacts in these parallel locations: - Requirements: `docs/reqstream/{system}/.../{item}.yaml` (kebab-case) - Design docs: `docs/design/{system}/.../{item}.md` (kebab-case) diff --git a/docs/verification/ots.md b/docs/verification/ots.md new file mode 100644 index 0000000..22a46aa --- /dev/null +++ b/docs/verification/ots.md @@ -0,0 +1,28 @@ +# OTS Verification Evidence + +This document describes the overall Off-The-Shelf (OTS) verification strategy for the Template +DotNet Library repository. + +## Overview + +Every OTS item used to build and verify this repository is verified through a combination of +self-validation CLI flags (where the tool provides a `--validate` or equivalent self-test mode) +and pipeline-evidence-based verification (where a passing CI pipeline run, having produced and +validated the expected output at each stage, constitutes proof that the tool executed correctly). +Each item's individual verification document (`docs/verification/ots/{ots-name}.md`) records the +detailed approach and named test scenarios. + +## OTS Items + +| OTS Item | Verification Approach | +|-------------|-----------------------------------------------------------------------------| +| BuildMark | Self-validation CLI suite plus pipeline evidence via build-notes document | +| FileAssert | Self-validation CLI suite plus transitive evidence from document assertions | +| Pandoc | Pipeline evidence: FileAssert assertions on each generated HTML document | +| ReqStream | Self-validation CLI suite plus pipeline evidence via --enforce traceability | +| ReviewMark | Self-validation CLI suite plus pipeline evidence via review plan/report | +| SarifMark | Self-validation CLI suite plus pipeline evidence via SARIF markdown report | +| SonarMark | Self-validation CLI suite plus pipeline evidence via SonarCloud report | +| VersionMark | Self-validation CLI suite plus pipeline evidence via version data | +| WeasyPrint | Pipeline evidence: FileAssert assertions on each generated PDF document | +| xUnit | Self-validation via discovery, execution, and TRX reporting of tests | diff --git a/docs/verification/template-dot-net-library/template-dot-net-library.md b/docs/verification/template-dot-net-library.md similarity index 75% rename from docs/verification/template-dot-net-library/template-dot-net-library.md rename to docs/verification/template-dot-net-library.md index e118a33..79d96a6 100644 --- a/docs/verification/template-dot-net-library/template-dot-net-library.md +++ b/docs/verification/template-dot-net-library.md @@ -2,7 +2,7 @@ This document describes the system-level verification strategy for the Template DotNet Library. -## Verification Strategy +## Verification Approach The Template DotNet Library system is verified through system-level integration tests that exercise the library as a whole from the perspective of a consumer. Tests instantiate the library @@ -91,19 +91,3 @@ public API correctly surfaces the configured prefix to callers. A system-level test run passes when all seven scenarios above pass without error or exception beyond those explicitly asserted. Any unexpected exception, wrong exception type, or wrong return value constitutes a failure. - -## Requirements Coverage - -| Requirement ID | Test Scenario(s) | -|------------------------------------------|------------------------------------------------------------------| -| Template-Lib-Greeting | Integration: Provides Expected Functionality | -| Template-Lib-Greeting | Customization: Handles Configuration Properly | -| Template-Lib-GreetingFormat | Integration: Provides Expected Functionality | -| Template-Lib-GreetingFormat | Customization: Handles Configuration Properly | -| Template-Lib-DefaultPrefix | Integration: Provides Expected Functionality | -| Template-Lib-CustomPrefix | Customization: Handles Configuration Properly | -| Template-Lib-Prefix | Integration: Exposes Configured Prefix | -| Template-Lib-ValidationNull-DemoMethod | Validation: DemoMethod Null Input Throws ArgumentNullException | -| Template-Lib-ValidationNull-Constructor | Validation: Constructor Null Prefix Throws ArgumentNullException | -| Template-Lib-ValidationEmpty-DemoMethod | Validation: DemoMethod Empty Input Throws ArgumentException | -| Template-Lib-ValidationEmpty-Constructor | Validation: Constructor Empty Prefix Throws ArgumentException | diff --git a/docs/verification/template-dot-net-library/demo.md b/docs/verification/template-dot-net-library/demo.md index 4a722fb..4532a9f 100644 --- a/docs/verification/template-dot-net-library/demo.md +++ b/docs/verification/template-dot-net-library/demo.md @@ -1,8 +1,8 @@ -# Demo Unit Verification Design +## Demo Unit Verification Design This document describes the unit-level verification strategy for the `Demo` class. -## Verification Strategy +### Verification Approach The `Demo` unit is verified through unit tests that exercise each public method and constructor in isolation. Because `Demo` has no external dependencies beyond the .NET base class library, no @@ -12,16 +12,16 @@ thrown exception types. Unit tests reside in `DemoTests.cs` within the `DemaConsulting.TemplateDotNetLibrary.Tests` project. -## Test Environment +### Test Environment - **Framework**: xUnit v3 running under the .NET SDK - **Execution**: `dotnet test` invoked by `build.ps1` and the CI pipeline - **Mocking**: None required; `Demo` has no injectable dependencies - **Isolation**: Each test method constructs its own `Demo` instance; no shared state between tests -## Unit-Level Test Scenarios +### Unit-Level Test Scenarios -### Template-Demo-Greeting: DemoMethod Default Prefix Returns Greeting +#### Template-Demo-Greeting: DemoMethod Default Prefix Returns Greeting **Test**: `Demo_DemoMethod_DefaultPrefix_ReturnsGreeting` @@ -29,7 +29,7 @@ Constructs a `Demo` using the default constructor and calls `DemoMethod("World") return value is exactly `"Hello, World!"`. Verifies the core greeting format `"{prefix}, {name}!"` under the default prefix `"Hello"`. -### Template-Demo-Greeting: DemoMethod Custom Prefix Returns Greeting +#### Template-Demo-Greeting: DemoMethod Custom Prefix Returns Greeting **Test**: `Demo_DemoMethod_CustomPrefix_ReturnsGreeting` @@ -37,7 +37,7 @@ Constructs a `Demo` with custom prefix `"Hi"` and calls `DemoMethod("Alice")`. A value is exactly `"Hi, Alice!"`. Verifies that a non-default prefix is correctly combined with the caller-supplied name in the `"{prefix}, {name}!"` format. -### Template-Demo-DefaultPrefix: DefaultPrefix Constant Is Hello +#### Template-Demo-DefaultPrefix: DefaultPrefix Constant Is Hello **Test**: `Demo_DefaultPrefix_Read_IsHello` @@ -45,7 +45,7 @@ Reads the `Demo.DefaultPrefix` constant directly and asserts its value is `"Hell that the constant has not silently changed, protecting callers who depend on the default greeting string. -### Template-Demo-DefaultPrefix: Default Constructor Sets Default Prefix +#### Template-Demo-DefaultPrefix: Default Constructor Sets Default Prefix **Test**: `Demo_DefaultConstructor_WithNoArgs_SetsDefaultPrefix` @@ -53,7 +53,7 @@ Constructs a `Demo` using the default constructor and reads the `Prefix` propert property value equals `Demo.DefaultPrefix`. Verifies that the default constructor stores the expected prefix constant, confirming the `"Hello"` default is propagated end-to-end. -### Template-Demo-AcceptCustomPrefix: Constructor With Custom Prefix Sets Prefix +#### Template-Demo-AcceptCustomPrefix: Constructor With Custom Prefix Sets Prefix **Test**: `Demo_Prefix_WithCustomConstruction_ReturnsCustomPrefix` @@ -62,7 +62,7 @@ property value exactly matches the string passed at construction. Verifies that accepts and stores a caller-specified prefix, and that the `Prefix` property exposes the configured value correctly. -### Template-Demo-ValidationNull-DemoMethod: DemoMethod Null Input Throws ArgumentNullException +#### Template-Demo-ValidationNull-DemoMethod: DemoMethod Null Input Throws ArgumentNullException **Test**: `Demo_DemoMethod_NullInput_ThrowsArgumentNullException` @@ -70,7 +70,7 @@ Constructs a `Demo` with the default constructor and calls `DemoMethod(null)`. A `ArgumentNullException` (not the base `ArgumentException`) is thrown. Verifies that the unit explicitly rejects `null` with the precise exception subtype. -### Template-Demo-ValidationEmpty-DemoMethod: DemoMethod Empty Input Throws ArgumentException +#### Template-Demo-ValidationEmpty-DemoMethod: DemoMethod Empty Input Throws ArgumentException **Test**: `Demo_DemoMethod_EmptyInput_ThrowsArgumentException` @@ -78,7 +78,7 @@ Constructs a `Demo` with the default constructor and calls `DemoMethod(string.Em that `ArgumentException` (not `ArgumentNullException`) is thrown. This is the empty-string boundary condition — distinct from the null case. -### Template-Demo-ValidationNull-Constructor: Constructor Null Prefix Throws ArgumentNullException +#### Template-Demo-ValidationNull-Constructor: Constructor Null Prefix Throws ArgumentNullException **Test**: `Demo_Constructor_NullPrefix_ThrowsArgumentNullException` @@ -86,7 +86,7 @@ Attempts to construct a `Demo` with a `null` prefix argument. Asserts that `ArgumentNullException` (not the base `ArgumentException`) is thrown. Verifies that the custom-prefix constructor explicitly rejects `null`. -### Template-Demo-ValidationEmpty-Constructor: Constructor Empty Prefix Throws ArgumentException +#### Template-Demo-ValidationEmpty-Constructor: Constructor Empty Prefix Throws ArgumentException **Test**: `Demo_Constructor_EmptyPrefix_ThrowsArgumentException` @@ -94,18 +94,7 @@ Attempts to construct a `Demo` with `string.Empty` as the prefix. Asserts that `ArgumentException` (not `ArgumentNullException`) is thrown. This is the empty-string boundary condition for the constructor — distinct from the null case. -## Requirements Coverage - -| Requirement ID | Test Scenario(s) | -|-------------------------------------------|-----------------------------------------------------------| -| Template-Demo-Greeting | DemoMethod Default Prefix Returns Greeting | -| Template-Demo-Greeting | DemoMethod Custom Prefix Returns Greeting | -| Template-Demo-DefaultPrefix | DefaultPrefix Constant Is Hello | -| Template-Demo-DefaultPrefix | Default Constructor Sets Default Prefix | -| Template-Demo-AcceptCustomPrefix | Constructor With Custom Prefix Sets Prefix | -| Template-Demo-Prefix | Constructor With Custom Prefix Sets Prefix | -| Template-Demo-Prefix | Default Constructor Sets Default Prefix | -| Template-Demo-ValidationNull-DemoMethod | DemoMethod Null Input Throws ArgumentNullException | -| Template-Demo-ValidationNull-Constructor | Constructor Null Prefix Throws ArgumentNullException | -| Template-Demo-ValidationEmpty-DemoMethod | DemoMethod Empty Input Throws ArgumentException | -| Template-Demo-ValidationEmpty-Constructor | Constructor Empty Prefix Throws ArgumentException | +### Acceptance Criteria + +A unit test run passes when all nine scenarios above pass without error or unexpected exception; +any unexpected exception type or wrong return value constitutes a failure. diff --git a/lint.ps1 b/lint.ps1 index e4d68ac..89b344d 100644 --- a/lint.ps1 +++ b/lint.ps1 @@ -99,7 +99,7 @@ if (-not $skipNpm) { # } # --- DOTNET LINTING SECTION --- -# Runs compliance tools: reqstream, versionmark, reviewmark. +# Runs compliance tools: reqstream, versionmark, reviewmark, sysml2tools. Write-Host "Linting: compliance tools..." $skipDotnetTools = $false dotnet tool restore > $null @@ -114,6 +114,11 @@ if (-not $skipDotnetTools) { dotnet reviewmark --lint if ($LASTEXITCODE -ne 0) { $lintError = $true } + + if (Test-Path docs/sysml2) { + dotnet sysml2tools lint 'docs/sysml2/**/*.sysml' + if ($LASTEXITCODE -ne 0) { $lintError = $true } + } } # [PROJECT-SPECIFIC] Add additional dotnet tool lint checks here. diff --git a/requirements.yaml b/requirements.yaml index eddf147..d96ca98 100644 --- a/requirements.yaml +++ b/requirements.yaml @@ -1,7 +1,7 @@ --- # Root requirements file - includes all system, unit, platform, and OTS requirements includes: - - docs/reqstream/template-dot-net-library/template-dot-net-library.yaml + - docs/reqstream/template-dot-net-library.yaml - docs/reqstream/template-dot-net-library/demo.yaml - docs/reqstream/template-dot-net-library/platform-requirements.yaml - docs/reqstream/ots/xunit.yaml From c141b14376a72fb9f3348462ca1e5d41baa79cc5 Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Sat, 11 Jul 2026 12:17:18 -0400 Subject: [PATCH 2/4] Add SysML2Tools OTS item and fix introduction.md References sections - Add sysml2tools as an OTS item, mirroring the other pipeline tools: create docs/reqstream/ots/sysml2tools.yaml, docs/design/ots/sysml2tools.md, docs/verification/ots/sysml2tools.md; wire into requirements.yaml, docs/design/definition.yaml, docs/verification/definition.yaml, docs/design/ots.md, docs/verification/ots.md, docs/design/introduction.md, and add an OTS-SysML2Tools review-set to .reviewmark.yaml - Fix References sections in docs/design/introduction.md and docs/verification/introduction.md to use document-name-only bullets instead of direct URL links to internal docs/ source files, per the technical-documentation.md standard, as flagged by formal review - Remove an unrequested/untraceable NuGet package metadata interface claim from the system design flagged by formal review Verified via dotnet reqstream/reviewmark/sysml2tools --lint, markdownlint-cli2, cspell, yamllint, dotnet format, and formal-review agents (gpt-5.4-mini) across all affected review-sets, including the new OTS-SysML2Tools set. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .reviewmark.yaml | 8 +++++ docs/design/definition.yaml | 1 + docs/design/introduction.md | 6 ++-- docs/design/ots.md | 1 + docs/design/ots/sysml2tools.md | 28 +++++++++++++++ docs/reqstream/ots/sysml2tools.yaml | 27 +++++++++++++++ docs/verification/definition.yaml | 1 + docs/verification/introduction.md | 5 +-- docs/verification/ots.md | 1 + docs/verification/ots/sysml2tools.md | 52 ++++++++++++++++++++++++++++ requirements.yaml | 1 + 11 files changed, 127 insertions(+), 4 deletions(-) create mode 100644 docs/design/ots/sysml2tools.md create mode 100644 docs/reqstream/ots/sysml2tools.yaml create mode 100644 docs/verification/ots/sysml2tools.md diff --git a/.reviewmark.yaml b/.reviewmark.yaml index a8b3de0..b16671c 100644 --- a/.reviewmark.yaml +++ b/.reviewmark.yaml @@ -170,6 +170,14 @@ reviews: - "docs/design/ots/sonarmark.md" # OTS integration design - "docs/verification/ots/sonarmark.md" # OTS verification + # OTS-SysML2Tools Review (one per OTS item) + - id: OTS-SysML2Tools + title: Review that SysML2Tools Provides Required Functionality + paths: + - "docs/reqstream/ots/sysml2tools.yaml" # OTS requirements + - "docs/design/ots/sysml2tools.md" # OTS integration design + - "docs/verification/ots/sysml2tools.md" # OTS verification + # OTS-VersionMark Review (one per OTS item) - id: OTS-VersionMark title: Review that VersionMark Provides Required Functionality diff --git a/docs/design/definition.yaml b/docs/design/definition.yaml index a98a693..f2dbaa0 100644 --- a/docs/design/definition.yaml +++ b/docs/design/definition.yaml @@ -15,6 +15,7 @@ input-files: - docs/design/ots/reviewmark.md - docs/design/ots/sarifmark.md - docs/design/ots/sonarmark.md + - docs/design/ots/sysml2tools.md - docs/design/ots/versionmark.md - docs/design/ots/weasyprint.md - docs/design/ots/xunit.md diff --git a/docs/design/introduction.md b/docs/design/introduction.md index 1f5d758..3286a1c 100644 --- a/docs/design/introduction.md +++ b/docs/design/introduction.md @@ -36,6 +36,7 @@ The following OTS items are also covered: - **ReviewMark** — file review enforcement tool - **SarifMark** — SARIF report conversion tool - **SonarMark** — SonarCloud quality report tool +- **SysML2Tools** — architecture model lint and diagram rendering tool - **VersionMark** — tool-version documentation tool - **WeasyPrint** — HTML-to-PDF conversion tool - **xUnit** — unit-testing framework @@ -102,5 +103,6 @@ Each software item has corresponding artifacts in parallel directory trees: ## References -- [REF-1] Template DotNet Library User Guide () -- [REF-2] Template DotNet Library Repository () +- Template DotNet Library User Guide — the compiled User Guide document for this repository. +- Template DotNet Library Repository — the TemplateDotNetLibrary source repository hosted on + GitHub. diff --git a/docs/design/ots.md b/docs/design/ots.md index adf128f..f86238e 100644 --- a/docs/design/ots.md +++ b/docs/design/ots.md @@ -23,6 +23,7 @@ these tools are linked into, or shipped with, the compiled NuGet package. | ReviewMark | Enforces file review coverage and currency | | SarifMark | Converts CodeQL SARIF results into a markdown report | | SonarMark | Generates a SonarCloud quality report | +| SysML2Tools | Validates the SysML2 architecture model and renders its views to SVG | | VersionMark | Captures and publishes tool-version information | | WeasyPrint | Converts HTML documentation to PDF | | xUnit | Discovers and executes unit and integration tests | diff --git a/docs/design/ots/sysml2tools.md b/docs/design/ots/sysml2tools.md new file mode 100644 index 0000000..9a7b018 --- /dev/null +++ b/docs/design/ots/sysml2tools.md @@ -0,0 +1,28 @@ +## SysML2Tools + +### Purpose + +DemaConsulting.SysML2Tools is used to lint and render the repository's SysML2 architecture +model. It was chosen because it is the reference implementation for the SysML v2 subset used by +this project's Continuous Compliance methodology, and it integrates directly with the same +dotnet-tool restore and CI pipeline used by the other pipeline tools. + +### Features Used + +- Model validation via `dotnet sysml2tools lint 'docs/sysml2/**/*.sysml'`, which reports syntax + errors and unresolved references without producing output files +- View rendering via `dotnet sysml2tools render`, which renders every `view` declared in + `docs/sysml2/views/design-views.sysml` to an SVG file named after the view (for example + `SoftwareStructureView.svg`) +- Self-validation mode (`--validate`), which exercises `lint` and `render` against known fixtures + +### Integration Pattern + +SysML2Tools is invoked as a `dotnet tool` from two places: `lint.ps1` runs +`dotnet sysml2tools lint 'docs/sysml2/**/*.sysml'` as an early-detection lint gate, and +`.github/workflows/build.yaml` runs +`dotnet sysml2tools render --output docs/design/generated --format svg 'docs/sysml2/model/**/*.sysml' 'docs/sysml2/views/design-views.sysml'` +immediately before Pandoc compiles the Design document. It is a stateless CLI invocation — each +run reads the SysML2 source files and writes its output, and exits; there is no initialization, +configuration object, or disposal step beyond the command-line arguments supplied on each +invocation. diff --git a/docs/reqstream/ots/sysml2tools.yaml b/docs/reqstream/ots/sysml2tools.yaml new file mode 100644 index 0000000..e84ee35 --- /dev/null +++ b/docs/reqstream/ots/sysml2tools.yaml @@ -0,0 +1,27 @@ +--- +# SysML2Tools OTS Software Requirements +# +# Requirements for the SysML2Tools architecture modeling tool functionality. + +sections: + - title: OTS Software Requirements + sections: + - title: SysML2Tools Requirements + requirements: + - id: Template-OTS-SysML2Tools-Lint + title: SysML2Tools shall validate the SysML2 model for syntax and reference errors. + justification: | + Linting the model in CI catches broken references and syntax errors in the + architecture model before they reach the generated documentation. + tags: [ots] + tests: + - SysML2Tools_LintSelfTest + + - id: Template-OTS-SysML2Tools-Render + title: SysML2Tools shall render the declared views to SVG diagrams. + justification: | + The rendered diagrams are embedded in the design documentation, so a failure to + render must fail the build rather than silently omit a diagram. + tags: [ots] + tests: + - SysML2Tools_RenderSvgSelfTest diff --git a/docs/verification/definition.yaml b/docs/verification/definition.yaml index 37f6b43..20518eb 100644 --- a/docs/verification/definition.yaml +++ b/docs/verification/definition.yaml @@ -15,6 +15,7 @@ input-files: - docs/verification/ots/reviewmark.md - docs/verification/ots/sarifmark.md - docs/verification/ots/sonarmark.md + - docs/verification/ots/sysml2tools.md - docs/verification/ots/versionmark.md - docs/verification/ots/weasyprint.md - docs/verification/ots/xunit.md diff --git a/docs/verification/introduction.md b/docs/verification/introduction.md index 311e63e..97e2fd1 100644 --- a/docs/verification/introduction.md +++ b/docs/verification/introduction.md @@ -69,5 +69,6 @@ Review-sets: defined in `.reviewmark.yaml` ## References -- [REF-1] Template DotNet Library User Guide () -- [REF-2] Template DotNet Library Repository () +- Template DotNet Library User Guide — the compiled User Guide document for this repository. +- Template DotNet Library Repository — the TemplateDotNetLibrary source repository hosted on + GitHub. diff --git a/docs/verification/ots.md b/docs/verification/ots.md index 22a46aa..7612abd 100644 --- a/docs/verification/ots.md +++ b/docs/verification/ots.md @@ -23,6 +23,7 @@ detailed approach and named test scenarios. | ReviewMark | Self-validation CLI suite plus pipeline evidence via review plan/report | | SarifMark | Self-validation CLI suite plus pipeline evidence via SARIF markdown report | | SonarMark | Self-validation CLI suite plus pipeline evidence via SonarCloud report | +| SysML2Tools | Self-validation CLI suite plus pipeline evidence via lint and rendered SVGs | | VersionMark | Self-validation CLI suite plus pipeline evidence via version data | | WeasyPrint | Pipeline evidence: FileAssert assertions on each generated PDF document | | xUnit | Self-validation via discovery, execution, and TRX reporting of tests | diff --git a/docs/verification/ots/sysml2tools.md b/docs/verification/ots/sysml2tools.md new file mode 100644 index 0000000..02e9beb --- /dev/null +++ b/docs/verification/ots/sysml2tools.md @@ -0,0 +1,52 @@ +# SysML2Tools Verification + +This document provides the verification evidence for the `SysML2Tools` OTS software item. + +## Required Functionality + +DemaConsulting.SysML2Tools validates the SysML2 architecture model under `docs/sysml2/` for +syntax and reference errors, and renders each view declared in +`docs/sysml2/views/design-views.sysml` to an SVG diagram embedded in the design documentation. +Both behaviors run in the same CI pipeline that produces the compiled Design document, so a +successful pipeline run is evidence that SysML2Tools executed without error. + +## Verification Approach + +SysML2Tools is verified by two complementary layers of evidence. First, the CI pipeline runs +`dotnet sysml2tools --validate --results artifacts/sysml2tools-self-validation.trx`, which +exercises the tool's built-in self-test suite against known-good and known-bad model fixtures +and writes a TRX file consumed by `reqstream --enforce`. + +Second, `lint.ps1` runs `dotnet sysml2tools lint 'docs/sysml2/**/*.sysml'` against the actual +Template DotNet Library model and fails the build on any syntax or reference error. The build-docs +job runs `dotnet sysml2tools render` to produce one SVG file per declared view under +`docs/design/generated/`. Pandoc then compiles `docs/design/*.md`, which embed those SVG files by +filename; if a declared view failed to render, the missing image reference would cause a broken +image in the compiled Design HTML and PDF. A CI build failure at either step is evidence that +SysML2Tools did not produce the required model validation or diagrams against the real model. + +## Test Scenarios + +### SysML2Tools_LintSelfTest + +**Scenario**: SysML2Tools is invoked with `--validate`, which exercises `lint` against a known-good +and a known-bad model fixture as part of its built-in self-test suite. + +**Expected**: Exits 0 with no reported syntax or reference errors for the valid fixture, and +correctly reports an error for the invalid fixture. + +**Requirement coverage**: `Template-OTS-SysML2Tools-Lint`. + +### SysML2Tools_RenderSvgSelfTest + +**Scenario**: SysML2Tools is invoked with `--validate`, which exercises `render --format svg` +against a known-good model fixture as part of its built-in self-test suite. + +**Expected**: Exits 0 and produces a non-empty SVG file for the fixture's declared view. + +**Requirement coverage**: `Template-OTS-SysML2Tools-Render`. + +## Requirements Coverage + +- **`Template-OTS-SysML2Tools-Lint`**: SysML2Tools_LintSelfTest +- **`Template-OTS-SysML2Tools-Render`**: SysML2Tools_RenderSvgSelfTest diff --git a/requirements.yaml b/requirements.yaml index d96ca98..8567932 100644 --- a/requirements.yaml +++ b/requirements.yaml @@ -10,6 +10,7 @@ includes: - docs/reqstream/ots/versionmark.yaml - docs/reqstream/ots/sarifmark.yaml - docs/reqstream/ots/sonarmark.yaml + - docs/reqstream/ots/sysml2tools.yaml - docs/reqstream/ots/reviewmark.yaml - docs/reqstream/ots/pandoc.yaml - docs/reqstream/ots/weasyprint.yaml From d9b387579e909d525d87c7cb1e2e8851b16e0888 Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Sat, 11 Jul 2026 12:33:29 -0400 Subject: [PATCH 3/4] Fix CI failure: add missing SysML2Tools self-validation step and FileAssert SVG checks - build.yaml referenced SysML2Tools_LintSelfTest/SysML2Tools_RenderSvgSelfTest requirement evidence, but never ran dotnet sysml2tools --validate to produce that TRX, causing ReqStream --enforce to fail CI with 2 unsatisfied requirements. Add the missing "Run SysML2Tools self-validation" step in the design-docs job, matching FileAssert's reference implementation placement (before the render step). - Add direct FileAssert checks (SysML2Tools_SoftwareStructureViewSvg, SysML2Tools_TemplateDotNetLibraryViewSvg) asserting each rendered view's SVG exists in docs/design/generated/ and is well-formed XML with an root element, strengthening Template-OTS-SysML2Tools-Render's evidence beyond the tool's internal self-test fixture. - Update docs/design/ots/sysml2tools.md and docs/verification/ots/sysml2tools.md to document the new FileAssert-based verification evidence. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .fileassert.yaml | 20 ++++++++++++++++ .github/workflows/build.yaml | 6 +++++ docs/design/ots/sysml2tools.md | 9 ++++---- docs/reqstream/ots/sysml2tools.yaml | 2 ++ docs/verification/ots/sysml2tools.md | 34 ++++++++++++++++++++++++---- 5 files changed, 62 insertions(+), 9 deletions(-) diff --git a/.fileassert.yaml b/.fileassert.yaml index fe76953..72dbc35 100644 --- a/.fileassert.yaml +++ b/.fileassert.yaml @@ -143,6 +143,26 @@ tests: # --- DESIGN DOCUMENT --- + - name: SysML2Tools_SoftwareStructureViewSvg + description: "Software Structure View diagram was rendered by SysML2Tools" + tags: [design] + files: + - pattern: "docs/design/generated/SoftwareStructureView.svg" + count: 1 + xml: + - query: "//*[local-name()='svg']" + count: 1 + + - name: SysML2Tools_TemplateDotNetLibraryViewSvg + description: "Template DotNet Library View diagram was rendered by SysML2Tools" + tags: [design] + files: + - pattern: "docs/design/generated/TemplateDotNetLibraryView.svg" + count: 1 + xml: + - query: "//*[local-name()='svg']" + count: 1 + - name: Pandoc_DesignHtml description: "Design HTML was generated by Pandoc" tags: [design] diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index 5140bf1..e1d6a3b 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -615,6 +615,12 @@ jobs: shell: bash run: mkdir -p docs/design/generated + - name: Run SysML2Tools self-validation + run: > + dotnet sysml2tools + --validate + --results artifacts/sysml2tools-self-validation.trx + - name: Render Software Structure diagrams with SysML2Tools shell: pwsh run: > diff --git a/docs/design/ots/sysml2tools.md b/docs/design/ots/sysml2tools.md index 9a7b018..50e7bde 100644 --- a/docs/design/ots/sysml2tools.md +++ b/docs/design/ots/sysml2tools.md @@ -22,7 +22,8 @@ SysML2Tools is invoked as a `dotnet tool` from two places: `lint.ps1` runs `dotnet sysml2tools lint 'docs/sysml2/**/*.sysml'` as an early-detection lint gate, and `.github/workflows/build.yaml` runs `dotnet sysml2tools render --output docs/design/generated --format svg 'docs/sysml2/model/**/*.sysml' 'docs/sysml2/views/design-views.sysml'` -immediately before Pandoc compiles the Design document. It is a stateless CLI invocation — each -run reads the SysML2 source files and writes its output, and exits; there is no initialization, -configuration object, or disposal step beyond the command-line arguments supplied on each -invocation. +immediately before Pandoc compiles the Design document. FileAssert then asserts that each declared +view's rendered SVG file exists in `docs/design/generated/` and is well-formed XML, before Pandoc +embeds it in the compiled document. It is a stateless CLI invocation — each run reads the SysML2 +source files and writes its output, and exits; there is no initialization, configuration object, +or disposal step beyond the command-line arguments supplied on each invocation. diff --git a/docs/reqstream/ots/sysml2tools.yaml b/docs/reqstream/ots/sysml2tools.yaml index e84ee35..6081695 100644 --- a/docs/reqstream/ots/sysml2tools.yaml +++ b/docs/reqstream/ots/sysml2tools.yaml @@ -25,3 +25,5 @@ sections: tags: [ots] tests: - SysML2Tools_RenderSvgSelfTest + - SysML2Tools_SoftwareStructureViewSvg + - SysML2Tools_TemplateDotNetLibraryViewSvg diff --git a/docs/verification/ots/sysml2tools.md b/docs/verification/ots/sysml2tools.md index 02e9beb..c2a8e2e 100644 --- a/docs/verification/ots/sysml2tools.md +++ b/docs/verification/ots/sysml2tools.md @@ -20,10 +20,11 @@ and writes a TRX file consumed by `reqstream --enforce`. Second, `lint.ps1` runs `dotnet sysml2tools lint 'docs/sysml2/**/*.sysml'` against the actual Template DotNet Library model and fails the build on any syntax or reference error. The build-docs job runs `dotnet sysml2tools render` to produce one SVG file per declared view under -`docs/design/generated/`. Pandoc then compiles `docs/design/*.md`, which embed those SVG files by -filename; if a declared view failed to render, the missing image reference would cause a broken -image in the compiled Design HTML and PDF. A CI build failure at either step is evidence that -SysML2Tools did not produce the required model validation or diagrams against the real model. +`docs/design/generated/`. FileAssert then directly asserts that each declared view's SVG file +exists and is well-formed XML with an `` root element (`SysML2Tools_SoftwareStructureViewSvg`, +`SysML2Tools_TemplateDotNetLibraryViewSvg`), before Pandoc compiles `docs/design/*.md`, which embed +those SVG files by filename. A CI build failure at any of these steps is evidence that SysML2Tools +did not produce the required model validation or diagrams against the real model. ## Test Scenarios @@ -46,7 +47,30 @@ against a known-good model fixture as part of its built-in self-test suite. **Requirement coverage**: `Template-OTS-SysML2Tools-Render`. +### SysML2Tools_SoftwareStructureViewSvg + +**Scenario**: The build-docs CI job runs `dotnet sysml2tools render` against the real Template +DotNet Library model, then FileAssert checks the resulting file at +`docs/design/generated/SoftwareStructureView.svg`. + +**Expected**: Exactly one file exists at that path, and it is well-formed XML with a root element +named `svg`. + +**Requirement coverage**: `Template-OTS-SysML2Tools-Render`. + +### SysML2Tools_TemplateDotNetLibraryViewSvg + +**Scenario**: The build-docs CI job runs `dotnet sysml2tools render` against the real Template +DotNet Library model, then FileAssert checks the resulting file at +`docs/design/generated/TemplateDotNetLibraryView.svg`. + +**Expected**: Exactly one file exists at that path, and it is well-formed XML with a root element +named `svg`. + +**Requirement coverage**: `Template-OTS-SysML2Tools-Render`. + ## Requirements Coverage - **`Template-OTS-SysML2Tools-Lint`**: SysML2Tools_LintSelfTest -- **`Template-OTS-SysML2Tools-Render`**: SysML2Tools_RenderSvgSelfTest +- **`Template-OTS-SysML2Tools-Render`**: SysML2Tools_RenderSvgSelfTest, + SysML2Tools_SoftwareStructureViewSvg, SysML2Tools_TemplateDotNetLibraryViewSvg From ed4ace47cc909ed97b9de0a5bc36affd8843e2de Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Sat, 11 Jul 2026 12:51:31 -0400 Subject: [PATCH 4/4] Fix heading depth in docs/verification/ots/*.md files All 11 OTS verification documents started at heading depth 1 (# {Item} Verification) instead of depth 2, inconsistent with docs/design/ots/*.md (which correctly start at depth 2) and with the sibling FileAssert repository's reference implementation. Shift each file's headings down one level: top heading is now ##, with Required Functionality/Verification Approach/Test Scenarios/Requirements Coverage at ### and individual test scenario names at ####. Verified via markdownlint-cli2, cspell, dotnet reviewmark --lint, and formal-review agents (gpt-5.4-mini) on TemplateDotNetLibrary-Verification and OTS-SysML2Tools. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/verification/ots/buildmark.md | 20 ++++++++++---------- docs/verification/ots/fileassert.md | 16 ++++++++-------- docs/verification/ots/pandoc.md | 24 ++++++++++++------------ docs/verification/ots/reqstream.md | 22 +++++++++++----------- docs/verification/ots/reviewmark.md | 24 ++++++++++++------------ docs/verification/ots/sarifmark.md | 16 ++++++++-------- docs/verification/ots/sonarmark.md | 18 +++++++++--------- docs/verification/ots/sysml2tools.md | 18 +++++++++--------- docs/verification/ots/versionmark.md | 18 +++++++++--------- docs/verification/ots/weasyprint.md | 24 ++++++++++++------------ docs/verification/ots/xunit.md | 28 ++++++++++++++-------------- 11 files changed, 114 insertions(+), 114 deletions(-) diff --git a/docs/verification/ots/buildmark.md b/docs/verification/ots/buildmark.md index da5e4bf..f94ea12 100644 --- a/docs/verification/ots/buildmark.md +++ b/docs/verification/ots/buildmark.md @@ -1,15 +1,15 @@ -# BuildMark Verification +## BuildMark Verification This document provides the verification evidence for the `BuildMark` OTS software item. -## Required Functionality +### Required Functionality DemaConsulting.BuildMark queries the GitHub API to capture workflow run details and renders them as a markdown build-notes document included in the release artifacts. It runs as part of the same CI pipeline that produces the TRX test results, so a successful pipeline run is evidence that BuildMark executed without error. -## Verification Approach +### Verification Approach BuildMark is verified by two complementary layers of evidence. First, the CI pipeline runs `buildmark --validate --results artifacts/buildmark-self-validation.trx`, which exercises @@ -22,9 +22,9 @@ artifact, and FileAssert asserts the PDF exists, has content, and contains expec (`WeasyPrint_BuildNotesPdf`). A CI build failure at any step in this chain is evidence that BuildMark did not produce the required output. -## Test Scenarios +### Test Scenarios -### BuildMark_MarkdownReportGeneration +#### BuildMark_MarkdownReportGeneration **Scenario**: A CI pipeline run triggers BuildMark with live GitHub Actions metadata. @@ -33,7 +33,7 @@ in the release artifacts. **Requirement coverage**: `Template-OTS-BuildMark`. -### BuildMark_GitIntegration +#### BuildMark_GitIntegration **Scenario**: BuildMark self-validation reads version tags and commits from a mock Git history. @@ -41,7 +41,7 @@ in the release artifacts. **Requirement coverage**: `Template-OTS-BuildMark`. -### BuildMark_IssueTracking +#### BuildMark_IssueTracking **Scenario**: BuildMark self-validation processes mock GitHub issues and pull requests. @@ -49,7 +49,7 @@ in the release artifacts. **Requirement coverage**: `Template-OTS-BuildMark`. -### BuildMark_KnownIssuesReporting +#### BuildMark_KnownIssuesReporting **Scenario**: BuildMark self-validation includes open bugs in the generated report when requested. @@ -57,7 +57,7 @@ in the release artifacts. **Requirement coverage**: `Template-OTS-BuildMark`. -### BuildMark_RulesRouting +#### BuildMark_RulesRouting **Scenario**: BuildMark self-validation assigns mock items to report sections based on label and type rules. @@ -66,7 +66,7 @@ type rules. **Requirement coverage**: `Template-OTS-BuildMark`. -## Requirements Coverage +### Requirements Coverage - **`Template-OTS-BuildMark`**: BuildMark_MarkdownReportGeneration, BuildMark_GitIntegration, BuildMark_IssueTracking, BuildMark_KnownIssuesReporting, BuildMark_RulesRouting diff --git a/docs/verification/ots/fileassert.md b/docs/verification/ots/fileassert.md index 4eda8ff..0b7eab8 100644 --- a/docs/verification/ots/fileassert.md +++ b/docs/verification/ots/fileassert.md @@ -1,16 +1,16 @@ -# FileAssert Verification +## FileAssert Verification This document provides the verification evidence for the FileAssert OTS software item. Requirements for this OTS item are defined in the FileAssert OTS Software Requirements document. -## Required Functionality +### Required Functionality DemaConsulting.FileAssert validates HTML and PDF documents produced during the build, asserting that each document exists 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. -## Verification Approach +### Verification Approach FileAssert is verified by two complementary layers of evidence. First, the CI pipeline runs `fileassert --validate --results artifacts/fileassert-self-validation.trx` after all documents @@ -24,9 +24,9 @@ incorrect results, causing `reqstream --enforce` to report missing test coverage build. A passing CI build therefore constitutes transitive evidence that FileAssert correctly asserted document content at each stage of the pipeline. -## Test Scenarios +### Test Scenarios -### FileAssert_Results +#### FileAssert_Results **Scenario**: FileAssert self-validation exercises the `--results` option, generating TRX test results containing both passing and failing outcomes. @@ -35,7 +35,7 @@ results containing both passing and failing outcomes. **Requirement coverage**: `Template-OTS-FileAssert`. -### FileAssert_Exists +#### FileAssert_Exists **Scenario**: FileAssert self-validation exercises a test configuration using a glob pattern to assert file existence. @@ -44,7 +44,7 @@ assert file existence. **Requirement coverage**: `Template-OTS-FileAssert`. -### FileAssert_Contains +#### FileAssert_Contains **Scenario**: FileAssert self-validation exercises a test configuration using a `contains` assertion to verify file content. @@ -53,6 +53,6 @@ to verify file content. **Requirement coverage**: `Template-OTS-FileAssert`. -## Requirements Coverage +### Requirements Coverage - **`Template-OTS-FileAssert`**: FileAssert_Results, FileAssert_Exists, FileAssert_Contains diff --git a/docs/verification/ots/pandoc.md b/docs/verification/ots/pandoc.md index ca29411..4f9f8fd 100644 --- a/docs/verification/ots/pandoc.md +++ b/docs/verification/ots/pandoc.md @@ -1,23 +1,23 @@ -# Pandoc Verification +## Pandoc Verification This document provides the verification evidence for the `Pandoc` OTS software item. -## Required Functionality +### Required Functionality DemaConsulting.PandocTool converts Markdown source documents to HTML as part of the documentation build pipeline. FileAssert validates that each generated HTML file exists, contains a valid HTML title element, and includes expected document content. Passing FileAssert assertions for each document type proves Pandoc executed correctly and produced meaningful output. -## Verification Approach +### Verification Approach Pandoc is verified by self-validation evidence from the CI pipeline. Each scenario is a FileAssert assertion that runs after Pandoc converts a specific Markdown document to HTML. A passing pipeline run for all scenarios constitutes evidence that the requirement is satisfied. -## Test Scenarios +### Test Scenarios -### Pandoc_BuildNotesHtml +#### Pandoc_BuildNotesHtml **Scenario**: FileAssert asserts the build-notes HTML file exists, contains a valid HTML title element, and includes expected document content. @@ -26,7 +26,7 @@ element, and includes expected document content. **Requirement coverage**: `Template-OTS-Pandoc`. -### Pandoc_CodeQualityHtml +#### Pandoc_CodeQualityHtml **Scenario**: FileAssert asserts the code-quality HTML file exists, contains a valid HTML title element, and includes expected document content. @@ -35,7 +35,7 @@ element, and includes expected document content. **Requirement coverage**: `Template-OTS-Pandoc`. -### Pandoc_ReviewPlanHtml +#### Pandoc_ReviewPlanHtml **Scenario**: FileAssert asserts the review plan HTML file exists, contains a valid HTML title element, and includes expected document content. @@ -44,7 +44,7 @@ element, and includes expected document content. **Requirement coverage**: `Template-OTS-Pandoc`. -### Pandoc_ReviewReportHtml +#### Pandoc_ReviewReportHtml **Scenario**: FileAssert asserts the review report HTML file exists, contains a valid HTML title element, and includes expected document content. @@ -53,7 +53,7 @@ element, and includes expected document content. **Requirement coverage**: `Template-OTS-Pandoc`. -### Pandoc_DesignHtml +#### Pandoc_DesignHtml **Scenario**: FileAssert asserts the design document HTML file exists, contains a valid HTML title element, and includes expected document content. @@ -62,7 +62,7 @@ element, and includes expected document content. **Requirement coverage**: `Template-OTS-Pandoc`. -### Pandoc_VerificationHtml +#### Pandoc_VerificationHtml **Scenario**: FileAssert asserts the verification HTML file exists, contains a valid HTML title element, and includes expected verification document content. @@ -71,7 +71,7 @@ element, and includes expected verification document content. **Requirement coverage**: `Template-OTS-Pandoc`. -### Pandoc_UserGuideHtml +#### Pandoc_UserGuideHtml **Scenario**: FileAssert asserts the user guide HTML file exists, contains a valid HTML title element, and includes expected document content. @@ -80,7 +80,7 @@ element, and includes expected document content. **Requirement coverage**: `Template-OTS-Pandoc`. -## Requirements Coverage +### Requirements Coverage - **`Template-OTS-Pandoc`**: Pandoc_BuildNotesHtml, Pandoc_CodeQualityHtml, Pandoc_ReviewPlanHtml, Pandoc_ReviewReportHtml, Pandoc_DesignHtml, Pandoc_VerificationHtml, Pandoc_UserGuideHtml diff --git a/docs/verification/ots/reqstream.md b/docs/verification/ots/reqstream.md index b2af701..8cb6b9a 100644 --- a/docs/verification/ots/reqstream.md +++ b/docs/verification/ots/reqstream.md @@ -1,8 +1,8 @@ -# ReqStream Verification +## ReqStream Verification This document provides the verification evidence for the `ReqStream` OTS software item. -## Required Functionality +### Required Functionality DemaConsulting.ReqStream processes requirements.yaml and the TRX test-result files to produce a requirements report, justifications document, and traceability matrix. When run with `--enforce`, it @@ -10,7 +10,7 @@ exits with a non-zero code if any requirement lacks test evidence, making unprov build-breaking condition. A successful pipeline run with `--enforce` proves all requirements are covered and that ReqStream is functioning. -## Verification Approach +### Verification Approach ReqStream is verified by two complementary layers of evidence. First, the CI pipeline runs `reqstream --validate --results artifacts/reqstream-self-validation.trx`, which exercises @@ -25,9 +25,9 @@ non-zero if any requirement lacks test evidence, which would also fail the build CI build proves ReqStream correctly processed the project's real requirements and found complete test coverage. -## Test Scenarios +### Test Scenarios -### ReqStream_RequirementsProcessing +#### ReqStream_RequirementsProcessing **Scenario**: ReqStream self-validation loads and processes a set of requirements YAML files. @@ -35,7 +35,7 @@ complete test coverage. **Requirement coverage**: `Template-OTS-ReqStream`. -### ReqStream_TraceMatrix +#### ReqStream_TraceMatrix **Scenario**: ReqStream self-validation generates a trace matrix from requirements and TRX test results. @@ -44,7 +44,7 @@ results. **Requirement coverage**: `Template-OTS-ReqStream`. -### ReqStream_ReportExport +#### ReqStream_ReportExport **Scenario**: ReqStream self-validation exports a requirements report to a markdown file. @@ -52,7 +52,7 @@ results. **Requirement coverage**: `Template-OTS-ReqStream`. -### ReqStream_TagsFiltering +#### ReqStream_TagsFiltering **Scenario**: ReqStream self-validation filters requirements by tags. @@ -60,7 +60,7 @@ results. **Requirement coverage**: `Template-OTS-ReqStream`. -### ReqStream_EnforcementMode +#### ReqStream_EnforcementMode **Scenario**: ReqStream self-validation exercises enforcement mode where all requirements have test coverage. @@ -69,7 +69,7 @@ coverage. **Requirement coverage**: `Template-OTS-ReqStream`. -### ReqStream_Lint +#### ReqStream_Lint **Scenario**: ReqStream self-validation exercises lint mode against a requirements file with deliberate issues. @@ -78,7 +78,7 @@ deliberate issues. **Requirement coverage**: `Template-OTS-ReqStream-Lint`. -## Requirements Coverage +### Requirements Coverage - **`Template-OTS-ReqStream`**: ReqStream_RequirementsProcessing, ReqStream_TraceMatrix, ReqStream_ReportExport, ReqStream_TagsFiltering, ReqStream_EnforcementMode diff --git a/docs/verification/ots/reviewmark.md b/docs/verification/ots/reviewmark.md index 7a2b9a1..9773e62 100644 --- a/docs/verification/ots/reviewmark.md +++ b/docs/verification/ots/reviewmark.md @@ -1,16 +1,16 @@ -# ReviewMark Verification +## ReviewMark Verification This document provides the verification evidence for the ReviewMark OTS software item. Requirements for this OTS item are defined in the ReviewMark OTS Software Requirements document. -## Required Functionality +### Required Functionality DemaConsulting.ReviewMark reads the `.reviewmark.yaml` configuration and the review evidence store to produce a review plan and review report documenting file review coverage and currency. It runs in the same CI pipeline that produces the TRX test results, so a successful pipeline run is evidence that ReviewMark executed without error. -## Verification Approach +### Verification Approach ReviewMark is verified by two complementary layers of evidence. First, the CI pipeline runs `reviewmark --validate --results artifacts/reviewmark-self-validation.trx`, which exercises @@ -24,9 +24,9 @@ WeasyPrint renders both to PDF and FileAssert asserts their content (`WeasyPrint_ReviewPlanPdf`, `WeasyPrint_ReviewReportPdf`). A CI build failure at any step is evidence that ReviewMark did not produce the required review documents. -## Test Scenarios +### Test Scenarios -### ReviewMark_ReviewPlanGeneration +#### ReviewMark_ReviewPlanGeneration **Scenario**: ReviewMark self-validation uses `--definition` and `--plan` to generate a review plan from a test configuration. @@ -35,7 +35,7 @@ from a test configuration. **Requirement coverage**: `Template-OTS-ReviewMark`. -### ReviewMark_ReviewReportGeneration +#### ReviewMark_ReviewReportGeneration **Scenario**: ReviewMark self-validation uses `--definition` and `--report` to generate a review report from a test configuration and evidence store. @@ -44,7 +44,7 @@ report from a test configuration and evidence store. **Requirement coverage**: `Template-OTS-ReviewMark`. -### ReviewMark_IndexScan +#### ReviewMark_IndexScan **Scenario**: ReviewMark self-validation uses `--index` to scan PDF evidence files and write an `index.json` catalogue. @@ -53,7 +53,7 @@ report from a test configuration and evidence store. **Requirement coverage**: `Template-OTS-ReviewMark-IndexScan`. -### ReviewMark_WorkingDirectoryOverride +#### ReviewMark_WorkingDirectoryOverride **Scenario**: ReviewMark self-validation uses `--dir` to override the working directory for file operations. @@ -62,7 +62,7 @@ operations. **Requirement coverage**: `Template-OTS-ReviewMark-DirectoryOverride`. -### ReviewMark_Enforce +#### ReviewMark_Enforce **Scenario**: ReviewMark self-validation uses `--enforce` against a configuration with review issues. @@ -71,7 +71,7 @@ issues. **Requirement coverage**: `Template-OTS-ReviewMark-Enforce`. -### ReviewMark_Elaborate +#### ReviewMark_Elaborate **Scenario**: ReviewMark self-validation uses `--elaborate` to print a Markdown elaboration of a named review set. @@ -80,7 +80,7 @@ named review set. **Requirement coverage**: `Template-OTS-ReviewMark-Elaborate`. -### ReviewMark_Lint +#### ReviewMark_Lint **Scenario**: ReviewMark self-validation uses `--lint` to validate a definition file and report issues. @@ -90,7 +90,7 @@ semantic error in the test definition that contains known errors. **Requirement coverage**: `Template-OTS-ReviewMark-Lint`. -## Requirements Coverage +### Requirements Coverage - **`Template-OTS-ReviewMark`**: ReviewMark_ReviewPlanGeneration, ReviewMark_ReviewReportGeneration - **`Template-OTS-ReviewMark-IndexScan`**: ReviewMark_IndexScan diff --git a/docs/verification/ots/sarifmark.md b/docs/verification/ots/sarifmark.md index 10d3fcc..a3e7197 100644 --- a/docs/verification/ots/sarifmark.md +++ b/docs/verification/ots/sarifmark.md @@ -1,16 +1,16 @@ -# SarifMark Verification +## SarifMark Verification This document provides the verification evidence for the SarifMark OTS software item. Requirements for this OTS item are defined in the SarifMark OTS Software Requirements document. -## Required Functionality +### Required Functionality DemaConsulting.SarifMark reads the SARIF output produced by CodeQL code scanning and renders it as a human-readable markdown document included in the release artifacts. It runs in the same CI pipeline that produces the TRX test results, so a successful pipeline run is evidence that SarifMark executed without error. -## Verification Approach +### Verification Approach SarifMark is verified by two complementary layers of evidence. First, the CI pipeline runs `sarifmark --validate --results artifacts/sarifmark-self-validation.trx`, which exercises @@ -24,9 +24,9 @@ renders the result to PDF and FileAssert asserts the PDF contains expected conte (`WeasyPrint_CodeQualityPdf`). A CI build failure at any step is evidence that SarifMark did not produce the required output. -## Test Scenarios +### Test Scenarios -### SarifMark_SarifReading +#### SarifMark_SarifReading **Scenario**: SarifMark is invoked with a CodeQL SARIF results file as input. @@ -34,7 +34,7 @@ not produce the required output. **Requirement coverage**: `Template-OTS-SarifMark`. -### SarifMark_MarkdownReportGeneration +#### SarifMark_MarkdownReportGeneration **Scenario**: SarifMark renders the SARIF input as a markdown report included in the release artifacts. @@ -43,7 +43,7 @@ artifacts. **Requirement coverage**: `Template-OTS-SarifMark`. -### SarifMark_Enforcement +#### SarifMark_Enforcement **Scenario**: SarifMark self-validation processes a SARIF file containing known issues in enforcement mode. @@ -52,7 +52,7 @@ enforcement mode. **Requirement coverage**: `Template-OTS-SarifMark-Enforcement`. -## Requirements Coverage +### Requirements Coverage - **`Template-OTS-SarifMark`**: SarifMark_SarifReading, SarifMark_MarkdownReportGeneration - **`Template-OTS-SarifMark-Enforcement`**: SarifMark_Enforcement diff --git a/docs/verification/ots/sonarmark.md b/docs/verification/ots/sonarmark.md index 57155a6..fbcfd32 100644 --- a/docs/verification/ots/sonarmark.md +++ b/docs/verification/ots/sonarmark.md @@ -1,16 +1,16 @@ -# SonarMark Verification +## SonarMark Verification This document provides the verification evidence for the SonarMark OTS software item. Requirements for this OTS item are defined in the SonarMark OTS Software Requirements document. -## Required Functionality +### Required Functionality DemaConsulting.SonarMark retrieves quality-gate and metrics data from SonarCloud and renders it as a markdown document included in the release artifacts. It runs in the same CI pipeline that produces the TRX test results, so a successful pipeline run is evidence that SonarMark executed without error. -## Verification Approach +### Verification Approach SonarMark is verified by two complementary layers of evidence. First, the CI pipeline runs `sonarmark --validate --results artifacts/sonarmark-self-validation.trx`, which exercises @@ -24,9 +24,9 @@ renders the result to PDF and FileAssert asserts the PDF contains expected conte (`WeasyPrint_CodeQualityPdf`). A CI build failure at any step is evidence that SonarMark did not retrieve and render quality data correctly. -## Test Scenarios +### Test Scenarios -### SonarMark_QualityGateRetrieval +#### SonarMark_QualityGateRetrieval **Scenario**: SonarMark queries the SonarCloud API for quality-gate status. @@ -34,7 +34,7 @@ not retrieve and render quality data correctly. **Requirement coverage**: `Template-OTS-SonarMark`. -### SonarMark_IssuesRetrieval +#### SonarMark_IssuesRetrieval **Scenario**: SonarMark queries the SonarCloud API for issues. @@ -42,7 +42,7 @@ not retrieve and render quality data correctly. **Requirement coverage**: `Template-OTS-SonarMark`. -### SonarMark_HotSpotsRetrieval +#### SonarMark_HotSpotsRetrieval **Scenario**: SonarMark queries the SonarCloud API for hot spots. @@ -50,7 +50,7 @@ not retrieve and render quality data correctly. **Requirement coverage**: `Template-OTS-SonarMark`. -### SonarMark_MarkdownReportGeneration +#### SonarMark_MarkdownReportGeneration **Scenario**: SonarMark renders quality-gate, issues, and hot-spots data as a markdown report. @@ -58,7 +58,7 @@ not retrieve and render quality data correctly. **Requirement coverage**: `Template-OTS-SonarMark`. -## Requirements Coverage +### Requirements Coverage - **`Template-OTS-SonarMark`**: SonarMark_QualityGateRetrieval, SonarMark_IssuesRetrieval, SonarMark_HotSpotsRetrieval, SonarMark_MarkdownReportGeneration diff --git a/docs/verification/ots/sysml2tools.md b/docs/verification/ots/sysml2tools.md index c2a8e2e..a68d2db 100644 --- a/docs/verification/ots/sysml2tools.md +++ b/docs/verification/ots/sysml2tools.md @@ -1,8 +1,8 @@ -# SysML2Tools Verification +## SysML2Tools Verification This document provides the verification evidence for the `SysML2Tools` OTS software item. -## Required Functionality +### Required Functionality DemaConsulting.SysML2Tools validates the SysML2 architecture model under `docs/sysml2/` for syntax and reference errors, and renders each view declared in @@ -10,7 +10,7 @@ syntax and reference errors, and renders each view declared in Both behaviors run in the same CI pipeline that produces the compiled Design document, so a successful pipeline run is evidence that SysML2Tools executed without error. -## Verification Approach +### Verification Approach SysML2Tools is verified by two complementary layers of evidence. First, the CI pipeline runs `dotnet sysml2tools --validate --results artifacts/sysml2tools-self-validation.trx`, which @@ -26,9 +26,9 @@ exists and is well-formed XML with an `` root element (`SysML2Tools_Softwar those SVG files by filename. A CI build failure at any of these steps is evidence that SysML2Tools did not produce the required model validation or diagrams against the real model. -## Test Scenarios +### Test Scenarios -### SysML2Tools_LintSelfTest +#### SysML2Tools_LintSelfTest **Scenario**: SysML2Tools is invoked with `--validate`, which exercises `lint` against a known-good and a known-bad model fixture as part of its built-in self-test suite. @@ -38,7 +38,7 @@ correctly reports an error for the invalid fixture. **Requirement coverage**: `Template-OTS-SysML2Tools-Lint`. -### SysML2Tools_RenderSvgSelfTest +#### SysML2Tools_RenderSvgSelfTest **Scenario**: SysML2Tools is invoked with `--validate`, which exercises `render --format svg` against a known-good model fixture as part of its built-in self-test suite. @@ -47,7 +47,7 @@ against a known-good model fixture as part of its built-in self-test suite. **Requirement coverage**: `Template-OTS-SysML2Tools-Render`. -### SysML2Tools_SoftwareStructureViewSvg +#### SysML2Tools_SoftwareStructureViewSvg **Scenario**: The build-docs CI job runs `dotnet sysml2tools render` against the real Template DotNet Library model, then FileAssert checks the resulting file at @@ -58,7 +58,7 @@ named `svg`. **Requirement coverage**: `Template-OTS-SysML2Tools-Render`. -### SysML2Tools_TemplateDotNetLibraryViewSvg +#### SysML2Tools_TemplateDotNetLibraryViewSvg **Scenario**: The build-docs CI job runs `dotnet sysml2tools render` against the real Template DotNet Library model, then FileAssert checks the resulting file at @@ -69,7 +69,7 @@ named `svg`. **Requirement coverage**: `Template-OTS-SysML2Tools-Render`. -## Requirements Coverage +### Requirements Coverage - **`Template-OTS-SysML2Tools-Lint`**: SysML2Tools_LintSelfTest - **`Template-OTS-SysML2Tools-Render`**: SysML2Tools_RenderSvgSelfTest, diff --git a/docs/verification/ots/versionmark.md b/docs/verification/ots/versionmark.md index ad10f9d..1140e7e 100644 --- a/docs/verification/ots/versionmark.md +++ b/docs/verification/ots/versionmark.md @@ -1,15 +1,15 @@ -# VersionMark Verification +## VersionMark Verification This document provides the verification evidence for the `VersionMark` OTS software item. -## Required Functionality +### Required Functionality DemaConsulting.VersionMark reads version metadata for each dotnet tool used in the pipeline and writes a versions markdown document included in the release artifacts. It runs in the same CI pipeline that produces the TRX test results, so a successful pipeline run is evidence that VersionMark executed without error. -## Verification Approach +### Verification Approach VersionMark is verified by two complementary layers of evidence. First, the CI pipeline runs `versionmark --validate --results *.trx` in each build job, exercising VersionMark's built-in @@ -22,9 +22,9 @@ compiled by Pandoc. If VersionMark failed to produce the versions document, the compilation would be incomplete and the subsequent Pandoc step would fail. A CI build failure at any step is evidence that VersionMark did not execute correctly. -## Test Scenarios +### Test Scenarios -### VersionMark_CapturesVersions +#### VersionMark_CapturesVersions **Scenario**: VersionMark reads version metadata for each dotnet tool defined in the pipeline. @@ -32,7 +32,7 @@ at any step is evidence that VersionMark did not execute correctly. **Requirement coverage**: `Template-OTS-VersionMark`. -### VersionMark_GeneratesMarkdownReport +#### VersionMark_GeneratesMarkdownReport **Scenario**: VersionMark writes a versions markdown document to the release artifacts. @@ -40,7 +40,7 @@ at any step is evidence that VersionMark did not execute correctly. **Requirement coverage**: `Template-OTS-VersionMark`. -### VersionMark_LintPassesForValidConfig +#### VersionMark_LintPassesForValidConfig **Scenario**: VersionMark self-validation exercises lint mode against a valid `.versionmark.yaml` config. @@ -49,7 +49,7 @@ config. **Requirement coverage**: `Template-OTS-VersionMark-Lint`. -### VersionMark_LintReportsErrorsForInvalidConfig +#### VersionMark_LintReportsErrorsForInvalidConfig **Scenario**: VersionMark self-validation exercises lint mode against a malformed config with deliberate errors. @@ -58,7 +58,7 @@ deliberate errors. **Requirement coverage**: `Template-OTS-VersionMark-Lint`. -## Requirements Coverage +### Requirements Coverage - **`Template-OTS-VersionMark`**: VersionMark_CapturesVersions, VersionMark_GeneratesMarkdownReport - **`Template-OTS-VersionMark-Lint`**: VersionMark_LintPassesForValidConfig, diff --git a/docs/verification/ots/weasyprint.md b/docs/verification/ots/weasyprint.md index a33a892..94e985d 100644 --- a/docs/verification/ots/weasyprint.md +++ b/docs/verification/ots/weasyprint.md @@ -1,24 +1,24 @@ -# WeasyPrint Verification +## WeasyPrint Verification This document provides the verification evidence for the WeasyPrint OTS software item. Requirements for this OTS item are defined in the WeasyPrint OTS Software Requirements document. -## Required Functionality +### Required Functionality DemaConsulting.WeasyPrintTool converts HTML documents to PDF as part of the documentation build pipeline. FileAssert validates that each generated PDF file exists, contains at least one page, and includes expected document content in the rendered text. Passing FileAssert assertions for each document type proves WeasyPrint executed correctly and produced meaningful output. -## Verification Approach +### Verification Approach WeasyPrint is verified by self-validation evidence from the CI pipeline. Each scenario is a FileAssert assertion that runs after WeasyPrint converts a specific HTML document to PDF. A passing pipeline run for all scenarios constitutes evidence that the requirement is satisfied. -## Test Scenarios +### Test Scenarios -### WeasyPrint_BuildNotesPdf +#### WeasyPrint_BuildNotesPdf **Scenario**: FileAssert asserts the build-notes PDF file exists, contains at least one page, and includes expected document content. @@ -27,7 +27,7 @@ includes expected document content. **Requirement coverage**: `Template-OTS-WeasyPrint`. -### WeasyPrint_CodeQualityPdf +#### WeasyPrint_CodeQualityPdf **Scenario**: FileAssert asserts the code-quality PDF file exists, contains at least one page, and includes expected document content. @@ -36,7 +36,7 @@ includes expected document content. **Requirement coverage**: `Template-OTS-WeasyPrint`. -### WeasyPrint_ReviewPlanPdf +#### WeasyPrint_ReviewPlanPdf **Scenario**: FileAssert asserts the review plan PDF file exists, contains at least one page, and includes expected document content. @@ -45,7 +45,7 @@ includes expected document content. **Requirement coverage**: `Template-OTS-WeasyPrint`. -### WeasyPrint_ReviewReportPdf +#### WeasyPrint_ReviewReportPdf **Scenario**: FileAssert asserts the review report PDF file exists, contains at least one page, and includes expected document content. @@ -54,7 +54,7 @@ includes expected document content. **Requirement coverage**: `Template-OTS-WeasyPrint`. -### WeasyPrint_DesignPdf +#### WeasyPrint_DesignPdf **Scenario**: FileAssert asserts the design document PDF file exists, contains at least one page, and includes expected document content. @@ -63,7 +63,7 @@ and includes expected document content. **Requirement coverage**: `Template-OTS-WeasyPrint`. -### WeasyPrint_VerificationPdf +#### WeasyPrint_VerificationPdf **Scenario**: FileAssert asserts the verification PDF file exists, contains at least one page, and includes expected verification document content. @@ -72,7 +72,7 @@ includes expected verification document content. **Requirement coverage**: `Template-OTS-WeasyPrint`. -### WeasyPrint_UserGuidePdf +#### WeasyPrint_UserGuidePdf **Scenario**: FileAssert asserts the user guide PDF file exists, contains at least one page, and includes expected document content. @@ -81,7 +81,7 @@ includes expected document content. **Requirement coverage**: `Template-OTS-WeasyPrint`. -## Requirements Coverage +### Requirements Coverage - **`Template-OTS-WeasyPrint`**: WeasyPrint_BuildNotesPdf, WeasyPrint_CodeQualityPdf, WeasyPrint_ReviewPlanPdf, WeasyPrint_ReviewReportPdf, WeasyPrint_DesignPdf, diff --git a/docs/verification/ots/xunit.md b/docs/verification/ots/xunit.md index a78dcbf..53d110d 100644 --- a/docs/verification/ots/xunit.md +++ b/docs/verification/ots/xunit.md @@ -1,24 +1,24 @@ -# xUnit Verification +## xUnit Verification This document provides the verification evidence for the xUnit OTS software item. Requirements for this OTS item are defined in the xUnit OTS Software Requirements document. -## Required Functionality +### Required Functionality xUnit v3 (xunit.v3 and xunit.runner.visualstudio) is the unit-testing framework used by the project. It discovers and runs all test methods and writes TRX result files that feed into coverage reporting and requirements traceability. Passing tests confirm the framework is functioning correctly. -## Verification Approach +### Verification Approach xUnit is verified by self-validation evidence from the CI pipeline. Each scenario names a specific test method that xUnit must discover, execute, and record in a TRX result file. A passing pipeline run for all scenarios constitutes evidence that both requirements are satisfied. -## Test Scenarios +### Test Scenarios -### Demo_DemoMethod_DefaultPrefix_ReturnsGreeting +#### Demo_DemoMethod_DefaultPrefix_ReturnsGreeting **Scenario**: xUnit discovers and runs this test; the test verifies that DemoMethod returns the expected greeting using the default prefix. @@ -27,7 +27,7 @@ expected greeting using the default prefix. **Requirement coverage**: `Template-OTS-xUnit-Execute`, `Template-OTS-xUnit-Report`. -### Demo_DemoMethod_CustomPrefix_ReturnsGreeting +#### Demo_DemoMethod_CustomPrefix_ReturnsGreeting **Scenario**: xUnit discovers and runs this test; the test verifies that DemoMethod returns the expected greeting using a custom prefix. @@ -36,7 +36,7 @@ expected greeting using a custom prefix. **Requirement coverage**: `Template-OTS-xUnit-Execute`, `Template-OTS-xUnit-Report`. -### Demo_DemoMethod_NullInput_ThrowsArgumentNullException +#### Demo_DemoMethod_NullInput_ThrowsArgumentNullException **Scenario**: xUnit discovers and runs this test; the test verifies that DemoMethod rejects a null argument with ArgumentNullException. @@ -45,7 +45,7 @@ argument with ArgumentNullException. **Requirement coverage**: `Template-OTS-xUnit-Execute`, `Template-OTS-xUnit-Report`. -### Demo_DemoMethod_EmptyInput_ThrowsArgumentException +#### Demo_DemoMethod_EmptyInput_ThrowsArgumentException **Scenario**: xUnit discovers and runs this test; the test verifies that DemoMethod rejects an empty string argument with ArgumentException. @@ -54,7 +54,7 @@ empty string argument with ArgumentException. **Requirement coverage**: `Template-OTS-xUnit-Execute`, `Template-OTS-xUnit-Report`. -### Demo_Constructor_NullPrefix_ThrowsArgumentNullException +#### Demo_Constructor_NullPrefix_ThrowsArgumentNullException **Scenario**: xUnit discovers and runs this test; the test verifies that the constructor rejects a null prefix with ArgumentNullException. @@ -63,7 +63,7 @@ null prefix with ArgumentNullException. **Requirement coverage**: `Template-OTS-xUnit-Execute`, `Template-OTS-xUnit-Report`. -### Demo_Constructor_EmptyPrefix_ThrowsArgumentException +#### Demo_Constructor_EmptyPrefix_ThrowsArgumentException **Scenario**: xUnit discovers and runs this test; the test verifies that the constructor rejects an empty string prefix with ArgumentException. @@ -72,7 +72,7 @@ empty string prefix with ArgumentException. **Requirement coverage**: `Template-OTS-xUnit-Execute`, `Template-OTS-xUnit-Report`. -### Demo_DefaultPrefix_Read_IsHello +#### Demo_DefaultPrefix_Read_IsHello **Scenario**: xUnit discovers and runs this test; the test verifies that the DefaultPrefix constant has the value "Hello". @@ -81,7 +81,7 @@ has the value "Hello". **Requirement coverage**: `Template-OTS-xUnit-Execute`, `Template-OTS-xUnit-Report`. -### Demo_Prefix_WithCustomConstruction_ReturnsCustomPrefix +#### Demo_Prefix_WithCustomConstruction_ReturnsCustomPrefix **Scenario**: xUnit discovers and runs this test; the test verifies that the Prefix property returns the value supplied at construction. @@ -90,7 +90,7 @@ returns the value supplied at construction. **Requirement coverage**: `Template-OTS-xUnit-Execute`, `Template-OTS-xUnit-Report`. -### Demo_DefaultConstructor_WithNoArgs_SetsDefaultPrefix +#### Demo_DefaultConstructor_WithNoArgs_SetsDefaultPrefix **Scenario**: xUnit discovers and runs this test; the test verifies that the default constructor sets Prefix to the DefaultPrefix constant. @@ -99,7 +99,7 @@ sets Prefix to the DefaultPrefix constant. **Requirement coverage**: `Template-OTS-xUnit-Execute`, `Template-OTS-xUnit-Report`. -## Requirements Coverage +### Requirements Coverage - **`Template-OTS-xUnit-Execute`**: Demo_DemoMethod_DefaultPrefix_ReturnsGreeting, Demo_DemoMethod_CustomPrefix_ReturnsGreeting,