diff --git a/docs/agentic.md b/docs/agentic.md index 2bb7b91..9f01b02 100644 --- a/docs/agentic.md +++ b/docs/agentic.md @@ -1,65 +1,99 @@ -# AI Coding Agents - -AI coding agents are most effective when they understand the standards they are being held to before they -write a single line of code. Without that context, an agent implementing a feature must discover -compliance requirements through repeated CI failure cycles — adding a requirement entry after a -ReqStream enforcement failure, fixing linting errors after a markdownlint failure, adjusting code style -after a formatter check failure. - -Continuous Compliance projects short-circuit this cycle by providing agents with machine-readable, -authoritative project standards up front. When an agent consults these files at the start of a task, it -can produce compliant code on the first attempt. - -## Agent Guidance Files - -DEMA Consulting projects use two layers of agent guidance: - -### AGENTS.md — Root Quick Reference - -`AGENTS.md` at the repository root is the primary entry point for any agent working on the project. It -is a compact quick-reference card covering everything an agent needs to know to work effectively: - -- **Available specialized agents** — roles defined for the project and when to invoke each -- **Tech stack** — languages, frameworks, runtimes, and package managers in use -- **Key files** — location of `requirements.yaml`, linting configs, and `.editorconfig` +# AI Coding Agents and Continuous Compliance + +## The Challenge: Agents Without Constraints + +AI coding agents left to their own devices tend to "vibe-code" — implementing what they think +is wanted based on the immediate prompt, without considering the broader system they are +working within. An unconstrained agent rarely asks: + +- Does this feature have a documented requirement? +- Are all existing requirements still linked to passing tests? +- Does the new code meet the project's formatting and style rules? +- Does the changed file need a formal review record? + +Without this context, the agent will often produce something that works in isolation but +fails the project's compliance gates. The result is a CI failure loop: add a requirement +entry after a ReqStream enforcement failure, fix linting errors after a markdownlint failure, +adjust code style after a formatter check failure — each cycle costing another pipeline run +and more agent turns. + +## The Context Problem + +The obvious solution — "just give the agent the whole repository" — does not scale. A +typical software project contains hundreds of source files, multiple documentation +directories, configuration files, test suites, and generated artifacts. Loading everything +floods the agent's context window with information irrelevant to the current task, crowding +out the content the agent actually needs to reason well. + +What agents need is **targeted, structured context**: enough information to understand the +project's standards and their current task, without drowning in the rest of the codebase. + +## How Continuous Compliance Helps + +Continuous Compliance projects provide that targeted context through a set of machine-readable +files — each covering one layer of the project — that an agent can load selectively. Together +they build a complete picture of the project from general to specific, but an agent only needs +to load the layers relevant to its task: + ++----------------------+-----------------------------------------------+----------------------------------------------+ +| Layer | File(s) | What It Tells an Agent | ++======================+===============================================+==============================================+ +| **Requirements** | `requirements.yaml` | What the software must do; which tests | +| | | prove it | ++----------------------+-----------------------------------------------+----------------------------------------------+ +| **Review coverage** | `.reviewmark.yaml` | Which files need formal review; how they | +| | | are grouped | ++----------------------+-----------------------------------------------+----------------------------------------------+ +| **Code quality** | `.editorconfig`, `.cspell.yaml`, | How code and documentation must be | +| | `.markdownlint-cli2.yaml`, `.yamllint.yaml` | formatted | ++----------------------+-----------------------------------------------+----------------------------------------------+ +| **Build and test** | `AGENTS.md` | How to build, test, and lint locally; | +| | | where everything lives | ++----------------------+-----------------------------------------------+----------------------------------------------+ + +An agent implementing a new feature needs the requirements layer and the build layer. An agent +performing a code review needs the review-coverage layer and the requirements layer. An agent +fixing a documentation spelling error needs only the code-quality layer. None of them needs +to read the whole repository. + +This is the core benefit of Continuous Compliance for agentic development: **the project +documents its own standards in a form that machines can read, so agents can load exactly what +they need, when they need it.** + +## AGENTS.md — The Entry Point + +`AGENTS.md` at the repository root is the primary entry point for any agent working on the +project. It is a compact quick-reference card — a map to the project's standards — covering +the essential information an agent needs to orient itself before starting work: + +- **Key compliance files** — where to find `requirements.yaml`, `.reviewmark.yaml`, and linting configs - **Requirements rules** — all requirements must be linked to tests; enforced in CI - **Test source filters** — platform- and runtime-specific test evidence requirements - **Test naming conventions** — patterns that make tests linkable to requirements -- **Code style** — XML documentation, error types, namespace style, string formatting -- **Build and test commands** — how to build, test, run self-validation, and lint locally -- **Documentation map** — where user guides, requirements, and trace matrices live +- **Code style** — formatting rules, documentation conventions, naming patterns +- **Build and test commands** — how to build, test, and lint locally + +An agent that reads `AGENTS.md` at the start of every session has an immediate, accurate +picture of the project's structure and standards, without needing to discover them through +trial and error or CI failure. **Example `AGENTS.md` structure:** ```markdown # Agent Quick Reference -## Available Specialized Agents - -- **Requirements Agent** - Develops requirements and ensures test coverage linkage -- **Technical Writer** - Creates accurate documentation following regulatory best practices -- **Software Developer** - Writes production code and self-validation tests -- **Test Developer** - Creates unit and integration tests -- **Code Quality Agent** - Enforces linting, static analysis, and security standards -- **Code Review Agent** - Assists in performing formal file reviews -- **Repo Consistency Agent** - Ensures downstream repositories remain consistent with template patterns +## Key Compliance Files -## Agent Selection Guide +- `requirements.yaml` — all project requirements (ALL must be linked to passing tests) +- `.reviewmark.yaml` — files requiring formal review and named review-set groupings +- `.cspell.yaml`, `.markdownlint-cli2.yaml`, `.yamllint.yaml` — linting configuration +- `.editorconfig` — code formatting rules -- Fix a bug → **Software Developer** -- Add a new feature → **Requirements Agent** → **Software Developer** → **Test Developer** -- Write a test → **Test Developer** -- Fix linting or static analysis issues → **Code Quality Agent** -- Update documentation → **Technical Writer** -- Add or update requirements → **Requirements Agent** -- Run security scanning or address CodeQL alerts → **Code Quality Agent** -- Perform a formal file review → **Code Review Agent** -- Propagate template changes → **Repo Consistency Agent** +## Requirements Rules -## Requirements - -- All requirements MUST be linked to tests (enforced via `dotnet reqstream --enforce`) -- When adding features: add requirement + link to test +- ALL requirements MUST be linked to tests (enforced via `dotnet reqstream --enforce`) +- When adding features: add a requirement entry and link to at least one test +- When writing tests: name them so they can be linked in `requirements.yaml` ## Test Source Filters @@ -76,31 +110,20 @@ is a compact quick-reference card covering everything an agent needs to know to dotnet build --configuration Release dotnet test --configuration Release +./lint.sh # or lint.bat on Windows ``` -### .github/agents/ — Specialized Role Instructions - -For projects that use specialized agent roles, each role has its own instruction file in -`.github/agents/`. These files define the role's responsibilities, when to invoke it, what it owns, -and which other agents it defers to. +## Agent Guidance Files -DEMA Consulting projects define the following specialized roles: +For larger or more complex projects, a single `AGENTS.md` may not be enough. Projects can +provide additional layers of guidance through two mechanisms: -| Agent | File | Responsibilities | -| :---- | :--- | :--------------- | -| Requirements Agent | `requirements-agent.md` | Creates and maintains `requirements.yaml`; determines test coverage strategy | -| Technical Writer | `technical-writer.md` | Creates and maintains documentation following regulatory best practices | -| Software Developer | `software-developer.md` | Writes production code and self-validation tests in literate style | -| Test Developer | `test-developer.md` | Creates unit and integration tests following the AAA pattern | -| Code Quality Agent | `code-quality-agent.md` | Enforces all quality gates (linting, static analysis, requirements traceability) | -| Code Review Agent | `code-review-agent.md` | Performs formal ReviewMark file reviews; elaborates review-sets and produces structured findings reports | -| Repo Consistency Agent | `repo-consistency-agent.md` | Ensures downstream repositories remain consistent with template patterns | +### Specialized Role Files -The `AGENTS.md` file should also include an **Agent Selection Guide** — a short decision table that -maps common tasks (fix a bug, add a feature, update documentation, perform a review) to the -appropriate agent role. This guide helps both human developers and AI agents quickly identify which -specialized role to invoke for a given task, reducing the risk of using the wrong agent or -duplicating effort across roles. +Projects that use specialized agent roles place an instruction file for each role in +`.github/agents/`. These files define the role's responsibilities, when to invoke it, what +it owns, and which other agents it defers to. This allows different agents to load only the +guidance relevant to their role, keeping each agent's context focused. Role files use the GitHub Copilot agent front-matter format: @@ -115,99 +138,51 @@ description: Develops requirements and ensures appropriate test coverage linkage ... ``` -## What Helps Agents Most - -The following information, when present in `AGENTS.md` or role files, has the highest impact on -agent compliance: +### Detailed Guidance Files -### Requirements Format +Projects may also include detailed guidance files covering specific domains — requirements +management, file review configuration, documentation structure, code style conventions, and +so on. Unlike the compact quick-reference in `AGENTS.md`, these files contain the full detail +agents need to produce compliant output in complex situations. -Agents that know the `requirements.yaml` schema can add correctly formatted requirements when they -add features, rather than leaving requirements management as a separate pass: - -```yaml -sections: - - title: Functional Requirements - requirements: - - id: Tool-Version - title: The tool shall display version information. - justification: Users need to verify the installed tool version. - tests: - - TemplateTool_VersionDisplay -``` - -### Test Naming Conventions - -When the test naming convention is documented, agents can write tests whose names will automatically -match requirement links in `requirements.yaml`. For example, DEMA Consulting tools use the pattern -`ToolName_FeatureName` for self-validation tests. An agent that knows this will name its test -`MyTool_NewFeature` and link it in requirements as `MyTool_NewFeature` — immediately satisfying the -ReqStream enforcement check. - -### Test Source Filters - -When requirements need platform-specific or runtime-specific evidence, the source filter syntax must -be documented. An agent that understands that `windows@TestName` restricts evidence to Windows -results will write and link tests correctly, rather than accidentally removing filters that invalidate -compliance evidence. - -### Quality Gates - -Knowing all the quality gates the CI enforces — build warnings, linting, static analysis, requirements -traceability, test results — allows an agent to validate its own work before triggering a pipeline -run. The Code Quality Agent role captures this checklist in its instruction file, making it reusable -across agent sessions. - -### Code Style - -Documenting `.editorconfig` conventions in human-readable form (`AGENTS.md`) prevents the most common -class of agent style violations: incorrect namespace declaration style, missing XML documentation, -wrong string formatting. An agent that knows these rules generates code that passes `dotnet format` -without additional correction. +By placing these files in the repository alongside the code they govern, projects make their +standards self-documenting: an agent working on requirements can load the requirements +guidance; an agent performing a review can load the review guidance. No external configuration +or pre-training is required — the project explains itself. ## Agent Report Files -When agents need to communicate intermediate results or hand off work between roles, they write -report files. DEMA Consulting projects use a naming convention that keeps these files out of the -committed codebase: +When agents need to communicate intermediate results or hand off work between roles, they +write report files to a dedicated folder. Projects using agentic workflows typically use +a `.agent-logs/` folder that is excluded from source control and linting: -- **Pattern**: `AGENT_REPORT_.md` (e.g., `AGENT_REPORT_analysis.md`) -- **Purpose**: Temporary inter-agent communication; not intended for long-term storage -- **Exclusions**: Files matching this pattern are excluded from: +- **Location**: `.agent-logs/[agent-name]-[subject]-[unique-id].md` +- **Purpose**: Records work performed, decisions made, and follow-up items; also used for + temporary inter-agent communication +- **Exclusions**: The `.agent-logs/` folder is excluded from: - Git tracking (via `.gitignore`) - Markdown linting - Spell checking -This prevents agent-generated scratch files from polluting the project history or triggering false -linting failures. - -## Continuous Compliance as Agent Context - -From an agent's perspective, a Continuous Compliance project is self-documenting: the standards it -enforces are written in the same repository the agent is working in. A fully equipped Continuous -Compliance project provides an agent with: - -- **What to build** — `requirements.yaml` defines all requirements -- **How to prove it** — test naming conventions and source filters define the evidence format -- **What style to follow** — `.editorconfig`, `.cspell.yaml`, `.markdownlint-cli2.yaml`, `.yamllint.yaml` -- **What gates to pass** — `AGENTS.md` and role files enumerate every CI enforcement step -- **Where to look** — the documentation map points to guides, requirements, and trace matrices - -An agent that reads `AGENTS.md` at the start of every session has all of this context available -immediately, without needing to discover it through trial and error. +This prevents agent-generated log files from polluting the project history or triggering +false linting failures. ## ReviewMark and AI-Assisted Reviews Beyond its role in CI/CD enforcement, ReviewMark's review-set grouping is directly useful for -AI-assisted reviews. When an AI agent is asked to review a feature or subsystem, directing it to -the corresponding review-set in `.reviewmark.yaml` gives it a precise, pre-defined scope that -groups all relevant files together. +AI-assisted reviews. When an AI agent is asked to review a feature or subsystem, directing it +to the corresponding review-set in `.reviewmark.yaml` gives it a precise, pre-defined scope +that groups all relevant files together. -Review-sets designed for AI context group requirements, design documentation, source code, and -tests by feature area. An agent that reviews all files in a review-set at once can reason across -the full chain of evidence — from what the code must do (requirements), to how it is structured -(design), to what it actually does (code), to what is verified (tests) — rather than reviewing -any one category in isolation. +A well-designed review-set contains all the files that belong together conceptually: +requirements documents, design documents, source code, and tests that collectively form a +coherent unit of functionality. An agent that reviews all files in a review-set at once can +reason across the full chain of evidence: + +- **Requirements** — what the code must do and why +- **Design documents** — how the code is structured and the rationale behind key decisions +- **Source code** — what the code actually does +- **Tests** — which behaviors are verified and how This context-aware grouping enables agents to identify: @@ -216,5 +191,11 @@ This context-aware grouping enables agents to identify: - **Coverage gaps** — code paths not covered by any test - **Consistency issues** — discrepancies between stated requirements and actual behavior +Without ReviewMark's explicit groupings, an agent asked to "review the authentication module" +must guess which files are relevant, often missing files or including unrelated ones. With +ReviewMark, the scope is authoritative and machine-readable — the agent loads exactly the +right files, every time. + See [File Reviews](file-reviews.md#ai-assisted-reviews) for guidance on designing review-sets that maximize the usefulness of AI-assisted reviews. + diff --git a/docs/file-reviews.md b/docs/file-reviews.md index 7b5ad7b..46e8dfc 100644 --- a/docs/file-reviews.md +++ b/docs/file-reviews.md @@ -64,26 +64,30 @@ files require review and how to group them into named review-sets. # Patterns identifying all files that require review. # Processed in order; prefix a pattern with '!' to exclude. needs-review: - - "**/*.cs" - - "**/*.yaml" - - "!**/obj/**" # exclude build output - - "!src/Generated/**" # exclude auto-generated files + - "**/*.cs" # All C# source and test files + - "docs/design/**/*.md" # Design documentation + - "docs/reqstream/**/*.yaml" # Requirements files only + - "!**/obj/**" # exclude build output + - "!**/bin/**" # exclude binary output # Source of review evidence - see ReviewMark user guide. evidence-source: type: none reviews: - - id: Core-Logic - title: Review of core business logic + - id: MyProduct-PasswordValidator + title: Password Validator Unit Review paths: - - "src/Core/**/*.cs" - - "src/Core/**/*.yaml" - - "!src/Core/Generated/**" - - id: Security-Layer - title: Review of authentication and authorization + - "docs/reqstream/auth-passwordvalidator-class.yaml" + - "docs/design/password-validation.md" + - "src/Auth/PasswordValidator.cs" + - "test/Auth/PasswordValidatorTests.cs" + + - id: MyProduct-AllRequirements + title: All Requirements Review paths: - - "src/Auth/**/*.cs" + - "requirements.yaml" + - "docs/reqstream/**/*.yaml" ``` ### Key Fields @@ -120,9 +124,8 @@ In a CI/CD pipeline, map repository secrets to those environment variables: REVIEWMARK_TOKEN: ${{ secrets.REVIEW_TOKEN }} run: > dotnet reviewmark - --definition .reviewmark.yaml - --plan docs/reviewplan/review-plan.md - --report docs/reviewreport/review-report.md + --plan docs/code_review_plan/plan.md + --report docs/code_review_report/report.md --enforce ``` @@ -134,32 +137,32 @@ produces one PDF release artifact and contains a hand-authored `introduction.md` | Folder | PDF Produced | Hand-authored files | | :----- | :----------- | :------------------ | -| `docs/reviewplan/` | Review Plan PDF | `introduction.md`, `definition.yaml` | -| `docs/reviewreport/` | Review Report PDF | `introduction.md`, `definition.yaml` | +| `docs/code_review_plan/` | Review Plan PDF | `introduction.md`, `definition.yaml` | +| `docs/code_review_report/` | Review Report PDF | `introduction.md`, `definition.yaml` | -The generated markdown files (`review-plan.md`, `review-report.md`) are written by ReviewMark on +The generated markdown files (`plan.md`, `report.md`) are written by ReviewMark on each CI/CD run and must **not** be committed — they are always regenerated from the current state of the repository. ``` docs/ - reviewplan/ + code_review_plan/ introduction.md # hand-authored introduction for the Review Plan PDF definition.yaml # Pandoc definition for the Review Plan document - review-plan.md # generated by ReviewMark --plan (not committed) - reviewreport/ + plan.md # generated by ReviewMark --plan (not committed) + code_review_report/ introduction.md # hand-authored introduction for the Review Report PDF definition.yaml # Pandoc definition for the Review Report document - review-report.md # generated by ReviewMark --report (not committed) + report.md # generated by ReviewMark --report (not committed) ``` ### Pandoc definition.yaml examples ```yaml -# docs/reviewplan/definition.yaml +# docs/code_review_plan/definition.yaml input-files: - - docs/reviewplan/introduction.md - - docs/reviewplan/review-plan.md + - docs/code_review_plan/introduction.md + - docs/code_review_plan/plan.md template: docs/template/template.html css: docs/template/template.css standalone: true @@ -170,10 +173,10 @@ metadata: ``` ```yaml -# docs/reviewreport/definition.yaml +# docs/code_review_report/definition.yaml input-files: - - docs/reviewreport/introduction.md - - docs/reviewreport/review-report.md + - docs/code_review_report/introduction.md + - docs/code_review_report/report.md template: docs/template/template.html css: docs/template/template.css standalone: true @@ -189,10 +192,9 @@ ReviewMark runs in the document generation job after all source files are in the ```bash dotnet reviewmark \ - --definition .reviewmark.yaml \ - --plan docs/reviewplan/review-plan.md \ + --plan docs/code_review_plan/plan.md \ --plan-depth 1 \ - --report docs/reviewreport/review-report.md \ + --report docs/code_review_report/report.md \ --report-depth 1 \ --enforce ``` @@ -206,41 +208,40 @@ so the review plan is available to diagnose coverage gaps. - name: Generate Review Documents run: > dotnet reviewmark - --definition .reviewmark.yaml - --plan docs/reviewplan/review-plan.md + --plan docs/code_review_plan/plan.md --plan-depth 1 - --report docs/reviewreport/review-report.md + --report docs/code_review_report/report.md --report-depth 1 --enforce - name: Generate Review Plan HTML run: > dotnet pandoc - --defaults docs/reviewplan/definition.yaml + --defaults docs/code_review_plan/definition.yaml --metadata version="${{ inputs.version }}" --metadata date="$(date +'%Y-%m-%d')" - --output docs/reviewplan/review-plan.html + --output docs/code_review_plan/plan.html - name: Generate Review Plan PDF run: > dotnet weasyprint --pdf-variant pdf/a-3u - docs/reviewplan/review-plan.html + docs/code_review_plan/plan.html "docs/MyProject Review Plan.pdf" - name: Generate Review Report HTML run: > dotnet pandoc - --defaults docs/reviewreport/definition.yaml + --defaults docs/code_review_report/definition.yaml --metadata version="${{ inputs.version }}" --metadata date="$(date +'%Y-%m-%d')" - --output docs/reviewreport/review-report.html + --output docs/code_review_report/report.html - name: Generate Review Report PDF run: > dotnet weasyprint --pdf-variant pdf/a-3u - docs/reviewreport/review-report.html + docs/code_review_report/report.html "docs/MyProject Review Report.pdf" ``` @@ -451,6 +452,63 @@ Software unit reviews are appropriate when design-requirements specify the preci a single class, enabling a reviewer — human or AI — to verify each requirement against its direct implementation and tests without noise from unrelated files. +### Standard Review-Set Patterns + +Projects following DEMA Consulting standards use a set of named review-set types that agents and +reviewers can recognize and rely upon: + ++----------------------+------------------------------+----------------------------------------------------------+ +| Review-Set Type | ID Pattern | Contents | ++======================+==============================+==========================================================+ +| **System** | `[Project]-System` | System-level requirements, design introduction, | +| | | system design documents, integration tests | ++----------------------+------------------------------+----------------------------------------------------------+ +| **Design** | `[Product]-Design` | System-level requirements, platform requirements, | +| | | all design documents | ++----------------------+------------------------------+----------------------------------------------------------+ +| **All Requirements** | `[Product]-AllRequirements` | All requirement files including root | +| | | `requirements.yaml` | ++----------------------+------------------------------+----------------------------------------------------------+ +| **Unit** | `[Product]-[Unit]` | Unit requirements, design documents, source code, | +| | | unit tests | ++----------------------+------------------------------+----------------------------------------------------------+ + +A typical project would have one System review, one Design review, one AllRequirements review, and +one Unit review per software unit (class). This structure gives reviewers — and review agents — a +predictable set of entry points into the codebase: + +```yaml +reviews: + - id: MyProduct-System + title: System Integration Review + paths: + - "docs/reqstream/myproduct-system.yaml" + - "docs/design/introduction.md" + - "docs/design/system.md" + - "tests/**/IntegrationTests.cs" + + - id: MyProduct-Design + title: Architecture and Design Review + paths: + - "docs/reqstream/myproduct-system.yaml" + - "docs/reqstream/platform-requirements.yaml" + - "docs/design/**/*.md" + + - id: MyProduct-AllRequirements + title: All Requirements Review + paths: + - "requirements.yaml" + - "docs/reqstream/**/*.yaml" + + - id: MyProduct-MyComponent + title: MyComponent Unit Review + paths: + - "docs/reqstream/unit-mycomponent.yaml" + - "docs/design/mycomponent.md" + - "src/MyComponent.cs" + - "tests/MyComponentTests.cs" +``` + ### Using ReviewMark with AI Review Agents The `.reviewmark.yaml` configuration makes the file grouping explicit and machine-readable, which @@ -491,22 +549,16 @@ Shows which files are covered by which review-sets, and flags any files not cove ```markdown # Review Plan -## Core-Logic - -**Title:** Review of core business logic - -| File | Status | -| :--- | :----- | -| src/Core/Engine.cs | ✅ Covered | -| src/Core/Parser.cs | ✅ Covered | - -## Security-Layer +## MyProduct-PasswordValidator -**Title:** Review of authentication and authorization +**Title:** Password Validator Unit Review | File | Status | | :--- | :----- | -| src/Auth/AuthService.cs | ✅ Covered | +| docs/reqstream/auth-passwordvalidator-class.yaml | ✅ Covered | +| docs/design/password-validation.md | ✅ Covered | +| src/Auth/PasswordValidator.cs | ✅ Covered | +| test/Auth/PasswordValidatorTests.cs | ✅ Covered | ## Uncovered Files @@ -524,6 +576,6 @@ Shows the status of each review-set — whether the evidence is current, stale, | Review | Title | Status | | :----- | :---- | :----- | -| Core-Logic | Review of core business logic | ✅ Current | -| Security-Layer | Review of authentication and authorization | ⚠️ Stale | +| MyProduct-PasswordValidator | Password Validator Unit Review | ✅ Current | +| MyProduct-AllRequirements | All Requirements Review | ⚠️ Stale | ``` diff --git a/docs/requirements.md b/docs/requirements.md index e042799..963c6e9 100644 --- a/docs/requirements.md +++ b/docs/requirements.md @@ -16,6 +16,8 @@ The `templates/reqstream` folder provides ready-to-use template files for a new .NET local tool manifest - [`requirements.yaml`][reqstream-root] — root requirements file that includes all files from `docs/reqstream/` +- [`docs/reqstream/system-example.yaml`][reqstream-system-example] — example software system + requirements - [`docs/reqstream/subsystem-example.yaml`][reqstream-subsystem-example] — example software subsystem requirements - [`docs/reqstream/unit-example.yaml`][reqstream-unit-example] — example software unit requirements @@ -24,17 +26,39 @@ The `templates/reqstream` folder provides ready-to-use template files for a new [reqstream-dotnet-tools]: https://github.com/demaconsulting/ContinuousCompliance/blob/main/templates/reqstream/.config/dotnet-tools.json [reqstream-root]: https://github.com/demaconsulting/ContinuousCompliance/blob/main/templates/reqstream/requirements.yaml +[reqstream-system-example]: https://github.com/demaconsulting/ContinuousCompliance/blob/main/templates/reqstream/docs/reqstream/system-example.yaml [reqstream-subsystem-example]: https://github.com/demaconsulting/ContinuousCompliance/blob/main/templates/reqstream/docs/reqstream/subsystem-example.yaml [reqstream-unit-example]: https://github.com/demaconsulting/ContinuousCompliance/blob/main/templates/reqstream/docs/reqstream/unit-example.yaml [reqstream-ots-example]: https://github.com/demaconsulting/ContinuousCompliance/blob/main/templates/reqstream/docs/reqstream/ots-example.yaml -The recommended approach is to keep a separate requirements YAML file per software subsystem, unit, -or OTS component under `docs/reqstream/`, and list them in `requirements.yaml` using the `includes` -field. This keeps each file focused on one component and makes reviews easier. +The recommended approach is to keep a separate requirements YAML file per software system, subsystem, +unit, or OTS component under `docs/reqstream/`, and list them in `requirements.yaml` using the +`includes` field. A consistent naming convention makes the scope of each file immediately clear: + +```text +docs/reqstream/ + {project}-system.yaml # System-level requirements + subsystem-{name}.yaml # Subsystem requirements + unit-{name}.yaml # Software unit (class-level) requirements + ots-{component}.yaml # OTS software item requirements +``` + +This keeps each file focused on one component and makes reviews easier. ## Requirement Classes -Requirements fall into three classes based on the component they describe: +Requirements fall into four classes based on the component they describe: + +### Software System Requirements + +System requirements describe the complete deliverable product from the perspective of its external +users and interfaces. They capture what the system as a whole must do — its observable behaviors, +qualities, and constraints — without specifying how any individual subsystem or unit implements +them. System requirements are satisfied when end-to-end or integration tests demonstrate that the +product meets its stated obligations. + +The recommended approach is to keep system-level requirements in a dedicated file (e.g., +`docs/reqstream/{project}-system.yaml`) separate from subsystem and unit requirements. ### Software Subsystem Requirements diff --git a/templates/lint/.cspell.yaml b/templates/lint/.cspell.yaml index 371ca3b..003fbe5 100644 --- a/templates/lint/.cspell.yaml +++ b/templates/lint/.cspell.yaml @@ -32,6 +32,7 @@ ignorePaths: - "**/third-party/**" - "**/3rd-party/**" - "**/AGENT_REPORT_*.md" + - "**/.agent-logs/**" - "**/bin/**" - "**/obj/**" - package-lock.json diff --git a/templates/lint/.gitignore b/templates/lint/.gitignore index 533e9e5..a9c45c5 100644 --- a/templates/lint/.gitignore +++ b/templates/lint/.gitignore @@ -1,2 +1,3 @@ .venv/ node_modules/ +.agent-logs/ diff --git a/templates/lint/.markdownlint-cli2.yaml b/templates/lint/.markdownlint-cli2.yaml index 04f1f80..199d48b 100644 --- a/templates/lint/.markdownlint-cli2.yaml +++ b/templates/lint/.markdownlint-cli2.yaml @@ -44,4 +44,4 @@ ignores: - "**/thirdparty/**" - "**/third-party/**" - "**/3rd-party/**" - - "**/AGENT_REPORT_*.md" + - "**/.agent-logs/**" diff --git a/templates/lint/lint.bat b/templates/lint/lint.bat index 42e38b4..21f52e5 100644 --- a/templates/lint/lint.bat +++ b/templates/lint/lint.bat @@ -12,17 +12,19 @@ REM - Agents execute this script to identify files needing fixes set "LINT_ERROR=0" REM Install npm dependencies -call npm install +call npm install --silent +if errorlevel 1 set "LINT_ERROR=1" REM Create Python virtual environment (for yamllint) if missing if not exist ".venv\Scripts\activate.bat" ( python -m venv .venv ) call .venv\Scripts\activate.bat -pip install -r pip-requirements.txt +pip install -r pip-requirements.txt --quiet --disable-pip-version-check +if errorlevel 1 set "LINT_ERROR=1" REM Run spell check -call npx cspell --no-progress --no-color "**/*.{md,yaml,yml,json,cs,cpp,hpp,h,txt}" +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 check diff --git a/templates/lint/lint.sh b/templates/lint/lint.sh index 9da073e..4ca7641 100644 --- a/templates/lint/lint.sh +++ b/templates/lint/lint.sh @@ -11,17 +11,17 @@ lint_error=0 # Install npm dependencies -npm install +npm install --silent || lint_error=1 # Create Python virtual environment (for yamllint) if [ ! -d ".venv" ]; then python -m venv .venv fi source .venv/bin/activate -pip install -r pip-requirements.txt +pip install -r pip-requirements.txt --quiet --disable-pip-version-check || lint_error=1 # Run spell check -npx cspell --no-progress --no-color "**/*.{md,yaml,yml,json,cs,cpp,hpp,h,txt}" || lint_error=1 +npx cspell --no-progress --no-color --quiet "**/*.{md,yaml,yml,json,cs,cpp,hpp,h,txt}" || lint_error=1 # Run markdownlint check npx markdownlint-cli2 "**/*.md" || lint_error=1 diff --git a/templates/reqstream/docs/reqstream/system-example.yaml b/templates/reqstream/docs/reqstream/system-example.yaml new file mode 100644 index 0000000..e7ec0b6 --- /dev/null +++ b/templates/reqstream/docs/reqstream/system-example.yaml @@ -0,0 +1,32 @@ +--- +# Software System Requirements Example +# +# PURPOSE: +# - Demonstrate software system requirements in ReqStream YAML format +# - System requirements describe the complete deliverable product from the perspective +# of its external users and interfaces +# - System requirements are verified by integration or end-to-end tests +# +# USAGE: +# - Replace "TemplateTool" with your project name +# - Add, remove, or modify requirements to match your system's specification +# - Reference tests using the id of the test method in your test suite + +sections: + - title: System Requirements + requirements: + - id: TemplateTool-System-Version + title: The tool shall display version information. + justification: | + Users need to verify the installed tool version to confirm compatibility + with their workflow and to support traceability in regulated environments. + tests: + - TemplateTool_VersionDisplay + + - id: TemplateTool-System-ExitCode + title: The tool shall exit with a non-zero exit code when processing fails. + justification: | + CI/CD pipelines rely on exit codes to detect failures. A non-zero exit code + on failure allows pipelines to stop and report the issue automatically. + tests: + - TemplateTool_ExitCode_Failure diff --git a/templates/reqstream/requirements.yaml b/templates/reqstream/requirements.yaml index afbb8c3..c728c91 100644 --- a/templates/reqstream/requirements.yaml +++ b/templates/reqstream/requirements.yaml @@ -19,6 +19,7 @@ # - Add new requirement files under docs/reqstream/ and include them here includes: + - docs/reqstream/system-example.yaml - docs/reqstream/subsystem-example.yaml - docs/reqstream/unit-example.yaml - docs/reqstream/ots-example.yaml diff --git a/templates/reviews/.reviewmark.yaml b/templates/reviews/.reviewmark.yaml index 419ef9e..2da72f8 100644 --- a/templates/reviews/.reviewmark.yaml +++ b/templates/reviews/.reviewmark.yaml @@ -9,10 +9,9 @@ # - Run ReviewMark to generate the Review Plan and Review Report: # # dotnet reviewmark \ -# --definition .reviewmark.yaml \ -# --plan docs/reviewplan/review-plan.md \ +# --plan docs/code_review_plan/plan.md \ # --plan-depth 1 \ -# --report docs/reviewreport/review-report.md \ +# --report docs/code_review_report/report.md \ # --report-depth 1 \ # --enforce #