diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json index 337f9ec..7ccda75 100644 --- a/.config/dotnet-tools.json +++ b/.config/dotnet-tools.json @@ -61,6 +61,12 @@ "commands": [ "fileassert" ] + }, + "demaconsulting.sysml2tools.tool": { + "version": "0.1.0-beta.5", + "commands": [ + "sysml2tools" + ] } } } \ No newline at end of file diff --git a/.cspell.yaml b/.cspell.yaml index 1145ebd..8cabe28 100644 --- a/.cspell.yaml +++ b/.cspell.yaml @@ -17,6 +17,7 @@ words: - buildmark - compilability - Dema + - demaconsulting - entrantly - fileassert - hotspot @@ -36,6 +37,8 @@ words: - slnx - sonar - sonarmark + - sysml + - sysml2tools - versionmark - VSINSTALLDIR - Weasy diff --git a/.github/agents/developer.agent.md b/.github/agents/developer.agent.md index 5f208eb..5f2b988 100644 --- a/.github/agents/developer.agent.md +++ b/.github/agents/developer.agent.md @@ -19,7 +19,7 @@ Perform software development tasks by determining and applying appropriate stand If one exists, fetch it as the starting point; adjust placeholder names and heading depth to match the target path before writing the file - For each modified file, identify which companion artifacts need updating - (requirements, design docs, tests, review-sets) + (requirements, design docs, verification docs, tests, review-sets, README.md, user guides) - Include companion artifact updates in the work plan 4. **Execute work** following standards requirements and quality checks 5. **Formatting**: Run `pwsh ./fix.ps1` to silently apply all @@ -35,8 +35,7 @@ Perform software development tasks by determining and applying appropriate stand # Developer Agent Report **Result**: (SUCCEEDED|FAILED) - -## Work Summary +**Report**: `.agent-logs/developer-{subject}-{unique-id}.md` - **Files Modified**: {List of files created/modified/deleted} - **Languages Detected**: {Languages identified} diff --git a/.github/agents/formal-review.agent.md b/.github/agents/formal-review.agent.md index 7dd8e84..cb78ddf 100644 --- a/.github/agents/formal-review.agent.md +++ b/.github/agents/formal-review.agent.md @@ -31,12 +31,14 @@ standards from the selection matrix in AGENTS.md. 1. Download the review checklist from . If the download fails, report the failure rather than proceeding without the template. -2. Use `dotnet reviewmark --elaborate {review-set}` to get the files to review -3. Review all files holistically, checking for cross-file consistency and - compliance with the review checklist -4. Save the populated review checklist to `.agent-logs/reviews/review-report-{review-set}.md`. +2. Run `dotnet reviewmark --elaborate {review-set}`. Read all files listed under + `## Context` first — these are reference material, not under review — then review + all files listed under `## Files` holistically, using the context to understand + the intended role and scope within the broader system, and checking for cross-file + consistency and compliance with the review checklist. +3. Save the populated review checklist to `.agent-logs/reviews/review-report-{review-set}.md`. This directory holds formal review artifacts, not agent logs. -5. Generate a completion report per the AGENTS.md reporting requirements. +4. Generate a completion report per the AGENTS.md reporting requirements. # Report Template @@ -44,6 +46,7 @@ standards from the selection matrix in AGENTS.md. # Formal Review Report **Result**: (SUCCEEDED|FAILED) +**Report**: `.agent-logs/formal-review-{subject}-{unique-id}.md` ## Review Summary diff --git a/.github/agents/implementation.agent.md b/.github/agents/implementation.agent.md index 7cc0352..d94e880 100644 --- a/.github/agents/implementation.agent.md +++ b/.github/agents/implementation.agent.md @@ -28,36 +28,18 @@ The state-transitions include retrying a limited number of times: ## PLANNING State (start) -Call the **explore** agent as a sub-agent (built-in agent type) with: +Call the **planning** agent as a sub-agent (custom agent from `.github/agents/`) with: - **context**: the user's request + any previous quality findings + retry context -- **goal**: produce a verified implementation plan through these steps: - - 1. Investigate the codebase and develop a concrete implementation plan that - addresses the request - 2. **Identify companion artifact deliverables**: for every code change in the - plan, list the requirements files, design documents, and review-set entries - that must be created or updated - traceability must flow requirements → - design → code, so these are mandatory deliverables, not optional extras - 3. Review the plan for assumptions, weaknesses, and gaps - identify up to 5 - key assumptions and rate each as: - - **VERIFIED**: confirmed by codebase evidence - - **LIKELY**: consistent with codebase patterns but not directly confirmed - - **UNVERIFIED**: not confirmed by any evidence - 4. For any assumption rated UNVERIFIED or LIKELY, attempt to resolve it - through additional investigation and revise the plan to address identified - weaknesses - repeat the critique-and-strengthen cycle up to 2 additional - times if unresolved issues remain, but stop as soon as the plan is stable - 5. List up to 5 risks to the implementation - 6. Assess feasibility: can this be implemented in a single development pass? - 7. State a **recommendation**: GO or INCOMPLETE - GO if the plan is sound, or - INCOMPLETE if critical unknowns remain that only the user can resolve - -Once the explore sub-agent finishes: - -- IF recommendation is INCOMPLETE: Transition to REPORT with Result: INCOMPLETE, +- **goal**: produce a verified implementation plan, or a targeted plan to address + the identified quality issues if this is a retry + +Once the planning sub-agent finishes: + +- IF Result is FAILED: Transition to REPORT with Result: FAILED +- IF Result is INCOMPLETE: Transition to REPORT with Result: INCOMPLETE, listing the unknowns and what CAN be implemented once they are resolved -- OTHERWISE (GO): Transition to DEVELOPMENT +- OTHERWISE (SUCCEEDED): Transition to DEVELOPMENT ## DEVELOPMENT State @@ -76,7 +58,8 @@ Once the developer sub-agent finishes: Call the **quality** agent as a sub-agent (custom agent from `.github/agents/`) with: -- **context**: the user's request + development summary + files changed + previous issues (if any) +- **context**: the user's request + development summary + files changed + planning companion artifact table + + previous issues (if any) - **goal**: check the quality of the work performed for any issues Once the quality sub-agent finishes: @@ -92,6 +75,9 @@ Once the quality sub-agent finishes: this agent may report INCOMPLETE when the request cannot be implemented without information only the user can provide. +For full planning details (assumptions, risks, feasibility), read the planning +report file referenced in the planning agent's response. + Generate the completion report using the template below, then save it to `.agent-logs/{agent-name}-{subject}-{unique-id}.md` per the AGENTS.md reporting requirements, and return the summary to the caller. @@ -102,19 +88,20 @@ requirements, and return the summary to the caller. # Implementation Orchestration Report **Result**: (SUCCEEDED|FAILED|INCOMPLETE) -**Final State**: (PLANNING|DEVELOPMENT|QUALITY|REPORT) +**Report**: `.agent-logs/implementation-{subject}-{unique-id}.md` +**Last Active State**: (PLANNING|DEVELOPMENT|QUALITY) **Retry Count**: ## State Machine Execution -- **Planning Results**: {Implementation plan, assumption ratings, risks, and recommendation} +- **Planning Results**: {Planning report path; plan summary and SUCCEEDED/INCOMPLETE/FAILED result} - **Development Results**: {Summary of developer agent results} - **Quality Results**: {Summary of quality agent results} - **State Transitions**: {Log of state changes and decisions} ## Sub-Agent Coordination -- **Explore Agent (Planning)**: {Plan, assumption verdicts, top risks, GO/INCOMPLETE recommendation} +- **Planning Agent**: {Report file path, SUCCEEDED/INCOMPLETE/FAILED result, plan summary} - **Developer Agent**: {Development status and files modified} - **Quality Agent**: {Validation results and compliance status} @@ -123,4 +110,9 @@ requirements, and return the summary to the caller. - **Implementation Success**: {Overall completion status} - **Quality Compliance**: {Final quality validation status} - **Issues Resolved**: {Problems encountered and resolution attempts} + +## Unknowns (only when Result is INCOMPLETE) + +- **Unresolved Questions**: {List each question the user must answer} +- **What Can Proceed**: {Work that can be done without the missing information} ``` diff --git a/.github/agents/lint-fix.agent.md b/.github/agents/lint-fix.agent.md index 549e751..36d3ca1 100644 --- a/.github/agents/lint-fix.agent.md +++ b/.github/agents/lint-fix.agent.md @@ -68,8 +68,7 @@ submission, not during normal development. # Lint Fix Report **Result**: (SUCCEEDED|FAILED) - -## Summary +**Report**: `.agent-logs/lint-fix-{subject}-{unique-id}.md` - **Iterations**: {Number of fix-loop iterations performed} - **Files Modified**: {List of all files changed} diff --git a/.github/agents/planning.agent.md b/.github/agents/planning.agent.md new file mode 100644 index 0000000..20e75ee --- /dev/null +++ b/.github/agents/planning.agent.md @@ -0,0 +1,134 @@ +--- +name: planning +description: Planning agent that investigates the codebase, develops a verified implementation plan, and identifies all companion artifact deliverables. +user-invocable: true +--- + +# Planning Agent + +Investigate the codebase and produce a verified implementation plan with all +companion artifact deliverables. + +## Step 1 — Load Standards + +Read the relevant standards from `.github/standards/` using the selection matrix +in `AGENTS.md` based on the artifact types in scope for the request (requirements, +design, verification, documentation, code). + +## Step 2 — Investigate and Plan + +Read `docs/design/introduction.md` first (if present), then investigate the +codebase to develop a concrete implementation plan: + +- Identify all files to create, modify, or delete +- Describe the change required for each file + +## Step 3 — Identify Companion Artifact Deliverables + +For each planned change, assess the mandatory companion artifacts below (create/update/N/A +with justification): + +- **Requirements** — functional changes require a requirement entry +- **Design Documentation** — new or changed components require design docs +- **Verification Documentation** — new or changed components require verification docs +- **Tests** — functional changes require test coverage +- **Review Sets** — changes to the software item hierarchy (units or subsystems + added, removed, or reorganized) require review-set updates +- **README.md** — user-facing changes require README updates +- **User Guide** — user-facing features require user guide updates + +## Step 4 — Critique and Strengthen + +Identify up to 5 key assumptions and rate each: + +- **VERIFIED**: confirmed by codebase evidence +- **LIKELY**: consistent with codebase patterns but not directly confirmed +- **UNVERIFIED**: not confirmed by any evidence + +For UNVERIFIED or LIKELY assumptions, investigate further and revise the plan. +Repeat up to 2 more times, stopping when the plan is stable. + +## Step 5 — Risk Assessment + +List up to 5 risks with a brief mitigation for each. + +## Step 6 — Feasibility Assessment + +State whether this can be implemented in a single development pass and any +preconditions that affect feasibility. + +## Step 7 — Recommendation + +- **SUCCEEDED** — the plan is sound and the developer agent can proceed +- **INCOMPLETE** — critical unknowns remain that only the user can resolve; + list each unknown explicitly +- **FAILED** — investigation could not produce a viable plan + +# REPORT Phase + +Save the full analysis to `.agent-logs/planning-{subject}-{unique-id}.md` per +the AGENTS.md reporting requirements. + +Then respond to the caller with ONLY the lean structured summary below. + +# Report Template + +```markdown +# Planning Report + +**Result**: (SUCCEEDED|INCOMPLETE|FAILED) +**Request Summary**: {Brief restatement of the task as understood} +**Report**: `.agent-logs/planning-{subject}-{unique-id}.md` + +## Implementation Plan + +| File | Action | Description | +|------|--------|-------------| +| {path} | create/modify/delete | {what changes and why} | + +## Companion Artifact Deliverables + +| Category | File | Action | +|----------|------|--------| +| Requirements | {path} | create/update/N/A — {justification} | +| Design Documentation | {path} | create/update/N/A — {justification} | +| Verification Documentation | {path} | create/update/N/A — {justification} | +| Tests | {path} | create/update/N/A — {justification} | +| Review Sets | {path} | create/update/N/A — {justification} | +| README.md | {path} | create/update/N/A — {justification} | +| User Guide | {path} | create/update/N/A — {justification} | + +## Assumption Analysis + +| # | Assumption | Rating | Resolution | +|---|-----------|--------|------------| +| 1 | {assumption} | VERIFIED/LIKELY/UNVERIFIED | {resolution or N/A} | + +## Risk Assessment + +1. **[severity]** {risk} — {mitigation} + +## Feasibility Assessment + +{Single-pass or not, and why. Any preconditions.} + +## Unknowns + +{Only present when Result is INCOMPLETE. List each question the user must +resolve before implementation can proceed.} +``` + +# Lean Structured Response (returned to caller) + +```markdown +**Result**: (SUCCEEDED|INCOMPLETE|FAILED) +**Report**: `.agent-logs/planning-{subject}-{unique-id}.md` + +**Plan**: +{Repeat the Implementation Plan table} + +**Companion Artifacts**: +{Repeat the Companion Artifact Deliverables table} + +**Unknowns**: {Only if INCOMPLETE — list questions for the user} +``` diff --git a/.github/agents/quality.agent.md b/.github/agents/quality.agent.md index 380d11f..26fd251 100644 --- a/.github/agents/quality.agent.md +++ b/.github/agents/quality.agent.md @@ -13,14 +13,23 @@ Grade and validate software development work by ensuring compliance with project 1. **Analyze the task request AND completed work** to determine scope: identify which artifact categories were changed, and which *should have been changed* given the task - new user-visible features always require requirements, - design, and review-set coverage regardless of whether those files were touched; - test-only additions (corner-case tests, defensive boundary tests, regression - tests) do not require a corresponding requirement + design, verification docs, and README/user guide updates regardless of + whether those files were touched; Review Sets are always in scope when + the software item hierarchy changes (units or subsystems added, removed, or + reorganized); test-only additions (corner-case tests, defensive boundary + tests, regression tests) do not require a corresponding requirement; if a + planning companion artifact table is provided in context, cross-reference it + — any artifact listed as create/update must be covered in the evaluation and + FAIL if the artifact was not produced 2. **Read relevant standards** using the selection matrix in AGENTS.md 3. **Evaluate all in-scope categories** - N/A only when the task genuinely cannot affect a category; if the task introduces new user-visible features or - structural changes then Requirements, Design Documentation, and Review - Management are always in scope and FAIL if the artifacts were not updated + structural changes then Requirements, Design Documentation, and Verification + Documentation are always in scope and FAIL if the artifacts were not updated; + Documentation (README/user guide) is always in scope for user-facing changes + and FAIL if not updated; Review Sets are always in scope when the + software item hierarchy changes (units or subsystems added, removed, or + reorganized) and FAIL if review-sets were not updated 4. **Validate tool compliance** using ReqStream, ReviewMark, and build tools 5. **Generate focused quality report** per the AGENTS.md reporting requirements - save to `.agent-logs/{agent-name}-{subject}-{unique-id}.md` and return the summary to the caller @@ -36,6 +45,7 @@ For each checklist item in the template below, record as `(PASS|FAIL|N/A) - {one # Quality Assessment Report **Result**: (SUCCEEDED|FAILED) +**Report**: `.agent-logs/quality-{subject}-{unique-id}.md` **Overall Grade**: (PASS|FAIL) ## Required Fixes (only when Result is FAILED) @@ -50,13 +60,13 @@ Priority-ordered list of issues that MUST be resolved for the next retry: - **Evaluated**: {List sections assessed and why} - **Skipped**: {One-line per skipped section with reason, e.g., "Design - Documentation: N/A - no design files modified"} + Documentation: N/A - no component behavior, structure, or interface changed"} ## Requirements Compliance: (PASS|FAIL|N/A) - Were requirements created/updated for all functional changes? - Were source filters applied for platform-specific requirements? -- Is requirements traceability maintained to tests? +- Is forward traceability from requirements to verification artifacts preserved? ## Design Documentation Compliance: (PASS|FAIL|N/A) @@ -80,7 +90,14 @@ Priority-ordered list of issues that MUST be resolved for the next retry: - Are cross-hierarchy test dependencies documented in design docs? - Do all tests pass? -## Review Management Compliance: (PASS|FAIL|N/A) +## Verification Documentation Compliance: (PASS|FAIL|N/A) + +- Were verification documents created/updated for all new or changed components? +- Do verification documents include all mandatory sections (Verification Approach, Test Environment, + Acceptance Criteria, Test Scenarios)? +- Is requirements-to-test coverage tracked via the ReqStream trace matrix (not embedded in verification docs)? + +## Review Sets Compliance: (PASS|FAIL|N/A) - Were review-sets updated for structural changes? - Is review scope appropriate for change magnitude? diff --git a/.github/agents/template-sync.agent.md b/.github/agents/template-sync.agent.md index c013503..baf5fa8 100644 --- a/.github/agents/template-sync.agent.md +++ b/.github/agents/template-sync.agent.md @@ -21,13 +21,21 @@ Delegate each group to a sub-agent. # Work Groups - **Root config files** - all non-collection files at the repository root +- **`docs/sysml2/`** - SysML2 model files and rendered views (root-level flat folder, + not a Pandoc collection) - **One group per flat `docs/` folder** - e.g. `docs/build_notes/`, `docs/user_guide/` +- **One group for root files in each of `docs/design/`, `docs/verification/`, + `docs/reqstream/`** - e.g. `docs/design/introduction.md` — separate from the + system subtrees beneath them - **One group per system subtree** in `docs/design/`, `docs/verification/`, `docs/reqstream/` - each subtree and all its descendants is one group # Orchestration -For each group intersecting the requested scope, call a sub-agent with: +For Audit mode, call an **explore** sub-agent (built-in) per group. +For Sync, Scaffold, and Recreate modes, call a **general-purpose** sub-agent (built-in) per group. + +For each group intersecting the requested scope, call the appropriate sub-agent with: - **context**: - Group scope and template URL from the `# Reference Template` section in `AGENTS.md` @@ -40,7 +48,10 @@ For each group intersecting the requested scope, call a sub-agent with: each item is a subsystem or unit, then select the appropriate template (`subsystem-name.*` or `unit-name.*`) regardless of the item's folder depth — do not infer item type from path depth alone - - If a template counterpart cannot be fetched, skip the file and report it + - If a file has no template counterpart, skip it and report it as + "No template found" — this is not a failure + - If a file appears in `repository-map.md` but its template cannot be fetched, + report Result: FAILED and list the affected files - **goal**: - Based on the given mode: - **Audit** - fetch each template counterpart; compare headings; report missing @@ -78,9 +89,25 @@ For each group intersecting the requested scope, call a sub-agent with: `TODO:` placeholders in YAML string values (e.g. `title:`, `justification:`) are content placeholders — always resolve them to real content; infer from README, related files, sibling docs, and path; if confident write directly; - if ambiguous offer 2–3 concrete options and ask the user; keep asking until - they answer - never leave a TODO or TEMPLATE-DIRECTIVE in the output unless - the user explicitly requests it + if ambiguous, **do not ask interactively** — return the unresolved questions + in the result so the orchestrator can ask the user and re-invoke; never leave + a TODO or TEMPLATE-DIRECTIVE in the output unless the user explicitly requests it + - Return results in this format for each file in the group: + + ```markdown + ### {file-path} + + - **Template**: {template path or "not found"} + - **Missing sections**: {list or "none"} + - **Heading depth issues**: {list or "none"} + - **Content format issues**: {list or "none"} *(Recreate only)* + - **Action**: (Reported | Sections added | Created | Rebuilt | No template found) + - **Unresolved Questions**: {list or "none"} + ``` + +If any sub-agent returns unresolved questions, collect them, ask the user, then +re-invoke the affected sub-agent(s) with the answers before assembling the final report. +If questions remain unresolved after asking the user, report Result: INCOMPLETE. Collect sub-agent results and assemble the final report. @@ -89,7 +116,8 @@ Collect sub-agent results and assemble the final report. ```markdown # Template Sync Report -**Result**: (SUCCEEDED|FAILED) +**Result**: (SUCCEEDED|FAILED|INCOMPLETE) +**Report**: `.agent-logs/template-sync-{subject}-{unique-id}.md` **Mode**: (Audit|Sync|Scaffold|Recreate) ## Files @@ -102,8 +130,13 @@ Collect sub-agent results and assemble the final report. - **Content format issues**: {list of sections where intra-section content did not match the template comment's prescribed format, or "none"} *(Recreate only)* - **Action**: (Reported | Sections added | Created | Rebuilt | No template found) +- **Unresolved Questions**: {list or "none"} ## Summary - **Conformant**: {count} | **Deviations**: {count} | **Updated**: {count} + +## Unknowns (only when Result is INCOMPLETE) + +- **Unresolved Questions**: {List each placeholder or ambiguity the user must resolve} ``` diff --git a/.github/skills/sysml2tools-query/SKILL.md b/.github/skills/sysml2tools-query/SKILL.md new file mode 100644 index 0000000..f754338 --- /dev/null +++ b/.github/skills/sysml2tools-query/SKILL.md @@ -0,0 +1,145 @@ +--- +name: sysml2tools-query +description: Query this repository's SysML2 architecture model (docs/sysml2/) to understand software structure, purpose, and relationships before deep-diving into source code. Use this when asked to understand the codebase, find which unit implements something, assess the impact of a change, or trace requirements to code. +--- + +# SysML2Tools Query Skill + +This repository models its software structure in SysML2 under `docs/sysml2/`. Prefer +querying this model over grepping/reading source files when you need to understand +*what* a piece of the system is, *why* it exists, or *what it depends on*. + +## Prerequisites + +The `sysml2tools` CLI is a local .NET tool pinned in `.config/dotnet-tools.json`. +Restore it once per session if not already available: + +```pwsh +dotnet tool restore +``` + +## Model files + +- `docs/sysml2/model/{system-name}.sysml` — system-level `part def` only (no subsystems/units + inline). A repository may contain more than one system. +- `docs/sysml2/model/{system-name}/{subsystem-name}.sysml` and + `docs/sysml2/model/{system-name}/{subsystem-name}/{unit-name}.sysml` — one file per + Subsystem/Unit, nested to mirror the same folder depth as that item's companion + `docs/design/`, `docs/reqstream/`, and `docs/verification/` files. +- `docs/sysml2/model/ots.sysml` — off-the-shelf (OTS) dependency parts (present when OTS items + exist). +- `docs/sysml2/model/shared.sysml` — Shared Package parts (present when Shared Package items + exist). +- `docs/sysml2/views/design-views.sysml` — named views rendered for the design document; a + sibling of `model/`, not nested inside it. Not usually needed for query workflows, but + useful to see how diagrams are scoped. + +Always pass all `.sysml` files (or a glob covering them) to every `sysml2tools` +invocation — the model spans multiple files and cross-references between them; files that +reopen the same `package Name { ... }` from different files merge into one namespace +automatically, no `import` required. As of `sysml2tools` 0.1.0-beta.5, every subcommand +(`lint`, `render`, `query`) expands `*`/`**` glob patterns internally and recurses +correctly — pass a single **quoted** glob string and let the tool resolve it, rather than +relying on the shell (quoting works identically in both PowerShell and bash): + +```pwsh +dotnet sysml2tools query list 'docs/sysml2/model/**/*.sysml' +``` + +## Artifact-location metadata + +Every System/Subsystem/Unit `part def` carries named `comment` elements pointing at its +companion artifacts (source, test, design, verification, and — for repositories that still +use ReqStream — requirements file). `query describe` returns every comment attached to +an element, so one query gets you every artifact location for that item without grepping the +source tree: + +```pwsh +dotnet sysml2tools query describe -e {SystemName}::{UnitName} 'docs/sysml2/model/**/*.sysml' +``` + +```text +- Documentation: One-line purpose statement for the unit. +- Comment: Source: src/{Project}/{Subsystem}/{UnitName}.cs +- Comment: Test: test/{Project}.Tests/{Subsystem}/{UnitName}Tests.cs +- Comment: Design: docs/design/{system-name}/{subsystem-name}/{unit-name}.md +- Comment: Verification: docs/verification/{system-name}/{subsystem-name}/{unit-name}.md +- Comment: Requirements: docs/reqstream/{system-name}/{subsystem-name}/{unit-name}.yaml +``` + +Not every item has all five comments — Systems/Subsystems have no `Source` comment, and +units without a dedicated companion doc point at their parent's doc instead (see the +Artifact-Location Comments section of `sysml2-modeling.md` for the full rules). Prefer these +paths over guessing a file location from the unit name; fall back to `grep`/`glob` only when +a comment is missing or the model is stale. + +## Recommended workflow + +1. **Discover the system(s) present** — do not assume a fixed name: + + ```pwsh + dotnet sysml2tools query list --kind "part def" 'docs/sysml2/model/**/*.sysml' + ``` + + Look for the top-level part def with no containing part (or the one with the most + children) to identify each system's qualified name. + +2. **Get the full hierarchy** (subsystems and units) for a system found above: + + ```pwsh + dotnet sysml2tools query describe -e 'docs/sysml2/model/**/*.sysml' + ``` + + `describe` lists direct children and every artifact-location comment; repeat on each + child to walk deeper, or use `query list` to see the full flat inventory. + +3. **Understand a specific unit's purpose and find its files** before opening its source + file — `describe` returns both the purpose `doc` and every `Comment:` artifact-location + line in one call (see Artifact-location metadata above): + + ```pwsh + dotnet sysml2tools query describe -e 'docs/sysml2/model/**/*.sysml' + ``` + +4. **Assess impact before editing a unit** — see what depends on it: + + ```pwsh + dotnet sysml2tools query used-by -e 'docs/sysml2/model/**/*.sysml' + dotnet sysml2tools query impact -e 'docs/sysml2/model/**/*.sysml' + ``` + + Note: this only surfaces structural (typing/containment) references modeled in + `.sysml` — not full call-graph/behavioral dependencies. Confirm actual usage in source + before making impact-sensitive changes. + +5. **Trace requirements** linked to a unit, if modeled: + + ```pwsh + dotnet sysml2tools query requirements -e 'docs/sysml2/model/**/*.sysml' + ``` + +6. **Search by name or kind** when the qualified name is unknown: + + ```pwsh + dotnet sysml2tools query find --name 'docs/sysml2/model/**/*.sysml' + dotnet sysml2tools query list --kind "part def" 'docs/sysml2/model/**/*.sysml' + ``` + +Use `--format json` on any query verb for machine-parsed output. + +## Fallback + +If the model is stale, doesn't yet cover a unit, or a query returns nothing useful, fall +back to `grep`/`glob`/reading source directly. When you finish work that adds or changes a +Unit/Subsystem, update the corresponding `.sysml` model file (including its artifact-location +comments) in the same change (mirrors the existing requirement to keep `docs/design/*.md` and +`docs/reqstream/*.yaml` companion artifacts in sync). See the `sysml2-modeling.md` +standard for full modeling and view-authoring conventions. + +## Validating changes to the model + +Before committing changes to any `.sysml` file, lint it: + +```pwsh +dotnet sysml2tools lint 'docs/sysml2/**/*.sysml' +``` diff --git a/.github/standards/design-documentation.md b/.github/standards/design-documentation.md index e5b7bf9..c6f107f 100644 --- a/.github/standards/design-documentation.md +++ b/.github/standards/design-documentation.md @@ -8,6 +8,8 @@ globs: ["docs/design/**/*.md"] - **`technical-documentation.md`** - General technical documentation standards - **`software-items.md`** - Software categorization (System/Subsystem/Unit/OTS/Shared Package) +- **`sysml2-modeling.md`** - SysML2 model and view conventions feeding the Software Structure + section # Folder Structure @@ -30,7 +32,6 @@ docs/design/ All sections in every file are mandatory; write "N/A - {justification}" rather than removing any. Determine subsystem vs. unit classification from `docs/design/introduction.md` — folder depth does not determine classification. -Do not record version numbers anywhere in design documentation — version information is managed in SBOMs. # introduction.md (MANDATORY) @@ -38,7 +39,8 @@ Must include: - **Purpose**: audience and compliance drivers - **Scope**: items covered and explicitly excluded (no test projects) -- **Software Structure**: text tree showing all Systems/Subsystems/Units/OTS/Shared items +- **Software Structure**: diagram(s) rendered from the SysML2 model under `docs/sysml2/`, + per `sysml2-modeling.md` — not a hand-maintained text tree - **Folder Layout**: text tree showing source folder structure - **Companion Artifact Structure**: parallel paths for requirements, design, verification, source, tests - **References** _(if applicable)_: external standards or specifications - only in `introduction.md` @@ -98,6 +100,12 @@ For each Shared Package, create `docs/design/shared/{package-name}.md` (`##` hea - Use Mermaid diagrams to supplement (not replace) text - Use verbal cross-references ("see _Parser Design_") - not markdown hyperlinks (break in PDF) - Provide sufficient detail for formal code review +- Do not record version numbers in design documentation — they go stale with dependency updates and + are managed in SBOMs. Version numbers are pinned release versions (e.g., `1.2.3`, `v2.0.1`). + The following are **not** version numbers and are permitted: + - Language/platform standards: `netstandard2.0`, `net10.0`, `C++20`, `C# 12` (stable standard identifiers) + - Protocol standards: `TLS 1.3`, `HTTP/2` (stable specifications) + - Placeholders: `0.0.0` (signals "not yet assigned") # Quality Checks diff --git a/.github/standards/reviewmark-usage.md b/.github/standards/reviewmark-usage.md index b521433..bc73da6 100644 --- a/.github/standards/reviewmark-usage.md +++ b/.github/standards/reviewmark-usage.md @@ -21,71 +21,86 @@ review, organizes them into review-sets, and generates review plans and reports. - **Lint Configuration**: `dotnet reviewmark --lint` - **Elaborate Review-Set**: `dotnet reviewmark --elaborate {review-set}` - **Generate Plan**: `dotnet reviewmark --plan docs/code_review_plan/generated/plan.md --enforce` - -> **Note**: `--enforce` causes the plan to fail with a non-zero exit code if any repository -> files are not covered by a review-set. Uncovered files indicate a gap in review-set -> configuration that should be addressed. + (exits non-zero if any files are uncovered) ## Repository Structure -Required repository items for ReviewMark operation: - - `.reviewmark.yaml` - Configuration for review-sets, file-patterns, and review evidence-source. -- `docs/code_review_plan/generated/` - Generated review plan (build output, do not edit) -- `docs/code_review_report/generated/` - Generated review report (build output, do not edit) # Review Definition Structure Configure reviews in `.reviewmark.yaml` at repository root: ```yaml -# Patterns identifying all files that require review needs-review: - # Include source code (adjust file extensions for your repo) - - "**/*.cs" # C# source files - - "**/*.cpp" # C++ source files - - "**/*.hpp" # C++ header files - - "!**/bin/**" # Generated source in build outputs - - "!**/obj/**" # Generated source in build intermediates - - # Include requirement files - - "requirements.yaml" # Root requirements file - - "docs/reqstream/**/*.yaml" # Requirements files - - # Include critical documentation files - - "README.md" # Root level README - - "docs/user_guide/**/*.md" # User guide - - "docs/design/**/*.md" # Design documentation - - "docs/verification/**/*.md" # Verification design documentation - -# Source of review evidence + - "**/*.cs" + - "**/*.cpp" + - "**/*.hpp" + - "!**/bin/**" + - "!**/obj/**" + - "requirements.yaml" + - "docs/reqstream/**/*.yaml" + - "docs/sysml2/**/*.sysml" + - "README.md" + - "docs/user_guide/**/*.md" + - "docs/design/**/*.md" + - "docs/verification/**/*.md" + evidence-source: type: none -# Review-sets (each focuses on a single compliance question) +context: + - docs/design/introduction.md + reviews: - id: Purpose - title: Review of user-facing capabilities and system promises + title: Review that README and User Guide are Coherent and Complete paths: - "README.md" - "docs/user_guide/**/*.md" - - "docs/reqstream/{system-name}.yaml" + - id: Decomposition + title: Review that {SystemName} Decomposition Addresses the Stated Purpose + context: + - "README.md" + - "docs/user_guide/**/*.md" + paths: + - "requirements.yaml" - "docs/design/introduction.md" - - "docs/design/{system-name}.md" ``` -# Review-Set Design Principles +For a complete annotated example with template directives, see `.reviewmark.yaml` in the +reference template (`{template-url}/.reviewmark.yaml` per `AGENTS.md`). -When constructing review-sets, follow these principles to maintain manageable scope and effective compliance evidence: +# Review-Set Design Principles - **Hierarchical Scope**: Higher-level reviews exclude lower-level implementation details, relying instead on design documents to describe what components they use. System reviews exclude subsystem/unit details, subsystem reviews exclude unit source code, only unit reviews include actual implementation. - **Single Focus**: Each review-set proves one specific compliance question (user promises, system architecture, design consistency, etc.) +- **Parent Context**: Unit and subsystem reviews include parent design and requirements as + context so reviewers understand the intended role and scope; see the Context Files section. - **Context Management**: Keep file counts manageable to prevent context overflow while maintaining complete coverage through the hierarchy +# Context Files + +Context files are shown to reviewers for orientation but not fingerprinted. Add a top-level +`context:` key for global context (every reviewer) and a per-review-set `context:` between +`title:` and `paths:` for review-specific context. Always include `docs/design/introduction.md` +as global context. + +| Review Type | Context to add | +| :---------- | :------------- | +| `Decomposition` | `README.md`, `docs/user_guide/**/*.md` | +| `{SystemName}-Architecture` | `README.md`, `docs/user_guide/**/*.md` | +| `{SystemName}-Design` | `docs/reqstream/{system-name}.yaml` | +| `{SystemName}-Verification` | `docs/reqstream/{system-name}.yaml` | +| `{SystemName}-AllRequirements` | Parent system design doc + `docs/reqstream/{system-name}.yaml` | +| `{SystemName}-{UnitName}` (direct unit) | Parent system design doc + parent system requirements | +| `{SystemName}-{SubsystemName}` (subsystem) | Parent system design doc + parent system requirements | +| `{SystemName}-{SubsystemName}-{UnitName}` (unit under subsystem) | System + subsystem design docs + requirements | + # Review-Set Organization **Naming conventions**: Placeholders in documentation, requirements, design, and @@ -96,23 +111,30 @@ placeholders are always PascalCase (e.g., `{SystemName}`). ## `Purpose` Review (only one per repository) -Reviews user-facing capabilities and system promises: - -- **Purpose**: Proves that the systems provide the capabilities the user is being told about -- **Title**: "Review that Advertised Features Match System Design" -- **Scope**: Excludes subsystem and unit files, relying on system-level design documents - to describe what subsystems and units they use +- **Purpose**: Proves that the user-facing docs are coherent and complete — the north-star for the hierarchy +- **Title**: "Review that README and User Guide are Coherent and Complete" +- **ID**: `Purpose` (no system prefix — one per repository) +- **Scope**: README and user_guide only; no requirements or design files - **File Path Patterns**: - README: `README.md` - User guide: `docs/user_guide/**/*.md` - - System requirements: `docs/reqstream/{system-name}.yaml` + +## `Decomposition` Review (only one per repository) + +- **Purpose**: Proves that the software items tree breakdown logically addresses the user-facing + promise; the structural mirror of the decomposition decision +- **Title**: "Review that {SystemName} Decomposition Addresses the Stated Purpose" +- **ID**: `Decomposition` (no system prefix — one per repository) +- **Scope**: introduction.md (the decomposition narrative), the SysML2 model (the + authoritative structural tree), and requirements.yaml; no system-level detail +- **File Path Patterns**: + - Root requirements: `requirements.yaml` - Design introduction: `docs/design/introduction.md` - - System design: `docs/design/{system-name}.md` + - SysML2 model: `docs/sysml2/**/*.sysml` +- **Context Files**: `README.md`, `docs/user_guide/**/*.md` ## `{SystemName}-Architecture` Review (one per system) -Reviews system architecture and operational validation: - - **Purpose**: Proves that the system is designed and tested to satisfy its requirements - **Title**: "Review that {SystemName} Architecture Satisfies Requirements" - **Scope**: Excludes subsystem and unit files, relying on system-level design to describe @@ -124,16 +146,15 @@ Reviews system architecture and operational validation: - Verification introduction: `docs/verification/introduction.md` - System verification design: `docs/verification/{system-name}.md` - System integration tests: `test/{SystemName}.Tests/{SystemName}Tests.{ext}` +- **Context Files**: `README.md`, `docs/user_guide/**/*.md` ## `{SystemName}-Design` Review (one per system) -Reviews architectural and design consistency: - - **Purpose**: Proves the system design is consistent and complete - **Title**: "Review that {SystemName} Design is Consistent and Complete" - **Scope**: Only brings in top-level requirements and relies on brevity of design documentation +- **Context Files**: `docs/reqstream/{system-name}.yaml` - **File Path Patterns**: - - System requirements: `docs/reqstream/{system-name}.yaml` - Platform requirements: `docs/reqstream/{system-name}/platform-requirements.yaml` - Design introduction: `docs/design/introduction.md` - System design: `docs/design/{system-name}.md` @@ -143,13 +164,11 @@ Reviews architectural and design consistency: ## `{SystemName}-Verification` Review (one per system) -Reviews verification completeness and consistency: - - **Purpose**: Proves the system verification design is consistent and covers all requirements - **Title**: "Review that {SystemName} Verification is Consistent and Complete" - **Scope**: Only brings in top-level requirements and all verification docs for the system +- **Context Files**: `docs/reqstream/{system-name}.yaml` - **File Path Patterns**: - - System requirements: `docs/reqstream/{system-name}.yaml` - Verification introduction: `docs/verification/introduction.md` - System verification: `docs/verification/{system-name}.md` - System verification files: `docs/verification/{system-name}/**/*.md` @@ -158,20 +177,15 @@ Reviews verification completeness and consistency: ## `{SystemName}-AllRequirements` Review (one per system) -Reviews requirements quality and traceability: - - **Purpose**: Proves the requirements are consistent and complete - **Title**: "Review that All {SystemName} Requirements are Complete" - **Scope**: Only brings in requirements files to keep review manageable - **File Path Patterns**: - - Root requirements: `requirements.yaml` - - System requirements: `docs/reqstream/{system-name}.yaml` - Subsystem/unit requirements: `docs/reqstream/{system-name}/**/*.yaml` +- **Context Files**: `docs/design/{system-name}.md`, `docs/reqstream/{system-name}.yaml` ## `{SystemName}-{SubsystemName}[-{SubsystemName}...]` Review (one per subsystem at any depth) -Reviews subsystem architecture and interfaces: - - **Purpose**: Proves that the subsystem is designed and tested to satisfy its requirements - **Title**: "Review that {SystemName} {SubsystemName} Satisfies Subsystem Requirements" - **Scope**: Excludes units under the subsystem, relying on subsystem design to describe @@ -181,11 +195,10 @@ Reviews subsystem architecture and interfaces: - Design: `docs/design/{system-name}[/{subsystem-name}...]/{subsystem-name}.md` - Verification design: `docs/verification/{system-name}[/{subsystem-name}...]/{subsystem-name}.md` - Tests: `test/{SystemName}.Tests[/{SubsystemName}...]/{SubsystemName}Tests.{ext}` +- **Context Files**: `docs/design/{system-name}.md`, `docs/reqstream/{system-name}.yaml` ## `{SystemName}-{SubsystemName}[-{SubsystemName}...]-{UnitName}` Review (one per unit) -Reviews individual software unit implementation: - - **Purpose**: Proves the unit is designed, implemented, and tested to satisfy its requirements - **Title**: "Review that {SystemName} {SubsystemName} {UnitName} Implementation is Correct" - **Scope**: Complete unit review including all artifacts @@ -197,11 +210,11 @@ Reviews individual software unit implementation: - Tests (C# example): `test/{SystemName}.Tests[/{SubsystemName}...]/{UnitName}Tests.cs` - Source (snake_case C++ example): `src/{system_name}[/{subsystem_name}...]/{unit_name}.cpp` - Tests (snake_case C++ example): `test/{system_name}_tests[/{subsystem_name}...]/{unit_name}_tests.cpp` +- **Context Files**: Parent system design + requirements; add subsystem design + + requirements for each subsystem level above the unit. ## `OTS-{OtsName}` Review (one per OTS item) -Reviews OTS item integration design, requirements, and verification evidence: - - **Purpose**: Proves that the OTS item provides the required functionality and is correctly integrated - **Title**: "Review that {OtsName} Provides Required Functionality" - **Scope**: No local source code; review covers integration design, requirements, and verification evidence @@ -214,8 +227,6 @@ Reviews OTS item integration design, requirements, and verification evidence: ## `Shared-{PackageName}` Review (one per Shared Package) -Reviews Shared Package integration design, requirements, and verification evidence: - - **Purpose**: Proves that the Shared Package provides the required advertised features and is correctly integrated - **Title**: "Review that {PackageName} Provides Required Features" - **Scope**: No local source code; review covers integration design, requirements, and verification evidence @@ -229,10 +240,9 @@ extensions (`.cs`, `.cpp`/`.hpp`, `.py`, etc.). Adapt to your repository's langu # Quality Checks -Before submitting ReviewMark configuration, verify: - - [ ] `.reviewmark.yaml` exists at repository root with proper structure - [ ] Review-set organization follows the standard hierarchy patterns - [ ] Each review-set focuses on a single compliance question (single focus principle) - [ ] File patterns use correct glob syntax and match intended files - [ ] Review-set file counts remain manageable (context management principle) +- [ ] Context configured per the Context Files section diff --git a/.github/standards/software-items.md b/.github/standards/software-items.md index 6c29525..3514228 100644 --- a/.github/standards/software-items.md +++ b/.github/standards/software-items.md @@ -130,3 +130,8 @@ the item is correct, well-designed, and proven to work: - **Verification Design** - HOW the requirements will be tested (applies to all item types) - **Source code** - The implementation of the design (local units only; not applicable to OTS or Shared Package) - **Tests** - PROOF the item does WHAT it is required to do (applies to all item types) + +Where the repository models its software structure in SysML2, each item's part def carries +`comment` metadata pointing at these same artifact locations (`sourceRef`/`testRef`/ +`designRef`/`verificationRef`/`reqRef`) so agents can query them directly — see +`sysml2-modeling.md`. diff --git a/.github/standards/sysml2-modeling.md b/.github/standards/sysml2-modeling.md new file mode 100644 index 0000000..c5558e1 --- /dev/null +++ b/.github/standards/sysml2-modeling.md @@ -0,0 +1,232 @@ +--- +name: SysML2 Modeling +description: Follow these standards when creating or modifying the SysML2 architecture + model, its rendered views, or the software structure it feeds into design documentation. +globs: ["docs/sysml2/**/*.sysml"] +--- + +# SysML2 Modeling Standard + +## Required Standards + +Read these standards first before applying this standard: + +- **`software-items.md`** - Software categorization (System/Subsystem/Unit/OTS/Shared Package) +- **`design-documentation.md`** - Design document structure that embeds the diagrams this + standard produces + +## Purpose + +The repository's software structure is modeled in SysML2 under `docs/sysml2/` rather than +hand-maintained as prose or an ASCII tree. The model is the authoritative, machine-queryable +source of structure; rendered diagrams and `docs/design/introduction.md`'s narrative are +generated/derived artifacts. AI agents should query the model (see `sysml2tools-query` +skill) before deep-diving into source code to understand what a piece of the system is, +why it exists, and what it depends on. + +## Repository Structure + +```text +docs/sysml2/ +├── model/ +│ ├── {system-name}.sysml # system-level part def only (no subsystems/units inline) +│ ├── {system-name}/ +│ │ ├── {subsystem-name}.sysml # subsystem part def; nests further for sub-subsystems +│ │ └── {subsystem-name}/ +│ │ └── {unit-name}.sysml # one file per unit +│ ├── ots.sysml # OTS dependency parts (optional; if OTS items exist) +│ └── shared.sysml # Shared Package parts (optional; if Shared Packages exist) +└── views/ + └── design-views.sysml # named view usages rendered for the design document +``` + +`docs/sysml2/model/` mirrors the same folder shape as `docs/design/`, `docs/reqstream/`, and +`docs/verification/` — one `.sysml` file per System/Subsystem/Unit, at the same nesting depth +as that item's companion design/requirements/verification files. This keeps each file small +and keeps PRs that touch one unit's model from producing unrelated diffs in unrelated units. +`docs/sysml2/views/` is a sibling of `model/`, not nested inside it, so a single +`docs/sysml2/model/**/*.sysml` glob never needs to exclude view files (`sysml2tools` has no +exclude-glob syntax). + +There is no separate "stable entry point" file — a repository may contain multiple systems, +so no single alias name would generalize. Agents discover the system(s) present by running +`query list --kind "part def"` or `query find` (see the `sysml2tools-query` skill) over +`docs/sysml2/model/**/*.sysml`, not by assuming a fixed name. + +Always pass the full set of `.sysml` files (or an equivalent glob) to every `sysml2tools` +invocation — the model spans multiple files and cross-references between them; files sharing +the same `package Name { ... }` merge into one namespace automatically with no `import` +required, as long as all files are passed together. As of `sysml2tools` 0.1.0-beta.5, +`lint` and `render` both expand `*`/`**` glob patterns internally (recursing correctly into +subdirectories), so pass a single **quoted** glob string (e.g. `'docs/sysml2/**/*.sysml'`) +and let the tool resolve it — do not rely on the shell to expand it, and do not quote-strip +the pattern before it reaches the tool. Quoting keeps the behavior identical across +PowerShell and bash, since neither shell needs to (or reliably does) expand `**` itself. + +## Model Content + +- `{system-name}.sysml` defines one `part def` for the System only, with `part` usages + referencing its direct Subsystems/Units (defined in their own files, see below). +- Each `{subsystem-name}.sysml` / `{unit-name}.sysml` defines exactly one `part def`, with a + `doc /* ... */` comment stating its purpose — mirroring what would otherwise be written as + prose in `docs/design/introduction.md`'s Software Structure section. Subsystem files add + `part` usages for their own direct children (nested subsystems or units), matching the + Software Item Hierarchy in `software-items.md`. +- `ots.sysml` / `shared.sysml` define one `part def` per OTS item / Shared Package, referenced + as `part` usages from the system(s) that depend on them. + +## Artifact-Location Comments + +Every System/Subsystem/Unit `part def` records where its companion artifacts live, as named +`comment` elements — not `attribute`s (attribute values are not surfaced by `sysml2tools query +describe`, even in JSON output; comments are). Comments have zero effect on rendered diagrams +(verified: a part def with several comments attached renders with no extra nodes or size +change) and are fully returned by `query describe`, in declaration order, as +`Comment: ...` summary lines — this is how an agent gets every artifact location for a unit +in a single query, without grepping the source tree. + +Use these comment names, in this order, when applicable to the item: + +```sysml +part def {UnitName} { + doc /* One-line purpose statement. */ + + comment sourceRef /* Source: {path to the unit's source file} */ + comment testRef /* Test: {path to the unit's test file} */ + comment designRef /* Design: {path to the unit's design doc} */ + comment verificationRef /* Verification: {path to the unit's verification doc} */ + comment reqRef /* Requirements: {path to the unit's reqstream file} */ +} +``` + +Not every item has all five: + +- **Systems and Subsystems** have no `sourceRef` (no single source file represents a whole + system or subsystem) — use `testRef` for the subsystem-level test file when one exists. +- **Units without a dedicated companion doc** (e.g. small data-model types documented inline + within their subsystem's design doc rather than in their own file) point `designRef` / + `verificationRef` / `reqRef` at the subsystem-level doc, with a short parenthetical note, + e.g. `/* Design: docs/design/{system}/{subsystem}.md (documented as a supporting value type) */`. +- **Units without a dedicated test file** (exercised only indirectly through another unit's + tests) omit `testRef` entirely rather than pointing at an unrelated test file. +- **OTS items** have no `sourceRef`/`testRef` (no local integration code); use `designRef` + (when the optional design doc exists) / `verificationRef` / `reqRef` only. + +This is prose-searchable metadata only — it is not a substitute for the authoritative +requirements/design/verification artifacts, and it does not replace ReqStream as the +requirements source of truth. (This repository currently keeps requirements traceability in +ReqStream; a future migration to native SysML2 `requirement`/`satisfy` modeling is a separate, +not-yet-scheduled change.) + +## Views (`docs/sysml2/views/design-views.sysml`) + +Views control what gets rendered into diagrams for the design document. Use named `view` +**usages** (not `view def` **definitions**) — `expose` is only valid inside a usage: + +```sysml +package {SystemName} { + view SoftwareStructureView { + expose {SystemName}; // whole package: system + subsystems + units + } + + view {SystemName}View { + expose {SystemName}System; // system def only, not expanded into subsystems + } + + view {SubsystemName}View { + expose {SubsystemName}; // one subsystem def only + } +} +``` + +**Critical distinction** (do not confuse these — this cost significant trial-and-error to +discover): `expose ;` is what scopes a rendered diagram's content (the union of the +named element's containment subtree). `render ;` selects a rendering *style* (e.g. +`asInterconnectionDiagram`) — it has **no effect on scope**. `expose` is only legal inside a named +`view Name { ... }` **usage**; it is a syntax/semantic error inside a `view def Name { ... }` +**definition**. `expose` targets must be `::`-qualified or locally-resolvable names, not +dotted member-access chains (`expose foo.bar;` is invalid — use `expose Bar;`). + +**Naming convention** — one `View` suffix per rendered diagram, no `System`/`Subsystem` +suffix duplication: + +- `SoftwareStructureView` - full detail: every system, subsystem, and unit in one diagram +- `{SystemName}View` - one per system, direct members only (not expanded into subsystems) +- `{SubsystemName}View` - one per subsystem (at any nesting depth), that subsystem's own + members only + +When a repository has multiple systems, `SoftwareStructureView` may expose each system's +package individually (`expose {SystemNameA}; expose {SystemNameB};`) or the whole workspace, +whichever produces a single coherent overview diagram. + +## Diagram Embedding + +Render with a single quoted recursive glob for the model tree, plus the views file +(`sysml2tools` 0.1.0-beta.5+ expands and recurses `**` internally, so no shell-side globbing +or explicit per-file listing is needed): + +```pwsh +dotnet sysml2tools render ` + --output docs/design/generated --format svg ` + 'docs/sysml2/model/**/*.sysml' ` + 'docs/sysml2/views/design-views.sysml' +``` + +With multiple views declared and no `--view` flag, `sysml2tools` renders every declared view +in one invocation, one file per view, using each view's own name as the filename +(`{ViewName}.svg`) — no post-render rename step is needed. + +Embed diagrams in `docs/design/` per this rule: every design doc for an item embeds the +diagram for the narrowest view that still shows that item's own immediate structure — + +- `docs/design/introduction.md` — `SoftwareStructureView.svg` (the full-detail overview) +- `docs/design/{system-name}.md` and every unit doc for a unit directly under the system + (no subsystem parent) — `{SystemName}View.svg` +- `docs/design/{system-name}/{subsystem-name}.md` and every unit doc nested under that + subsystem (at any depth) — `{SubsystemName}View.svg` + +Place the image directly under the file's top-level heading, before its first prose +subsection, e.g. `![{Name} Structure]({ViewName}.svg)`. + +## Build and Lint Integration + +- `sysml2tools lint` belongs in `lint.ps1`'s compliance-tools section, **not** as a separate + step in the CI design-document job — `lint.ps1` gates every later job (including document + generation) transitively, so linting the model there is both earlier and non-duplicated. + Pass a single quoted recursive glob, e.g. `dotnet sysml2tools lint 'docs/sysml2/**/*.sysml'` + — `sysml2tools` (0.1.0-beta.5+) expands and recurses this itself, so no + `Get-ChildItem`/shell-side globbing is needed. +- The CI design-document job renders the views (see the render command above) before running + Pandoc, so generated SVGs exist before HTML generation. Rename/stable-filename workarounds + are unnecessary since view names are stable by definition. Pass the model and views globs as + separate quoted arguments (e.g. `'docs/sysml2/model/**/*.sysml' 'docs/sysml2/views/design-views.sysml'`) + — plain PowerShell (the default shell) is sufficient; no `shell: bash`/`shopt -s globstar` + workaround is needed. +- Add `sysml2tools` to `.config/dotnet-tools.json` (`demaconsulting.sysml2tools.tool`) and to + `.versionmark.yaml`'s captured tool list. + +## Fallback + +If the model is stale, doesn't yet cover an item, or a query returns nothing useful, fall +back to `grep`/`glob`/reading source directly. When work adds or changes a Unit/Subsystem, +update the corresponding `.sysml` model file in the same change — this mirrors the existing +requirement to keep `docs/design/*.md` and `docs/reqstream/*.yaml` companion artifacts in +sync. + +## Quality Checks + +- [ ] Every System/Subsystem/Unit in `docs/design/introduction.md` has a matching `part def` + in its own file under `docs/sysml2/model/`, at the same folder depth as its companion + design/reqstream/verification files, with a purpose `doc` comment +- [ ] Every Unit-level `part def` has `sourceRef`/`testRef`/`designRef`/`verificationRef`/ + `reqRef` comments where applicable (see Artifact-Location Comments for documented + exceptions); System/Subsystem `part def`s have `testRef`/`designRef`/`verificationRef`/ + `reqRef` but no `sourceRef` +- [ ] `docs/sysml2/views/design-views.sysml` uses `view Name { expose ...; }` usages, not + `view def` definitions +- [ ] View names follow the `SoftwareStructureView` / `{SystemName}View` / + `{SubsystemName}View` convention +- [ ] `sysml2tools lint` passes on all `.sysml` files +- [ ] Rendered diagrams are embedded in every design doc per the Diagram Embedding rule +- [ ] `sysml2tools` is present in `lint.ps1`, `.config/dotnet-tools.json`, and + `.versionmark.yaml` diff --git a/.github/standards/technical-documentation.md b/.github/standards/technical-documentation.md index a413657..23893bd 100644 --- a/.github/standards/technical-documentation.md +++ b/.github/standards/technical-documentation.md @@ -132,7 +132,7 @@ Instead use **verbal references** - plain prose that identifies the target by na Follow `.markdownlint-cli2.yaml` formatting standards: -- **120 Character Line Limit (Guideline)**: Prefer lines 120 characters or fewer; break at punctuation or logical breaks when practical. +- **120 Character Line Limit**: Keep lines 120 characters or fewer; break at punctuation or logical breaks. - **No Trailing Whitespace**: Remove all trailing spaces and tabs. - **Blank Lines Around Headings**: Include a blank line before and after each heading. - **Blank Lines Around Lists**: Include a blank line before and after numbered and bullet lists. diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index be48de3..3fa57cb 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -479,7 +479,7 @@ jobs: dotnet versionmark --capture --job-id "build-docs" \ --output "artifacts/versionmark-build-docs.json" -- \ dotnet git node npm pandoc weasyprint sarifmark sonarmark reqstream \ - buildmark versionmark reviewmark fileassert + buildmark versionmark reviewmark fileassert sysml2tools echo "✓ Tool versions captured" # === PREPARE DOCUMENT OUTPUT === @@ -738,6 +738,20 @@ jobs: shell: bash run: mkdir -p docs/design/generated + - name: Run SysML2Tools self-validation + run: > + dotnet sysml2tools + --validate + --results artifacts/sysml2tools-self-validation.trx + + - name: Render Software Structure diagrams with SysML2Tools + shell: pwsh + run: > + dotnet sysml2tools render + --output docs/design/generated --format svg + 'docs/sysml2/model/**/*.sysml' + 'docs/sysml2/views/design-views.sysml' + - name: Generate Design HTML with Pandoc shell: bash run: > diff --git a/.reviewmark.yaml b/.reviewmark.yaml index 873f4a9..a7a0b11 100644 --- a/.reviewmark.yaml +++ b/.reviewmark.yaml @@ -13,6 +13,7 @@ needs-review: - docs/reqstream/**/*.yaml - docs/design/**/*.md - docs/verification/**/*.md + - docs/sysml2/**/*.sysml - '!**/obj/**' - '!**/bin/**' - '!**/generated/**' @@ -25,21 +26,38 @@ evidence-source: type: url location: https://raw.githubusercontent.com/demaconsulting/VersionMark/reviews/index.json +# Global context shown to every reviewer for orientation (not fingerprinted). +context: + - docs/design/introduction.md + # Review sets following standardized patterns for hierarchical compliance coverage reviews: # Purpose - id: Purpose - title: Review that Advertised Features Match System Design + title: Review that README and User Guide are Coherent and Complete + context: + - '!docs/design/introduction.md' paths: - README.md - docs/user_guide/**/*.md - - docs/reqstream/version-mark.yaml + + # Decomposition + - id: Decomposition + title: Review that VersionMark Decomposition Addresses the Stated Purpose + context: + - README.md + - docs/user_guide/**/*.md + paths: + - requirements.yaml - docs/design/introduction.md - - docs/design/version-mark.md + - docs/sysml2/**/*.sysml # VersionMark - Architecture (system-level) - id: VersionMark-Architecture title: Review that VersionMark Architecture Satisfies Requirements + context: + - README.md + - docs/user_guide/**/*.md paths: - docs/reqstream/version-mark.yaml - docs/design/introduction.md @@ -53,18 +71,23 @@ reviews: # VersionMark - Design (consistency and completeness) - id: VersionMark-Design title: Review that VersionMark Design is Consistent and Complete + context: + - docs/reqstream/version-mark.yaml paths: - docs/reqstream/version-mark.yaml - docs/reqstream/version-mark/platform-requirements.yaml - docs/design/introduction.md - docs/design/version-mark.md - docs/design/version-mark/**/*.md + - docs/design/ots.md - docs/verification/introduction.md - docs/verification/ots.md # VersionMark - Verification (consistency and completeness) - id: VersionMark-Verification title: Review that VersionMark Verification is Consistent and Complete + context: + - docs/reqstream/version-mark.yaml paths: - docs/reqstream/version-mark.yaml - docs/verification/introduction.md @@ -75,6 +98,9 @@ reviews: # VersionMark - All Requirements - id: VersionMark-AllRequirements title: Review that All VersionMark Requirements are Complete + context: + - docs/design/version-mark.md + - docs/reqstream/version-mark.yaml paths: - requirements.yaml - docs/reqstream/**/*.yaml @@ -82,6 +108,9 @@ reviews: # VersionMark - Cli - id: VersionMark-Cli title: Review that VersionMark Cli Satisfies Subsystem Requirements + context: + - docs/design/version-mark.md + - docs/reqstream/version-mark.yaml paths: - docs/reqstream/version-mark/cli.yaml - docs/design/version-mark/cli.md @@ -90,6 +119,11 @@ reviews: - id: VersionMark-Cli-Program title: Review that VersionMark Cli Program Implementation is Correct + context: + - docs/design/version-mark.md + - docs/reqstream/version-mark.yaml + - docs/design/version-mark/cli.md + - docs/reqstream/version-mark/cli.yaml paths: - docs/reqstream/version-mark/cli/program.yaml - docs/design/version-mark/cli/program.md @@ -99,6 +133,11 @@ reviews: - id: VersionMark-Cli-Context title: Review that VersionMark Cli Context Implementation is Correct + context: + - docs/design/version-mark.md + - docs/reqstream/version-mark.yaml + - docs/design/version-mark/cli.md + - docs/reqstream/version-mark/cli.yaml paths: - docs/reqstream/version-mark/cli/context.yaml - docs/design/version-mark/cli/context.md @@ -109,6 +148,9 @@ reviews: # VersionMark - Configuration - id: VersionMark-Configuration title: Review that VersionMark Configuration Satisfies Subsystem Requirements + context: + - docs/design/version-mark.md + - docs/reqstream/version-mark.yaml paths: - docs/reqstream/version-mark/configuration.yaml - docs/design/version-mark/configuration.md @@ -118,6 +160,11 @@ reviews: - id: VersionMark-Configuration-VersionMarkConfig title: Review that VersionMark Configuration VersionMarkConfig Implementation is Correct + context: + - docs/design/version-mark.md + - docs/reqstream/version-mark.yaml + - docs/design/version-mark/configuration.md + - docs/reqstream/version-mark/configuration.yaml paths: - docs/reqstream/version-mark/configuration/version-mark-config.yaml - docs/design/version-mark/configuration/version-mark-config.md @@ -128,6 +175,11 @@ reviews: - id: VersionMark-Configuration-ToolConfig title: Review that VersionMark Configuration ToolConfig Implementation is Correct + context: + - docs/design/version-mark.md + - docs/reqstream/version-mark.yaml + - docs/design/version-mark/configuration.md + - docs/reqstream/version-mark/configuration.yaml paths: - docs/reqstream/version-mark/configuration/tool-config.yaml - docs/design/version-mark/configuration/tool-config.md @@ -137,6 +189,11 @@ reviews: - id: VersionMark-Configuration-LintIssue title: Review that VersionMark Configuration LintIssue Implementation is Correct + context: + - docs/design/version-mark.md + - docs/reqstream/version-mark.yaml + - docs/design/version-mark/configuration.md + - docs/reqstream/version-mark/configuration.yaml paths: - docs/reqstream/version-mark/configuration/load.yaml - docs/design/version-mark/configuration/lint-issue.md @@ -147,6 +204,9 @@ reviews: # VersionMark - Capture - id: VersionMark-Capture title: Review that VersionMark Capture Satisfies Subsystem Requirements + context: + - docs/design/version-mark.md + - docs/reqstream/version-mark.yaml paths: - docs/reqstream/version-mark/capture.yaml - docs/design/version-mark/capture.md @@ -155,6 +215,11 @@ reviews: - id: VersionMark-Capture-VersionInfo title: Review that VersionMark Capture VersionInfo Implementation is Correct + context: + - docs/design/version-mark.md + - docs/reqstream/version-mark.yaml + - docs/design/version-mark/capture.md + - docs/reqstream/version-mark/capture.yaml paths: - docs/reqstream/version-mark/capture/version-info.yaml - docs/design/version-mark/capture/version-info.md @@ -165,6 +230,9 @@ reviews: # VersionMark - Publishing - id: VersionMark-Publishing title: Review that VersionMark Publishing Satisfies Subsystem Requirements + context: + - docs/design/version-mark.md + - docs/reqstream/version-mark.yaml paths: - docs/reqstream/version-mark/publishing.yaml - docs/design/version-mark/publishing.md @@ -174,6 +242,11 @@ reviews: - id: VersionMark-Publishing-MarkdownFormatter title: Review that VersionMark Publishing MarkdownFormatter Implementation is Correct + context: + - docs/design/version-mark.md + - docs/reqstream/version-mark.yaml + - docs/design/version-mark/publishing.md + - docs/reqstream/version-mark/publishing.yaml paths: - docs/reqstream/version-mark/publishing/markdown-formatter.yaml - docs/design/version-mark/publishing/markdown-formatter.md @@ -184,6 +257,9 @@ reviews: # VersionMark - SelfTest - id: VersionMark-SelfTest title: Review that VersionMark SelfTest Satisfies Subsystem Requirements + context: + - docs/design/version-mark.md + - docs/reqstream/version-mark.yaml paths: - docs/reqstream/version-mark/self-test.yaml - docs/design/version-mark/self-test.md @@ -192,6 +268,11 @@ reviews: - id: VersionMark-SelfTest-Validation title: Review that VersionMark SelfTest Validation Implementation is Correct + context: + - docs/design/version-mark.md + - docs/reqstream/version-mark.yaml + - docs/design/version-mark/self-test.md + - docs/reqstream/version-mark/self-test.yaml paths: - docs/reqstream/version-mark/self-test/validation.yaml - docs/design/version-mark/self-test/validation.md @@ -202,6 +283,9 @@ reviews: # VersionMark - Utilities - id: VersionMark-Utilities title: Review that VersionMark Utilities Satisfies Subsystem Requirements + context: + - docs/design/version-mark.md + - docs/reqstream/version-mark.yaml paths: - docs/reqstream/version-mark/utilities.yaml - docs/design/version-mark/utilities.md @@ -211,6 +295,11 @@ reviews: - id: VersionMark-Utilities-GlobMatcher title: Review that VersionMark Utilities GlobMatcher Implementation is Correct + context: + - docs/design/version-mark.md + - docs/reqstream/version-mark.yaml + - docs/design/version-mark/utilities.md + - docs/reqstream/version-mark/utilities.yaml paths: - docs/reqstream/version-mark/utilities/glob-matcher.yaml - docs/design/version-mark/utilities/glob-matcher.md @@ -220,6 +309,11 @@ reviews: - id: VersionMark-Utilities-PathHelpers title: Review that VersionMark Utilities PathHelpers Implementation is Correct + context: + - docs/design/version-mark.md + - docs/reqstream/version-mark.yaml + - docs/design/version-mark/utilities.md + - docs/reqstream/version-mark/utilities.yaml paths: - docs/reqstream/version-mark/utilities/path-helpers.yaml - docs/design/version-mark/utilities/path-helpers.md @@ -229,55 +323,83 @@ reviews: # OTS Items - id: OTS-BuildMark - title: Review of BuildMark OTS verification evidence + title: Review that BuildMark Provides Required Functionality paths: - docs/reqstream/ots/buildmark.yaml - docs/verification/ots/buildmark.md - id: OTS-FileAssert - title: Review of FileAssert OTS verification evidence + title: Review that FileAssert Provides Required Functionality paths: - docs/reqstream/ots/fileassert.yaml - docs/verification/ots/fileassert.md - id: OTS-xUnit - title: Review of xUnit OTS verification evidence + title: Review that xUnit Provides Required Functionality paths: - docs/reqstream/ots/xunit.yaml - docs/verification/ots/xunit.md - id: OTS-Pandoc - title: Review of Pandoc OTS verification evidence + title: Review that Pandoc Provides Required Functionality paths: - docs/reqstream/ots/pandoc.yaml - docs/verification/ots/pandoc.md - id: OTS-ReqStream - title: Review of ReqStream OTS verification evidence + title: Review that ReqStream Provides Required Functionality paths: - docs/reqstream/ots/reqstream.yaml - docs/verification/ots/reqstream.md - id: OTS-ReviewMark - title: Review of ReviewMark OTS verification evidence + title: Review that ReviewMark Provides Required Functionality paths: - docs/reqstream/ots/reviewmark.yaml - docs/verification/ots/reviewmark.md - id: OTS-SarifMark - title: Review of SarifMark OTS verification evidence + title: Review that SarifMark Provides Required Functionality paths: - docs/reqstream/ots/sarifmark.yaml - docs/verification/ots/sarifmark.md - id: OTS-SonarMark - title: Review of SonarMark OTS verification evidence + title: Review that SonarMark Provides Required Functionality paths: - docs/reqstream/ots/sonarmark.yaml - docs/verification/ots/sonarmark.md - id: OTS-WeasyPrint - title: Review of WeasyPrint OTS verification evidence + title: Review that WeasyPrint Provides Required Functionality paths: - docs/reqstream/ots/weasyprint.yaml - docs/verification/ots/weasyprint.md + + - id: OTS-SysML2Tools + title: Review that SysML2Tools Provides Required Functionality + paths: + - docs/reqstream/ots/sysml2tools.yaml + - docs/design/ots/sysml2tools.md + - docs/verification/ots/sysml2tools.md + + - id: OTS-YamlDotNet + title: Review that YamlDotNet Provides Required Functionality + paths: + - docs/reqstream/ots/yaml-dot-net.yaml + - docs/design/ots/yaml-dot-net.md + - docs/verification/ots/yaml-dot-net.md + + - id: OTS-FileSystemGlobbing + title: Review that FileSystemGlobbing Provides Required Functionality + paths: + - docs/reqstream/ots/microsoft-extensions-file-system-globbing.yaml + - docs/design/ots/microsoft-extensions-file-system-globbing.md + - docs/verification/ots/microsoft-extensions-file-system-globbing.md + + - id: OTS-TestResults + title: Review that TestResults Provides Required Functionality + paths: + - docs/reqstream/ots/dema-consulting-test-results.yaml + - docs/design/ots/dema-consulting-test-results.md + - docs/verification/ots/dema-consulting-test-results.md diff --git a/.versionmark.yaml b/.versionmark.yaml index 09bb0eb..042496c 100644 --- a/.versionmark.yaml +++ b/.versionmark.yaml @@ -72,3 +72,8 @@ tools: fileassert: command: dotnet tool list regex: (?i)demaconsulting\.fileassert\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?) + + # sysml2tools (DemaConsulting.Sysml2Tools.Tool from dotnet tool list) + sysml2tools: + command: dotnet tool list + regex: (?i)demaconsulting\.sysml2tools\.tool\s+(?\d+\.\d+\.\d+(?:-[a-zA-Z0-9.]+)?) diff --git a/AGENTS.md b/AGENTS.md index 6ab2319..0c6e1cc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,6 +21,7 @@ │ ├── requirements_doc/ │ ├── requirements_report/ │ ├── reqstream/ +│ ├── sysml2/ │ ├── user_guide/ │ └── verification/ ├── src/ @@ -38,16 +39,18 @@ commit messages, and reports). This repository follows a reference template for structure and file conventions. -- **Template URL**: `https://github.com/demaconsulting/Agents/raw/refs/heads/template` +- **template-url**: `https://github.com/demaconsulting/Agents/raw/refs/heads/template` - **Repository map**: `{template-url}/repository-map.md` - **Template files**: `{template-url}/{file-path}` for files described in the map # Codebase Navigation (ALL Agents) -When working with source code, design, or requirements artifacts, read -`docs/design/introduction.md` first. It provides the software structure, -folder layout, and companion artifact locations. Use it as the primary map -before searching the filesystem. +When working with source code, design, or requirements artifacts, query the SysML2 +architecture model under `docs/sysml2/` first (see the `sysml2tools-query` skill) to +understand software structure, purpose, and relationships. Fall back to +`docs/design/introduction.md` for the human-facing narrative, folder layout, and +companion artifact locations, and use it as the primary map when the model doesn't +yet cover something. # Key Configuration Files @@ -62,6 +65,7 @@ before searching the filesystem. - **`package.json`** - Node.js dependencies for formatting tools - **`requirements.yaml`** - Root requirements file with includes - **`pip-requirements.txt`** - Python dependencies for yamllint and yamlfix +- **`docs/sysml2/`** - SysML2 architecture model; authoritative source for software structure - **`fix.ps1`** - Applies all auto-fixers silently (dotnet format, markdown, YAML). Always exits 0. - **`build.ps1`** - Builds the solution and runs all tests. @@ -78,6 +82,7 @@ from `.github/standards/`. Use this matrix to determine which to load: - **Design docs**: `software-items.md`, `design-documentation.md`, `technical-documentation.md` - **Verification docs**: `software-items.md`, `verification-documentation.md`, `technical-documentation.md` - **Review configuration**: `software-items.md`, `reviewmark-usage.md` +- **Software structure**: `sysml2-modeling.md` - **Any documentation**: `technical-documentation.md` Load only the standards relevant to your specific task scope. @@ -88,12 +93,15 @@ The default agent should handle simple, straightforward tasks directly. Delegate to specialized agents only for specific scenarios: - **Pre-PR lint cleanup** (fix all lint issues before pull request) → Call the lint-fix agent -- **Light development work** (small fixes, simple features) → Call the developer agent +- **Scoped fixes with no new user-visible behavior** (PR review comments, doc + corrections, known bug fixes with defined root cause) → Call the developer agent - **Light quality checking** (basic validation) → Call the quality agent -- **Formal feature implementation** (complex, multi-step) → Call the implementation agent -- **Formal bug resolution** (complex debugging, systematic fixes) → Call the implementation agent +- **Any change introducing new user-visible behavior** (features, enhancements, + new commands or options) → Call the implementation agent +- **Formal bug resolution** (complex debugging, unknown root cause) → Call the implementation agent - **Formal reviews** (compliance verification, detailed analysis) → Call the formal-review agent - **Structural audit**: (repository layout vs. template) → Call the template-sync agent +- **Implementation planning only** (review a plan before committing to implementation) → Call the planning agent # Agent Reporting (Specialized Agents Must Follow) @@ -102,16 +110,16 @@ Specialized agents MUST generate a completion report: 1. Save to `.agent-logs/{agent-name}-{subject}-{unique-id}.md` where `{subject}` is a kebab-case task summary (max 5 words) and `{unique-id}` is a short unique suffix (e.g., 8-char hex or timestamp) -2. Start with `**Result**: (SUCCEEDED|FAILED)` as the first metadata field +2. Start with `**Result**: (SUCCEEDED|FAILED|INCOMPLETE)` as the first metadata field 3. Include the agent-specific report sections defined in each agent's prompt 4. Return the summary to the caller Result semantics for orchestrator decision-making: -- **SUCCEEDED**: Work completed and all applicable quality gates met +- **SUCCEEDED**: Work completed and all quality gates applicable to that agent's scope met - **FAILED**: Work could not be completed or quality gates not met - **INCOMPLETE**: Work cannot proceed without information only the user can - provide (implementation agent only) + provide (implementation, planning, and template-sync agents) # Formatting (After Making Changes) @@ -129,7 +137,7 @@ responsibility - invoke the lint-fix agent once before submitting a pull request ## CI Quality Tools CI runs `lint.ps1` which checks: markdownlint-cli2, cspell, yamllint, dotnet format, -reqstream, versionmark, and reviewmark. +reqstream, versionmark, reviewmark, and sysml2tools. # Scope Discipline (ALL Agents Must Follow) diff --git a/docs/design/definition.yaml b/docs/design/definition.yaml index 9a3d307..b67e324 100644 --- a/docs/design/definition.yaml +++ b/docs/design/definition.yaml @@ -22,6 +22,11 @@ input-files: - docs/design/version-mark/utilities.md - docs/design/version-mark/utilities/glob-matcher.md - docs/design/version-mark/utilities/path-helpers.md + - docs/design/ots.md + - docs/design/ots/yaml-dot-net.md + - docs/design/ots/microsoft-extensions-file-system-globbing.md + - docs/design/ots/dema-consulting-test-results.md + - docs/design/ots/sysml2tools.md template: template.html table-of-contents: true number-sections: true diff --git a/docs/design/introduction.md b/docs/design/introduction.md index b620db8..e8a77e4 100644 --- a/docs/design/introduction.md +++ b/docs/design/introduction.md @@ -17,85 +17,46 @@ and .NET development and general concepts of command-line tool design. ## Scope -This document covers the design of the VersionMark system and its six subsystems: - -- The **Cli Subsystem**: the `Program` entry point and `Context` class that handle argument - parsing, output routing, and program flow control -- The **Configuration Subsystem**: the `VersionMarkConfig`, `ToolConfig`, and `LintIssue` - classes that read, validate, and interpret `.versionmark.yaml` configuration files -- The **Capture Subsystem**: the `VersionInfo` record that serializes and deserializes - captured version data to and from JSON -- The **Publishing Subsystem**: the `MarkdownFormatter` class that generates the markdown - version report from captured data -- The **SelfTest Subsystem**: the `Validation` class that provides built-in verification - of the tool's core functionality -- The **Utilities Subsystem**: the `GlobMatcher` class that provides glob-pattern file - matching and the `PathHelpers` class that provides safe path combination - -This document does not cover installation, end-user usage patterns, CI/CD pipeline -configuration, or the internal design of OTS dependencies. Those topics are addressed in -the *VersionMark User Guide*, the *VersionMark Requirements Document*, and the respective -OTS package documentation. - -Each component described here corresponds to one or more requirements defined in the -`docs/reqstream/` files. The source code in `src/DemaConsulting.VersionMark/` is the -authoritative implementation. Any discrepancy between this document and the code should be -resolved by updating this document to reflect the actual implementation, or by raising a -defect against the code. +This document covers the following software items: + +Local items: + +- **VersionMark**: system, subsystem, and unit design for all local components. + +OTS items: + +- **DemaConsulting.TestResults**: integration and usage design. +- **FileSystemGlobbing**: integration and usage design. +- **SysML2Tools**: integration and usage design. +- **YamlDotNet**: integration and usage design. + +The following topics are out of scope: + +- Installation and end-user usage patterns +- CI/CD pipeline configuration +- External library internals +- Test projects ## Software Structure -The following tree shows how the VersionMark software items are organized across the -system, subsystem, and unit levels: - -```text -VersionMark (System) Version capture/publish tool -├── Cli (Subsystem) Argument parsing and dispatch -│ ├── Program (Unit) Tool entry point -│ └── Context (Unit) Command-line state container -├── Configuration (Subsystem) YAML configuration loading and validation -│ ├── VersionMarkConfig (Unit) Top-level config container and validator -│ ├── ToolConfig (Unit) Per-tool config record -│ └── LintIssue (Unit) Lint severity, issue record, and load result -├── Capture (Subsystem) Tool version capture -│ └── VersionInfo (Unit) JSON version data record -├── Publishing (Subsystem) Markdown report publishing -│ └── MarkdownFormatter (Unit) Version report formatter -├── SelfTest (Subsystem) Built-in self-validation -│ └── Validation (Unit) Self-validation runner -└── Utilities (Subsystem) General-purpose helper utilities - ├── GlobMatcher (Unit) Glob-pattern file matching - └── PathHelpers (Unit) Safe path combination -``` +The software structure is modeled in SysML2 under `docs/sysml2/` and rendered to the +diagram below by SysML2Tools as part of the build pipeline. The model is the authoritative, +machine-queryable source of structure; the diagram is a generated/derived artifact. AI +agents should query the SysML2 model directly (see the `sysml2tools-query` skill) rather +than parsing this diagram before deep-diving into source code. + +![Software Structure](SoftwareStructureView.svg) ## Folder Layout -The source code folder structure mirrors the top-level subsystem breakdown above, giving -reviewers an explicit navigation aid from design to code: - -```text -src/DemaConsulting.VersionMark/ -├── Program.cs — entry point and execution orchestrator -├── Cli/ -│ └── Context.cs — command-line argument parser and I/O owner -├── Configuration/ -│ ├── LintIssue.cs — lint issue record and severity enum -│ └── VersionMarkConfig.cs — YAML configuration, tool definitions, and validation -├── Capture/ -│ └── VersionInfo.cs — captured version data record -├── Publishing/ -│ └── MarkdownFormatter.cs — markdown report generation -├── SelfTest/ -│ └── Validation.cs — self-validation test runner -└── Utilities/ - ├── GlobMatcher.cs — glob-pattern file matching - └── PathHelpers.cs — safe path utilities -``` - -`Program.cs` resides at the project root rather than inside `Cli/` because .NET uses the -presence of a top-level `Program.cs` at the project root as the conventional entry-point -file. It is conceptually part of the Cli Subsystem, as shown in the Software Structure tree -above. The test project mirrors the same layout under `test/DemaConsulting.VersionMark.Tests/`. +- **src/** - source files and projects + - **DemaConsulting.VersionMark/** - VersionMark system source + - **Cli/** - Cli subsystem + - **Configuration/** - Configuration subsystem + - **Capture/** - Capture subsystem + - **Publishing/** - Publishing subsystem + - **SelfTest/** - SelfTest subsystem + - **Utilities/** - Utilities subsystem ## Companion Artifact Structure diff --git a/docs/design/ots.md b/docs/design/ots.md index 5ca02ad..9b540b8 100644 --- a/docs/design/ots.md +++ b/docs/design/ots.md @@ -2,25 +2,38 @@ VersionMark consumes three runtime Off-The-Shelf (OTS) libraries: **YamlDotNet**, **Microsoft.Extensions.FileSystemGlobbing**, and -**DemaConsulting.TestResults**. This document describes the overall integration -strategy and provides a cross-reference to the per-item design files. +**DemaConsulting.TestResults**. It also relies on **SysML2Tools**, a build-time +dotnet global tool that validates the architecture model and renders its +declared views to SVG diagrams consumed by this design documentation. This +document describes the overall integration strategy and provides a +cross-reference to the per-item design files. ## Integration Strategy -Each OTS library is consumed only through a single local unit that acts as an -adapter boundary. No OTS type leaks beyond the unit that owns it: +The OTS items used by this project fall into two functional groups: -| OTS Item | Consuming Unit | Subsystem | -|-------------------------------------------|---------------------|---------------| -| YamlDotNet | VersionMarkConfig | Configuration | -| Microsoft.Extensions.FileSystemGlobbing | GlobMatcher | Utilities | -| DemaConsulting.TestResults | Validation | SelfTest | +- **Production code libraries** — YamlDotNet, Microsoft.Extensions.FileSystemGlobbing, and + DemaConsulting.TestResults are each consumed only through a single local unit that acts as an + adapter boundary. No OTS type leaks beyond the unit that owns it: -Restricting each OTS item to a single consuming unit minimizes the blast radius -of an API change during an upgrade: only the adapter unit needs to change. See -the individual per-item design files for details of features used and -initialization requirements: + | OTS Item | Consuming Unit | Subsystem | + |-------------------------------------------|---------------------|---------------| + | YamlDotNet | VersionMarkConfig | Configuration | + | Microsoft.Extensions.FileSystemGlobbing | GlobMatcher | Utilities | + | DemaConsulting.TestResults | Validation | SelfTest | + + Restricting each OTS item to a single consuming unit minimizes the blast radius of an API + change during an upgrade: only the adapter unit needs to change. + +- **Build pipeline tool** — SysML2Tools is a dotnet global tool installed via + `.config/dotnet-tools.json` and invoked directly from `lint.ps1` and the GitHub Actions + workflow. It operates on the `docs/sysml2/` architecture model rather than on any in-house + unit, so it has no consuming unit of its own. + +See the individual per-item design files for details of features used and initialization +requirements: - See _YamlDotNet Integration Design_ - See _Microsoft.Extensions.FileSystemGlobbing Integration Design_ - See _DemaConsulting.TestResults Integration Design_ +- See _SysML2Tools OTS Design_ diff --git a/docs/design/ots/sysml2tools.md b/docs/design/ots/sysml2tools.md new file mode 100644 index 0000000..76cc56f --- /dev/null +++ b/docs/design/ots/sysml2tools.md @@ -0,0 +1,53 @@ +## SysML2Tools OTS Design + +DemaConsulting.SysML2Tools is a .NET dotnet global tool that lints a SysML2 architecture model +and renders its declared views to SVG diagrams consumed by the design documentation. + +### Purpose + +SysML2Tools provides the toolchain that keeps VersionMark's architecture model +(`docs/sysml2/model/**/*.sysml`) and its declared views (`docs/sysml2/views/design-views.sysml`) +consistent with the design documentation. It validates the model for syntax and reference errors, +and renders each declared view to an SVG diagram embedded directly in the corresponding design +document (for example `docs/design/version-mark.md` embeds `VersionMarkView.svg` and +`docs/design/introduction.md` embeds `SoftwareStructureView.svg`). AI agents also query the model +directly via the `sysml2tools-query` skill rather than parsing the rendered diagrams or +hand-maintained prose. + +SysML2Tools is chosen because it is the reference implementation for the SysML v2 subset used by +this project's Continuous Compliance methodology, and it integrates directly with the same +dotnet-tool restore and CI pipeline used by the other pipeline tools. + +### Features Used + +- Model validation via `dotnet sysml2tools lint 'docs/sysml2/**/*.sysml'`, which reports syntax + errors and unresolved references without producing output files. +- View rendering via + `dotnet sysml2tools render --output docs/design/generated --format svg 'docs/sysml2/model/**/*.sysml' 'docs/sysml2/views/design-views.sysml'`, + which renders every `view` declared in `design-views.sysml` to an SVG file named after the view + (for example `SoftwareStructureView.svg`). +- Model querying via the `sysml2tools-query` skill, used by AI agents to answer structural and + traceability questions about the model without parsing the raw SysML2 source or the rendered + diagrams. + +### Integration Pattern + +SysML2Tools is installed as a .NET local tool defined in `.config/dotnet-tools.json` under the +package name `demaconsulting.sysml2tools.tool` and restored with `dotnet tool restore`. It operates +directly on the SysML2 source files under `docs/sysml2/`; no separate configuration file is +required. + +It is used in two places in the pipeline: + +- **Lint** (`lint.ps1`, all CI jobs and local pre-PR checks): `dotnet sysml2tools lint + 'docs/sysml2/**/*.sysml'` fails the build if the model contains syntax errors or unresolved + references. +- **Render** (`build.yaml`, build-docs job): `dotnet sysml2tools render` renders each declared view + to an SVG file in `docs/design/generated/`, immediately before Pandoc compiles the Design + document. The rendered SVGs sit alongside the compiled `design.html`, so the design Markdown + sources embed bare filenames (for example `![VersionMark Structure](VersionMarkView.svg)`) + that Pandoc and the browser resolve relative to that directory. + +SysML2Tools reads only the local SysML2 model files and writes only local SVG output files; it +requires no external service or network access, and it has no transitive NuGet dependencies that +propagate to the main source project. It is a build-time tool only. diff --git a/docs/design/version-mark.md b/docs/design/version-mark.md index 4025c53..a9cb131 100644 --- a/docs/design/version-mark.md +++ b/docs/design/version-mark.md @@ -1,5 +1,7 @@ # VersionMark +![VersionMark Structure](VersionMarkView.svg) + ## Architecture VersionMark is structured as a single system comprising six subsystems. There is no diff --git a/docs/design/version-mark/capture.md b/docs/design/version-mark/capture.md index ec5b6eb..d58cca4 100644 --- a/docs/design/version-mark/capture.md +++ b/docs/design/version-mark/capture.md @@ -1,5 +1,7 @@ ## Capture +![Capture Structure](CaptureView.svg) + ### Overview The Capture subsystem is responsible for persisting tool version information for the diff --git a/docs/design/version-mark/capture/version-info.md b/docs/design/version-mark/capture/version-info.md index c6e7dd2..ad6a709 100644 --- a/docs/design/version-mark/capture/version-info.md +++ b/docs/design/version-mark/capture/version-info.md @@ -1,5 +1,7 @@ ### VersionInfo +![Capture Structure](CaptureView.svg) + #### Purpose `VersionInfo` is the data transfer record between the capture and publish operational modes. diff --git a/docs/design/version-mark/cli.md b/docs/design/version-mark/cli.md index 30b32df..899afa0 100644 --- a/docs/design/version-mark/cli.md +++ b/docs/design/version-mark/cli.md @@ -1,5 +1,7 @@ ## Cli +![Cli Structure](CliView.svg) + ### Overview The Cli subsystem is responsible for parsing command-line arguments, routing program flow diff --git a/docs/design/version-mark/cli/context.md b/docs/design/version-mark/cli/context.md index 970a07b..773146b 100644 --- a/docs/design/version-mark/cli/context.md +++ b/docs/design/version-mark/cli/context.md @@ -1,5 +1,7 @@ ### Context +![Cli Structure](CliView.svg) + #### Purpose `Context` (`Context.cs`) is a sealed, disposable container for all parsed command-line diff --git a/docs/design/version-mark/cli/program.md b/docs/design/version-mark/cli/program.md index 4a10a04..0a060e4 100644 --- a/docs/design/version-mark/cli/program.md +++ b/docs/design/version-mark/cli/program.md @@ -1,5 +1,7 @@ ### Program +![Cli Structure](CliView.svg) + #### Purpose `Program` (`Program.cs`) is the top-level entry point for VersionMark. It owns the `Main` diff --git a/docs/design/version-mark/configuration.md b/docs/design/version-mark/configuration.md index 5911c3e..4b2f2df 100644 --- a/docs/design/version-mark/configuration.md +++ b/docs/design/version-mark/configuration.md @@ -1,5 +1,7 @@ ## Configuration +![Configuration Structure](ConfigurationView.svg) + ### Overview The Configuration subsystem reads and interprets the `.versionmark.yaml` file that defines diff --git a/docs/design/version-mark/configuration/lint-issue.md b/docs/design/version-mark/configuration/lint-issue.md index a26f87b..23a8c93 100644 --- a/docs/design/version-mark/configuration/lint-issue.md +++ b/docs/design/version-mark/configuration/lint-issue.md @@ -1,5 +1,7 @@ ### LintIssue +![Configuration Structure](ConfigurationView.svg) + #### Purpose `LintIssue.cs` defines the types used to surface validation issues found while loading a diff --git a/docs/design/version-mark/configuration/tool-config.md b/docs/design/version-mark/configuration/tool-config.md index e32d3e6..d72b917 100644 --- a/docs/design/version-mark/configuration/tool-config.md +++ b/docs/design/version-mark/configuration/tool-config.md @@ -1,5 +1,7 @@ ### ToolConfig +![Configuration Structure](ConfigurationView.svg) + #### Purpose `ToolConfig` (`VersionMarkConfig.cs`) represents the configuration for a single tool diff --git a/docs/design/version-mark/configuration/version-mark-config.md b/docs/design/version-mark/configuration/version-mark-config.md index 4ce435d..ca84c78 100644 --- a/docs/design/version-mark/configuration/version-mark-config.md +++ b/docs/design/version-mark/configuration/version-mark-config.md @@ -1,5 +1,7 @@ ### VersionMarkConfig +![Configuration Structure](ConfigurationView.svg) + #### Purpose `VersionMarkConfig` is the top-level record for a loaded `.versionmark.yaml` configuration diff --git a/docs/design/version-mark/publishing.md b/docs/design/version-mark/publishing.md index 529d4c1..a5925d1 100644 --- a/docs/design/version-mark/publishing.md +++ b/docs/design/version-mark/publishing.md @@ -1,5 +1,7 @@ ## Publishing +![Publishing Structure](PublishingView.svg) + ### Overview The Publishing subsystem is responsible for generating a human-readable markdown version diff --git a/docs/design/version-mark/publishing/markdown-formatter.md b/docs/design/version-mark/publishing/markdown-formatter.md index 7944eed..4bd5518 100644 --- a/docs/design/version-mark/publishing/markdown-formatter.md +++ b/docs/design/version-mark/publishing/markdown-formatter.md @@ -1,5 +1,7 @@ ### MarkdownFormatter +![Publishing Structure](PublishingView.svg) + #### Purpose `MarkdownFormatter` (`MarkdownFormatter.cs`) converts a collection of `VersionInfo` records diff --git a/docs/design/version-mark/self-test.md b/docs/design/version-mark/self-test.md index d40180e..b0888c3 100644 --- a/docs/design/version-mark/self-test.md +++ b/docs/design/version-mark/self-test.md @@ -1,5 +1,7 @@ ## SelfTest +![SelfTest Structure](SelfTestView.svg) + ### Overview The SelfTest subsystem provides built-in verification of the tool's core functionality. diff --git a/docs/design/version-mark/self-test/validation.md b/docs/design/version-mark/self-test/validation.md index 36c70ff..b9a7a76 100644 --- a/docs/design/version-mark/self-test/validation.md +++ b/docs/design/version-mark/self-test/validation.md @@ -1,5 +1,7 @@ ### Validation +![SelfTest Structure](SelfTestView.svg) + #### Purpose `Validation` (`Validation.cs`) implements the built-in self-validation suite for diff --git a/docs/design/version-mark/utilities.md b/docs/design/version-mark/utilities.md index 9a4b5cb..1ccf170 100644 --- a/docs/design/version-mark/utilities.md +++ b/docs/design/version-mark/utilities.md @@ -1,5 +1,7 @@ ## Utilities +![Utilities Structure](UtilitiesView.svg) + ### Overview The Utilities subsystem provides general-purpose helper classes used by other subsystems diff --git a/docs/design/version-mark/utilities/glob-matcher.md b/docs/design/version-mark/utilities/glob-matcher.md index 79e1950..58509e2 100644 --- a/docs/design/version-mark/utilities/glob-matcher.md +++ b/docs/design/version-mark/utilities/glob-matcher.md @@ -1,5 +1,7 @@ ### GlobMatcher +![Utilities Structure](UtilitiesView.svg) + #### Purpose `GlobMatcher` (`GlobMatcher.cs`) is a static utility class that resolves an array of glob diff --git a/docs/design/version-mark/utilities/path-helpers.md b/docs/design/version-mark/utilities/path-helpers.md index cabad57..787ab7a 100644 --- a/docs/design/version-mark/utilities/path-helpers.md +++ b/docs/design/version-mark/utilities/path-helpers.md @@ -1,5 +1,7 @@ ### PathHelpers +![Utilities Structure](UtilitiesView.svg) + #### Purpose `PathHelpers` (`PathHelpers.cs`) is a static utility class that provides safe path diff --git a/docs/reqstream/ots/dema-consulting-test-results.yaml b/docs/reqstream/ots/dema-consulting-test-results.yaml new file mode 100644 index 0000000..81d9fd0 --- /dev/null +++ b/docs/reqstream/ots/dema-consulting-test-results.yaml @@ -0,0 +1,24 @@ +--- +# DemaConsulting.TestResults OTS Software Requirements +# +# Requirements for the DemaConsulting.TestResults library functionality consumed by +# VersionMark. + +sections: + - title: OTS Software Requirements + sections: + - title: TestResults Requirements + requirements: + - id: VersionMark-OTS-TestResults + title: TestResults shall collect self-validation test outcomes and serialize + them to TRX and JUnit XML formats. + justification: | + DemaConsulting.TestResults is used inside the SelfTest subsystem's + `Validation` class to accumulate pass/fail outcomes for each + self-validation scenario and serialize them via `TrxSerializer` or + `JUnitSerializer` when `--results`/`--results-xml` is specified, + matching the TRX format consumed by the CI/CD traceability pipeline. + tags: [ots] + tests: + - SelfTest_Run_WithResultsFlag_WritesResultsFile + - SelfTest_Run_WithResultsXmlFlag_WritesJUnitResultsFile diff --git a/docs/reqstream/ots/microsoft-extensions-file-system-globbing.yaml b/docs/reqstream/ots/microsoft-extensions-file-system-globbing.yaml new file mode 100644 index 0000000..e208309 --- /dev/null +++ b/docs/reqstream/ots/microsoft-extensions-file-system-globbing.yaml @@ -0,0 +1,25 @@ +--- +# Microsoft.Extensions.FileSystemGlobbing OTS Software Requirements +# +# Requirements for the Microsoft.Extensions.FileSystemGlobbing library functionality +# consumed by VersionMark. + +sections: + - title: OTS Software Requirements + sections: + - title: FileSystemGlobbing Requirements + requirements: + - id: VersionMark-OTS-FileSystemGlobbing + title: FileSystemGlobbing shall match relative and absolute glob patterns + against the file system and deduplicate overlapping matches. + justification: | + Microsoft.Extensions.FileSystemGlobbing provides the `Matcher` class + used by VersionMark's `GlobMatcher.FindMatchingFiles` to resolve + relative and absolute glob patterns supplied in CI/CD pipeline + configuration into concrete file lists. VersionMark relies on it for + correct wildcard, recursive-wildcard, and cross-platform path matching. + tags: [ots] + tests: + - GlobMatcher_FindMatchingFiles_RelativePattern_ReturnsMatchingFiles + - GlobMatcher_FindMatchingFiles_AbsolutePattern_ReturnsMatchingFiles + - GlobMatcher_FindMatchingFiles_OverlappingPatterns_DeduplicatesResults diff --git a/docs/reqstream/ots/sysml2tools.yaml b/docs/reqstream/ots/sysml2tools.yaml new file mode 100644 index 0000000..3fe9fb2 --- /dev/null +++ b/docs/reqstream/ots/sysml2tools.yaml @@ -0,0 +1,28 @@ +--- +# SysML2Tools OTS Software Requirements +# +# Requirements for the SysML2Tools architecture modeling tool functionality. + +sections: + - title: OTS Software Requirements + sections: + - title: SysML2Tools Requirements + requirements: + - id: VersionMark-OTS-SysML2Tools-Lint + title: SysML2Tools shall validate the SysML2 model for syntax and reference + errors. + justification: | + Linting the model in CI catches broken references and syntax errors in the + architecture model before they reach the generated documentation. + tags: [ots] + tests: + - SysML2Tools_LintSelfTest + + - id: VersionMark-OTS-SysML2Tools-Render + title: SysML2Tools shall render the declared views to SVG diagrams. + justification: | + The rendered diagrams are embedded in the design documentation, so a failure to + render must fail the build rather than silently omit a diagram. + tags: [ots] + tests: + - SysML2Tools_RenderSvgSelfTest diff --git a/docs/reqstream/ots/yaml-dot-net.yaml b/docs/reqstream/ots/yaml-dot-net.yaml new file mode 100644 index 0000000..d842846 --- /dev/null +++ b/docs/reqstream/ots/yaml-dot-net.yaml @@ -0,0 +1,24 @@ +--- +# YamlDotNet OTS Software Requirements +# +# Requirements for the YamlDotNet library functionality consumed by VersionMark. + +sections: + - title: OTS Software Requirements + sections: + - title: YamlDotNet Requirements + requirements: + - id: VersionMark-OTS-YamlDotNet + title: YamlDotNet shall parse YAML configuration files and report parse + errors with source location. + justification: | + YamlDotNet is the YAML parser used by VersionMark to deserialize + `.versionmark.yaml` configuration files inside + `VersionMarkConfig.Load`, using its object-model API to preserve + source-location (`Mark`) information for precise lint issue + reporting. VersionMark relies on YamlDotNet for correct YAML + parsing and for surfacing malformed-document errors. + tags: [ots] + tests: + - VersionMarkConfig_Load_ValidConfig_ReturnsConfig + - VersionMarkConfig_Load_InvalidYaml_ReturnsNullConfig diff --git a/docs/sysml2/model/ots.sysml b/docs/sysml2/model/ots.sysml new file mode 100644 index 0000000..62a9390 --- /dev/null +++ b/docs/sysml2/model/ots.sysml @@ -0,0 +1,27 @@ +package OtsDependencies { + doc /* Off-the-shelf (OTS) runtime dependencies used by VersionMark. */ + + part def YamlDotNet { + doc /* OTS: YamlDotNet. */ + + comment designRef /* Design: docs/design/ots/yaml-dot-net.md */ + comment verificationRef /* Verification: docs/verification/ots/yaml-dot-net.md */ + comment reqRef /* Requirements: docs/reqstream/ots/yaml-dot-net.yaml */ + } + + part def FileSystemGlobbing { + doc /* OTS: Microsoft.Extensions.FileSystemGlobbing. */ + + comment designRef /* Design: docs/design/ots/microsoft-extensions-file-system-globbing.md */ + comment verificationRef /* Verification: docs/verification/ots/microsoft-extensions-file-system-globbing.md */ + comment reqRef /* Requirements: docs/reqstream/ots/microsoft-extensions-file-system-globbing.yaml */ + } + + part def TestResults { + doc /* OTS: DemaConsulting.TestResults. */ + + comment designRef /* Design: docs/design/ots/dema-consulting-test-results.md */ + comment verificationRef /* Verification: docs/verification/ots/dema-consulting-test-results.md */ + comment reqRef /* Requirements: docs/reqstream/ots/dema-consulting-test-results.yaml */ + } +} diff --git a/docs/sysml2/model/version-mark.sysml b/docs/sysml2/model/version-mark.sysml new file mode 100644 index 0000000..cfe2efa --- /dev/null +++ b/docs/sysml2/model/version-mark.sysml @@ -0,0 +1,29 @@ +package VersionMark { + import OtsDependencies::*; + + doc + /* + * VersionMark is a .NET global tool that captures tool/dependency versions, + * publishes markdown version reports, and self-validates its own operation. + */ + + part def VersionMarkSystem { + doc /* The VersionMark system as a whole. */ + + comment testRef /* Test: test/DemaConsulting.VersionMark.Tests/IntegrationTests.cs */ + comment designRef /* Design: docs/design/version-mark.md */ + comment verificationRef /* Verification: docs/verification/version-mark.md */ + comment reqRef /* Requirements: docs/reqstream/version-mark.yaml */ + + part cli : CliSubsystem; + part configuration : ConfigurationSubsystem; + part capture : CaptureSubsystem; + part publishing : PublishingSubsystem; + part selfTest : SelfTestSubsystem; + part utilities : UtilitiesSubsystem; + + part yamlDotNet : YamlDotNet; + part fileSystemGlobbing : FileSystemGlobbing; + part testResults : TestResults; + } +} diff --git a/docs/sysml2/model/version-mark/capture.sysml b/docs/sysml2/model/version-mark/capture.sysml new file mode 100644 index 0000000..58de543 --- /dev/null +++ b/docs/sysml2/model/version-mark/capture.sysml @@ -0,0 +1,12 @@ +package VersionMark { + part def CaptureSubsystem { + doc /* JSON serialization of captured version data. */ + + comment testRef /* Test: test/DemaConsulting.VersionMark.Tests/Capture/CaptureTests.cs */ + comment designRef /* Design: docs/design/version-mark/capture.md */ + comment verificationRef /* Verification: docs/verification/version-mark/capture.md */ + comment reqRef /* Requirements: docs/reqstream/version-mark/capture.yaml */ + + part versionInfo : VersionInfo; + } +} diff --git a/docs/sysml2/model/version-mark/capture/version-info.sysml b/docs/sysml2/model/version-mark/capture/version-info.sysml new file mode 100644 index 0000000..0ab39e4 --- /dev/null +++ b/docs/sysml2/model/version-mark/capture/version-info.sysml @@ -0,0 +1,11 @@ +package VersionMark { + part def VersionInfo { + doc /* Captured version record; JSON serialization for capture/publish handoff. */ + + comment sourceRef /* Source: src/DemaConsulting.VersionMark/Capture/VersionInfo.cs */ + comment testRef /* Test: test/DemaConsulting.VersionMark.Tests/Capture/VersionInfoTests.cs */ + comment designRef /* Design: docs/design/version-mark/capture/version-info.md */ + comment verificationRef /* Verification: docs/verification/version-mark/capture/version-info.md */ + comment reqRef /* Requirements: docs/reqstream/version-mark/capture/version-info.yaml */ + } +} diff --git a/docs/sysml2/model/version-mark/cli.sysml b/docs/sysml2/model/version-mark/cli.sysml new file mode 100644 index 0000000..3724399 --- /dev/null +++ b/docs/sysml2/model/version-mark/cli.sysml @@ -0,0 +1,13 @@ +package VersionMark { + part def CliSubsystem { + doc /* Command-line argument parsing, mode dispatch, and output routing. */ + + comment testRef /* Test: test/DemaConsulting.VersionMark.Tests/Cli/CliTests.cs */ + comment designRef /* Design: docs/design/version-mark/cli.md */ + comment verificationRef /* Verification: docs/verification/version-mark/cli.md */ + comment reqRef /* Requirements: docs/reqstream/version-mark/cli.yaml */ + + part program : Program; + part context : Context; + } +} diff --git a/docs/sysml2/model/version-mark/cli/context.sysml b/docs/sysml2/model/version-mark/cli/context.sysml new file mode 100644 index 0000000..8dd2fba --- /dev/null +++ b/docs/sysml2/model/version-mark/cli/context.sysml @@ -0,0 +1,11 @@ +package VersionMark { + part def Context { + doc /* Command-line argument and output container (console, error, log file). */ + + comment sourceRef /* Source: src/DemaConsulting.VersionMark/Cli/Context.cs */ + comment testRef /* Test: test/DemaConsulting.VersionMark.Tests/Cli/ContextTests.cs */ + comment designRef /* Design: docs/design/version-mark/cli/context.md */ + comment verificationRef /* Verification: docs/verification/version-mark/cli/context.md */ + comment reqRef /* Requirements: docs/reqstream/version-mark/cli/context.yaml */ + } +} diff --git a/docs/sysml2/model/version-mark/cli/program.sysml b/docs/sysml2/model/version-mark/cli/program.sysml new file mode 100644 index 0000000..5f737a4 --- /dev/null +++ b/docs/sysml2/model/version-mark/cli/program.sysml @@ -0,0 +1,11 @@ +package VersionMark { + part def Program { + doc /* Entry point and mode dispatcher (capture, publish, lint, validate). */ + + comment sourceRef /* Source: src/DemaConsulting.VersionMark/Program.cs */ + comment testRef /* Test: test/DemaConsulting.VersionMark.Tests/ProgramTests.cs */ + comment designRef /* Design: docs/design/version-mark/cli/program.md */ + comment verificationRef /* Verification: docs/verification/version-mark/cli/program.md */ + comment reqRef /* Requirements: docs/reqstream/version-mark/cli/program.yaml */ + } +} diff --git a/docs/sysml2/model/version-mark/configuration.sysml b/docs/sysml2/model/version-mark/configuration.sysml new file mode 100644 index 0000000..c40c8c2 --- /dev/null +++ b/docs/sysml2/model/version-mark/configuration.sysml @@ -0,0 +1,14 @@ +package VersionMark { + part def ConfigurationSubsystem { + doc /* YAML configuration loading, validation, and version capture execution. */ + + comment testRef /* Test: test/DemaConsulting.VersionMark.Tests/Configuration/ConfigurationTests.cs */ + comment designRef /* Design: docs/design/version-mark/configuration.md */ + comment verificationRef /* Verification: docs/verification/version-mark/configuration.md */ + comment reqRef /* Requirements: docs/reqstream/version-mark/configuration.yaml */ + + part versionMarkConfig : VersionMarkConfig; + part toolConfig : ToolConfig; + part lintIssue : LintIssue; + } +} diff --git a/docs/sysml2/model/version-mark/configuration/lint-issue.sysml b/docs/sysml2/model/version-mark/configuration/lint-issue.sysml new file mode 100644 index 0000000..c287a74 --- /dev/null +++ b/docs/sysml2/model/version-mark/configuration/lint-issue.sysml @@ -0,0 +1,11 @@ +package VersionMark { + part def LintIssue { + doc /* Represents a single configuration validation issue with source location. */ + + comment sourceRef /* Source: src/DemaConsulting.VersionMark/Configuration/LintIssue.cs */ + comment testRef /* Test: test/DemaConsulting.VersionMark.Tests/Configuration/LintIssueTests.cs */ + comment designRef /* Design: docs/design/version-mark/configuration/lint-issue.md */ + comment verificationRef /* Verification: docs/verification/version-mark/configuration/lint-issue.md */ + comment reqRef /* Requirements: docs/reqstream/version-mark/configuration/lint-issue.yaml */ + } +} diff --git a/docs/sysml2/model/version-mark/configuration/tool-config.sysml b/docs/sysml2/model/version-mark/configuration/tool-config.sysml new file mode 100644 index 0000000..cf77a4d --- /dev/null +++ b/docs/sysml2/model/version-mark/configuration/tool-config.sysml @@ -0,0 +1,11 @@ +package VersionMark { + part def ToolConfig { + doc /* Per-tool capture configuration (command, regex, OS-specific overrides). */ + + comment sourceRef /* Source: src/DemaConsulting.VersionMark/Configuration/VersionMarkConfig.cs (ToolConfig record; no dedicated file) */ + comment testRef /* Test: test/DemaConsulting.VersionMark.Tests/Configuration/VersionMarkConfigTests.cs */ + comment designRef /* Design: docs/design/version-mark/configuration/tool-config.md */ + comment verificationRef /* Verification: docs/verification/version-mark/configuration/tool-config.md */ + comment reqRef /* Requirements: docs/reqstream/version-mark/configuration/tool-config.yaml */ + } +} diff --git a/docs/sysml2/model/version-mark/configuration/version-mark-config.sysml b/docs/sysml2/model/version-mark/configuration/version-mark-config.sysml new file mode 100644 index 0000000..72f8734 --- /dev/null +++ b/docs/sysml2/model/version-mark/configuration/version-mark-config.sysml @@ -0,0 +1,11 @@ +package VersionMark { + part def VersionMarkConfig { + doc /* Loads, validates, and executes `.versionmark.yaml` tool version capture. */ + + comment sourceRef /* Source: src/DemaConsulting.VersionMark/Configuration/VersionMarkConfig.cs */ + comment testRef /* Test: test/DemaConsulting.VersionMark.Tests/Configuration/VersionMarkConfigTests.cs (also see VersionMarkConfigLoadTests.cs) */ + comment designRef /* Design: docs/design/version-mark/configuration/version-mark-config.md */ + comment verificationRef /* Verification: docs/verification/version-mark/configuration/version-mark-config.md */ + comment reqRef /* Requirements: docs/reqstream/version-mark/configuration/version-mark-config.yaml (also load.yaml for VersionMarkConfig.Load behavior) */ + } +} diff --git a/docs/sysml2/model/version-mark/publishing.sysml b/docs/sysml2/model/version-mark/publishing.sysml new file mode 100644 index 0000000..ce44e71 --- /dev/null +++ b/docs/sysml2/model/version-mark/publishing.sysml @@ -0,0 +1,12 @@ +package VersionMark { + part def PublishingSubsystem { + doc /* Markdown report generation from captured version data. */ + + comment testRef /* Test: test/DemaConsulting.VersionMark.Tests/Publishing/PublishingTests.cs */ + comment designRef /* Design: docs/design/version-mark/publishing.md */ + comment verificationRef /* Verification: docs/verification/version-mark/publishing.md */ + comment reqRef /* Requirements: docs/reqstream/version-mark/publishing.yaml */ + + part markdownFormatter : MarkdownFormatter; + } +} diff --git a/docs/sysml2/model/version-mark/publishing/markdown-formatter.sysml b/docs/sysml2/model/version-mark/publishing/markdown-formatter.sysml new file mode 100644 index 0000000..9e60770 --- /dev/null +++ b/docs/sysml2/model/version-mark/publishing/markdown-formatter.sysml @@ -0,0 +1,11 @@ +package VersionMark { + part def MarkdownFormatter { + doc /* Converts loaded version records into a consolidated markdown report. */ + + comment sourceRef /* Source: src/DemaConsulting.VersionMark/Publishing/MarkdownFormatter.cs */ + comment testRef /* Test: test/DemaConsulting.VersionMark.Tests/Publishing/MarkdownFormatterTests.cs */ + comment designRef /* Design: docs/design/version-mark/publishing/markdown-formatter.md */ + comment verificationRef /* Verification: docs/verification/version-mark/publishing/markdown-formatter.md */ + comment reqRef /* Requirements: docs/reqstream/version-mark/publishing/markdown-formatter.yaml */ + } +} diff --git a/docs/sysml2/model/version-mark/self-test.sysml b/docs/sysml2/model/version-mark/self-test.sysml new file mode 100644 index 0000000..9b35bdc --- /dev/null +++ b/docs/sysml2/model/version-mark/self-test.sysml @@ -0,0 +1,12 @@ +package VersionMark { + part def SelfTestSubsystem { + doc /* Built-in self-verification of all operational modes. */ + + comment testRef /* Test: test/DemaConsulting.VersionMark.Tests/SelfTest/SelfTestTests.cs */ + comment designRef /* Design: docs/design/version-mark/self-test.md */ + comment verificationRef /* Verification: docs/verification/version-mark/self-test.md */ + comment reqRef /* Requirements: docs/reqstream/version-mark/self-test.yaml */ + + part validation : Validation; + } +} diff --git a/docs/sysml2/model/version-mark/self-test/validation.sysml b/docs/sysml2/model/version-mark/self-test/validation.sysml new file mode 100644 index 0000000..95f411b --- /dev/null +++ b/docs/sysml2/model/version-mark/self-test/validation.sysml @@ -0,0 +1,11 @@ +package VersionMark { + part def Validation { + doc /* Exercises capture, publish, and lint modes end-to-end for self-validation. */ + + comment sourceRef /* Source: src/DemaConsulting.VersionMark/SelfTest/Validation.cs */ + comment testRef /* Test: test/DemaConsulting.VersionMark.Tests/SelfTest/SelfTestTests.cs (no dedicated ValidationTests.cs) */ + comment designRef /* Design: docs/design/version-mark/self-test/validation.md */ + comment verificationRef /* Verification: docs/verification/version-mark/self-test/validation.md */ + comment reqRef /* Requirements: docs/reqstream/version-mark/self-test/validation.yaml */ + } +} diff --git a/docs/sysml2/model/version-mark/utilities.sysml b/docs/sysml2/model/version-mark/utilities.sysml new file mode 100644 index 0000000..74f2f12 --- /dev/null +++ b/docs/sysml2/model/version-mark/utilities.sysml @@ -0,0 +1,12 @@ +package VersionMark { + part def UtilitiesSubsystem { + doc /* Glob-pattern matching and safe path combination helpers. */ + + comment designRef /* Design: docs/design/version-mark/utilities.md */ + comment verificationRef /* Verification: docs/verification/version-mark/utilities.md */ + comment reqRef /* Requirements: docs/reqstream/version-mark/utilities.yaml */ + + part globMatcher : GlobMatcher; + part pathHelpers : PathHelpers; + } +} diff --git a/docs/sysml2/model/version-mark/utilities/glob-matcher.sysml b/docs/sysml2/model/version-mark/utilities/glob-matcher.sysml new file mode 100644 index 0000000..f8b8a4b --- /dev/null +++ b/docs/sysml2/model/version-mark/utilities/glob-matcher.sysml @@ -0,0 +1,11 @@ +package VersionMark { + part def GlobMatcher { + doc /* Resolves glob patterns into concrete file path lists for publish mode. */ + + comment sourceRef /* Source: src/DemaConsulting.VersionMark/Utilities/GlobMatcher.cs */ + comment testRef /* Test: test/DemaConsulting.VersionMark.Tests/Utilities/GlobMatcherTests.cs */ + comment designRef /* Design: docs/design/version-mark/utilities/glob-matcher.md */ + comment verificationRef /* Verification: docs/verification/version-mark/utilities/glob-matcher.md */ + comment reqRef /* Requirements: docs/reqstream/version-mark/utilities/glob-matcher.yaml */ + } +} diff --git a/docs/sysml2/model/version-mark/utilities/path-helpers.sysml b/docs/sysml2/model/version-mark/utilities/path-helpers.sysml new file mode 100644 index 0000000..ac40370 --- /dev/null +++ b/docs/sysml2/model/version-mark/utilities/path-helpers.sysml @@ -0,0 +1,11 @@ +package VersionMark { + part def PathHelpers { + doc /* Safe path combination helpers used to construct paths within temp directories. */ + + comment sourceRef /* Source: src/DemaConsulting.VersionMark/Utilities/PathHelpers.cs */ + comment testRef /* Test: test/DemaConsulting.VersionMark.Tests/Utilities/PathHelpersTests.cs */ + comment designRef /* Design: docs/design/version-mark/utilities/path-helpers.md */ + comment verificationRef /* Verification: docs/verification/version-mark/utilities/path-helpers.md */ + comment reqRef /* Requirements: docs/reqstream/version-mark/utilities/path-helpers.yaml */ + } +} diff --git a/docs/sysml2/views/design-views.sysml b/docs/sysml2/views/design-views.sysml new file mode 100644 index 0000000..24041bf --- /dev/null +++ b/docs/sysml2/views/design-views.sysml @@ -0,0 +1,38 @@ +// Views rendered into docs/design/generated/ for the Design document. +// Reopens the VersionMark package so each 'expose' statement can reference +// its target part def directly. Per SysML2Tools syntax, 'expose' is only valid +// inside a named 'view' usage (not a 'view def' definition), and it - not +// 'render' - is what scopes the rendered diagram content. +package VersionMark { + view SoftwareStructureView { + expose VersionMark; + } + + view VersionMarkView { + expose VersionMarkSystem; + } + + view CliView { + expose CliSubsystem; + } + + view ConfigurationView { + expose ConfigurationSubsystem; + } + + view CaptureView { + expose CaptureSubsystem; + } + + view PublishingView { + expose PublishingSubsystem; + } + + view SelfTestView { + expose SelfTestSubsystem; + } + + view UtilitiesView { + expose UtilitiesSubsystem; + } +} diff --git a/docs/verification/definition.yaml b/docs/verification/definition.yaml index d5795ee..ec12169 100644 --- a/docs/verification/definition.yaml +++ b/docs/verification/definition.yaml @@ -39,6 +39,7 @@ input-files: - docs/verification/ots/reviewmark.md - docs/verification/ots/sarifmark.md - docs/verification/ots/sonarmark.md + - docs/verification/ots/sysml2tools.md - docs/verification/ots/weasyprint.md template: template.html table-of-contents: true diff --git a/docs/verification/introduction.md b/docs/verification/introduction.md index e8e9924..79a3c54 100644 --- a/docs/verification/introduction.md +++ b/docs/verification/introduction.md @@ -38,6 +38,7 @@ It also covers verification evidence for the following Off-The-Shelf (OTS) compo - **ReviewMark** - code review enforcement tool - **SarifMark** - SARIF report tool - **SonarMark** - SonarCloud report tool +- **SysML2Tools** - SysML2 architecture modeling and diagram rendering tool - **WeasyPrint** - HTML-to-PDF conversion tool - **xUnit** - unit testing framework - **YamlDotNet** - YAML parsing library @@ -46,31 +47,6 @@ This document does not cover installation, end-user usage patterns, or CI/CD pip configuration. Those topics are addressed in the VersionMark User Guide and the VersionMark Requirements documents. -## Software Structure - -The following tree shows how the VersionMark software items are organized across the -system, subsystem, and unit levels: - -```text -VersionMark (System) -├── Cli (Subsystem) -│ ├── Program (Unit) -│ └── Context (Unit) -├── Configuration (Subsystem) -│ ├── VersionMarkConfig (Unit) -│ ├── ToolConfig (Unit) -│ └── LintIssue (Unit) -├── Capture (Subsystem) -│ └── VersionInfo (Unit) -├── Publishing (Subsystem) -│ └── MarkdownFormatter (Unit) -├── SelfTest (Subsystem) -│ └── Validation (Unit) -└── Utilities (Subsystem) - ├── GlobMatcher (Unit) - └── PathHelpers (Unit) -``` - ## Companion Artifact Structure In-house items have parallel artifacts in the following locations: diff --git a/docs/verification/ots.md b/docs/verification/ots.md index 40d5c06..8c5738f 100644 --- a/docs/verification/ots.md +++ b/docs/verification/ots.md @@ -17,7 +17,7 @@ provides a built-in self-validation mode. Tools that expose a `--validate` flag are verified by invoking that flag directly in the CI pipeline. The following tools fall into this category: BuildMark, FileAssert, ReqStream, -ReviewMark, SarifMark, and SonarMark. Each tool's self-validation exercises its own +ReviewMark, SarifMark, SonarMark, and SysML2Tools. Each tool's self-validation exercises its own internal logic and reports results in TRX format. xUnit is treated similarly: the `dotnet test` run that executes the VersionMark test suite simultaneously validates that xUnit itself is operating correctly. @@ -41,7 +41,7 @@ exercise YAML parsing. The following evidence artifacts are collected during each CI run: For tools with built-in self-validation (BuildMark, FileAssert, ReqStream, ReviewMark, -SarifMark, SonarMark), the CI pipeline captures TRX result files stored as pipeline +SarifMark, SonarMark, SysML2Tools), the CI pipeline captures TRX result files stored as pipeline artifacts under the path `artifacts/{tool}-self-validation.trx`, where `{tool}` is the lowercase tool name (for example, `artifacts/buildmark-self-validation.trx`). @@ -65,8 +65,8 @@ When an OTS component is upgraded to a new version, the full CI pipeline is re-r that version before the upgrade is accepted. For tools with built-in self-validation (BuildMark, FileAssert, ReqStream, ReviewMark, -SarifMark, SonarMark, xUnit), the corresponding self-validation TRX must complete with -zero failures. Any failure in the TRX output blocks the upgrade until the root cause is +SarifMark, SonarMark, SysML2Tools, xUnit), the corresponding self-validation TRX must complete +with zero failures. Any failure in the TRX output blocks the upgrade until the root cause is resolved. For Pandoc and WeasyPrint, all FileAssert assertions on the seven generated document types diff --git a/docs/verification/ots/sysml2tools.md b/docs/verification/ots/sysml2tools.md new file mode 100644 index 0000000..e8be1de --- /dev/null +++ b/docs/verification/ots/sysml2tools.md @@ -0,0 +1,54 @@ +## SysML2Tools Verification + +This document provides the verification evidence for the `SysML2Tools` OTS software item. +Requirements for this OTS item are defined in the SysML2Tools OTS Software Requirements document. + +### Required Functionality + +DemaConsulting.SysML2Tools validates the SysML2 architecture model under `docs/sysml2/` for syntax +and reference errors, and renders each view declared in `docs/sysml2/views/design-views.sysml` to +an SVG diagram embedded in the design documentation. Both behaviors run in the same CI pipeline +that produces the compiled Design document, so a successful pipeline run is evidence that +SysML2Tools executed without error. + +### Verification Approach + +SysML2Tools is verified by a combination of authored self-validation evidence and CI pipeline +evidence: + +- **Self-validation evidence**: `dotnet sysml2tools --validate --results ` runs the + tool's built-in self-test suite, which exercises `lint` and `render --format svg` against known + model fixtures and writes a TRX file consumed by `reqstream --enforce` + (`SysML2Tools_LintSelfTest`, `SysML2Tools_RenderSvgSelfTest`). +- **Pipeline evidence**: `lint.ps1` runs `dotnet sysml2tools lint 'docs/sysml2/**/*.sysml'` against + the actual VersionMark model and fails the build on any syntax or reference error. The + build-docs job runs `dotnet sysml2tools render` to produce one SVG file per declared view under + `docs/design/generated/`. Pandoc then compiles `docs/design/*.md`, which embed those SVG files by + filename; if a declared view failed to render, the missing image reference would cause a broken + image in the compiled Design HTML and PDF. WeasyPrint renders the result to PDF and FileAssert + asserts its content (`artifacts/fileassert-design.trx`). A CI build failure at either step is + evidence that SysML2Tools did not produce the required model validation or diagrams against the + real model. + +### Test Scenarios + +#### SysML2Tools_LintSelfTest + +**Scenario**: SysML2Tools is invoked with `--validate`, which exercises `lint` against a known-good +and a known-bad model fixture as part of its built-in self-test suite. + +**Expected**: Exits 0 with no reported syntax or reference errors for the valid fixture, and +correctly reports an error for the invalid fixture. + +#### SysML2Tools_RenderSvgSelfTest + +**Scenario**: SysML2Tools is invoked with `--validate`, which exercises `render --format svg` +against a known-good model fixture as part of its built-in self-test suite. + +**Expected**: Exits 0 and produces a non-empty SVG file for the fixture's declared view. + +### Acceptance Criteria + +N/A - Acceptance criteria are managed at the system integration level. This OTS item is considered +verified when the integration test scenarios that exercise its functionality pass in the CI +pipeline. diff --git a/lint.ps1 b/lint.ps1 index 5650ff3..0a0cd50 100644 --- a/lint.ps1 +++ b/lint.ps1 @@ -102,6 +102,11 @@ if (-not $skipDotnetTools) { dotnet reviewmark --lint if ($LASTEXITCODE -ne 0) { $lintError = $true } + + if (Test-Path docs/sysml2) { + dotnet sysml2tools lint 'docs/sysml2/**/*.sysml' + if ($LASTEXITCODE -ne 0) { $lintError = $true } + } } # [PROJECT-SPECIFIC] Add additional dotnet tool lint checks here. diff --git a/requirements.yaml b/requirements.yaml index 4e900bb..b771ef3 100644 --- a/requirements.yaml +++ b/requirements.yaml @@ -34,3 +34,7 @@ includes: - docs/reqstream/ots/pandoc.yaml - docs/reqstream/ots/weasyprint.yaml - docs/reqstream/ots/fileassert.yaml + - docs/reqstream/ots/sysml2tools.yaml + - docs/reqstream/ots/yaml-dot-net.yaml + - docs/reqstream/ots/microsoft-extensions-file-system-globbing.yaml + - docs/reqstream/ots/dema-consulting-test-results.yaml