diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json index 51145f0..e0e656a 100644 --- a/.config/dotnet-tools.json +++ b/.config/dotnet-tools.json @@ -20,18 +20,18 @@ "weasyprint" ] }, - "demaconsulting.sonarmark": { - "version": "1.4.0", - "commands": [ - "sonarmark" - ] - }, "demaconsulting.sarifmark": { "version": "1.3.2", "commands": [ "sarifmark" ] }, + "demaconsulting.sonarmark": { + "version": "1.4.0", + "commands": [ + "sonarmark" + ] + }, "demaconsulting.reqstream": { "version": "1.7.0", "commands": [ @@ -55,6 +55,12 @@ "commands": [ "reviewmark" ] + }, + "demaconsulting.fileassert": { + "version": "0.3.0", + "commands": [ + "fileassert" + ] } } } \ No newline at end of file diff --git a/.cspell.yaml b/.cspell.yaml index 6cf2530..08138a9 100644 --- a/.cspell.yaml +++ b/.cspell.yaml @@ -14,59 +14,27 @@ language: en # Project-specific technical terms and tool names words: - - antipatterns - - Antipatterns - - Blockquotes - buildmark - - BuildMark - - camelcase - - CodeQL - - copilot - - cspell - - csproj - - dcterms - DEMA - - DemaConsulting - - demaconsulting - - dependabot - - Dependabot - - dotnet - - editorconfig - - filepart - - gitattributes + - Dema + - fileassert - hotspots - - markdownlint - - MSTest - - nameof - - nuget - - NuGet - - nupkg + - mstest + - pandoc - Pandoc - - pagetitle - - passwordvalidator - reqstream - - ReqStream - reviewmark - - ReviewMark - SARIF - - SarifMark - - SBOM - - slnx - - snupkg - - Qube - - sonarcloud - - SonarMark + - Sarif + - sarifmark + - sonarmark - testname - tracematrix - - Triaging - venv - versionmark - - VersionMark - - Weasyprint + - Weasy - weasyprint - - xunit - - YAML - - yamllint + - yamlfix # Exclude common build artifacts, dependencies, and vendored third-party code ignorePaths: diff --git a/.editorconfig b/.editorconfig index 9cedbec..204f58d 100644 --- a/.editorconfig +++ b/.editorconfig @@ -88,8 +88,8 @@ dotnet_naming_style.pascal_case.capitalization = pascal_case dotnet_sort_system_directives_first = true dotnet_separate_import_directive_groups = false -# Code quality -dotnet_code_quality_unused_parameters = all:warning +# Code quality - set to suggestion to not break existing code +dotnet_code_quality_unused_parameters = all:suggestion # Nullable reference types csharp_nullable_reference_types = enable diff --git a/.fileassert.yaml b/.fileassert.yaml new file mode 100644 index 0000000..503470d --- /dev/null +++ b/.fileassert.yaml @@ -0,0 +1,276 @@ +--- +# FileAssert document validation tests for ReqStream. +# Tests are tagged by document group to allow per-group execution during the build pipeline. +# Tags: build-notes, code-quality, code-review, design, user-guide, requirements. +# +# NOTE: build-notes through user-guide tests provide OTS evidence for Pandoc and WeasyPrint +# and run before ReqStream. The requirements tests run after ReqStream and validate the +# final outputs, but do not contribute to OTS requirements evidence. + +tests: + + # --- BUILD NOTES --- + + - name: Pandoc_BuildNotesHtml + description: "Build Notes HTML was generated by Pandoc" + tags: [build-notes] + files: + - pattern: "docs/build_notes/build_notes.html" + count: 1 + html: + - query: "//head/title" + count: 1 + text: + - contains: "Build Notes" + + - name: WeasyPrint_BuildNotesPdf + description: "Build Notes PDF was generated by WeasyPrint" + tags: [build-notes] + files: + - pattern: "docs/ReqStream Build Notes.pdf" + count: 1 + pdf: + metadata: + - field: "Title" + contains: "ReqStream" + - field: "Author" + contains: "DEMA Consulting" + - field: "Subject" + contains: "Build notes" + pages: + min: 1 + text: + - contains: "Build Notes" + + # --- CODE QUALITY --- + + - name: Pandoc_CodeQualityHtml + description: "Code Quality HTML was generated by Pandoc" + tags: [code-quality] + files: + - pattern: "docs/code_quality/quality.html" + count: 1 + html: + - query: "//head/title" + count: 1 + text: + - contains: "CodeQL" + + - name: WeasyPrint_CodeQualityPdf + description: "Code Quality PDF was generated by WeasyPrint" + tags: [code-quality] + files: + - pattern: "docs/ReqStream Code Quality.pdf" + count: 1 + pdf: + metadata: + - field: "Title" + contains: "Code Quality" + - field: "Author" + contains: "DEMA Consulting" + - field: "Subject" + contains: "Code Quality" + pages: + min: 1 + text: + - contains: "CodeQL" + + # --- CODE REVIEW PLAN --- + + - name: Pandoc_ReviewPlanHtml + description: "Code Review Plan HTML was generated by Pandoc" + tags: [code-review] + files: + - pattern: "docs/code_review_plan/plan.html" + count: 1 + html: + - query: "//head/title" + count: 1 + text: + - contains: "Review Plan" + + - name: WeasyPrint_ReviewPlanPdf + description: "Code Review Plan PDF was generated by WeasyPrint" + tags: [code-review] + files: + - pattern: "docs/ReqStream Review Plan.pdf" + count: 1 + pdf: + metadata: + - field: "Title" + contains: "Review Plan" + - field: "Author" + contains: "DEMA Consulting" + - field: "Subject" + contains: "Review Plan" + pages: + min: 1 + text: + - contains: "Review Plan" + + # --- CODE REVIEW REPORT --- + + - name: Pandoc_ReviewReportHtml + description: "Code Review Report HTML was generated by Pandoc" + tags: [code-review] + files: + - pattern: "docs/code_review_report/report.html" + count: 1 + html: + - query: "//head/title" + count: 1 + text: + - contains: "Review Report" + + - name: WeasyPrint_ReviewReportPdf + description: "Code Review Report PDF was generated by WeasyPrint" + tags: [code-review] + files: + - pattern: "docs/ReqStream Review Report.pdf" + count: 1 + pdf: + metadata: + - field: "Title" + contains: "Review Report" + - field: "Author" + contains: "DEMA Consulting" + - field: "Subject" + contains: "Review Report" + pages: + min: 1 + text: + - contains: "Review Report" + + # --- DESIGN DOCUMENT --- + + - name: Pandoc_DesignHtml + description: "Design HTML was generated by Pandoc" + tags: [design] + files: + - pattern: "docs/design/design.html" + count: 1 + html: + - query: "//head/title" + count: 1 + text: + - contains: "Design" + + - name: WeasyPrint_DesignPdf + description: "Design PDF was generated by WeasyPrint" + tags: [design] + files: + - pattern: "docs/ReqStream Software Design.pdf" + count: 1 + pdf: + metadata: + - field: "Title" + contains: "Design" + - field: "Author" + contains: "DEMA Consulting" + - field: "Subject" + contains: "Detailed design" + pages: + min: 3 + text: + - contains: "Design" + + # --- USER GUIDE --- + + - name: Pandoc_UserGuideHtml + description: "User Guide HTML was generated by Pandoc" + tags: [user-guide] + files: + - pattern: "docs/user_guide/user_guide.html" + count: 1 + html: + - query: "//head/title" + count: 1 + text: + - contains: "User Guide" + + - name: WeasyPrint_UserGuidePdf + description: "User Guide PDF was generated by WeasyPrint" + tags: [user-guide] + files: + - pattern: "docs/ReqStream User Guide.pdf" + count: 1 + pdf: + metadata: + - field: "Title" + contains: "User Guide" + - field: "Author" + contains: "DEMA Consulting" + - field: "Subject" + contains: "Requirements Management" + pages: + min: 3 + text: + - contains: "User Guide" + + # --- REQUIREMENTS DOCUMENT --- + # Note: these tests run after ReqStream and do not contribute to OTS requirements evidence. + + - name: Pandoc_RequirementsHtml + description: "Requirements HTML was generated by Pandoc" + tags: [requirements] + files: + - pattern: "docs/requirements_doc/requirements.html" + count: 1 + html: + - query: "//head/title" + count: 1 + text: + - contains: "Requirements" + + - name: WeasyPrint_RequirementsPdf + description: "Requirements PDF was generated by WeasyPrint" + tags: [requirements] + files: + - pattern: "docs/ReqStream Requirements.pdf" + count: 1 + pdf: + metadata: + - field: "Title" + contains: "Requirements" + - field: "Author" + contains: "DEMA Consulting" + - field: "Subject" + contains: "Requirements" + pages: + min: 1 + text: + - contains: "Requirements" + + # --- TRACE MATRIX --- + # Note: these tests run after ReqStream and do not contribute to OTS requirements evidence. + + - name: Pandoc_TraceMatrixHtml + description: "Trace Matrix HTML was generated by Pandoc" + tags: [requirements] + files: + - pattern: "docs/requirements_report/trace_matrix.html" + count: 1 + html: + - query: "//head/title" + count: 1 + text: + - contains: "Trace Matrix" + + - name: WeasyPrint_TraceMatrixPdf + description: "Trace Matrix PDF was generated by WeasyPrint" + tags: [requirements] + files: + - pattern: "docs/ReqStream Trace Matrix.pdf" + count: 1 + pdf: + metadata: + - field: "Title" + contains: "Trace Matrix" + - field: "Author" + contains: "DEMA Consulting" + - field: "Subject" + contains: "Traceability" + pages: + min: 1 + text: + - contains: "Trace Matrix" diff --git a/.github/agents/developer.agent.md b/.github/agents/developer.agent.md index 2671008..a898e60 100644 --- a/.github/agents/developer.agent.md +++ b/.github/agents/developer.agent.md @@ -1,28 +1,29 @@ --- name: developer -description: > - General-purpose software development agent that applies appropriate standards - based on the work being performed. +description: Comprehensive development agent for code, documentation, and requirements across multiple languages user-invocable: true --- # Developer Agent -Perform software development tasks by determining and applying appropriate DEMA Consulting standards from `.github/standards/`. +Perform software development tasks by determining and applying appropriate standards from `.github/standards/`. # Standards-Based Workflow 1. **Analyze the request** to identify scope: languages, file types, requirements, testing, reviews -2. **Read relevant standards** from `.github/standards/` as defined in AGENTS.md based on work performed -3. **Apply loaded standards** throughout development process +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 modified file, identify which companion artifacts need updating + (requirements, design docs, tests, review-sets) + - Include companion artifact updates in the work plan 4. **Execute work** following standards requirements and quality checks -5. **Lint fixes** follow the linting process before performing quality gates -6. **Generate completion report** with results and compliance status +5. **Formatting**: Run `pwsh ./fix.ps1` to silently apply all + available auto-fixers (dotnet format, markdown, YAML) before committing +6. **Generate completion report** per the AGENTS.md reporting requirements - save to + `.agent-logs/{agent-name}-{subject}-{unique-id}.md` and return the summary to the caller -# Reporting - -Upon completion create a summary in `.agent-logs/{agent-name}-{subject}-{unique-id}.md` -of the project consisting of: +# Report Template ```markdown # Developer Agent Report @@ -37,7 +38,7 @@ of the project consisting of: ## Tooling Executed -- **Language Tools**: {Compilers, linters, formatters used} +- **Language Tools**: {Compilers, formatters, and build tools used} - **Compliance Tools**: {ReqStream, ReviewMark tools used} - **Validation Results**: {Tool execution results} @@ -46,5 +47,3 @@ of the project consisting of: - **Quality Checks**: {Standards quality checks status} - **Issues Resolved**: {Any problems encountered and resolved} ``` - -Return this summary to the caller. diff --git a/.github/agents/code-review.agent.md b/.github/agents/formal-review.agent.md similarity index 58% rename from .github/agents/code-review.agent.md rename to .github/agents/formal-review.agent.md index bb48e5c..825d904 100644 --- a/.github/agents/code-review.agent.md +++ b/.github/agents/formal-review.agent.md @@ -1,41 +1,30 @@ --- -name: code-review +name: formal-review description: Agent for performing formal reviews user-invocable: true --- -# Code Review Agent +# Formal Review Agent This agent runs the formal review based on the review-set it's told to perform. +Document findings only - never modify code during a review. # Formal Review Steps -Formal reviews are a quality enforcement mechanism, and as such MUST be performed using the following four steps: - -1. Download the - - to get the checklist to fill in +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 the files all together -4. Populate the checklist with the findings to `.agent-logs/reviews/review-report-{review-set}.md` of the project. - -# Don't Do These Things - -- **Never modify code during review** (document findings only) -- **Never skip applicable checklist items** (comprehensive review required) -- **Never approve reviews with unresolved critical findings** -- **Never bypass review status requirements** for compliance -- **Never conduct reviews without proper documentation** -- **Never ignore security or compliance findings** -- **Never approve without verifying all quality gates** +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`. + This directory holds formal review artifacts, not agent logs. +5. Generate a completion report per the AGENTS.md reporting requirements. -# Reporting - -Upon completion create a summary in `.agent-logs/{agent-name}-{subject}-{unique-id}.md` -of the project consisting of: +# Report Template ```markdown -# Code Review Report +# Formal Review Report **Result**: (SUCCEEDED|FAILED) @@ -70,5 +59,3 @@ For each issue found, include: - **Quality Gates**: {Status of review checklist items} - **Approval Status**: {Approved/Rejected with justification} ``` - -Return summary to caller. diff --git a/.github/agents/implementation.agent.md b/.github/agents/implementation.agent.md index 03603a4..7cc0352 100644 --- a/.github/agents/implementation.agent.md +++ b/.github/agents/implementation.agent.md @@ -16,70 +16,105 @@ systematically. the quality of the implementation. The process consists of the following states: -- **RESEARCH** - performs initial analysis +- **PLANNING** - analyzes the request, develops a plan, and self-validates it - **DEVELOPMENT** - develops the implementation changes - **QUALITY** - performs quality validation - **REPORT** - generates final implementation report -The state-transitions include retrying a limited number of times, using a 'retry-count' -counting how many retries have occurred. +The state-transitions include retrying a limited number of times: -## RESEARCH State (start) +- **Quality retry budget**: maximum 3 retries (QUALITY → PLANNING) - when + exhausted, transition directly to REPORT with Result: FAILED -Call the built-in explore sub-agent with: +## PLANNING State (start) -- **context**: the user's request + any previous quality findings + retry context -- **goal**: analyze the implementation state and develop a plan to implement the request +Call the **explore** agent as a sub-agent (built-in agent type) with: -Once the explore sub-agent finishes, transition to the DEVELOPMENT state. +- **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, + listing the unknowns and what CAN be implemented once they are resolved +- OTHERWISE (GO): Transition to DEVELOPMENT ## DEVELOPMENT State -Call the developer sub-agent with: +Call the **developer** agent as a sub-agent (custom agent from `.github/agents/`) with: -- **context** the user's request + research plan + specific quality issues to address (if retry) -- **goal** implement the user's request and any identified quality fixes +- **context**: the user's request + planning results + specific quality issues to address (if retry) +- **goal**: implement the user's request as described in the planning results, addressing + any identified quality fixes Once the developer sub-agent finishes: - IF developer SUCCEEDED: Transition to QUALITY state to check the quality of the work -- IF developer FAILED: Transition to REPORT state to report the failure +- OTHERWISE (FAILED): Transition to REPORT state to report the failure ## QUALITY State -Call the quality sub-agent with: +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) -- **goal** check the quality of the work performed for any issues +- **context**: the user's request + development summary + files changed + previous issues (if any) +- **goal**: check the quality of the work performed for any issues Once the quality sub-agent finishes: - IF quality SUCCEEDED: Transition to REPORT state to report completion -- IF quality FAILED and retry-count < 3: Transition to RESEARCH state to plan quality fixes -- IF quality FAILED and retry-count >= 3: Transition to REPORT state to report failure +- IF quality FAILED and quality retry budget not exhausted: Transition to PLANNING + state to plan quality fixes (counts against the quality retry budget) +- OTHERWISE (budget exhausted): Transition to REPORT state to report failure + +## REPORT State (end) -### REPORT State (end) +**Implementation-specific Result rule**: In addition to SUCCEEDED and FAILED, +this agent may report INCOMPLETE when the request cannot be implemented without +information only the user can provide. -Upon completion create a summary in `.agent-logs/{agent-name}-{subject}-{unique-id}.md` -of the project consisting of: +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. + +# Report Template ```markdown # Implementation Orchestration Report -**Result**: (SUCCEEDED|FAILED) -**Final State**: (RESEARCH|DEVELOPMENT|QUALITY|REPORT) +**Result**: (SUCCEEDED|FAILED|INCOMPLETE) +**Final State**: (PLANNING|DEVELOPMENT|QUALITY|REPORT) **Retry Count**: ## State Machine Execution -- **Research Results**: {Summary of explore agent findings} +- **Planning Results**: {Implementation plan, assumption ratings, risks, and recommendation} - **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**: {Research findings and context} +- **Explore Agent (Planning)**: {Plan, assumption verdicts, top risks, GO/INCOMPLETE recommendation} - **Developer Agent**: {Development status and files modified} - **Quality Agent**: {Validation results and compliance status} @@ -89,5 +124,3 @@ of the project consisting of: - **Quality Compliance**: {Final quality validation status} - **Issues Resolved**: {Problems encountered and resolution attempts} ``` - -Return this summary to the caller. diff --git a/.github/agents/lint-fix.agent.md b/.github/agents/lint-fix.agent.md new file mode 100644 index 0000000..83ad8cb --- /dev/null +++ b/.github/agents/lint-fix.agent.md @@ -0,0 +1,77 @@ +--- +name: lint-fix +description: Fixes all lint issues. Run this once before submitting a pull request. +user-invocable: true +--- + +# Lint Fix Agent + +Fix all lint issues in the repository until `pwsh ./lint.ps1` exits cleanly. +This is the **pre-PR lint sweep** - run it once before pull request +submission, not during normal development. + +# Workflow (MANDATORY) + +1. **Auto-fix pass**: Run `pwsh ./fix.ps1` to silently apply all + automatic fixes (dotnet format, markdownlint, yamlfix). + +2. **Fix loop** (maximum 5 iterations): + + a. Run `pwsh ./lint.ps1` and capture the full output. + + b. If exit code is 0 - the repository is lint-clean. Proceed to the report. + + c. Parse the failures and fix each one using the guidance below. + + d. Repeat. + +3. **Budget exhausted**: If still failing after 5 iterations, report the + remaining issues and stop with Result: FAILED. + +# Fix Guidance by Failure Type + +- **cspell spelling errors**: Add legitimate technical terms to `.cspell.yaml` + under the `words` list. Correct genuine misspellings in the source text. + Do not add misspelled words to the dictionary. + +- **markdownlint MD013 (line length)**: Wrap long lines at natural break points, + after commas, before conjunctions, or at sentence boundaries. Do not break + in the middle of a code span or URL. + +- **markdownlint other rules**: Apply the specific fix indicated in the output + (e.g., missing blank lines, heading levels, code fence languages). + +- **yamllint errors**: Fix indentation, trailing spaces, or missing document + markers as indicated. Run `pwsh ./fix.ps1` again if structural YAML + issues appear - yamlfix may handle them. + +- **reqstream / reviewmark / versionmark failures**: Fix the referenced + requirements or review configuration per the standards in + `.github/standards/reqstream-usage.md` and `.github/standards/reviewmark-usage.md`. + +# Rules + +- Fix **only** lint issues - do not refactor, restructure, or make functional changes +- For spelling: prefer adding terms to `.cspell.yaml` over rewriting correct technical text +- Never modify auto-generated files (check file headers for "auto-generated" or "do not edit") +- Respect all protected configuration files listed in AGENTS.md +- Report **all** files modified + +# Report Template + +```markdown +# Lint Fix Report + +**Result**: (SUCCEEDED|FAILED) + +## Summary + +- **Iterations**: {Number of fix-loop iterations performed} +- **Files Modified**: {List of all files changed} +- **Issues Fixed**: {Brief categorized description of what was corrected} + +## Remaining Issues (only when Result is FAILED) + +{List of unfixed lint failures with file:line references and why they could +not be automatically resolved} +``` diff --git a/.github/agents/quality.agent.md b/.github/agents/quality.agent.md index 8376693..f80cfae 100644 --- a/.github/agents/quality.agent.md +++ b/.github/agents/quality.agent.md @@ -1,137 +1,128 @@ --- name: quality -description: > - Quality assurance agent that grades developer work against DEMA Consulting - standards and Continuous Compliance practices. +description: Quality assurance agent that validates work against project standards, compliance practices, and quality gates. user-invocable: true --- # Quality Agent -Grade and validate software development work by ensuring compliance with -DEMA Consulting standards and Continuous Compliance practices. +Grade and validate software development work by ensuring compliance with project standards and practices. # Standards-Based Quality Assessment -This assessment is a quality control system of the project and MUST be performed systematically. +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 features or components always require requirements, + design, and review-set coverage regardless of whether those files were touched +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 features, components, + or structural changes then Requirements, Design Documentation, and Review + Management are always in scope and FAIL if the artifacts 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 -1. **Analyze completed work** to identify scope and changes made -2. **Read relevant standards** from `.github/standards/` as defined in AGENTS.md based on work performed -3. **Execute comprehensive quality assessment** using the structured evaluation criteria in the reporting template -4. **Validate tool compliance** using ReqStream, ReviewMark, and language tools -5. **Generate quality assessment report** with findings and recommendations +**Quality-specific Result rule**: Result SUCCEEDED requires Overall Grade PASS. +Result FAILED when Overall Grade is FAIL. -# Reporting +# Report Template -Upon completion create a summary in `.agent-logs/{agent-name}-{subject}-{unique-id}.md` -of the project consisting of: +For each checklist item in the template below, record as `(PASS|FAIL|N/A) - {one-line evidence}`. ```markdown # Quality Assessment Report **Result**: (SUCCEEDED|FAILED) -**Overall Grade**: (PASS|FAIL|NEEDS_WORK) +**Overall Grade**: (PASS|FAIL) -## Assessment Summary +## Required Fixes (only when Result is FAILED) -- **Work Reviewed**: {Description of work assessed} -- **Standards Applied**: {Standards files used for assessment} -- **Categories Evaluated**: {Quality check categories assessed} +Priority-ordered list of issues that MUST be resolved for the next retry: + +1. **[severity]** {one-line description} + - File: {path:line} + - Action: {specific fix instruction} + +## Evaluation Scope + +- **Evaluated**: {List sections assessed and why} +- **Skipped**: {One-line per skipped section with reason, e.g., "Design + Documentation: N/A - no design files modified"} ## Requirements Compliance: (PASS|FAIL|N/A) -- Were requirements updated to reflect functional changes? (PASS|FAIL|N/A) - {Evidence} -- Were new requirements created for new features? (PASS|FAIL|N/A) - {Evidence} -- Do requirement IDs follow semantic naming standards? (PASS|FAIL|N/A) - {Evidence} -- Do requirement files follow kebab-case naming convention? (PASS|FAIL|N/A) - {Evidence} -- Are requirement files organized under `docs/reqstream/` with proper folder structure? (PASS|FAIL|N/A) - {Evidence} -- Are OTS requirements properly placed in `docs/reqstream/ots/` subfolder? (PASS|FAIL|N/A) - {Evidence} -- Were source filters applied appropriately for platform-specific requirements? (PASS|FAIL|N/A) - {Evidence} -- Does ReqStream enforcement pass without errors? (PASS|FAIL|N/A) - {Evidence} -- Is requirements traceability maintained to tests? (PASS|FAIL|N/A) - {Evidence} +- 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? ## Design Documentation Compliance: (PASS|FAIL|N/A) -- Were design documents updated for architectural changes? (PASS|FAIL|N/A) - {Evidence} -- Were new design artifacts created for new components? (PASS|FAIL|N/A) - {Evidence} -- Do design folder names use kebab-case convention matching source structure? (PASS|FAIL|N/A) - {Evidence} -- Are design files properly named ({subsystem-name}.md, {unit-name}.md patterns)? (PASS|FAIL|N/A) - {Evidence} -- Is `docs/design/introduction.md` present with required Software Structure section? (PASS|FAIL|N/A) - {Evidence} -- Are design decisions documented with rationale? (PASS|FAIL|N/A) - {Evidence} -- Is system/subsystem/unit categorization maintained? (PASS|FAIL|N/A) - {Evidence} -- Is design-to-implementation traceability preserved? (PASS|FAIL|N/A) - {Evidence} +- 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)? +- Is `docs/design/introduction.md` present with required Software Structure section? +- Are design decisions documented with rationale? +- Is system/subsystem/unit categorization maintained? +- Is design-to-implementation traceability preserved? ## Code Quality Compliance: (PASS|FAIL|N/A) -- Are language-specific standards followed (from applicable standards files)? (PASS|FAIL|N/A) - {Evidence} -- Are quality checks from standards files satisfied? (PASS|FAIL|N/A) - {Evidence} -- Is code properly categorized (system/subsystem/unit/OTS)? (PASS|FAIL|N/A) - {Evidence} -- Is appropriate separation of concerns maintained? (PASS|FAIL|N/A) - {Evidence} -- Was language-specific tooling executed and passing? (PASS|FAIL|N/A) - {Evidence} +- 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? ## Testing Compliance: (PASS|FAIL|N/A) -- Were tests created/updated for all functional changes? (PASS|FAIL|N/A) - {Evidence} -- Is test coverage maintained for all requirements? (PASS|FAIL|N/A) - {Evidence} -- Are testing standards followed (AAA pattern, etc.)? (PASS|FAIL|N/A) - {Evidence} -- Do tests respect software item hierarchy boundaries (System/Subsystem/Unit scope)? (PASS|FAIL|N/A) - {Evidence} -- Are cross-hierarchy test dependencies documented in design docs? (PASS|FAIL|N/A) - {Evidence} -- Does test categorization align with code structure? (PASS|FAIL|N/A) - {Evidence} -- Do all tests pass without failures? (PASS|FAIL|N/A) - {Evidence} +- 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)? +- Are cross-hierarchy test dependencies documented in design docs? +- Does test categorization align with code structure? +- Do all tests pass without failures? ## Review Management Compliance: (PASS|FAIL|N/A) -- Were review-sets updated for structural changes (new/deleted systems, subsystems, or units)? (PASS|FAIL|N/A) - {Evidence} -- Do file patterns follow include-then-exclude approach? (PASS|FAIL|N/A) - {Evidence} -- Is review scope appropriate for change magnitude? (PASS|FAIL|N/A) - {Evidence} -- Was ReviewMark tooling executed and passing? (PASS|FAIL|N/A) - {Evidence} -- Were review artifacts generated correctly? (PASS|FAIL|N/A) - {Evidence} +- Were review-sets updated for structural changes (new/deleted systems, subsystems, or units)? +- Do file patterns follow include-then-exclude approach? +- Is review scope appropriate for change magnitude? +- Was ReviewMark tooling executed and passing? +- Were review artifacts generated correctly? ## Documentation Compliance: (PASS|FAIL|N/A) -- Was README.md updated for user-facing changes? (PASS|FAIL|N/A) - {Evidence} -- Were user guides updated for feature changes? (PASS|FAIL|N/A) - {Evidence} -- Does API documentation reflect code changes? (PASS|FAIL|N/A) - {Evidence} -- Was compliance documentation generated? (PASS|FAIL|N/A) - {Evidence} -- Does documentation follow standards formatting? (PASS|FAIL|N/A) - {Evidence} -- Is documentation organized under `docs/` following standard folder structure? (PASS|FAIL|N/A) - {Evidence} -- Do Pandoc collections include proper `introduction.md` with Purpose and Scope sections? (PASS|FAIL|N/A) - {Evidence} -- Are auto-generated markdown files left unmodified? (PASS|FAIL|N/A) - {Evidence} -- Do README.md files use absolute URLs and include concrete examples? (PASS|FAIL|N/A) - {Evidence} -- Is documentation integrated into ReviewMark review-sets for formal review? (PASS|FAIL|N/A) - {Evidence} +- Was README.md updated for user-facing changes? +- Were user guides updated for feature 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? ## Software Item Completeness: (PASS|FAIL|N/A) -- Does every identified software unit have its own requirements file? (PASS|FAIL|N/A) - {Evidence} -- Does every identified software unit have its own design document? (PASS|FAIL|N/A) - {Evidence} -- Does every identified subsystem have its own requirements file? (PASS|FAIL|N/A) - {Evidence} -- Does every identified subsystem have its own design document? (PASS|FAIL|N/A) - {Evidence} +- 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? ## Process Compliance: (PASS|FAIL|N/A) -- Was Continuous Compliance workflow followed? (PASS|FAIL|N/A) - {Evidence} -- Did all quality gates execute successfully? (PASS|FAIL|N/A) - {Evidence} -- Were appropriate tools used for validation? (PASS|FAIL|N/A) - {Evidence} -- Were standards consistently applied across work? (PASS|FAIL|N/A) - {Evidence} -- Was compliance evidence generated and preserved? (PASS|FAIL|N/A) - {Evidence} - -## Overall Findings - -- **Critical Issues**: {Count and description of critical findings} -- **Recommendations**: {Suggested improvements and next steps} -- **Tools Executed**: {Quality tools used for validation} - -## Compliance Status - -- **Standards Adherence**: {Overall compliance rating with specific standards} -- **Quality Gates**: {Status of automated quality checks with tool outputs} +- 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? ``` - -The **Result** field MUST reflect the quality validation outcome for orchestrator decision-making: - -- **Result: SUCCEEDED** - Only when Overall Grade is PASS (all compliance requirements met) -- **Result: FAILED** - When Overall Grade is FAIL or NEEDS_WORK (compliance failures present) - -This ensures orchestrators properly halt workflows when quality gates fail. - -Return this summary to the caller. diff --git a/.github/agents/repo-consistency.agent.md b/.github/agents/repo-consistency.agent.md index b623895..5dbe99f 100644 --- a/.github/agents/repo-consistency.agent.md +++ b/.github/agents/repo-consistency.agent.md @@ -23,6 +23,8 @@ benefit from template evolution while respecting project-specific customizations while respecting project-specific customizations 4. **Apply Appropriate Updates**: Implement applicable template improvements with proper translation for project context 5. **Validate Consistency**: Verify that applied changes maintain functionality and follow project patterns +6. **Generate completion report** per the AGENTS.md reporting requirements - save to + `.agent-logs/{agent-name}-{subject}-{unique-id}.md` and return the summary to the caller ## Key Principles @@ -40,10 +42,7 @@ benefit from template evolution while respecting project-specific customizations - **Never skip validation** of preserved functionality after template alignment - **Never assume all template patterns apply universally** (assess project-specific needs) -# Reporting - -Upon completion create a summary in `.agent-logs/{agent-name}-{subject}-{unique-id}.md` -of the project consisting of: +# Report Template ```markdown # Repo Consistency Report @@ -76,5 +75,3 @@ of the project consisting of: - **Enhancement Adoptions**: {Template improvements successfully integrated} - **Validation Results**: {Testing and validation outcomes} ``` - -Return this summary to the caller. diff --git a/.github/standards/coding-principles.md b/.github/standards/coding-principles.md index b00143d..213c031 100644 --- a/.github/standards/coding-principles.md +++ b/.github/standards/coding-principles.md @@ -14,9 +14,15 @@ Continuous Compliance environments. All code MUST follow literate programming principles: -- **Intent Comments**: Every function/method begins with a comment explaining WHY (not what) -- **Logical Separation**: Complex functions use comments to separate logical blocks +- **Intent Documentation**: Function and method documentation (XmlDoc, Doxygen, + JSDoc, etc.) MUST explain WHY the function exists and its design purpose - + not just restate what it does - because reviewers must verify implementation + matches design intent without reading the full codebase +- **Logical Separation**: Complex functions use block comments to separate and + describe logical steps within the implementation - **Public Documentation**: All public interfaces have comprehensive documentation + because consumers and auditors rely on interface contracts for integration + and compliance verification - **Clarity Over Cleverness**: Code should be immediately understandable by team members ## Universal Code Architecture Principles @@ -28,9 +34,8 @@ All code MUST follow literate programming principles: - **Pure Functions**: Minimize side effects and hidden state - **Clear Interfaces**: Well-defined API contracts - **Separation of Concerns**: Business logic separate from infrastructure -- **Repository Structure Adherence**: Before creating any new files, analyze the repository structure to - understand established directory conventions and file placement patterns. Place new files in locations - consistent with existing patterns. +- **Repository Structure Adherence**: Analyze existing directory conventions + before creating files; place new files consistent with established patterns ### Compliance-Ready Code Structure @@ -53,7 +58,8 @@ All code MUST follow literate programming principles: - **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 - **Hidden Dependencies**: Don't create untestable code with hidden dependencies -- **Hidden Functionality**: Don't implement functionality without requirement traceability +- **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 - **Premature Optimization**: Don't optimize for performance before establishing correctness @@ -62,9 +68,5 @@ All code MUST follow literate programming principles: # Language-Specific Implementation -For each detected language: - -- **Load Standards**: Read the appropriate `{language}-language.md` file from `.github/standards/` -- **Apply Tooling**: Use language-specific formatting, linting, and build tools -- **Follow Conventions**: Apply language-specific naming, patterns, and best practices -- **Generate Documentation**: Use language-appropriate documentation format (XmlDoc, Doxygen, JSDoc, etc.) +For each detected language, read `{language}-language.md` from `.github/standards/` +and apply its standards, tooling, and conventions. diff --git a/.github/standards/csharp-language.md b/.github/standards/csharp-language.md index 5dbdda6..707b0f9 100644 --- a/.github/standards/csharp-language.md +++ b/.github/standards/csharp-language.md @@ -45,3 +45,4 @@ return OutputFormatter.Format(validatedResults); - [ ] Zero compiler warnings (`TreatWarningsAsErrors=true`) - [ ] XmlDoc documentation complete on all members (public, internal, protected, private) +- [ ] `dotnet format` applied (run `pwsh ./fix.ps1`) diff --git a/.github/standards/csharp-testing.md b/.github/standards/csharp-testing.md index 3d9de81..1591eeb 100644 --- a/.github/standards/csharp-testing.md +++ b/.github/standards/csharp-testing.md @@ -6,7 +6,7 @@ globs: ["**/test/**/*.cs", "**/tests/**/*.cs", "**/*Tests.cs", "**/*Test.cs"] # C# Testing Standards (MSTest) -This document defines DEMA Consulting standards for C# test development using +This document defines standards for C# test development using MSTest within Continuous Compliance environments. ## Required Standards diff --git a/.github/standards/design-documentation.md b/.github/standards/design-documentation.md index f5bbbcd..30becb5 100644 --- a/.github/standards/design-documentation.md +++ b/.github/standards/design-documentation.md @@ -6,10 +6,9 @@ globs: ["docs/design/**/*.md"] # Design Documentation Standards -This document defines DEMA Consulting standards for design documentation -within Continuous Compliance environments, extending the general technical -documentation standards with specific requirements for software design -artifacts. +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 @@ -39,8 +38,9 @@ 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 design documents (kebab-case folder names) + ├── {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) ``` @@ -74,6 +74,8 @@ Example format: ```text Project1Name (System) ├── ComponentA (Subsystem) +│ ├── SubComponentP (Subsystem) +│ │ └── ClassW (Unit) │ ├── ClassX (Unit) │ └── ClassY (Unit) ├── ComponentB (Subsystem) @@ -94,14 +96,35 @@ Example format: ```text src/Project1Name/ ├── ComponentA/ -│ ├── ClassX.cs — Core business logic handler -│ └── ClassY.cs — Data validation service +│ ├── 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 +│ └── ClassZ.cs - Integration interface +└── UtilityClass.cs - Common utility functions src/Project2Name/ -└── HelperClass.cs — Helper functions +└── HelperClass.cs - Helper functions +``` + +### Companion Artifact Structure (RECOMMENDED) + +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: + +Example format: + +```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) +- 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` ``` ## System Design Documentation (MANDATORY) @@ -133,12 +156,9 @@ For every unit identified in the software structure: # Software Items Integration (CRITICAL) -Before creating design documentation, agents MUST: - -1. **Read `.github/standards/software-items.md`** to understand System/Subsystem/Unit classifications -2. **Apply proper categorization** when creating software structure diagrams -3. **Ensure consistency** between software structure and folder layout -4. **Validate mapping** from design categories to source code organization +Read `software-items.md` before creating design documentation - correct +System/Subsystem/Unit categorization is required for software structure +diagrams and folder layout. # Writing Guidelines diff --git a/.github/standards/reqstream-usage.md b/.github/standards/reqstream-usage.md index e4103b1..1c7643a 100644 --- a/.github/standards/reqstream-usage.md +++ b/.github/standards/reqstream-usage.md @@ -6,8 +6,8 @@ globs: ["requirements.yaml", "docs/reqstream/**/*.yaml"] # ReqStream Requirements Management Standards -This document defines DEMA Consulting standards for requirements management -using ReqStream within Continuous Compliance environments. +This document defines standards for requirements management using ReqStream +within Continuous Compliance environments. ## Required Standards @@ -29,11 +29,8 @@ generation: # Software Items Integration (CRITICAL) -Before creating requirements files, agents MUST: - -1. **Read `.github/standards/software-items.md`** to understand System/Subsystem/Unit/OTS classifications -2. **Apply proper categorization** when organizing requirements files -3. **Mirror source code structure** in requirements folder organization +Read `software-items.md` before creating requirements files - correct +categorization and folder structure must mirror source code organization. # Requirements Organization @@ -47,8 +44,9 @@ docs/reqstream/ ├── {system-name}/ # System-level requirements folder (one per system) │ ├── {system-name}.yaml # System-level requirements │ ├── platform-requirements.yaml # Platform support requirements -│ ├── {subsystem-name}/ # Subsystem requirements (kebab-case folders) +│ ├── {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 software items folder @@ -65,7 +63,7 @@ ones they decompose into: - **System requirements** → may link to subsystem or unit requirements - **Subsystem requirements** → may link to unit requirements within that subsystem -- **Unit requirements** → should NOT link upward to parent requirements +- **Unit requirements** → MUST NOT link upward to parent requirements This prevents circular dependencies and ensures clear hierarchical relationships for compliance auditing. @@ -87,7 +85,7 @@ are validated through integration behavior at their architectural level. sections: - title: Functional Requirements requirements: - - id: System-Subsystem-Feature + - id: System-Component-Feature title: The system shall perform the required function. justification: | Business rationale explaining why this requirement exists. @@ -123,10 +121,14 @@ sections: # Semantic IDs (MANDATORY) -Use meaningful IDs following `System-Section-ShortDesc` pattern because -auditors need to understand requirements without cross-referencing: +Use meaningful IDs following the `System-Component-Feature` pattern because +auditors need to understand requirements without cross-referencing. The +`Component` segment identifies the relevant part of the system at any level +(functional area, subsystem, or unit): -- **Good**: `TemplateTool-Core-DisplayHelp` +- **System-level**: `TemplateTool-Core-DisplayHelp` +- **Subsystem-level**: `TemplateTool-Parser-ParseYaml` +- **Unit-level**: `TemplateTool-Validator-CheckFormat` - **Bad**: `REQ-042` (requires lookup to understand) # Source Filter Requirements (CRITICAL) @@ -185,5 +187,4 @@ Before submitting requirements, verify: - [ ] OTS requirements placed in `ots/` subfolder - [ ] Every software unit has requirements file, design doc, and tests - [ ] Valid YAML syntax passes yamllint validation -- [ ] ReqStream enforcement passes: `dotnet reqstream --enforce` - [ ] Test result formats compatible (TRX, JUnit XML) diff --git a/.github/standards/reviewmark-usage.md b/.github/standards/reviewmark-usage.md index 48380c5..5d6219e 100644 --- a/.github/standards/reviewmark-usage.md +++ b/.github/standards/reviewmark-usage.md @@ -20,8 +20,11 @@ review, organizes them into review-sets, and generates review plans and reports. - **Lint Configuration**: `dotnet reviewmark --lint` - **Elaborate Review-Set**: `dotnet reviewmark --elaborate {review-set}` -- **Generate Plan**: `dotnet reviewmark --plan docs/code_review_plan/plan.md` -- **Generate Report**: `dotnet reviewmark --report docs/code_review_report/report.md` +- **Generate Plan**: `dotnet reviewmark --plan docs/code_review_plan/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. ## Repository Structure @@ -29,7 +32,6 @@ Required repository items for ReviewMark operation: - `.reviewmark.yaml` - Configuration for review-sets, file-patterns, and review evidence-source. - `docs/code_review_plan/` - Review planning artifacts -- `docs/code_review_report/` - Review status reports # Review Definition Structure @@ -76,9 +78,9 @@ When constructing review-sets, follow these principles to maintain manageable sc Organize review-sets using these standard patterns to ensure comprehensive coverage while keeping each review manageable in scope: -**Note**: File path patterns shown below use C# naming conventions (PascalCase, `.cs` extensions). -Other languages should adapt these patterns to their conventions (e.g., C++ might use -`snake_case` with `.cpp`/`.hpp` extensions). +**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. ## `Purpose` Review (only one per repository) @@ -107,7 +109,7 @@ Reviews system architecture and operational validation: - 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 integration tests: `test/{SystemName}.Tests/{SystemName}Tests.cs` + - System integration tests: `test/{SystemName}.Tests/{SystemName}Tests.{ext}` ## `{System}-Design` Review (one per system) @@ -134,7 +136,7 @@ Reviews requirements quality and traceability: - System requirements: `docs/reqstream/{system-name}/**/*.yaml` - OTS requirements: `docs/reqstream/ots/**/*.yaml` (if applicable) -## `{System}-{Subsystem}` Review (one per subsystem) +## `{System}-{Subsystem[-Child...]}` Review (one per subsystem at any depth) Reviews subsystem architecture and interfaces: @@ -143,11 +145,11 @@ Reviews subsystem architecture and interfaces: - **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` - - Tests: `test/{SystemName}.Tests/{SubsystemName}/{SubsystemName}Tests.cs` + - Requirements: `docs/reqstream/{system-name}/.../{subsystem-name}/{subsystem-name}.yaml` + - Design: `docs/design/{system-name}/.../{subsystem-name}/{subsystem-name}.md` + - Tests: `test/{SystemName}.Tests/.../{SubsystemName}/{SubsystemName}Tests.{ext}` -## `{System}-{Subsystem}-{Unit}` Review (one per unit) +## `{System}-{Subsystem[-Child...]}-{Unit}` Review (one per unit) Reviews individual software unit implementation: @@ -155,13 +157,13 @@ Reviews individual software unit implementation: - **Title**: "Review that {System} {Subsystem} {Unit} Implementation is Correct" - **Scope**: Complete unit review including all artifacts - **File Path Patterns**: - - Requirements: `docs/reqstream/{system-name}/{subsystem-name}/{unit-name}.yaml` or - `docs/reqstream/{system-name}/{unit-name}.yaml` - - Design: `docs/design/{system-name}/{subsystem-name}/{unit-name}.md` or - `docs/design/{system-name}/{unit-name}.md` - - Source: `src/{SystemName}/{SubsystemName}/{UnitName}.cs` or `src/{SystemName}/{UnitName}.cs` - - Tests: `test/{SystemName}.Tests/{SubsystemName}/{UnitName}Tests.cs` or - `test/{SystemName}.Tests/{UnitName}Tests.cs` + - Requirements: `docs/reqstream/{system-name}/.../{unit-name}.yaml` + - Design: `docs/design/{system-name}/.../{unit-name}.md` + - Source: `src/{SystemName}/.../{UnitName}.{ext}` + - Tests: `test/{SystemName}.Tests/.../{UnitName}Tests.{ext}` + +**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 @@ -176,4 +178,3 @@ Before submitting ReviewMark configuration, verify: - [ ] 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) -- [ ] Evidence source properly configured (`none` for dev, `url` for production) diff --git a/.github/standards/software-items.md b/.github/standards/software-items.md index 62abb9f..4ee5a91 100644 --- a/.github/standards/software-items.md +++ b/.github/standards/software-items.md @@ -5,10 +5,9 @@ description: Follow these standards when categorizing software components. # Software Items Definition Standards -This document defines DEMA Consulting standards for categorizing software -items within Continuous Compliance environments because proper categorization -determines requirements management approach, testing strategy, and review -scope. +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 @@ -28,6 +27,16 @@ Categorize all software into four primary groups: - System: Application/Library/System (e.g. TestResults → TestResultsLibrary) - Subsystem: Subsystem (e.g. Linter → LinterSubsystem) +# Naming Conventions in File Path Patterns + +Two placeholder styles 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 + # Categorization Guidelines Choose the appropriate category based on scope and testability: @@ -40,7 +49,8 @@ Choose the appropriate category based on scope and testability: ## Software Subsystem - Major architectural boundary (authentication, data layer, UI, communications) -- Contains multiple software units working together +- Contains software units and optionally child subsystems +- Subsystems may nest when a component has distinct internal boundaries - Typically maps to project folders or namespaces - Tested through subsystem integration tests diff --git a/.github/standards/technical-documentation.md b/.github/standards/technical-documentation.md index 9da6eab..8f38edc 100644 --- a/.github/standards/technical-documentation.md +++ b/.github/standards/technical-documentation.md @@ -6,8 +6,8 @@ globs: ["docs/**/*.md", "README.md"] # Technical Documentation Standards -This document defines DEMA Consulting standards for technical documentation -within Continuous Compliance environments. +This document defines standards for technical documentation within Continuous +Compliance environments. # Core Principles @@ -41,16 +41,18 @@ docs/ introduction.md # Design overview {system-name}/ # System architecture folder {system-name}.md # System architecture - {subsystem-name}/ # Subsystem design folder + {subsystem-name}/ # Subsystem folder; may nest recursively {subsystem-name}.md # Subsystem-specific designs + {child-subsystem}/ # Child subsystem (same structure) {unit-name}.md # Unit-specific designs {unit-name}.md # Top-level unit design reqstream/ # Requirements source files {system-name}/ # System requirements folder {system-name}.yaml # System requirements platform-requirements.yaml # Platform requirements - {subsystem-name}/ # Subsystem requirements folder + {subsystem-name}/ # Subsystem folder; may nest recursively {subsystem-name}.yaml # Subsystem requirements + {child-subsystem}/ # Child subsystem (same structure) {unit-name}.yaml # Unit-specific requirements {unit-name}.yaml # Top-level unit requirements ots/ # OTS requirement files diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index b1f7ccb..cee20a2 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -17,10 +17,9 @@ jobs: runs-on: ubuntu-latest permissions: contents: read - steps: # === INSTALL DEPENDENCIES === - # This section installs all required dependencies for quality checks. + # This section installs all required dependencies and tools for quality checks. # Downstream projects: Add any additional dependency installations here. - name: Checkout @@ -45,6 +44,10 @@ jobs: with: python-version: '3.14' + # === CAPTURE TOOL VERSIONS === + # This section captures the versions of all tools used in the build process. + # Downstream projects: Add any additional tools to capture here. + - name: Capture tool versions shell: bash run: | @@ -56,19 +59,27 @@ jobs: echo "✓ Tool versions captured" # === CAPTURE OTS SELF-VALIDATION RESULTS === - # This section captures self-validation results from OTS tools. - # Downstream projects: Add any additional self-validation steps here. + # This section runs the self-validation of each OTS tool and saves TRX results + # so that OTS Software Requirements in requirements.yaml can be satisfied. + # Downstream projects: Add any additional OTS tool self-validation steps here. - name: Run VersionMark self-validation - run: dotnet versionmark --validate --results artifacts/versionmark-self-validation-quality.trx + run: > + dotnet versionmark + --validate + --results artifacts/versionmark-self-validation-quality.trx # === RUN QUALITY CHECKS === - # This section runs all quality checks for the project. - # Downstream projects: Add any additional quality checks here. + # This section runs the linting and quality checks for the project. + # Downstream projects: Add any additional quality check steps here. - name: Run linters - shell: bash - run: bash ./lint.sh + shell: pwsh + run: ./lint.ps1 + + # === UPLOAD ARTIFACTS === + # This section uploads all generated artifacts for use by downstream jobs. + # Downstream projects: Add any additional artifact uploads here. - name: Upload quality artifacts uses: actions/upload-artifact@v7 @@ -95,7 +106,7 @@ jobs: steps: # === INSTALL DEPENDENCIES === - # This section installs all required dependencies for the build. + # This section installs all required dependencies and tools for building the project. # Downstream projects: Add any additional dependency installations here. - name: Checkout @@ -133,15 +144,19 @@ jobs: echo "✓ Tool versions captured" # === CAPTURE OTS SELF-VALIDATION RESULTS === - # This section captures self-validation results from OTS tools. - # Downstream projects: Add any additional self-validation steps here. + # This section runs the self-validation of each OTS tool and saves TRX results + # so that OTS Software Requirements in requirements.yaml can be satisfied. + # Downstream projects: Add any additional OTS tool self-validation steps here. - name: Run VersionMark self-validation - run: dotnet versionmark --validate --results artifacts/versionmark-self-validation-${{ matrix.os }}.trx + run: > + dotnet versionmark + --validate + --results artifacts/versionmark-self-validation-${{ matrix.os }}.trx # === BUILD AND TEST === # This section builds and tests the project. - # Downstream projects: Add any additional build and test steps here. + # Downstream projects: Add any additional build or test steps here. - name: Restore Dependencies run: > @@ -172,6 +187,7 @@ jobs: dotnet test --no-build --configuration Release + --property:Version=${{ inputs.version }} --collect "XPlat Code Coverage;Format=opencover" --logger "trx;LogFilePrefix=${{ matrix.os }}" --results-directory artifacts @@ -193,7 +209,7 @@ jobs: --property:PackageVersion=${{ inputs.version }} # === UPLOAD ARTIFACTS === - # This section uploads all build artifacts. + # This section uploads all generated artifacts for use by downstream jobs. # Downstream projects: Add any additional artifact uploads here. - name: Upload build artifacts @@ -223,7 +239,7 @@ jobs: steps: # === INSTALL DEPENDENCIES === - # This section installs all required dependencies for CodeQL analysis. + # This section installs all required dependencies and tools for CodeQL analysis. # Downstream projects: Add any additional dependency installations here. - name: Checkout @@ -256,7 +272,7 @@ jobs: dotnet restore # === BUILD AND ANALYZE === - # This section builds the project and runs CodeQL analysis. + # This section builds the project and performs CodeQL analysis. # Downstream projects: Add any additional analysis steps here. - name: Build @@ -274,7 +290,7 @@ jobs: upload: false # === UPLOAD ARTIFACTS === - # This section uploads all CodeQL artifacts. + # This section uploads all generated artifacts for use by downstream jobs. # Downstream projects: Add any additional artifact uploads here. - name: Upload CodeQL artifacts @@ -446,44 +462,100 @@ jobs: echo "Capturing tool versions..." 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 + dotnet git node npm pandoc weasyprint sarifmark sonarmark reqstream \ + buildmark versionmark reviewmark fileassert echo "✓ Tool versions captured" - # === CAPTURE OTS SELF-VALIDATION RESULTS === - # This section captures self-validation results from OTS tools. - # Downstream projects: Add any additional self-validation steps here. - - - name: Run ReqStream self-validation - run: dotnet reqstream --validate --results artifacts/reqstream-self-validation.trx + # === COMPILE BUILD NOTES === + # This section generates the Build Notes document. BuildMark and VersionMark self-validations + # run here to co-locate their evidence with the document that depends on their output. + # Pandoc converts the markdown to HTML, WeasyPrint renders the HTML to PDF, and FileAssert + # validates the outputs contain expected content. + # Downstream projects: Add any additional build notes steps here. - name: Run BuildMark self-validation - run: dotnet buildmark --validate --results artifacts/buildmark-self-validation.trx + run: > + dotnet buildmark + --validate + --results artifacts/buildmark-self-validation.trx - name: Run VersionMark self-validation - run: dotnet versionmark --validate --results artifacts/versionmark-self-validation.trx + run: > + dotnet versionmark + --validate + --results artifacts/versionmark-self-validation.trx - - name: Run SarifMark self-validation - run: dotnet sarifmark --validate --results artifacts/sarifmark-self-validation.trx + - name: Generate Build Notes with BuildMark + shell: bash + env: + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: > + dotnet buildmark + --build-version ${{ inputs.version }} + --report docs/build_notes.md + --report-depth 1 - - name: Run SonarMark self-validation - run: dotnet sonarmark --validate --results artifacts/sonarmark-self-validation.trx + - name: Display Build Notes Report + shell: bash + run: | + echo "=== Build Notes Report ===" + cat docs/build_notes.md - - name: Run ReviewMark self-validation - run: dotnet reviewmark --validate --results artifacts/reviewmark-self-validation.trx + - name: Publish Tool Versions + shell: bash + run: | + echo "Publishing tool versions..." + dotnet versionmark --publish --report docs/build_notes/versions.md --report-depth 1 \ + -- "artifacts/**/versionmark-*.json" + echo "✓ Tool versions published" - # === GENERATE MARKDOWN REPORTS === - # This section generates all markdown reports from various tools and sources. - # Downstream projects: Add any additional markdown report generation steps here. + - name: Display Tool Versions Report + shell: bash + run: | + echo "=== Tool Versions Report ===" + cat docs/build_notes/versions.md - - name: Generate Requirements Report, Justifications, and Trace Matrix + - name: Generate Build Notes HTML with Pandoc + shell: bash run: > - dotnet reqstream - --requirements requirements.yaml - --tests "artifacts/**/*.trx" - --report docs/requirements_doc/requirements.md - --justifications docs/requirements_doc/justifications.md - --matrix docs/requirements_report/trace_matrix.md - --enforce + dotnet pandoc + --defaults docs/build_notes/definition.yaml + --filter node_modules/.bin/mermaid-filter.cmd + --metadata version="${{ inputs.version }}" + --metadata date="$(date +'%Y-%m-%d')" + --output docs/build_notes/build_notes.html + + - name: Generate Build Notes PDF with WeasyPrint + run: > + dotnet weasyprint + --pdf-variant pdf/a-3u + docs/build_notes/build_notes.html + "docs/ReqStream Build Notes.pdf" + + - name: Assert Build Notes Documents with FileAssert + run: > + dotnet fileassert + --results artifacts/fileassert-build-notes.trx + build-notes + + # === COMPILE CODE QUALITY REPORT === + # This section generates the Code Quality document. SarifMark and SonarMark self-validations + # run here to co-locate their evidence with the document that depends on their output. + # Pandoc converts the markdown to HTML, WeasyPrint renders the HTML to PDF, and FileAssert + # validates the outputs contain expected content. + # Downstream projects: Add any additional code quality steps here. + + - name: Run SarifMark self-validation + run: > + dotnet sarifmark + --validate + --results artifacts/sarifmark-self-validation.trx + + - name: Run SonarMark self-validation + run: > + dotnet sonarmark + --validate + --results artifacts/sonarmark-self-validation.trx - name: Generate CodeQL Quality Report with SarifMark run: > @@ -518,6 +590,42 @@ jobs: echo "=== SonarCloud Quality Report ===" cat docs/code_quality/sonar-quality.md + - name: Generate Code Quality HTML with Pandoc + shell: bash + run: > + dotnet pandoc + --defaults docs/code_quality/definition.yaml + --filter node_modules/.bin/mermaid-filter.cmd + --metadata version="${{ inputs.version }}" + --metadata date="$(date +'%Y-%m-%d')" + --output docs/code_quality/quality.html + + - name: Generate Code Quality PDF with WeasyPrint + run: > + dotnet weasyprint + --pdf-variant pdf/a-3u + docs/code_quality/quality.html + "docs/ReqStream Code Quality.pdf" + + - name: Assert Code Quality Documents with FileAssert + run: > + dotnet fileassert + --results artifacts/fileassert-code-quality.trx + code-quality + + # === COMPILE CODE REVIEW === + # This section generates the Code Review Plan and Report documents. ReviewMark + # self-validation runs here to co-locate its evidence with the documents that depend + # on its output. Pandoc converts the markdown to HTML, WeasyPrint renders the HTML to + # PDF, and FileAssert validates the outputs contain expected content. + # Downstream projects: Add any additional code review steps here. + + - name: Run ReviewMark self-validation + run: > + dotnet reviewmark + --validate + --results artifacts/reviewmark-self-validation.trx + - name: Generate Review Plan and Review Report with ReviewMark shell: bash # TODO: Add --enforce once reviews branch is populated with review evidence PDFs and index.json @@ -540,179 +648,179 @@ jobs: echo "=== Review Report ===" cat docs/code_review_report/report.md - - name: Generate Build Notes with BuildMark - shell: bash - env: - GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} - run: > - dotnet buildmark - --build-version ${{ inputs.version }} - --report docs/build_notes.md - --report-depth 1 - - - name: Display Build Notes Report - shell: bash - run: | - echo "=== Build Notes Report ===" - cat docs/build_notes.md - - - name: Publish Tool Versions - shell: bash - run: | - echo "Publishing tool versions..." - dotnet versionmark --publish --report docs/build_notes/versions.md --report-depth 1 \ - -- "artifacts/**/versionmark-*.json" - echo "✓ Tool versions published" - - - name: Display Tool Versions Report - shell: bash - run: | - echo "=== Tool Versions Report ===" - cat docs/build_notes/versions.md - - # === GENERATE HTML DOCUMENTS WITH PANDOC === - # This section converts markdown documents to HTML using Pandoc. - # Downstream projects: Add any additional Pandoc HTML generation steps here. - - - name: Generate Build Notes HTML with Pandoc + - name: Generate Review Plan HTML with Pandoc shell: bash run: > dotnet pandoc - --defaults docs/build_notes/definition.yaml + --defaults docs/code_review_plan/definition.yaml --filter node_modules/.bin/mermaid-filter.cmd --metadata version="${{ inputs.version }}" --metadata date="$(date +'%Y-%m-%d')" - --output docs/build_notes/buildnotes.html + --output docs/code_review_plan/plan.html - - name: Generate Guide HTML with Pandoc - shell: bash + - name: Generate Review Plan PDF with WeasyPrint run: > - dotnet pandoc - --defaults docs/user_guide/definition.yaml - --filter node_modules/.bin/mermaid-filter.cmd - --metadata version="${{ inputs.version }}" - --metadata date="$(date +'%Y-%m-%d')" - --output docs/user_guide/introduction.html + dotnet weasyprint + --pdf-variant pdf/a-3u + docs/code_review_plan/plan.html + "docs/ReqStream Review Plan.pdf" - - name: Generate Code Quality HTML with Pandoc + - name: Generate Review Report HTML with Pandoc shell: bash run: > dotnet pandoc - --defaults docs/code_quality/definition.yaml + --defaults docs/code_review_report/definition.yaml --filter node_modules/.bin/mermaid-filter.cmd --metadata version="${{ inputs.version }}" --metadata date="$(date +'%Y-%m-%d')" - --output docs/code_quality/quality.html + --output docs/code_review_report/report.html - - name: Generate Requirements HTML with Pandoc - shell: bash + - name: Generate Review Report PDF with WeasyPrint run: > - dotnet pandoc - --defaults docs/requirements_doc/definition.yaml - --filter node_modules/.bin/mermaid-filter.cmd - --metadata version="${{ inputs.version }}" - --metadata date="$(date +'%Y-%m-%d')" - --output docs/requirements_doc/requirements.html + dotnet weasyprint + --pdf-variant pdf/a-3u + docs/code_review_report/report.html + "docs/ReqStream Review Report.pdf" - - name: Generate Trace Matrix HTML with Pandoc - shell: bash + - name: Assert Code Review Documents with FileAssert run: > - dotnet pandoc - --defaults docs/requirements_report/definition.yaml - --filter node_modules/.bin/mermaid-filter.cmd - --metadata version="${{ inputs.version }}" - --metadata date="$(date +'%Y-%m-%d')" - --output docs/requirements_report/trace_matrix.html + dotnet fileassert + --results artifacts/fileassert-code-review.trx + code-review - - name: Generate Review Plan HTML with Pandoc + # === COMPILE DESIGN DOCUMENT === + # This section generates the Design document using Pandoc and WeasyPrint. + # FileAssert validates that the HTML and PDF outputs contain expected content. + # Downstream projects: Add any additional design document steps here. + + - name: Generate Design HTML with Pandoc shell: bash run: > dotnet pandoc - --defaults docs/code_review_plan/definition.yaml + --defaults docs/design/definition.yaml --filter node_modules/.bin/mermaid-filter.cmd --metadata version="${{ inputs.version }}" --metadata date="$(date +'%Y-%m-%d')" - --output docs/code_review_plan/plan.html + --output docs/design/design.html - - name: Generate Review Report HTML with Pandoc - shell: bash + - name: Generate Design PDF with WeasyPrint run: > - dotnet pandoc - --defaults docs/code_review_report/definition.yaml - --filter node_modules/.bin/mermaid-filter.cmd - --metadata version="${{ inputs.version }}" - --metadata date="$(date +'%Y-%m-%d')" - --output docs/code_review_report/report.html + dotnet weasyprint + --pdf-variant pdf/a-3u + docs/design/design.html + "docs/ReqStream Software Design.pdf" - - name: Generate Design HTML with Pandoc + - name: Assert Design Documents with FileAssert + run: > + dotnet fileassert + --results artifacts/fileassert-design.trx + design + + # === COMPILE USER GUIDE === + # This section generates the User Guide document using Pandoc and WeasyPrint. + # FileAssert validates that the HTML and PDF outputs contain expected content. + # Downstream projects: Add any additional user guide steps here. + + - name: Generate User Guide HTML with Pandoc shell: bash run: > dotnet pandoc - --defaults docs/design/definition.yaml + --defaults docs/user_guide/definition.yaml --filter node_modules/.bin/mermaid-filter.cmd --metadata version="${{ inputs.version }}" --metadata date="$(date +'%Y-%m-%d')" - --output docs/design/design.html + --output docs/user_guide/user_guide.html - # === GENERATE PDF DOCUMENTS WITH WEASYPRINT === - # This section converts HTML documents to PDF using Weasyprint. - # Downstream projects: Add any additional Weasyprint PDF generation steps here. - - - name: Generate Build Notes PDF with Weasyprint + - name: Generate User Guide PDF with WeasyPrint run: > dotnet weasyprint --pdf-variant pdf/a-3u - docs/build_notes/buildnotes.html - "docs/ReqStream Build Notes.pdf" + docs/user_guide/user_guide.html + "docs/ReqStream User Guide.pdf" - - name: Generate Guide PDF with Weasyprint + - name: Assert User Guide Documents with FileAssert run: > - dotnet weasyprint - --pdf-variant pdf/a-3u - docs/user_guide/introduction.html - "docs/ReqStream User Guide.pdf" + dotnet fileassert + --results artifacts/fileassert-user-guide.trx + user-guide - - name: Generate Code Quality PDF with Weasyprint + # === FILEASSERT SELF-VALIDATION === + # By this point Pandoc and WeasyPrint have each produced 6 validated documents + # (Build Notes, Code Quality, Review Plan, Review Report, Design, User Guide), + # providing strong OTS evidence for both tools before ReqStream runs. FileAssert + # self-validation confirms the assertion tool itself is operational. + # Downstream projects: Add any additional FileAssert self-validation steps here. + + - name: Run FileAssert self-validation run: > - dotnet weasyprint - --pdf-variant pdf/a-3u - docs/code_quality/quality.html - "docs/ReqStream Code Quality.pdf" + dotnet fileassert + --validate + --results artifacts/fileassert-self-validation.trx + + # === COMPILE REQUIREMENTS AND TRACE MATRIX === + # This section generates the Requirements and Trace Matrix documents. ReqStream + # self-validation runs here, then ReqStream --enforce consumes all previously generated + # TRX evidence (including FileAssert results for Pandoc, WeasyPrint, and FileAssert OTS + # requirements). Pandoc and WeasyPrint compile the final documents, and FileAssert + # validates their outputs. These final assertions do not contribute to OTS evidence but + # confirm the requirements pipeline produced well-formed documents. + # Downstream projects: Add any additional requirements steps here. - - name: Generate Requirements PDF with Weasyprint + - name: Run ReqStream self-validation run: > - dotnet weasyprint - --pdf-variant pdf/a-3u - docs/requirements_doc/requirements.html - "docs/ReqStream Requirements.pdf" + dotnet reqstream + --validate + --results artifacts/reqstream-self-validation.trx - - name: Generate Trace Matrix PDF with Weasyprint + - name: Generate Requirements Report, Justifications, and Trace Matrix run: > - dotnet weasyprint - --pdf-variant pdf/a-3u - docs/requirements_report/trace_matrix.html - "docs/ReqStream Trace Matrix.pdf" + dotnet reqstream + --requirements requirements.yaml + --tests "artifacts/**/*.trx" + --report docs/requirements_doc/requirements.md + --justifications docs/requirements_doc/justifications.md + --matrix docs/requirements_report/trace_matrix.md + --enforce - - name: Generate Review Plan PDF with Weasyprint + - name: Generate Requirements HTML with Pandoc + shell: bash run: > - dotnet weasyprint - --pdf-variant pdf/a-3u - docs/code_review_plan/plan.html - "docs/ReqStream Review Plan.pdf" + dotnet pandoc + --defaults docs/requirements_doc/definition.yaml + --filter node_modules/.bin/mermaid-filter.cmd + --metadata version="${{ inputs.version }}" + --metadata date="$(date +'%Y-%m-%d')" + --output docs/requirements_doc/requirements.html - - name: Generate Review Report PDF with Weasyprint + - name: Generate Requirements PDF with WeasyPrint run: > dotnet weasyprint --pdf-variant pdf/a-3u - docs/code_review_report/report.html - "docs/ReqStream Review Report.pdf" + docs/requirements_doc/requirements.html + "docs/ReqStream Requirements.pdf" - - name: Generate Design PDF with Weasyprint + - name: Generate Trace Matrix HTML with Pandoc + shell: bash + run: > + dotnet pandoc + --defaults docs/requirements_report/definition.yaml + --filter node_modules/.bin/mermaid-filter.cmd + --metadata version="${{ inputs.version }}" + --metadata date="$(date +'%Y-%m-%d')" + --output docs/requirements_report/trace_matrix.html + + - name: Generate Trace Matrix PDF with WeasyPrint run: > dotnet weasyprint --pdf-variant pdf/a-3u - docs/design/design.html - "docs/ReqStream Design.pdf" + docs/requirements_report/trace_matrix.html + "docs/ReqStream Trace Matrix.pdf" + + - name: Assert Requirements Documents with FileAssert + run: > + dotnet fileassert + --results artifacts/fileassert-requirements.trx + requirements # === UPLOAD ARTIFACTS === # This section uploads all generated documentation artifacts. @@ -722,6 +830,6 @@ jobs: uses: actions/upload-artifact@v7 with: name: documents - path: | + path: |- docs/*.pdf docs/build_notes.md diff --git a/.github/workflows/build_on_push.yaml b/.github/workflows/build_on_push.yaml index d536b8e..344b21a 100644 --- a/.github/workflows/build_on_push.yaml +++ b/.github/workflows/build_on_push.yaml @@ -2,10 +2,10 @@ name: Build on Push on: - push: # On push to any branch - workflow_dispatch: # Allow manual trigger - schedule: # 5PM UTC every Monday - - cron: '0 17 * * 1' + push: + workflow_dispatch: + schedule: + - cron: '0 17 * * 1' # 5PM UTC every Monday jobs: build: diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index af09222..5d3adc2 100644 --- a/.github/workflows/release.yaml +++ b/.github/workflows/release.yaml @@ -68,13 +68,13 @@ jobs: uses: ncipollo/release-action@v1 with: tag: ${{ inputs.version }} - artifacts: artifacts/** + artifacts: artifacts/* bodyFile: artifacts/build_notes.md generateReleaseNotes: false - name: Publish to NuGet.org if: inputs.publish == 'publish' - run: | + run: |- set -e dotnet nuget push artifacts/*.nupkg \ --api-key ${{ secrets.DEMACONSULTINGNUGETKEY }} \ diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml index 4532ba3..c16c443 100644 --- a/.markdownlint-cli2.yaml +++ b/.markdownlint-cli2.yaml @@ -11,6 +11,7 @@ # - Do not relax rules to accommodate existing non-compliant files # - Consistency across repositories is critical for documentation quality +# Disable the banner message (e.g., version info) on stdout noBanner: true # Disable the progress indicator on stdout diff --git a/.reviewmark.yaml b/.reviewmark.yaml index a541de7..f1b935f 100644 --- a/.reviewmark.yaml +++ b/.reviewmark.yaml @@ -6,12 +6,12 @@ # Patterns identifying all files that require review. # Processed in order; prefix a pattern with '!' to exclude. needs-review: - - "requirements.yaml" # Root requirements file - - "README.md" # User-facing documentation + - "README.md" # Project readme - "**/*.cs" # All C# source and test files + - "requirements.yaml" # Root requirements file - "docs/reqstream/**/*.yaml" # Requirements files + - "docs/user_guide/**/*.md" # User guide documents - "docs/design/**/*.md" # Design documents - - "docs/user_guide/**/*.md" # User guide - "!**/obj/**" # Exclude build output - "!**/bin/**" # Exclude build output @@ -23,13 +23,7 @@ evidence-source: type: url location: https://raw.githubusercontent.com/demaconsulting/ReqStream/reviews/index.json -# Review sets following the standard hierarchy from reviewmark-usage.md: -# - Purpose (one per repo): user-facing capabilities and system promises -# - {System}-Architecture (one per system): system requirements and integration tests -# - {System}-Design (one per system): all design documentation -# - {System}-AllRequirements (one per system): all requirements for consistency review -# - {System}-{Subsystem} (one per subsystem): subsystem requirements and integration tests -# - {System}-{Subsystem}-{Unit} / {System}-{Unit} (one per unit): full unit artifact set +# Review sets following standardized patterns for hierarchical compliance coverage reviews: # ── Purpose Review ──────────────────────────────────────────────────────────── diff --git a/.versionmark.yaml b/.versionmark.yaml index 065c5ac..28387dc 100644 --- a/.versionmark.yaml +++ b/.versionmark.yaml @@ -68,3 +68,8 @@ tools: reviewmark: command: dotnet tool list regex: '(?i)demaconsulting\.reviewmark\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)' + + # FileAssert (DemaConsulting.FileAssert from dotnet tool list) + fileassert: + command: dotnet tool list + regex: '(?i)demaconsulting\.fileassert\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?)' diff --git a/.yamlfix.toml b/.yamlfix.toml new file mode 100644 index 0000000..233d73b --- /dev/null +++ b/.yamlfix.toml @@ -0,0 +1,16 @@ +# YAML Auto-Fix Configuration +# +# PURPOSE: +# - Configure yamlfix to auto-fix common YAML issues before yamllint checks +# - Settings MUST align with .yamllint.yaml to avoid conflicts +# - Use 'pwsh ./fix.ps1' or run 'yamlfix .' before 'pwsh ./lint.ps1' to auto-fix, then verify with yamllint +# +# RELATIONSHIP TO YAMLLINT: +# - line_length MUST match .yamllint.yaml line-length.max (120) +# - preserve_quotes prevents mangling GitHub Actions 'on:' boolean handling +# - After yamlfix auto-fix, yamllint should only fail on genuinely unresolvable issues + +line_length = 120 +preserve_quotes = true +sequence_style = "keep_style" +whitelines = 1 diff --git a/AGENTS.md b/AGENTS.md index f05c4e6..42e5acb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,12 +1,5 @@ -# Agent Quick Reference - -Comprehensive guidance for AI agents working on repositories following Continuous Compliance practices. - # Project Structure -The following is the basic folder structure of the project. Agents should use this information when searching for -existing files and to know where to make new files. - ```text ├── docs/ │ ├── build_notes/ @@ -16,113 +9,141 @@ existing files and to know where to make new files. │ ├── design/ │ ├── requirements_doc/ │ ├── requirements_report/ -│ ├── reqstream/ -│ └── user_guide/ +│ ├── user_guide/ +│ └── reqstream/ ├── src/ -│ └── {project}/ +│ └── DemaConsulting.ReqStream/ └── test/ - └── {test-project}/ + └── DemaConsulting.ReqStream.Tests/ ``` +# 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. + # Key Configuration Files - **`.config/dotnet-tools.json`** - Local tool manifest for Continuous Compliance tools - **`.editorconfig`** - Code formatting rules - **`.clang-format`** - C/C++ formatting (if applicable) - **`.cspell.yaml`** - Spell-check configuration and technical term dictionary -- **`.markdownlint-cli2.yaml`** - Markdown linting rules -- **`.yamllint.yaml`** - YAML linting configuration +- **`.markdownlint-cli2.yaml`** - Markdown formatting rules +- **`.yamllint.yaml`** - YAML formatting configuration - **`.reviewmark.yaml`** - File review definitions and tracking - **`nuget.config`** - NuGet package sources (if .NET) -- **`package.json`** - Node.js dependencies for linting tools +- **`package.json`** - Node.js dependencies for formatting tools - **`requirements.yaml`** - Root requirements file with includes -- **`pip-requirements.txt`** - Python dependencies for yamllint -- **`lint.sh` / `lint.bat`** - Cross-platform comprehensive linting scripts +- **`pip-requirements.txt`** - Python dependencies for yamllint and yamlfix +- **`fix.ps1`** - Applies all auto-fixers silently (dotnet format, markdown, YAML). Always exits 0. +- **`build.ps1`** - Builds the solution and runs all tests. # Standards Application (ALL Agents Must Follow) -Before performing any work, agents must read and apply the relevant standards from `.github/standards/`: +Before performing any work, agents must read and apply the relevant standards +from `.github/standards/`. Use this matrix to determine which to load: -- **`coding-principles.md`** - For universal coding standards (literate programming, architecture principles) -- **`testing-principles.md`** - For universal testing standards (dependency boundaries, AAA pattern) -- **`csharp-language.md`** - For C# code development (formatting, XML docs, C#-specific guidance) -- **`csharp-testing.md`** - For C# test development (AAA pattern, naming, MSTest anti-patterns) -- **`design-documentation.md`** - For design documentation (software structure diagrams, system.md, hierarchy) -- **`reqstream-usage.md`** - For requirements management (traceability, semantic IDs, source filters) -- **`reviewmark-usage.md`** - For file review management (review-sets, file patterns, enforcement) -- **`software-items.md`** - For software categorization (system/subsystem/unit/OTS classification) -- **`technical-documentation.md`** - For documentation creation and maintenance (structure, Pandoc, best practices) +| 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 | `software-items.md`, `reqstream-usage.md` | +| Design docs | `software-items.md`, `design-documentation.md`, `technical-documentation.md` | +| Review configuration | `software-items.md`, `reviewmark-usage.md` | +| Any documentation | `technical-documentation.md` | -Load only the standards relevant to your specific task scope and apply their -quality checks and guidelines throughout your work. +Load only the standards relevant to your specific task scope. # Agent Delegation Guidelines 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 -- **Light quality checking** (linting, basic validation) → Call the quality 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 -- **Formal reviews** (compliance verification, detailed analysis) → Call the code-review agent +- **Formal reviews** (compliance verification, detailed analysis) → Call the formal-review agent - **Template consistency** (downstream repository alignment) → Call the repo-consistency agent ## Available Specialized Agents +- **lint-fix** - Pre-PR lint sweep agent that loops running `pwsh ./lint.ps1`, + fixing issues until the repository is lint-clean - **developer** - General-purpose software development agent that applies appropriate standards based on the work being performed -- **code-review** - Agent for performing formal reviews using standardized review processes +- **formal-review** - Agent for performing formal reviews using standardized review processes - **implementation** - Orchestrator agent that manages quality implementations through a formal state machine workflow -- **quality** - Quality assurance agent that grades developer work against DEMA - Consulting standards and Continuous Compliance practices +- **quality** - Quality assurance agent that grades developer work against project + standards and Continuous Compliance practices - **repo-consistency** - Ensures downstream repositories remain consistent with the TemplateDotNetTool template patterns and best practices -# Linting (Required Before Quality Gates) +# Agent Reporting (Specialized Agents Must Follow) -1. **Markdown Auto-fix**: `npx markdownlint-cli2 --fix **/*.md` (fixes most markdown issues except line length) -2. **Dotnet Auto-fix**: `dotnet format` (reformats .NET languages) -3. **Run full check**: `lint.bat` (Windows) or `lint.sh` (Unix) -4. **Fix remaining**: Address line length, spelling, YAML syntax manually -5. **Verify clean**: Re-run until 0 errors before quality validation +Specialized agents (lint-fix, developer, quality, implementation, +formal-review, repo-consistency) MUST generate a completion report: -## Linting Tools (ALL Must Pass) +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 +3. Include the agent-specific report sections defined in each agent's prompt +4. Return the summary to the caller -- **markdownlint-cli2**: Markdown style and formatting enforcement -- **cspell**: Spell-checking across all text files (use `.cspell.yaml` for technical terms) -- **yamllint**: YAML structure and formatting validation -- **Language-specific linters**: Based on repository technology stack +Result semantics for orchestrator decision-making: -# Quality Gate Enforcement (ALL Agents Must Verify) +- **SUCCEEDED**: Work completed and all applicable quality gates 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) -Configuration files and scripts are self-documenting with their design intent and -modification policies in header comments. +# Formatting (After Making Changes) -1. **Build Quality**: Zero warnings (`TreatWarningsAsErrors=true`) -2. **Static Analysis**: SonarQube/CodeQL passing with no blockers -3. **Requirements Traceability**: `dotnet reqstream --enforce` passing -4. **Test Coverage**: All requirements linked to passing tests -5. **Documentation Currency**: All docs current and generated -6. **File Review Status**: All reviewable files have current reviews +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. -# Continuous Compliance Overview +```pwsh +pwsh ./fix.ps1 +``` -This repository follows the DEMA Consulting Continuous Compliance - approach, which enforces quality and -compliance gates on every CI/CD run instead of as a last-mile activity. +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. -## Core Principles +## CI Quality Tools -- **Requirements Traceability**: Every requirement MUST link to passing tests -- **Quality Gates**: All quality checks must pass before merge -- **Documentation Currency**: All docs auto-generated and kept current -- **Automated Evidence**: Full audit trail generated with every build +CI runs `lint.ps1` which checks: markdownlint-cli2, cspell, yamllint, dotnet format, +reqstream, versionmark, and reviewmark. -## Requirements & Compliance +# Scope Discipline (ALL Agents Must Follow) + +- **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 +- **No drive-by fixes**: If you discover pre-existing issues in files you are + reading but not modifying, document them in the report but do not fix them +- **Declare scope upfront**: Before making changes, determine which files will be + modified. Any file outside this scope requires explicit justification. + +# Protected Configuration Files + +These files contain carefully designed configuration with documented intent +in header comments. Agents MUST NOT modify them unless the task explicitly +requires it and the modification preserves the documented design intent: + +- `.reviewmark.yaml`, `.cspell.yaml`, `.editorconfig` +- `.markdownlint-cli2.yaml`, `.yamllint.yaml` +- `requirements.yaml`, `fix.ps1`, `lint.ps1` + +# Continuous Compliance Overview -- **ReqStream**: Requirements traceability enforcement (`dotnet reqstream --enforce`) -- **ReviewMark**: File review status enforcement -- **BuildMark**: Tool version documentation -- **VersionMark**: Version tracking across CI/CD jobs +This repository follows the [Continuous Compliance](https://github.com/demaconsulting/ContinuousCompliance) +approach. Tools: **ReqStream** (requirements traceability), **ReviewMark** (file review enforcement), +**BuildMark** (tool versions), **VersionMark** (version tracking). diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md deleted file mode 100644 index bd94217..0000000 --- a/ARCHITECTURE.md +++ /dev/null @@ -1,437 +0,0 @@ -# ReqStream Architecture - -This document describes the high-level architecture of ReqStream — the main building blocks, why they -exist, and how they relate to each other. - -## Overview - -ReqStream is a .NET command-line tool designed to manage requirements written in YAML files. It provides -three core capabilities: - -1. **Requirements Management**: Read, parse, and merge requirements from multiple YAML files into a - hierarchical structure -2. **Trace Matrix Construction**: Map test results (TRX and JUnit formats) to requirements for - traceability -3. **Test Coverage Enforcement**: Ensure all requirements have adequate test coverage as part of CI/CD - quality gates - -The tool is built with .NET 8.0+, uses YamlDotNet for YAML parsing, and follows a clear separation of -concerns with distinct classes for each major responsibility. - -### Components at a Glance - -| Component | File | Responsibility | -| --------- | ---- | -------------- | -| `Program` | `Program.cs` | Entry point; orchestrates the execution flow | -| `Context` | `Context.cs` | Parses CLI arguments; owns all options and output | -| `Requirements` | `Requirements.cs` | Reads, merges, and validates YAML requirement files | -| `TraceMatrix` | `TraceMatrix.cs` | Maps test results to requirements; calculates coverage | -| `Linter` | `Linter.cs` | Lints requirement YAML files and reports all structural issues | - -Two supporting value types live alongside `TraceMatrix`: - -- `TestMetrics` — aggregated pass/fail counts for a named test -- `TestExecution` — a single test result from one result file - -### How the Components Fit Together - -```mermaid -flowchart TD - yaml[YAML Files] - tests[Test Result Files] - args[CLI Arguments] - ctx[Context
options & output] - req[Requirements
parsed tree] - tm[TraceMatrix
coverage analysis] - lint[Linter
YAML structural checks] - reports[Markdown Reports
requirements · justifications · trace matrix] - exit[Exit Code
0 = pass · 1 = fail] - - yaml --> req - yaml --> lint - tests --> tm - args --> ctx - ctx --> req - ctx --> lint - req --> tm - tm --> reports - tm --> exit - lint --> exit -``` - -### Execution Flow at a Glance - -1. `--version` → print version and exit -2. Banner → printed for all remaining steps (`--help`, `--validate`, normal run) -3. `--help` → print usage and exit -4. `--validate` → run self-validation tests and exit -5. `--lint` → lint requirements files and exit -6. Normal run → read requirements → generate reports → enforce coverage - -Each step is described in detail in the [Program Execution Flow](#program-execution-flow) section. - -## Core Data Model - -### Requirement - -**Location**: `Requirement.cs` - -Represents a single requirement with its metadata. - -**Key Characteristics**: - -- `Id` must be unique across all requirements files -- `Title` must not be blank -- `Justification` is optional and explains why the requirement exists -- `Tests` lists test identifiers linked to this requirement (inline or via mappings) -- `Children` holds IDs of child requirements for hierarchical decomposition -- `Tags` are optional labels used for categorization and selective filtering - -### Section - -**Location**: `Section.cs` - -Container for requirements and child sections, enabling hierarchical organization. - -**Key Characteristics**: - -- Sections form a tree structure with arbitrary depth -- Section titles are used to match and merge sections across files -- Sections with identical titles at the same hierarchy level are merged - -### Requirements - -**Location**: `Requirements.cs` - -Root class that extends `Section` and manages YAML file loading and validation. - -**Key Responsibilities**: - -- Parse YAML files using YamlDotNet with hyphenated naming conventions -- Merge sections with identical hierarchy paths across multiple files -- Validate requirement IDs are unique and titles are non-blank -- Process file includes recursively with loop prevention -- Apply separate test mappings to the matching requirements -- Export requirements and justifications to Markdown reports - -### TraceMatrix - -**Location**: `TraceMatrix.cs` - -Maps test results to requirements and analyzes test coverage. - -**Key Responsibilities**: - -- Parse test result files in TRX and JUnit formats -- Aggregate test executions from multiple result files by test name -- Match test names to requirements (plain names vs. source-specific `file@testname`) -- Provide fast lookup of test metrics with optional source filtering -- Calculate requirement satisfaction, considering child requirement tests transitively -- Export trace matrix reports to Markdown - -### TestMetrics and TestExecution - -**Location**: `TraceMatrix.cs` - -`TestMetrics` is an immutable record of aggregated pass/fail counts for one test name. -`TestExecution` is an immutable record of results for one test name from one result file. - -**Key Characteristics**: - -- `TestMetrics(Passes, Fails)` exposes `Executed` (sum) and `AllPassed` (no failures, at least one run) -- `TestExecution` captures the file base name alongside `TestMetrics`, enabling source-specific filtering -- `GetTestResult` returns `TestMetrics(0, 0)` when the test name has no recorded executions -- Both types are used only as read-only value objects — they are never mutated after construction - -### Context - -**Location**: `Context.cs` - -Handles CLI argument parsing and owns all program-wide options and output. - -**Key Responsibilities**: - -- Parse command-line arguments and validate their values -- Expand glob patterns for requirements and test result files -- Parse `--filter` tags into a set used by all downstream operations -- Manage console and log file output through `WriteLine` / `WriteError` -- Track error state and surface the appropriate process exit code - -### Linter - -**Location**: `Linter.cs` - -Lints requirement YAML files and reports all structural issues found. - -**Key Responsibilities**: - -- Parse YAML files using YamlDotNet's representation model to retain position information -- Report unknown fields at document root, section, requirement, and mapping level -- Report missing required fields (`title` for sections; `id` and `title` for requirements; `id` for mappings) -- Report blank field values for `title`, `id`, and list entries (tests, tags) -- Detect and report duplicate requirement IDs across all files (including includes) -- Follow `includes:` directives recursively, deduplicating visited files -- Report **all** issues found rather than stopping at the first error -- Format errors as `{file}({line},{col}): error: {description}` -- Print a no-issues message when the files pass all checks - -## Requirements Processing Flow - -### 1. YAML File Parsing - -ReqStream uses **YamlDotNet** with the `HyphenatedNamingConvention` to deserialize YAML into internal -intermediate types (`YamlDocument`, `YamlSection`, `YamlRequirement`, `YamlMapping`). - -- Files are read as text and deserialized; empty or null documents are silently skipped -- File paths in `includes` are resolved relative to the current file's directory -- Validation errors (e.g., missing fields or invalid structure) surface the source file path for actionable error messages - -### 2. Section Merging - -Sections with **identical titles at the same hierarchy level** are merged across files, enabling -modular requirements spread over many files. - -- When a section from a new file matches an existing section by title, their requirements are combined -- Child sections are recursively merged by the same title-matching rule -- This allows teams to contribute to the same logical section from separate files - -### 3. Validation - -Requirements are validated during parsing to ensure data integrity: - -| Validation | Condition | Error | -| ---------- | --------- | ----- | -| Section Title | Must not be blank | `Section title cannot be blank` | -| Requirement ID | Must not be blank | `Requirement ID cannot be blank` | -| Requirement ID | Must be unique | `Duplicate requirement ID found: '{id}'` | -| Requirement Title | Must not be blank | `Requirement title cannot be blank` | -| Test Names | Must not be blank | `Test name cannot be blank` | -| Mapping ID | Must not be blank | `Mapping requirement ID cannot be blank` | - -Validation errors throw `InvalidOperationException` with file path context; they are caught in -`Program.Main` and reported to the user. - -### 4. Test Mappings - -Tests can be associated with requirements in two complementary ways: - -- **Inline tests** — listed directly under the requirement in YAML -- **Separate mappings** — listed in the file's `mappings` block and matched by requirement ID - -Both methods add entries to the same `Requirement.Tests` list. Mappings are applied after all sections -are processed. A mapping that references a non-existent requirement ID is silently ignored. - -### 5. File Includes - -The `includes` section of a YAML file triggers recursive processing of additional files. - -- Each file's absolute path is tracked; a file encountered a second time is silently skipped -- This prevents infinite include loops regardless of how deeply nested the include graph is -- Missing included files raise `FileNotFoundException` - -### 6. Child Requirements - -A requirement may list other requirement IDs in its `children` field, forming a hierarchy. - -- When evaluating satisfaction, tests from child requirements are collected transitively -- Child requirements can themselves have children (recursive traversal) -- Non-existent child IDs are ignored during satisfaction calculation -- Circular references are detected and rejected at load time (see - [How Circular Requirement References Are Prevented](#how-circular-requirement-references-are-prevented)) - -### 7. Tag Filtering - -Requirements can carry optional `tags` for categorization. - -- When `--filter` is specified, only requirements with at least one matching tag are included -- Tag matching uses OR logic — any matching tag is sufficient to include the requirement -- Filtering applies uniformly to requirements export, justifications export, trace matrix export, - satisfaction calculation, and enforcement -- When no filter is active, `Context.FilterTags` is `null` and all requirements are included - -## Trace Matrix Construction and Analysis - -### 1. Test Result File Parsing - -ReqStream supports two test result formats via the `DemaConsulting.TestResults.IO` library: - -- **TRX** — Visual Studio Test Results format -- **JUnit** — Java/XML test results format - -For each test result file, ReqStream uses `DemaConsulting.TestResults.IO.Serializer.Deserialize(content)` -to auto-detect the format and parse the results. If a file cannot be parsed, the underlying error is -wrapped in an `InvalidOperationException` that includes the file path. - -### 2. Test Name Matching - -ReqStream supports two test name formats, which determine how results are matched to requirements: - -**Plain test names** — aggregate results from all result files: - -```text -TestFeature_Valid_Passes -``` - -**Source-specific test names** — restrict matching to files whose base name contains the source part: - -```text -windows-latest@TestPlatform_Windows_Passes -ubuntu-latest@TestPlatform_Linux_Passes -``` - -The `source@testname` format is the mechanism that allows the same logical test to be run on multiple -platforms and tracked independently per platform. - -### 3. Requirement Satisfaction Calculation - -A requirement is **satisfied** if all of the following hold: - -| Criteria | Description | -| -------- | ----------- | -| Has tests | At least one test is mapped (directly or through children) | -| Tests found | All mapped tests exist in test result files | -| Tests executed | All mapped tests have `Executed > 0` | -| Tests passed | All mapped tests have `Passed == Executed` | - -A requirement is **unsatisfied** if any of the following apply: - -| Condition | Reason | -| --------- | ------ | -| No tests | Requirement has no tests and no children with tests | -| Test not found | A mapped test doesn't exist in any test result file | -| Test not executed | A mapped test has `Executed == 0` | -| Test failed | A mapped test has `Passed != Executed` | - -## Test Coverage Enforcement - -When `--enforce` is specified, ReqStream calculates requirement satisfaction after generating all -requested reports. If any requirements are unsatisfied, an error message listing each unsatisfied -requirement ID is written to stderr and the exit code is set to 1. Reports are always written before -enforcement results — this allows users to review the trace matrix even on a failing run. - -**Exit Code Behavior**: - -| Condition | Exit Code | Behavior | -| --------- | --------- | -------- | -| No errors | 0 | Success | -| Argument error | 1 | `ArgumentException` caught in `Main` | -| Enforcement failed | 1 | `Context.WriteError` sets internal error flag | -| Unexpected error | Exception | Printed and re-thrown for event logging | - -## Program Execution Flow - -### Priority Order - -```text -1. Version query (--version) - └─> Print version and exit - -2. Banner - └─> Print application banner (skipped if version was queried) - -3. Help (--help) - └─> Print usage information and exit - -4. Self-Validation (--validate) - └─> Run self-validation tests and exit - -5. Lint (--lint) - └─> Lint requirements files and exit - -6. Requirements Processing - ├─> Read and merge requirements files - ├─> Export requirements report (if --report specified) - ├─> Export justifications report (if --justifications specified) - ├─> Parse test result files (if --tests specified) - ├─> Export trace matrix (if --matrix specified) - └─> Enforce coverage (if --enforce specified) - -Note: When --filter is specified, tag filtering is applied to all exports and enforcement. -``` - -### Error Handling Patterns - -| Exception Type | Usage | Handling | -| -------------- | ----- | -------- | -| `ArgumentException` | Invalid command-line arguments | Caught in `Main`, error printed, exit code 1 | -| `InvalidOperationException` | Runtime errors during execution | Caught in `Main`, error printed, exit code 1 | -| Other exceptions | Unexpected errors | Printed and re-thrown for event logging | - -`ArgumentException` is thrown during `Context.Create`; `InvalidOperationException` during execution. -Output methods are only used after successful argument parsing. - -## Implementation Notes - -### Why Sections Are Merged by Matching Titles - -Title-based merging enables **modular requirements management** without any explicit namespace or import -declaration. Benefits: - -- Multiple files can contribute to the same logical section -- Requirements, mappings, and justifications can live in separate files owned by separate teams -- A repository can organize files by feature, component, or responsibility and still produce one - coherent requirement tree - -### How Infinite Include Loops Are Prevented - -The `Requirements` class maintains a `HashSet` of absolute file paths already processed -(`_includedFiles`). Before reading any file, the path is normalized to an absolute path; if it is -already in the set the file is silently skipped, otherwise it is added and processed. - -- Full-path normalization ensures aliases and relative paths resolve to the same entry -- Silent skipping allows the same utility mapping file to be safely referenced from multiple parents -- This prevents infinite recursion and stack overflow with no performance overhead - -### How Circular Requirement References Are Prevented - -Child requirement IDs can form circular chains (e.g., `REQ-A → REQ-B → REQ-C → REQ-A`). Without -detection these would cause infinite recursion during satisfaction analysis. - -`Requirements.Read()` calls `ValidateCycles()` immediately after all files are parsed, before any -downstream analysis begins. The method performs a **depth-first search (DFS)** over every requirement, -using three tracking structures: - -- **`visiting`** — requirement IDs on the current DFS stack; a node that appears here while being - recursed into indicates a back-edge and therefore a cycle -- **`path`** — the ordered sequence of IDs on the current DFS stack, used to build a human-readable - error message (`REQ-A -> REQ-B -> REQ-C -> REQ-A`) -- **`visited`** — IDs whose entire sub-tree has been confirmed cycle-free; these are skipped on future - encounters, keeping the overall check O(n) over all requirements - -Cycle detection runs once at load time before any analysis; a clear `InvalidOperationException` with -the full cycle path is thrown on detection. Because the guarantee is established at load time, -`TraceMatrix.CollectAllTests()` recurses through child requirements without its own cycle guard. - -### Design Decisions for Maintainability - -**Separation of Concerns**: - -- `Context` owns CLI argument handling and output; it never touches YAML or test results -- `Requirements` owns YAML parsing and merging; it never touches test results or reports -- `TraceMatrix` owns test result analysis; it receives an already-validated requirements tree -- `Program` owns execution flow; it delegates all work to the other three components - -**Immutable Data Structures**: - -- Properties prevent modification after construction; collections allow population during - construction but not replacement -- `TestMetrics` and `TestExecution` are immutable records - -**Error Context and Testability**: - -- Validation and parsing errors always include the source file path for actionable debugging -- Static factory methods (`Context.Create`, `Requirements.Read`) decouple construction from consumers -- Public satisfaction-calculation methods and clear parsing/analysis separation enable direct testing - -**Key Architectural Patterns**: - -- **Factory** — `Context.Create(args)` and `Requirements.Read(paths)` encapsulate object construction -- **Composite** — `Section` trees enable recursive traversal for export and satisfaction calculation -- **Strategy** — test result parsing tries TRX first, then JUnit; matching tries source-specific first, - then plain names -- **Disposable** — `Context` implements `IDisposable` for deterministic log file cleanup - ---- - -For questions or suggestions about this architecture document, please open an issue or submit a pull -request. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1de683a..a8fd30a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -202,7 +202,7 @@ spell-checking failure. Doing so defeats the purpose of spell-checking and reduc Before submitting a pull request, ensure all quality checks pass: -### 1. Build, Test, and Validate +### 1. Build and Test ```bash # Build the project @@ -210,20 +210,18 @@ dotnet build --configuration Release # Run unit tests dotnet test --configuration Release - -# Run self-validation tests -dotnet run --project src/DemaConsulting.ReqStream --configuration Release --framework net10.0 --no-build -- --validate ``` All tests must pass with zero warnings. ### 2. Linting -```bash -# Use the lint script which installs dependencies and runs all linters -./lint.sh # Linux/macOS (or: bash ./lint.sh) -cmd /c lint.bat # Windows (Command Prompt) -./lint.bat # Windows (PowerShell) +```pwsh +# After making changes: applies dotnet format, markdown, and YAML fixes silently +pwsh ./fix.ps1 + +# Before submitting a pull request: all linters must pass +pwsh ./lint.ps1 ``` ### 3. Code Coverage diff --git a/build.bat b/build.bat deleted file mode 100644 index 88b51d0..0000000 --- a/build.bat +++ /dev/null @@ -1,16 +0,0 @@ -@echo off -REM Build and test ReqStream (Windows) - -echo Building ReqStream... -dotnet build --configuration Release -if %errorlevel% neq 0 exit /b %errorlevel% - -echo Running unit tests... -dotnet test --configuration Release -if %errorlevel% neq 0 exit /b %errorlevel% - -echo Running self-validation... -dotnet run --project src/DemaConsulting.ReqStream --configuration Release --framework net10.0 --no-build -- --validate -if %errorlevel% neq 0 exit /b %errorlevel% - -echo Build, tests, and validation completed successfully! diff --git a/build.ps1 b/build.ps1 new file mode 100644 index 0000000..188d18f --- /dev/null +++ b/build.ps1 @@ -0,0 +1,29 @@ +# build.ps1 +# +# PURPOSE: +# Unified cross-platform build script (replaces build.bat and build.sh). +# Builds the solution in Release configuration and runs all unit tests. +# +# EXTENSION POINTS: +# Search for "[PROJECT-SPECIFIC]" comments to find the designated locations +# for adding project-specific build or test operations. +# +# MODIFICATION POLICY: +# Only modify this file to add project-specific operations at the designated +# [PROJECT-SPECIFIC] extension points. + +$ErrorActionPreference = 'Stop' + +Write-Host "Building project..." +dotnet build --configuration Release +if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } + +# [PROJECT-SPECIFIC] Add additional build steps here. + +Write-Host "Running unit tests..." +dotnet test --configuration Release +if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } + +# [PROJECT-SPECIFIC] Add additional test or post-build steps here. + +Write-Host "Build and tests completed successfully!" diff --git a/build.sh b/build.sh deleted file mode 100755 index be5a016..0000000 --- a/build.sh +++ /dev/null @@ -1,15 +0,0 @@ -#!/usr/bin/env bash -# Build and test ReqStream - -set -e # Exit on error - -echo "🔧 Building ReqStream..." -dotnet build --configuration Release - -echo "🧪 Running unit tests..." -dotnet test --configuration Release - -echo "✅ Running self-validation..." -dotnet run --project src/DemaConsulting.ReqStream --configuration Release --framework net10.0 --no-build -- --validate - -echo "✨ Build, tests, and validation completed successfully!" diff --git a/docs/build_notes/definition.yaml b/docs/build_notes/definition.yaml index 4aa8572..ff158c9 100644 --- a/docs/build_notes/definition.yaml +++ b/docs/build_notes/definition.yaml @@ -8,7 +8,6 @@ input-files: - docs/build_notes/introduction.md - docs/build_notes.md - docs/build_notes/versions.md - template: template.html table-of-contents: true diff --git a/docs/code_quality/title.txt b/docs/code_quality/title.txt index 86f9f72..dd02b0b 100644 --- a/docs/code_quality/title.txt +++ b/docs/code_quality/title.txt @@ -1,5 +1,5 @@ --- -title: ReqStream Tool +title: ReqStream Code Quality subtitle: Code Quality Report author: DEMA Consulting description: Code Quality Report for the ReqStream Tool for managing requirements in YAML format diff --git a/docs/design/definition.yaml b/docs/design/definition.yaml index 28ffc9b..2495529 100644 --- a/docs/design/definition.yaml +++ b/docs/design/definition.yaml @@ -21,7 +21,6 @@ input-files: - docs/design/reqstream/tracing/trace-matrix.md - docs/design/reqstream/self-test/self-test.md - docs/design/reqstream/self-test/validation.md - template: template.html table-of-contents: true diff --git a/docs/design/introduction.md b/docs/design/introduction.md index 6d0a4d7..2dcb1e7 100644 --- a/docs/design/introduction.md +++ b/docs/design/introduction.md @@ -107,10 +107,8 @@ Throughout this document: ## References -- [ReqStream Architecture][arch] -- [ReqStream User Guide][guide] +- [ReqStream System Design][arch] - [ReqStream Repository][repo] -[arch]: ../../ARCHITECTURE.md -[guide]: ../../README.md +[arch]: reqstream/reqstream.md [repo]: https://github.com/demaconsulting/ReqStream diff --git a/docs/design/reqstream/cli/cli.md b/docs/design/reqstream/cli/cli.md index 0587035..3b67b72 100644 --- a/docs/design/reqstream/cli/cli.md +++ b/docs/design/reqstream/cli/cli.md @@ -38,8 +38,8 @@ to all subsystems that need to produce output. ## References -- [ReqStream Architecture][arch] +- [ReqStream System Design][arch] - [ReqStream Repository][repo] -[arch]: ../../../../ARCHITECTURE.md +[arch]: ../reqstream.md [repo]: https://github.com/demaconsulting/ReqStream diff --git a/docs/design/reqstream/cli/context.md b/docs/design/reqstream/cli/context.md index 4d710a9..5350d75 100644 --- a/docs/design/reqstream/cli/context.md +++ b/docs/design/reqstream/cli/context.md @@ -99,8 +99,8 @@ via an early return path. ## References -- [ReqStream Architecture][arch] +- [ReqStream System Design][arch] - [ReqStream Repository][repo] -[arch]: ../../../../ARCHITECTURE.md +[arch]: ../reqstream.md [repo]: https://github.com/demaconsulting/ReqStream diff --git a/docs/design/reqstream/modeling/modeling.md b/docs/design/reqstream/modeling/modeling.md index bb8e9ed..385cc18 100644 --- a/docs/design/reqstream/modeling/modeling.md +++ b/docs/design/reqstream/modeling/modeling.md @@ -39,8 +39,8 @@ The `Modeling` subsystem exposes the following interface to the rest of the tool ## References -- [ReqStream Architecture][arch] +- [ReqStream System Design][arch] - [ReqStream Repository][repo] -[arch]: ../../../../ARCHITECTURE.md +[arch]: ../reqstream.md [repo]: https://github.com/demaconsulting/ReqStream diff --git a/docs/design/reqstream/modeling/requirements.md b/docs/design/reqstream/modeling/requirements.md index 71eb20d..9cdc03c 100644 --- a/docs/design/reqstream/modeling/requirements.md +++ b/docs/design/reqstream/modeling/requirements.md @@ -167,8 +167,8 @@ is `null` and `LoadResult.HasErrors` returns `true`. ## References -- [ReqStream Architecture][arch] +- [ReqStream System Design][arch] - [ReqStream Repository][repo] -[arch]: ../../../../ARCHITECTURE.md +[arch]: ../reqstream.md [repo]: https://github.com/demaconsulting/ReqStream diff --git a/docs/design/reqstream/program.md b/docs/design/reqstream/program.md index bc323eb..875a11e 100644 --- a/docs/design/reqstream/program.md +++ b/docs/design/reqstream/program.md @@ -110,8 +110,8 @@ internal error flag and eventually produces a non-zero exit code. ## References -- [ReqStream Architecture][arch] +- [ReqStream System Design][arch] - [ReqStream Repository][repo] -[arch]: ../../../ARCHITECTURE.md +[arch]: reqstream.md [repo]: https://github.com/demaconsulting/ReqStream diff --git a/docs/design/reqstream/reqstream.md b/docs/design/reqstream/reqstream.md index cee7e60..7ff93c0 100644 --- a/docs/design/reqstream/reqstream.md +++ b/docs/design/reqstream/reqstream.md @@ -95,10 +95,76 @@ so that the evidence can be fed back into ReqStream's own requirements enforceme | `Program` | `TraceMatrix` | `ProcessRequirements` | Loads test results and maps them to requirements | | `Validation` | `Program` | test methods | Invokes `Program.Run` to exercise the full pipeline | +## Component Interaction Diagram + +The following diagram shows the data flow between units during a standard requirements processing +invocation: + +```mermaid +flowchart TD + yaml[YAML Files] + tests[Test Result Files] + args[CLI Arguments] + ctx[Context
options & output] + req[Requirements.Load
parsed tree + lint issues] + tm[TraceMatrix
coverage analysis] + issues[Lint Issues
warnings · errors] + reports[Markdown Reports
requirements · justifications · trace matrix] + exit[Exit Code
0 = pass · 1 = fail] + + yaml --> req + tests --> tm + args --> ctx + ctx --> req + req --> tm + req --> issues + tm --> reports + tm --> exit + issues --> exit +``` + +## Design Decisions + +### Separation of Concerns + +Each unit owns a clearly bounded responsibility and never reaches across boundaries: + +- `Context` owns CLI argument handling and output; it never touches YAML or test results +- `Requirements` owns YAML parsing and merging; it never touches test results or reports +- `TraceMatrix` owns test result analysis; it receives an already-validated requirements tree +- `Program` owns execution flow; it delegates all work to the other units + +### Why Sections Are Merged by Title + +Title-based merging enables modular requirements management without any explicit namespace or import +declaration. Multiple files can contribute to the same logical section; requirements, mappings, and +justifications can live in separate files owned by separate teams. A repository can organize files +by feature, component, or responsibility and still produce one coherent requirement tree. + +### Immutable Data Structures + +Properties prevent modification after construction; collections allow population during construction +but not replacement. `TestMetrics` and `TestExecution` are immutable records. This removes an entire +class of concurrency and aliasing bugs and makes the data model easy to reason about. + +### Error Context and Testability + +Validation and parsing errors always include the source file path for actionable debugging. Static +factory methods (`Context.Create`, `Requirements.Load`) decouple construction from consumers. Public +satisfaction-calculation methods and clear parsing/analysis separation enable direct unit testing +without mocking or fixtures. + +### Key Architectural Patterns + +| Pattern | Usage | +| ------- | ----- | +| Factory | `Context.Create(args)` and `Requirements.Load(paths)` encapsulate object construction | +| Composite | `Section` trees enable recursive traversal for export and satisfaction calculation | +| Strategy | Test result parsing tries TRX first, then JUnit; name matching tries source-specific first, then plain | +| Disposable | `Context` implements `IDisposable` for deterministic log file cleanup | + ## References -- [ReqStream Architecture][arch] - [ReqStream Repository][repo] -[arch]: ../../../ARCHITECTURE.md [repo]: https://github.com/demaconsulting/ReqStream diff --git a/docs/design/reqstream/self-test/self-test.md b/docs/design/reqstream/self-test/self-test.md index c81b8db..5e3636d 100644 --- a/docs/design/reqstream/self-test/self-test.md +++ b/docs/design/reqstream/self-test/self-test.md @@ -35,8 +35,8 @@ The `SelfTest` subsystem exposes the following interface to the rest of the tool ## References -- [ReqStream Architecture][arch] +- [ReqStream System Design][arch] - [ReqStream Repository][repo] -[arch]: ../../../../ARCHITECTURE.md +[arch]: ../reqstream.md [repo]: https://github.com/demaconsulting/ReqStream diff --git a/docs/design/reqstream/self-test/validation.md b/docs/design/reqstream/self-test/validation.md index 920015e..237c38b 100644 --- a/docs/design/reqstream/self-test/validation.md +++ b/docs/design/reqstream/self-test/validation.md @@ -91,8 +91,8 @@ after the test completes, regardless of whether the test passes or fails. ## References -- [ReqStream Architecture][arch] +- [ReqStream System Design][arch] - [ReqStream Repository][repo] -[arch]: ../../../../ARCHITECTURE.md +[arch]: ../reqstream.md [repo]: https://github.com/demaconsulting/ReqStream diff --git a/docs/design/reqstream/tracing/trace-matrix.md b/docs/design/reqstream/tracing/trace-matrix.md index 6ea76d5..8268246 100644 --- a/docs/design/reqstream/tracing/trace-matrix.md +++ b/docs/design/reqstream/tracing/trace-matrix.md @@ -120,8 +120,8 @@ test. The heading depth for requirement IDs is controlled by `depth`. ## References -- [ReqStream Architecture][arch] +- [ReqStream System Design][arch] - [ReqStream Repository][repo] -[arch]: ../../../../ARCHITECTURE.md +[arch]: ../reqstream.md [repo]: https://github.com/demaconsulting/ReqStream diff --git a/docs/design/reqstream/tracing/tracing.md b/docs/design/reqstream/tracing/tracing.md index 8a76aef..ac37065 100644 --- a/docs/design/reqstream/tracing/tracing.md +++ b/docs/design/reqstream/tracing/tracing.md @@ -38,8 +38,8 @@ The `Tracing` subsystem exposes the following interface to the rest of the tool: ## References -- [ReqStream Architecture][arch] +- [ReqStream System Design][arch] - [ReqStream Repository][repo] -[arch]: ../../../../ARCHITECTURE.md +[arch]: ../reqstream.md [repo]: https://github.com/demaconsulting/ReqStream diff --git a/docs/reqstream/ots/buildmark.yaml b/docs/reqstream/ots/buildmark.yaml index 980e0e2..3946b7d 100644 --- a/docs/reqstream/ots/buildmark.yaml +++ b/docs/reqstream/ots/buildmark.yaml @@ -1,8 +1,12 @@ --- +# BuildMark OTS Software Requirements +# +# Requirements for the BuildMark build documentation tool functionality. + sections: - - title: ReqStream Requirements + - title: OTS Software Requirements sections: - - title: OTS Software + - title: BuildMark Requirements requirements: - id: ReqStream-OTS-BuildMark title: BuildMark shall generate build-notes documentation from GitHub Actions metadata. diff --git a/docs/reqstream/ots/fileassert.yaml b/docs/reqstream/ots/fileassert.yaml new file mode 100644 index 0000000..85f6065 --- /dev/null +++ b/docs/reqstream/ots/fileassert.yaml @@ -0,0 +1,22 @@ +--- +# FileAssert OTS Software Requirements +# +# Requirements for the FileAssert document assertion tool functionality. + +sections: + - title: OTS Software Requirements + sections: + - title: FileAssert Requirements + requirements: + - id: ReqStream-OTS-FileAssert + title: FileAssert shall validate generated documents against acceptance criteria. + justification: | + DemaConsulting.FileAssert validates HTML and PDF documents produced during the + build, asserting that each document exists, has a non-trivial size, is structurally + valid, and contains expected content. It provides OTS evidence for Pandoc and + WeasyPrint and independently confirms file assertion is functioning. Self-validation + proves the tool itself is operational before ReqStream consumes the results. + tags: [ots] + tests: + - FileAssert_VersionDisplay + - FileAssert_HelpDisplay diff --git a/docs/reqstream/ots/mstest.yaml b/docs/reqstream/ots/mstest.yaml index b13b734..6e12695 100644 --- a/docs/reqstream/ots/mstest.yaml +++ b/docs/reqstream/ots/mstest.yaml @@ -1,8 +1,12 @@ --- +# MSTest OTS Software Requirements +# +# Requirements for the MSTest testing framework functionality. + sections: - - title: ReqStream Requirements + - title: OTS Software Requirements sections: - - title: OTS Software + - title: MSTest Requirements requirements: - id: ReqStream-OTS-MSTest title: MSTest shall execute unit tests and report results. diff --git a/docs/reqstream/ots/pandoc.yaml b/docs/reqstream/ots/pandoc.yaml new file mode 100644 index 0000000..a4f9c6f --- /dev/null +++ b/docs/reqstream/ots/pandoc.yaml @@ -0,0 +1,26 @@ +--- +# Pandoc OTS Software Requirements +# +# Requirements for the Pandoc document conversion tool functionality. + +sections: + - title: OTS Software Requirements + sections: + - title: Pandoc Requirements + requirements: + - id: ReqStream-OTS-Pandoc + title: Pandoc shall convert Markdown documents to valid HTML. + justification: | + DemaConsulting.PandocTool converts Markdown source documents to HTML as part of the + documentation build pipeline. FileAssert validates that each generated HTML file + exists, has a non-trivial size, 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. + tags: [ots] + tests: + - Pandoc_BuildNotesHtml + - Pandoc_CodeQualityHtml + - Pandoc_ReviewPlanHtml + - Pandoc_ReviewReportHtml + - Pandoc_DesignHtml + - Pandoc_UserGuideHtml diff --git a/docs/reqstream/ots/sarifmark.yaml b/docs/reqstream/ots/sarifmark.yaml index 2c7cbdf..a57b5b9 100644 --- a/docs/reqstream/ots/sarifmark.yaml +++ b/docs/reqstream/ots/sarifmark.yaml @@ -1,8 +1,12 @@ --- +# SarifMark OTS Software Requirements +# +# Requirements for the SarifMark SARIF report processing tool functionality. + sections: - - title: ReqStream Requirements + - title: OTS Software Requirements sections: - - title: OTS Software + - title: SarifMark Requirements requirements: - id: ReqStream-OTS-SarifMark title: SarifMark shall convert CodeQL SARIF results into a markdown report. diff --git a/docs/reqstream/ots/sonarmark.yaml b/docs/reqstream/ots/sonarmark.yaml index 6be16ed..86fbc71 100644 --- a/docs/reqstream/ots/sonarmark.yaml +++ b/docs/reqstream/ots/sonarmark.yaml @@ -1,8 +1,12 @@ --- +# SonarMark OTS Software Requirements +# +# Requirements for the SonarMark quality reporting tool functionality. + sections: - - title: ReqStream Requirements + - title: OTS Software Requirements sections: - - title: OTS Software + - title: SonarMark Requirements requirements: - id: ReqStream-OTS-SonarMark title: SonarMark shall generate a SonarCloud quality report. diff --git a/docs/reqstream/ots/versionmark.yaml b/docs/reqstream/ots/versionmark.yaml index 1fadfeb..4121cfd 100644 --- a/docs/reqstream/ots/versionmark.yaml +++ b/docs/reqstream/ots/versionmark.yaml @@ -1,8 +1,12 @@ --- +# VersionMark OTS Software Requirements +# +# Requirements for the VersionMark version tracking tool functionality. + sections: - - title: ReqStream Requirements + - title: OTS Software Requirements sections: - - title: OTS Software + - title: VersionMark Requirements requirements: - id: ReqStream-OTS-VersionMark title: VersionMark shall publish captured tool-version information. diff --git a/docs/reqstream/ots/weasyprint.yaml b/docs/reqstream/ots/weasyprint.yaml new file mode 100644 index 0000000..65c2277 --- /dev/null +++ b/docs/reqstream/ots/weasyprint.yaml @@ -0,0 +1,26 @@ +--- +# WeasyPrint OTS Software Requirements +# +# Requirements for the WeasyPrint PDF generation tool functionality. + +sections: + - title: OTS Software Requirements + sections: + - title: WeasyPrint Requirements + requirements: + - id: ReqStream-OTS-WeasyPrint + title: WeasyPrint shall convert HTML documents to valid PDF. + justification: | + DemaConsulting.WeasyPrintTool converts HTML documents to PDF as part of the + documentation build pipeline. FileAssert validates that each generated PDF file + exists, has a non-trivial size, 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. + tags: [ots] + tests: + - WeasyPrint_BuildNotesPdf + - WeasyPrint_CodeQualityPdf + - WeasyPrint_ReviewPlanPdf + - WeasyPrint_ReviewReportPdf + - WeasyPrint_DesignPdf + - WeasyPrint_UserGuidePdf diff --git a/docs/reqstream/reqstream/platform-requirements.yaml b/docs/reqstream/reqstream/platform-requirements.yaml index b708a61..164522c 100644 --- a/docs/reqstream/reqstream/platform-requirements.yaml +++ b/docs/reqstream/reqstream/platform-requirements.yaml @@ -1,25 +1,3 @@ -# Source Filter Prefixes for Platform and Framework Requirements -# -# Test links can include a source filter prefix to restrict which test results count -# as evidence for a requirement. This is critical for platform and framework -# requirements - removing these filters invalidates the evidence-based proof. -# -# Source filter prefixes: -# windows@TestName - proves the test passed on a Windows platform -# ubuntu@TestName - proves the test passed on a Linux (Ubuntu) platform -# macos@TestName - proves the test passed on a macOS platform -# net8.0@TestName - proves the test passed under the .NET 8 target framework -# net9.0@TestName - proves the test passed under the .NET 9 target framework -# net10.0@TestName - proves the test passed under the .NET 10 target framework -# dotnet8.x@TestName - proves the self-validation test ran with .NET 8.x runtime -# dotnet9.x@TestName - proves the self-validation test ran with .NET 9.x runtime -# dotnet10.x@TestName - proves the self-validation test ran with .NET 10.x runtime -# -# NOTE: Running "reqstream --enforce" with only local test results (unit tests -# and local self-validation) is expected to show some unsatisfied requirements. -# Platform-specific requirements require test results from CI/CD runs across -# the full OS and runtime matrix. -# --- sections: - title: ReqStream Requirements diff --git a/fix.ps1 b/fix.ps1 new file mode 100644 index 0000000..6369087 --- /dev/null +++ b/fix.ps1 @@ -0,0 +1,111 @@ +# fix.ps1 +# +# PURPOSE: +# Applies all available auto-fixers with progress output. Always exits 0. +# Run this after making changes to automatically handle formatting +# so agents and developers do not need to respond to lint output. +# Handles: dotnet format, markdownlint, yamlfix, YAML line endings. +# +# EXTENSION POINTS: +# Search for "[PROJECT-SPECIFIC]" comments to find the designated locations +# for adding project-specific auto-fix operations. +# +# MODIFICATION POLICY: +# Only modify this file to add project-specific operations at the designated +# [PROJECT-SPECIFIC] extension points, or to update tool versions as needed. + +# ============================================================================== +# HELPER FUNCTIONS +# ============================================================================== + +function Get-VenvActivateScript { + if (Test-Path ".venv/Scripts/Activate.ps1") { return ".venv/Scripts/Activate.ps1" } # Windows + if (Test-Path ".venv/bin/Activate.ps1") { return ".venv/bin/Activate.ps1" } # Linux/macOS + return $null +} + +function Initialize-PythonVenv { + param([switch]$Silent) + + if (-not (Test-Path ".venv")) { + if ($Silent) { python -m venv .venv 2>$null } else { python -m venv .venv } + if ($LASTEXITCODE -ne 0) { return $false } + } + + $activateScript = Get-VenvActivateScript + if (-not $activateScript) { return $false } + if ($Silent) { & $activateScript 2>$null } else { & $activateScript } + if (-not (Get-Command deactivate -ErrorAction SilentlyContinue)) { return $false } + + $installSucceeded = $false + try { + if ($Silent) { + pip install -r pip-requirements.txt --quiet --disable-pip-version-check 2>$null + } else { + pip install -r pip-requirements.txt --quiet --disable-pip-version-check + } + $installSucceeded = $LASTEXITCODE -eq 0 + return $installSucceeded + } + finally { + if (-not $installSucceeded -and (Get-Command deactivate -ErrorAction SilentlyContinue)) { + deactivate 2>$null + } + } +} + +function Normalize-YamlLineEndings { + $utf8NoBom = New-Object System.Text.UTF8Encoding($false) + + Get-ChildItem -Recurse -Include "*.yaml", "*.yml" | + Where-Object { $_.FullName -notmatch '[/\\](\.git|node_modules|\.venv|thirdparty|third-party|3rd-party|\.agent-logs)[/\\]' } | + ForEach-Object { + $raw = [System.IO.File]::ReadAllText($_.FullName) + $fixed = $raw.Replace("`r`n", "`n") + if ($raw -ne $fixed) { + [System.IO.File]::WriteAllText($_.FullName, $fixed, $utf8NoBom) + } + } +} + +# ============================================================================== +# AUTO-FIX +# Applies all auto-fixers with progress output. Never fails — applies what it can and +# exits 0 so agents do not react to any output as a problem to solve. +# ============================================================================== + +# --- YAML Auto-Fix --- +Write-Host "Fixing: YAML..." +if (Initialize-PythonVenv -Silent) { + yamlfix . 2>$null + deactivate 2>$null +} +Normalize-YamlLineEndings + +# --- Markdown Auto-Fix --- +Write-Host "Fixing: markdown..." +$env:PUPPETEER_SKIP_DOWNLOAD = "true" +npm install --silent 2>$null +if ($LASTEXITCODE -eq 0) { + npx markdownlint-cli2 --fix "**/*.md" 2>$null +} + +# [PROJECT-SPECIFIC] Add additional auto-fixers here. +# Example (Prettier for TypeScript/JSON): +# npx prettier --write "src/**/*.{ts,json}" 2>$null + +# --- .NET Auto-Format --- +Write-Host "Fixing: dotnet format..." +$slnFiles = @(Get-ChildItem -Filter "*.sln" -ErrorAction SilentlyContinue) + + @(Get-ChildItem -Filter "*.slnx" -ErrorAction SilentlyContinue) +if ($slnFiles.Count -gt 0) { + dotnet format 2>$null +} + +# [PROJECT-SPECIFIC] Add additional language-specific auto-formatters here. +# Example (C/C++ with clang-format): +# Get-ChildItem -Recurse -Include "*.cpp","*.hpp","*.h" | +# ForEach-Object { clang-format -i $_.FullName } 2>$null + +Write-Host "Auto-fix complete." +exit 0 diff --git a/lint.bat b/lint.bat deleted file mode 100644 index f373b99..0000000 --- a/lint.bat +++ /dev/null @@ -1,100 +0,0 @@ -@echo off -setlocal - -REM Comprehensive Linting Script -REM -REM PURPOSE: -REM - Run ALL lint checks when executed (no options or modes) -REM - Output lint failures directly for agent parsing -REM - NO command-line arguments, pretty printing, or colorization -REM - Agents execute this script to identify files needing fixes - -set "LINT_ERROR=0" - -REM === PYTHON SECTION === - -REM Create python venv if necessary -if not exist ".venv\Scripts\activate.bat" python -m venv .venv -if errorlevel 1 goto abort_python - -REM Activate python venv -call .venv\Scripts\activate.bat -if errorlevel 1 goto abort_python - -REM Install python tools -pip install -r pip-requirements.txt --quiet --disable-pip-version-check -if errorlevel 1 goto abort_python - -REM Run yamllint -yamllint . -if errorlevel 1 set "LINT_ERROR=1" - -REM Section error handling -goto npm_section -:abort_python -set "LINT_ERROR=1" -:npm_section - -REM === NPM SECTION === - -REM Install npm dependencies -set "PUPPETEER_SKIP_DOWNLOAD=true" -call npm install --silent -if errorlevel 1 goto abort_npm - -REM Run cspell -call npx cspell --no-progress --no-color --quiet "**/*.{md,yaml,yml,json,cs,cpp,hpp,h,txt}" -if errorlevel 1 set "LINT_ERROR=1" - -REM Run markdownlint-cli2 -call npx markdownlint-cli2 "**/*.md" -if errorlevel 1 set "LINT_ERROR=1" - -REM Section error handling -goto dotnet_linting_section -:abort_npm -set "LINT_ERROR=1" -:dotnet_linting_section - -REM === DOTNET LINTING SECTION === - -REM Restore dotnet tools -dotnet tool restore > nul -if errorlevel 1 goto abort_dotnet_tools - -REM Run reqstream lint -dotnet reqstream --lint --requirements requirements.yaml -if errorlevel 1 set "LINT_ERROR=1" - -REM Run versionmark lint -dotnet versionmark --lint -if errorlevel 1 set "LINT_ERROR=1" - -REM Run reviewmark lint -dotnet reviewmark --lint -if errorlevel 1 set "LINT_ERROR=1" - -REM Section error handling -goto dotnet_format_section -:abort_dotnet_tools -set "LINT_ERROR=1" -:dotnet_format_section - -REM === DOTNET FORMATTING SECTION === - -REM Restore dotnet packages -dotnet restore > nul -if errorlevel 1 goto abort_dotnet_format - -REM Run dotnet format -dotnet format --verify-no-changes --no-restore -if errorlevel 1 set "LINT_ERROR=1" - -REM Section error handling -goto end -:abort_dotnet_format -set "LINT_ERROR=1" -:end - -REM Report result -exit /b %LINT_ERROR% diff --git a/lint.ps1 b/lint.ps1 new file mode 100644 index 0000000..e4d68ac --- /dev/null +++ b/lint.ps1 @@ -0,0 +1,145 @@ +# lint.ps1 +# +# PURPOSE: +# Runs all lint checks and reports failures. Exits 1 on error. +# Used by CI/CD as the merge gate and by the lint-fix agent +# during pre-PR cleanup. +# +# To auto-fix formatting issues, run fix.ps1 instead. +# +# EXTENSION POINTS: +# Search for "[PROJECT-SPECIFIC]" comments to find the designated locations +# for adding project-specific lint checks. +# +# MODIFICATION POLICY: +# Only modify this file to add project-specific operations at the designated +# [PROJECT-SPECIFIC] extension points, or to update tool versions as needed. + +# ============================================================================== +# HELPER FUNCTIONS +# ============================================================================== + +function Get-VenvActivateScript { + if (Test-Path ".venv/Scripts/Activate.ps1") { return ".venv/Scripts/Activate.ps1" } # Windows + if (Test-Path ".venv/bin/Activate.ps1") { return ".venv/bin/Activate.ps1" } # Linux/macOS + return $null +} + +function Initialize-PythonVenv { + if (-not (Test-Path ".venv")) { + python -m venv .venv + if ($LASTEXITCODE -ne 0) { return $false } + } + + $activateScript = Get-VenvActivateScript + if (-not $activateScript) { return $false } + & $activateScript + if (-not (Get-Command deactivate -ErrorAction SilentlyContinue)) { return $false } + + $installSucceeded = $false + try { + pip install -r pip-requirements.txt --quiet --disable-pip-version-check + $installSucceeded = $LASTEXITCODE -eq 0 + return $installSucceeded + } + finally { + if (-not $installSucceeded -and (Get-Command deactivate -ErrorAction SilentlyContinue)) { + deactivate 2>$null + } + } +} + +# ============================================================================== +# LINT CHECKS +# Runs all lint checks. Exits 1 if any check fails. +# ============================================================================== + +$lintError = $false + +# --- PYTHON SECTION --- +# Sets up a virtual environment and runs yamllint. +Write-Host "Linting: YAML..." +$skipPython = -not (Initialize-PythonVenv) +if ($skipPython) { $lintError = $true } + +if (-not $skipPython) { + yamllint . + if ($LASTEXITCODE -ne 0) { $lintError = $true } + deactivate +} + +# [PROJECT-SPECIFIC] Add additional Python-based lint checks here. +# Example: +# if (-not $skipPython) { +# flake8 src/ +# if ($LASTEXITCODE -ne 0) { $lintError = $true } +# } + +# --- NPM SECTION --- +# Installs npm dependencies and runs cspell and markdownlint-cli2. +Write-Host "Linting: spelling and markdown..." +$skipNpm = $false +$env:PUPPETEER_SKIP_DOWNLOAD = "true" +npm install --silent +if ($LASTEXITCODE -ne 0) { $lintError = $true; $skipNpm = $true } + +if (-not $skipNpm) { + npx cspell --no-progress --no-color --quiet "**/*.{md,yaml,yml,json,cs,cpp,hpp,h,txt}" + if ($LASTEXITCODE -ne 0) { $lintError = $true } + + npx markdownlint-cli2 "**/*.md" + if ($LASTEXITCODE -ne 0) { $lintError = $true } +} + +# [PROJECT-SPECIFIC] Add additional npm-based lint checks here. +# Example (ESLint for TypeScript): +# if (-not $skipNpm) { +# npx eslint "src/**/*.ts" +# if ($LASTEXITCODE -ne 0) { $lintError = $true } +# } + +# --- DOTNET LINTING SECTION --- +# Runs compliance tools: reqstream, versionmark, reviewmark. +Write-Host "Linting: compliance tools..." +$skipDotnetTools = $false +dotnet tool restore > $null +if ($LASTEXITCODE -ne 0) { $lintError = $true; $skipDotnetTools = $true } + +if (-not $skipDotnetTools) { + dotnet reqstream --lint --requirements requirements.yaml + if ($LASTEXITCODE -ne 0) { $lintError = $true } + + dotnet versionmark --lint + if ($LASTEXITCODE -ne 0) { $lintError = $true } + + dotnet reviewmark --lint + if ($LASTEXITCODE -ne 0) { $lintError = $true } +} + +# [PROJECT-SPECIFIC] Add additional dotnet tool lint checks here. +# Example: +# if (-not $skipDotnetTools) { +# dotnet custom-tool --lint +# if ($LASTEXITCODE -ne 0) { $lintError = $true } +# } + +# --- DOTNET FORMATTING SECTION --- +# Verifies C# code formatting matches .editorconfig rules. +Write-Host "Linting: dotnet format..." +$skipDotnetFormat = $false +dotnet restore > $null +if ($LASTEXITCODE -ne 0) { $lintError = $true; $skipDotnetFormat = $true } + +if (-not $skipDotnetFormat) { + dotnet format --verify-no-changes --no-restore + if ($LASTEXITCODE -ne 0) { $lintError = $true } +} + +# [PROJECT-SPECIFIC] Add additional format verification checks here. +# Example (clang-format check for C/C++): +# Get-ChildItem -Recurse -Include "*.cpp","*.hpp","*.h" | ForEach-Object { +# $result = clang-format --dry-run --Werror $_.FullName 2>&1 +# if ($LASTEXITCODE -ne 0) { Write-Output $result; $lintError = $true } +# } + +exit ($lintError ? 1 : 0) diff --git a/lint.sh b/lint.sh deleted file mode 100755 index 4588497..0000000 --- a/lint.sh +++ /dev/null @@ -1,82 +0,0 @@ -#!/bin/bash - -# Comprehensive Linting Script -# -# PURPOSE: -# - Run ALL lint checks when executed (no options or modes) -# - Output lint failures directly for agent parsing -# - NO command-line arguments, pretty printing, or colorization -# - Agents execute this script to identify files needing fixes - -lint_error=0 - -# === PYTHON SECTION === - -# Create python venv if necessary -if [ ! -d ".venv" ]; then - python -m venv .venv || { lint_error=1; skip_python=1; } -fi - -# Activate python venv -if [ "$skip_python" != "1" ]; then - source .venv/bin/activate || { lint_error=1; skip_python=1; } -fi - -# Install python tools -if [ "$skip_python" != "1" ]; then - pip install -r pip-requirements.txt --quiet --disable-pip-version-check || { lint_error=1; skip_python=1; } -fi - -# Run yamllint -if [ "$skip_python" != "1" ]; then - yamllint . || lint_error=1 -fi - -# === NPM SECTION === - -# Install npm dependencies -export PUPPETEER_SKIP_DOWNLOAD=true -npm install --silent || { lint_error=1; skip_npm=1; } - -# Run cspell -if [ "$skip_npm" != "1" ]; then - npx cspell --no-progress --no-color --quiet "**/*.{md,yaml,yml,json,cs,cpp,hpp,h,txt}" || lint_error=1 -fi - -# Run markdownlint-cli2 -if [ "$skip_npm" != "1" ]; then - npx markdownlint-cli2 "**/*.md" || lint_error=1 -fi - -# === DOTNET LINTING SECTION === - -# Restore dotnet tools -dotnet tool restore > /dev/null || { lint_error=1; skip_dotnet_tools=1; } - -# Run reqstream lint -if [ "$skip_dotnet_tools" != "1" ]; then - dotnet reqstream --lint --requirements requirements.yaml || lint_error=1 -fi - -# Run versionmark lint -if [ "$skip_dotnet_tools" != "1" ]; then - dotnet versionmark --lint || lint_error=1 -fi - -# Run reviewmark lint -if [ "$skip_dotnet_tools" != "1" ]; then - dotnet reviewmark --lint || lint_error=1 -fi - -# === DOTNET FORMATTING SECTION === - -# Restore dotnet packages -dotnet restore > /dev/null || { lint_error=1; skip_dotnet_format=1; } - -# Run dotnet format -if [ "$skip_dotnet_format" != "1" ]; then - dotnet format --verify-no-changes --no-restore || lint_error=1 -fi - -# Report result -exit $lint_error diff --git a/pip-requirements.txt b/pip-requirements.txt index 7ce0eab..8fb8a08 100644 --- a/pip-requirements.txt +++ b/pip-requirements.txt @@ -1 +1,2 @@ yamllint==1.38.0 +yamlfix==1.19.1 diff --git a/requirements.yaml b/requirements.yaml index a3bf9b7..c54a56c 100644 --- a/requirements.yaml +++ b/requirements.yaml @@ -24,3 +24,6 @@ includes: - docs/reqstream/ots/sarifmark.yaml - docs/reqstream/ots/sonarmark.yaml - docs/reqstream/ots/reviewmark.yaml + - docs/reqstream/ots/pandoc.yaml + - docs/reqstream/ots/weasyprint.yaml + - docs/reqstream/ots/fileassert.yaml