Update documentation, address review findings, and refine requirements

[Malcolmnixon]

This pull request introduces significant improvements and clarifications to the orchestration and reporting standards for all software development agents, and adds a new, formalized planning agent. The changes focus on making artifact deliverables and reporting more explicit, strengthening traceability, and improving the structure and clarity of agent interactions and outputs.

Key changes include:

Addition of Planning Agent

• Introduced a new planning agent (.github/agents/planning.agent.md) that formalizes the process for investigating the codebase, developing a verified implementation plan, identifying all required companion artifacts, and assessing assumptions, risks, and feasibility. The agent produces a structured plan and report, enhancing traceability and handoff to development and quality agents.

Enhanced Companion Artifact Requirements and Traceability

• Expanded the list of required companion artifacts for code changes to include verification docs, README, and user guides, and clarified when each is mandatory. These requirements are now consistently referenced across developer, planning, and quality agents. [1] [2] [3]
• Quality agent now cross-references the planning agent’s companion artifact table to ensure all required artifacts are produced, failing if any are missing.

Improved Reporting Structure and Clarity

• All major agents now explicitly include a Report field in their output, specifying the path to the detailed markdown report in .agent-logs/. This applies to developer, planning, implementation, formal-review, lint-fix, quality, and template-sync agents. [1] [2] [3] [4] [5] [6]
• Implementation and template-sync agents now include explicit sections for unknowns/unresolved questions when the result is INCOMPLETE, improving user feedback and next steps. [1] [2]

Orchestration and State Machine Refinements

• The implementation agent now uses the new planning agent as a sub-agent, with updated state transitions and clearer handling of planning results (SUCCEEDED/INCOMPLETE/FAILED). The planning phase is now more robust, with explicit reference to the planning report for full details. [1] [2] [3]
• Template-sync agent orchestration was clarified: sub-agent selection is now mode-dependent, and the results for each file include unresolved questions, which are surfaced to the user and must be resolved before proceeding. [1] [2] [3]

Quality and Compliance Assessment Improvements

• Quality agent’s checklist and compliance sections were updated to explicitly include verification documentation, forward traceability from requirements to verification, and clearer N/A criteria for documentation and review sets. [1] [2]

These changes together improve rigor, transparency, and developer experience in the agent-based development workflow.

---

References:

• Planning agent addition and structure:
• Companion artifact requirements and traceability: [1] [2] [3]
• Reporting structure improvements: [1] [2] [3] [4] [5] [6]
• Orchestration and state machine: [1] [2] [3] [4] [5] [6]
• Quality and compliance assessment: [1] [2]

[Copilot]

Pull request overview

This pull request strengthens SarifMark’s compliance artifacts (requirements/design/verification), expands and refines test coverage around CLI validation and report generation, and updates the repository’s agent and standards documentation (including a new formal planning agent) to make deliverables and reporting more explicit.

Changes:

• Adds a new .github/agents/planning.agent.md and updates agent orchestration/reporting standards across other agents.
• Tightens CLI depth validation (1–6) and improves SARIF read error messaging, with corresponding new/updated tests and test data.
• Refactors and expands requirements/design/verification documentation (including new OTS + shared-package artifacts) and updates ReviewMark review-set definitions accordingly.

Reviewed changes

Copilot reviewed 99 out of 99 changed files in this pull request and generated 21 comments.

Show a summary per file

File	Description
test/DemaConsulting.SarifMark.Tests/Utilities/PathHelpersTests.cs	Adds coverage for traversal-style relative paths escaping the base directory.
test/DemaConsulting.SarifMark.Tests/TestData/no-issues.sarif	Adds a “no findings” SARIF fixture for end-to-end report generation tests.
test/DemaConsulting.SarifMark.Tests/SelfTest/SelfTestTests.cs	Adds/expands self-test assertions for enforce behavior and output handling.
test/DemaConsulting.SarifMark.Tests/Sarif/SarifTests.cs	Refactors exception assertions for SARIF read error cases.
test/DemaConsulting.SarifMark.Tests/Sarif/SarifResultsTests.cs	Refactors tests to AAA and expands negative-path assertions.
test/DemaConsulting.SarifMark.Tests/ProgramTests.cs	Strengthens --validate test by asserting results output is actually produced.
test/DemaConsulting.SarifMark.Tests/IntegrationTests.cs	Adds integration coverage for “no issues” SARIF producing a valid report.
test/DemaConsulting.SarifMark.Tests/Cli/ContextTests.cs	Expands CLI parsing validation tests (depth bounds, improved messages).
test/DemaConsulting.SarifMark.Tests/Cli/CliTests.cs	Adds CLI depth boundary tests and aligns expected error messaging.
src/DemaConsulting.SarifMark/Sarif/SarifResults.cs	Adds IO read-failure wrapping to standardize errors surfaced to callers.
src/DemaConsulting.SarifMark/Program.cs	Documents deprecated CLI aliases being omitted from help output.
src/DemaConsulting.SarifMark/Cli/Context.cs	Enforces --depth/--report-depth range (1–6) and updates docs/messages.
requirements.yaml	Updates requirements includes (adds OTS test-results + shared SarifMark; removes obsolete report include).
docs/verification/shared/sarifmark.md	Adds verification evidence for the shared-package SarifMark use case.
docs/verification/shared.md	Adds top-level shared package verification strategy.
docs/verification/sarifmark/utilities/path-helpers.md	Updates PathHelpers verification scenarios to include traversal cases.
docs/verification/sarifmark/utilities.md	Updates utilities verification narrative and scenarios.
docs/verification/sarifmark/self-test/validation.md	Updates Validation verification content and removes embedded requirements-coverage mapping.
docs/verification/sarifmark/self-test.md	Updates SelfTest verification approach and scenarios.
docs/verification/sarifmark/sarif/sarif-run.md	Expands SarifRun verification scenarios and removes embedded coverage mapping.
docs/verification/sarifmark/sarif/sarif-results.md	Expands SarifResults verification scenarios and clarifies read/formatting behaviors.
docs/verification/sarifmark/sarif/sarif-finding.md	Updates SarifFinding verification narrative to include InternalsVisibleTo implications.
docs/verification/sarifmark/sarif.md	Removes embedded requirements-coverage section and keeps scenario-focused verification.
docs/verification/sarifmark/program.md	Refines Program verification scope and scenarios (validate output evidence).
docs/verification/sarifmark/cli/context.md	Adds depth-boundary scenarios and clarifies test dependency boundaries.
docs/verification/sarifmark/cli.md	Adds/clarifies CLI scenarios for depth validation and logging.
docs/verification/sarifmark.md	Updates system verification scenarios (adds safe path and no-issues report scenario).
docs/verification/ots/xunit-v3.md	Splits discovery vs execution scenarios; removes embedded requirements-coverage mapping.
docs/verification/ots/weasyprint.md	Adds rationale for excluding self-referential evidence and adds verification PDF scenario.
docs/verification/ots/versionmark.md	Updates verification approach to explicit --validate self-validation scenarios.
docs/verification/ots/test-results.md	Adds verification evidence for the TestResults OTS package integration.
docs/verification/ots/sonarmark.md	Updates verification to rely on --validate mock-based self-validation.
docs/verification/ots/reviewmark.md	Updates verification to rely on --validate self-validation scenarios.
docs/verification/ots/reqstream.md	Updates verification to rely on --validate self-validation scenarios.
docs/verification/ots/pandoc.md	Updates Pandoc verification scope (includes verification doc outputs; excludes self-referential outputs).
docs/verification/ots/fileassert.md	Updates FileAssert verification to rely on --validate self-validation scenarios.
docs/verification/ots/buildmark.md	Updates BuildMark verification approach to --validate self-validation.
docs/verification/ots.md	Updates overall OTS verification strategy and evidence categorization.
docs/verification/introduction.md	Updates scope to include shared packages and clarifies artifact structure.
docs/verification/definition.yaml	Adds shared + new OTS verification documents to the verification collection build.
docs/user_guide/usage.md	Clarifies global vs local installation usage and documents deprecated aliases.
docs/reqstream/shared/sarifmark.yaml	Adds requirements for the shared SarifMark package usage in CI.
docs/reqstream/sarifmark/utilities/path-helpers.yaml	Links PathHelpers traversal test to requirements evidence.
docs/reqstream/sarifmark/self-test/validation.yaml	Refactors Validation requirements (adds explicit results-output requirement; expands header metadata requirements).
docs/reqstream/sarifmark/self-test.yaml	Adds enforce exit-code test and depth propagation requirement coverage.
docs/reqstream/sarifmark/sarif/sarif-run.yaml	Refines SarifRun requirements (separates results vs count).
docs/reqstream/sarifmark/sarif/sarif-results.yaml	Refactors validation requirements (JSON/version/runs) and splits ToMarkdown single vs multi-run requirement.
docs/reqstream/sarifmark/sarif/sarif-finding.yaml	Refactors SarifFinding requirements into clearer property-specific requirements.
docs/reqstream/sarifmark/sarif/report.yaml	Removes the standalone report requirements file (migrated into system-level requirements).
docs/reqstream/sarifmark/sarif.yaml	Updates SARIF subsystem requirement structure and removes obsolete report subtree.
docs/reqstream/sarifmark/program.yaml	Refactors Program requirements into parse/dispatch/exit-code responsibilities and refines SARIF summary requirements.
docs/reqstream/sarifmark/cli/context.yaml	Refactors depth requirements (alias vs validation vs default) and removes redundant WriteError wrapper requirement.
docs/reqstream/sarifmark/cli.yaml	Refines CLI requirements (interface parsing, output routing, stderr writing, exit-code behavior).
docs/reqstream/sarifmark.yaml	Updates system-level requirements (summary, safe paths, and report-format requirements including “no issues” case).
docs/reqstream/ots/xunit-v3.yaml	Splits discovery vs execution requirements and clarifies TRX generation evidence expectations.
docs/reqstream/ots/weasyprint.yaml	Adds verification PDF evidence and self-referential exclusion rationale.
docs/reqstream/ots/versionmark.yaml	Expands VersionMark requirements to capture/publish/lint-valid/lint-invalid.
docs/reqstream/ots/test-results.yaml	Adds OTS requirements for TestResults collection + TRX/JUnit serialization.
docs/reqstream/ots/sonarmark.yaml	Expands SonarMark requirements by functional capability and maps to self-validation scenarios.
docs/reqstream/ots/reviewmark.yaml	Expands ReviewMark requirements by functional capability and maps to self-validation scenarios.
docs/reqstream/ots/reqstream.yaml	Expands ReqStream requirements by functional capability and maps to self-validation scenarios.
docs/reqstream/ots/pandoc.yaml	Updates Pandoc requirement evidence list and excludes self-referential outputs.
docs/reqstream/ots/fileassert.yaml	Expands FileAssert requirements by functional capability and maps to self-validation scenarios.
docs/reqstream/ots/buildmark.yaml	Expands BuildMark requirements by functional capability and maps to self-validation scenarios.
docs/design/shared/sarifmark.md	Adds shared-package integration design for SarifMark being consumed by its own CI.
docs/design/shared.md	Adds top-level shared package dependency design and policies.
docs/design/sarifmark/self-test/validation.md	Documents TestResults package usage within Validation design dependencies.
docs/design/sarifmark/program.md	Corrects Version property behavior description (no caching).
docs/design/sarifmark/cli/context.md	Updates depth/range constraints and documents deprecated alias behavior.
docs/design/sarifmark.md	Adds deprecated alias notes, adds TestResults OTS dependency, and formalizes report format contract description.
docs/design/ots/xunit-v3.md	Updates integration steps to include Microsoft.NET.Test.Sdk dependency.
docs/design/ots/versionmark.md	Documents use of --validate in CI for VersionMark evidence collection.
docs/design/ots/test-results.md	Adds integration design for DemaConsulting.TestResults as an OTS package.
docs/design/ots/sonarmark.md	Documents --validate mock-based self-validation usage in CI.
docs/design/ots/reviewmark.md	Documents --validate evidence collection and depth flag.
docs/design/ots/reqstream.md	Documents --validate evidence collection usage in CI.
docs/design/ots/fileassert.md	Documents --validate evidence collection usage in CI.
docs/design/ots/buildmark.md	Documents --validate evidence collection usage in CI and clarifies error handling.
docs/design/ots.md	Updates OTS dependency count and adds TestResults to the preferred tool list.
docs/design/introduction.md	Expands design scope to include shared packages; reformats item structure and adds shared/OTS listing.
docs/design/definition.yaml	Adds shared + new OTS design documents to the design collection build.
AGENTS.md	Refines delegation guidance, adds planning agent reference, and extends reporting result states.
.reviewmark.yaml	Updates review-set grouping/comments and adds review sets for TestResults and Shared SarifMark.
.github/standards/verification-documentation.md	Updates verification doc standards (mandatory sections, removes embedded req-coverage mapping, adds shared pkg guidance).
.github/standards/testing-principles.md	Removes redundant header text (content consolidation).
.github/standards/technical-documentation.md	Tightens and clarifies formatting/guidance sections and removes redundant prose.
.github/standards/software-items.md	Tightens and clarifies guidance and removes redundant prose.
.github/standards/reviewmark-usage.md	Removes redundant prose in quality checklist section.
.github/standards/design-documentation.md	Updates design doc standards (mandatory sections, shared package structure, no version numbers, adds Dependencies/Callers).
.github/standards/csharp-testing.md	Removes redundant prose; keeps checklist.
.github/standards/csharp-language.md	Removes redundant prose before example.
.github/standards/coding-principles.md	Removes redundant prose and tightens wording in core principles.
.github/agents/template-sync.agent.md	Clarifies orchestration by mode, adds unresolved-questions handling, and adds required Report field.
.github/agents/quality.agent.md	Expands companion artifact enforcement and adds Report field + verification-doc compliance section.
.github/agents/planning.agent.md	Introduces a formal planning agent and its report/summary templates.
.github/agents/lint-fix.agent.md	Adds required Report field.
.github/agents/implementation.agent.md	Updates orchestration to use the new planning agent and adds Report field + unknowns handling.
.github/agents/formal-review.agent.md	Adds required Report field.
.github/agents/developer.agent.md	Expands companion artifact expectations and adds required Report field.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 99 out of 99 changed files in this pull request and generated 5 comments.

Comments suppressed due to low confidence (1)

.reviewmark.yaml:57

• docs/design/ots.md and docs/design/shared.md are included in needs-review (via docs/design/**/*.md) and exist in the repo, but they are not included in any review-set paths. This will leave those files uncovered and can cause reviewmark --enforce to fail.

Add the two root-level documents to an appropriate design-focused review set (e.g., SarifMark-Design or Purpose).

  - id: SarifMark-Design
    title: Review that SarifMark Design is Consistent and Complete
    paths:
      - docs/reqstream/sarifmark.yaml
      - docs/reqstream/sarifmark/platform-requirements.yaml

[Copilot]

Pull request overview

Copilot reviewed 98 out of 98 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 98 out of 98 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 98 out of 98 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 98 out of 98 changed files in this pull request and generated 4 comments.

Comments suppressed due to low confidence (1)

src/DemaConsulting.SarifMark/Sarif/SarifResults.cs:99

• The invalid-JSON error message omits the SARIF file path, which makes troubleshooting harder (especially in --silent mode where the file path isn't echoed). Consider including filePath in the message for consistency with the I/O error path.