Sync DEMA agent definitions and update documentation standards#164
Merged
Conversation
Sync the .github/agents agent definitions and AGENTS.md with the latest DEMA Agents template, and add the new planning agent. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Bring all tracked files in line with the latest canonical DEMA template: - docs/design/introduction.md: convert Software Structure section from ASCII code-block tree to bullet-list with (System)/(Subsystem)/(Unit)/(OTS) labels - docs/design/ots.md: rename title, add Selection Criteria, Version Management Policy, General Integration Approach, Qualification Strategy - docs/design/ots/*.md: remove ' Integration Design' suffix from headings - docs/design/test-results-library/io/*.md: promote headings from ### to ## - docs/verification/ots.md: rename title and headings, add Qualification Evidence and Regression Approach sections - docs/verification/ots/*.md: remove ' Verification' suffix from headings - .fileassert.yaml: add verification tag and Pandoc/WeasyPrint verification document tests - fix.ps1, lint.ps1: add MODIFICATION POLICY comment blocks Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Add docs/verification/**/*.md to needs-review patterns - Add verification introduction and system verification docs to TestResults-Architecture review set per standard - Add new TestResults-Verification review set covering verification introduction, ots.md, system and subsystem verification docs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Follow the commenting style used across DEMA repositories:
- '# Purpose' before the Purpose review
- '# TestResults - Specials' before system-level reviews
- '# TestResults - {Name}' before each unit/subsystem group
- '# OTS Items' before OTS reviews
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The previous template-sync fix incorrectly promoted these headings from ### to ##. Per the technical-documentation standard, files two subfolders deep under the collection root must use ### as their top-level heading. Restored the original ### depth for all four io/ unit design files. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Fixes based on formal review of all 24 review-sets: README and system design: - Remove Continuous Compliance from library feature list - Add supported target frameworks (.NET Standard 2.0, 8, 9, 10) to design - Clarify Dependencies section to distinguish runtime vs CI tooling OTS items Verification docs: - Fix stale requirement IDs in test-result.md and test-results.md - Add IdentifyFormat verification scenario to system-level verification IO subsystem: - Move round-trip requirement from Serializer unit to IO subsystem (io.yaml) - Update Serializer design to position round-trip as subsystem-level guarantee - Add complete JUnit outcome mapping table (all 14 TestOutcome values) - Fix obsolete requirement ID references in SerializerTests.cs OTS documentation: - BuildMark: fix GITHUB_TOKEN -> GH_TOKEN; improve acceptance criteria; fix stale req ID - SarifMark: add enforcement requirement; add to acceptance criteria - SonarMark: remove unsupported metrics claim - FileAssert: fix --tags -> positional args syntax - WeasyPrint: add Requirements and TraceMatrix PDF coverage - ReqStream: split compound requirement into 5 atomic requirements - ReviewMark: split compound requirement into 5; add --lint req/design/verification - Pandoc: add template/TOC/numbered-sections requirements and verification Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Wrap four bullet-list lines exceeding 120-character limit - Fix British spelling 'organisation' -> 'organization' Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
WeasyPrint_RequirementsPdf and WeasyPrint_TraceMatrixPdf run after ReqStream in the CI pipeline and cannot be used as test evidence for the requirement at publishing time (temporal paradox). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This pull request updates the repository’s agent orchestration definitions and compliance documentation to strengthen planning/traceability expectations (including explicit verification documentation handling) and extends the documentation pipeline’s FileAssert coverage to include verification document outputs.
Changes:
- Added a dedicated
planningagent and updated orchestration/reporting templates across agents to standardize report metadata and improve companion artifact traceability. - Expanded verification, design, and ReqStream requirements documentation (notably for OTS tools) and updated review-set coverage to include verification artifacts.
- Extended
.fileassert.yamlchecks to validate verification HTML/PDF structure and metadata.
Reviewed changes
Copilot reviewed 52 out of 52 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| test/DemaConsulting.TestResults.Tests/IO/SerializerTests.cs | Updated requirement references in serializer round-trip test remarks. |
| README.md | Adjusted feature list messaging. |
| lint.ps1 | Clarified lint script purpose and modification policy (comments only). |
| fix.ps1 | Clarified fix script purpose and modification policy (comments only). |
| docs/verification/test-results-library/test-results.md | Updated requirement IDs/scenario mapping for TestResults. |
| docs/verification/test-results-library/test-result.md | Updated requirement IDs/scenario mapping for TestResult. |
| docs/verification/test-results-library.md | Added IdentifyFormat verification scenario. |
| docs/verification/ots/xunit.md | Standardized heading. |
| docs/verification/ots/weasyprint.md | Expanded/adjusted WeasyPrint verification narrative and scenarios. |
| docs/verification/ots/versionmark.md | Standardized heading. |
| docs/verification/ots/sonarmark.md | Standardized heading. |
| docs/verification/ots/sarifmark.md | Standardized heading and clarified enforcement evidence. |
| docs/verification/ots/reviewmark.md | Standardized heading and expanded scenarios/acceptance criteria. |
| docs/verification/ots/reqstream.md | Standardized heading and refined requirement-to-evidence language. |
| docs/verification/ots/pandoc.md | Expanded Pandoc verification to include structural behaviors (TOC/numbering/template). |
| docs/verification/ots/fileassert.md | Standardized heading. |
| docs/verification/ots/buildmark.md | Standardized heading and refined acceptance criteria. |
| docs/verification/ots/apimark.md | Standardized heading. |
| docs/verification/ots.md | Expanded OTS verification strategy and evidence categories. |
| docs/reqstream/test-results-library/io/serializer.yaml | Removed round-trip requirement from Serializer unit requirements. |
| docs/reqstream/test-results-library/io.yaml | Moved round-trip requirement to IO subsystem level. |
| docs/reqstream/ots/weasyprint.yaml | Updated WeasyPrint OTS requirement evidence list. |
| docs/reqstream/ots/sarifmark.yaml | Added SarifMark enforcement requirement. |
| docs/reqstream/ots/reviewmark.yaml | Expanded ReviewMark requirements (index scan, working-dir, enforce, lint, etc.). |
| docs/reqstream/ots/reqstream.yaml | Split ReqStream OTS requirement into multiple focused requirements. |
| docs/reqstream/ots/pandoc.yaml | Added Pandoc structural requirements (template/TOC/number-sections). |
| docs/design/test-results-library/io/serializer.md | Clarified Serializer’s role in round-trip fidelity (dispatch vs subsystem behavior). |
| docs/design/test-results-library/io/junit-serializer.md | Added detailed JUnit outcome-mapping table and fidelity notes. |
| docs/design/test-results-library.md | Clarified OTS documentation separation and updated constraints/targets text. |
| docs/design/ots/xunit.md | Standardized heading. |
| docs/design/ots/weasyprint.md | Standardized heading. |
| docs/design/ots/versionmark.md | Standardized heading. |
| docs/design/ots/sonarmark.md | Standardized heading and clarified SonarMark output scope. |
| docs/design/ots/sarifmark.md | Standardized heading. |
| docs/design/ots/reviewmark.md | Documented ReviewMark --lint integration behavior. |
| docs/design/ots/reqstream.md | Standardized heading. |
| docs/design/ots/pandoc.md | Standardized heading. |
| docs/design/ots/fileassert.md | Updated FileAssert CLI usage description (positional tags). |
| docs/design/ots/buildmark.md | Updated BuildMark token/env var documentation. |
| docs/design/ots/apimark.md | Standardized heading. |
| docs/design/ots.md | Expanded OTS selection/version management/qualification strategy documentation. |
| docs/design/introduction.md | Reformatted software structure overview and enumerated OTS dependencies. |
| AGENTS.md | Updated delegation guidance and reporting/result semantics; standardized template URL key. |
| .reviewmark.yaml | Included verification docs in needs-review and added/expanded review sets. |
| .github/agents/template-sync.agent.md | Updated grouping/orchestration rules and report template. |
| .github/agents/quality.agent.md | Expanded evaluation criteria to require verification docs and cross-check planning artifact table. |
| .github/agents/planning.agent.md | Added new planning agent definition and report template. |
| .github/agents/lint-fix.agent.md | Standardized report metadata fields. |
| .github/agents/implementation.agent.md | Switched planning phase to the new planning agent and updated reporting fields. |
| .github/agents/formal-review.agent.md | Standardized report metadata fields. |
| .github/agents/developer.agent.md | Expanded companion artifact expectations and standardized report metadata fields. |
| .fileassert.yaml | Added verification document HTML/PDF assertions and strengthened design HTML structure assertions. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Update stale 'eight' counts to reflect that only 6 tests are linked in the OTS requirement. RequirementsPdf and TraceMatrixPdf run after ReqStream and cannot be requirement evidence (temporal dependency). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Corrects the documentation to reflect that FileAssert validates all 9 Pandoc HTML and 9 WeasyPrint PDF outputs serving two distinct purposes: build guards (all 9) and requirements evidence (7 pre-ReqStream only). - pandoc.yaml: add Pandoc_VerificationHtml to TestResults-OTS-Pandoc; comment out RequirementsHtml/TraceMatrixHtml with temporal paradox note - weasyprint.yaml: add WeasyPrint_VerificationPdf (was missing) - verification/ots/pandoc.md: explain dual role, update counts (9/7/2), add scenarios for Verification, Requirements, and TraceMatrix HTML - verification/ots/weasyprint.md: explain dual role, update counts (9/7/2), add Verification PDF scenario, clarify Requirements/TraceMatrix as build guards excluded from requirement tracing Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This was referenced Jul 6, 2026
1 task
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request introduces significant enhancements and clarifications to the agent orchestration and quality assurance process, with a strong focus on explicit handling of verification documentation, improved companion artifact traceability, and clearer agent reporting conventions. The most important changes include the addition of a dedicated planning agent, expanded requirements for verification documentation, and updates to agent report templates and orchestration logic.
Agent orchestration and planning improvements:
planningagent (.github/agents/planning.agent.md) that investigates the codebase, develops a verified implementation plan, and explicitly identifies all companion artifact deliverables, including requirements, design, verification, tests, review sets, README, and user guides. The agent outputs a detailed report and a lean summary for orchestration.implementationagent to invoke the newplanningagent (instead of the previousexploreagent) as a sub-agent for the planning phase, and to pass the planning companion artifact table to the quality agent for improved traceability. The implementation report template now references the planning report file and includes a dedicated section for unknowns when the result is INCOMPLETE. [1] [2] [3] [4] [5]Quality and verification documentation requirements:
Test and validation improvements:
.fileassert.yamltests to verify generation and content of verification HTML and PDF documents, ensuring that verification artifacts are present and correctly structured in the documentation build. [1] [2] [3]Agent report and documentation conventions:
**Report**field with the path to the generated report file for developer, implementation, planning, quality, formal review, and lint-fix agents. [1] [2] [3]Companion artifact handling and template sync logic: