From a8e596804e3e64029a2e9665359e04f821438617 Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Tue, 7 Jul 2026 21:39:54 -0400 Subject: [PATCH 01/12] Sync agents, standards, and skills in preparation for sysml2 design work Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/agents/developer.agent.md | 5 +- .github/agents/formal-review.agent.md | 13 +- .github/agents/implementation.agent.md | 54 +++-- .github/agents/lint-fix.agent.md | 3 +- .github/agents/planning.agent.md | 134 ++++++++++++ .github/agents/quality.agent.md | 33 ++- .github/agents/template-sync.agent.md | 45 ++++- .github/skills/sysml2tools-query/SKILL.md | 145 +++++++++++++ .github/standards/design-documentation.md | 12 +- .github/standards/reviewmark-usage.md | 136 +++++++------ .github/standards/software-items.md | 5 + .github/standards/sysml2-modeling.md | 235 ++++++++++++++++++++++ AGENTS.md | 32 +-- 13 files changed, 720 insertions(+), 132 deletions(-) create mode 100644 .github/agents/planning.agent.md create mode 100644 .github/skills/sysml2tools-query/SKILL.md create mode 100644 .github/standards/sysml2-modeling.md 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..60f7b96 --- /dev/null +++ b/.github/standards/sysml2-modeling.md @@ -0,0 +1,235 @@ +--- +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 + render asTreeDiagram; + } + + view {SystemName}View { + expose {SystemName}System; // system def only, not expanded into subsystems + render asTreeDiagram; + } + + view {SubsystemName}View { + expose {SubsystemName}; // one subsystem def only + render asTreeDiagram; + } +} +``` + +**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. +`asTreeDiagram`) — 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/AGENTS.md b/AGENTS.md index 104e954..bd0249f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,6 +19,7 @@ │ ├── requirements_doc/ │ ├── requirements_report/ │ ├── reqstream/ +│ ├── sysml2/ │ ├── user_guide/ │ └── verification/ ├── src/ @@ -36,16 +37,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 @@ -60,6 +63,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. @@ -76,6 +80,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. @@ -86,12 +91,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) @@ -100,16 +108,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) @@ -127,7 +135,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) From 7893991789f137cde75722729056365b8f72838a Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Tue, 7 Jul 2026 22:14:07 -0400 Subject: [PATCH 02/12] Add SysML2 architecture model for BuildMark Adds docs/sysml2/model/**/*.sysml covering the BuildMark system, all subsystems (including nested GitHub/AzureDevOps/Mock repo-connector sub-subsystems), and all units, plus docs/sysml2/model/ots.sysml for the YamlDotNet OTS dependency and docs/sysml2/views/design-views.sysml with SoftwareStructureView, BuildMarkView, and one {SubsystemName}View per subsystem. Every part def carries sourceRef/testRef/designRef/verificationRef/ reqRef comments pointing at verified existing companion artifacts, with documented-exception comments for units that share a subsystem- level file (Configuration units' reqRef, RuleMatchConfig, IRepoConnector, ItemControlsInfo, AzureDevOpsApiTypes, GitHubGraphQLTypes) and for the YamlDotNet OTS gap (no verification/reqstream doc exists). Co-authored-by: GitHub Copilot <198982749+Copilot@users.noreply.github.com> --- docs/sysml2/model/build-mark.sysml | 28 ++++++++ .../sysml2/model/build-mark/build-notes.sysml | 14 ++++ .../build-notes/build-information.sysml | 11 ++++ .../build-mark/build-notes/item-info.sysml | 11 ++++ .../build-mark/build-notes/web-link.sysml | 11 ++++ docs/sysml2/model/build-mark/cli.sysml | 12 ++++ .../sysml2/model/build-mark/cli/context.sysml | 11 ++++ .../model/build-mark/configuration.sysml | 22 +++++++ .../azure-devops-connector-config.sysml | 11 ++++ .../build-mark-config-reader.sysml | 11 ++++ .../configuration/build-mark-config.sysml | 11 ++++ .../configuration/configuration-issue.sysml | 11 ++++ .../configuration-load-result.sysml | 11 ++++ .../configuration/connector-config.sysml | 11 ++++ .../github-connector-config.sysml | 13 ++++ .../configuration/report-config.sysml | 11 ++++ .../configuration/rule-config.sysml | 11 ++++ .../configuration/rule-match-config.sysml | 11 ++++ .../configuration/section-config.sysml | 11 ++++ docs/sysml2/model/build-mark/program.sysml | 11 ++++ .../model/build-mark/repo-connectors.sysml | 20 ++++++ .../repo-connectors/azure-devops.sysml | 15 +++++ .../azure-devops/azure-devops-api-types.sysml | 11 ++++ .../azure-devops-repo-connector.sysml | 11 ++++ .../azure-devops-rest-client.sysml | 11 ++++ .../azure-devops/work-item-mapper.sysml | 11 ++++ .../build-mark/repo-connectors/github.sysml | 14 ++++ .../github/github-graphql-client.sysml | 13 ++++ .../github/github-graphql-types.sysml | 13 ++++ .../github/github-repo-connector.sysml | 13 ++++ .../repo-connectors/i-repo-connector.sysml | 11 ++++ .../repo-connectors/item-controls-info.sysml | 11 ++++ .../item-controls-parser.sysml | 11 ++++ .../repo-connectors/item-router.sysml | 11 ++++ .../build-mark/repo-connectors/mock.sysml | 12 ++++ .../mock/mock-repo-connector.sysml | 11 ++++ .../repo-connectors/repo-connector-base.sysml | 11 ++++ .../repo-connector-factory.sysml | 11 ++++ docs/sysml2/model/build-mark/self-test.sysml | 12 ++++ .../build-mark/self-test/validation.sysml | 11 ++++ docs/sysml2/model/build-mark/utilities.sysml | 14 ++++ .../build-mark/utilities/path-helpers.sysml | 11 ++++ .../build-mark/utilities/process-runner.sysml | 11 ++++ .../utilities/temporary-directory.sysml | 11 ++++ docs/sysml2/model/build-mark/version.sysml | 17 +++++ .../version/version-commit-tag.sysml | 11 ++++ .../version/version-comparable.sysml | 11 ++++ .../version/version-interval-set.sysml | 11 ++++ .../build-mark/version/version-interval.sysml | 11 ++++ .../build-mark/version/version-semantic.sysml | 11 ++++ .../build-mark/version/version-tag.sysml | 11 ++++ docs/sysml2/model/ots.sysml | 11 ++++ docs/sysml2/views/design-views.sysml | 66 +++++++++++++++++++ 53 files changed, 705 insertions(+) create mode 100644 docs/sysml2/model/build-mark.sysml create mode 100644 docs/sysml2/model/build-mark/build-notes.sysml create mode 100644 docs/sysml2/model/build-mark/build-notes/build-information.sysml create mode 100644 docs/sysml2/model/build-mark/build-notes/item-info.sysml create mode 100644 docs/sysml2/model/build-mark/build-notes/web-link.sysml create mode 100644 docs/sysml2/model/build-mark/cli.sysml create mode 100644 docs/sysml2/model/build-mark/cli/context.sysml create mode 100644 docs/sysml2/model/build-mark/configuration.sysml create mode 100644 docs/sysml2/model/build-mark/configuration/azure-devops-connector-config.sysml create mode 100644 docs/sysml2/model/build-mark/configuration/build-mark-config-reader.sysml create mode 100644 docs/sysml2/model/build-mark/configuration/build-mark-config.sysml create mode 100644 docs/sysml2/model/build-mark/configuration/configuration-issue.sysml create mode 100644 docs/sysml2/model/build-mark/configuration/configuration-load-result.sysml create mode 100644 docs/sysml2/model/build-mark/configuration/connector-config.sysml create mode 100644 docs/sysml2/model/build-mark/configuration/github-connector-config.sysml create mode 100644 docs/sysml2/model/build-mark/configuration/report-config.sysml create mode 100644 docs/sysml2/model/build-mark/configuration/rule-config.sysml create mode 100644 docs/sysml2/model/build-mark/configuration/rule-match-config.sysml create mode 100644 docs/sysml2/model/build-mark/configuration/section-config.sysml create mode 100644 docs/sysml2/model/build-mark/program.sysml create mode 100644 docs/sysml2/model/build-mark/repo-connectors.sysml create mode 100644 docs/sysml2/model/build-mark/repo-connectors/azure-devops.sysml create mode 100644 docs/sysml2/model/build-mark/repo-connectors/azure-devops/azure-devops-api-types.sysml create mode 100644 docs/sysml2/model/build-mark/repo-connectors/azure-devops/azure-devops-repo-connector.sysml create mode 100644 docs/sysml2/model/build-mark/repo-connectors/azure-devops/azure-devops-rest-client.sysml create mode 100644 docs/sysml2/model/build-mark/repo-connectors/azure-devops/work-item-mapper.sysml create mode 100644 docs/sysml2/model/build-mark/repo-connectors/github.sysml create mode 100644 docs/sysml2/model/build-mark/repo-connectors/github/github-graphql-client.sysml create mode 100644 docs/sysml2/model/build-mark/repo-connectors/github/github-graphql-types.sysml create mode 100644 docs/sysml2/model/build-mark/repo-connectors/github/github-repo-connector.sysml create mode 100644 docs/sysml2/model/build-mark/repo-connectors/i-repo-connector.sysml create mode 100644 docs/sysml2/model/build-mark/repo-connectors/item-controls-info.sysml create mode 100644 docs/sysml2/model/build-mark/repo-connectors/item-controls-parser.sysml create mode 100644 docs/sysml2/model/build-mark/repo-connectors/item-router.sysml create mode 100644 docs/sysml2/model/build-mark/repo-connectors/mock.sysml create mode 100644 docs/sysml2/model/build-mark/repo-connectors/mock/mock-repo-connector.sysml create mode 100644 docs/sysml2/model/build-mark/repo-connectors/repo-connector-base.sysml create mode 100644 docs/sysml2/model/build-mark/repo-connectors/repo-connector-factory.sysml create mode 100644 docs/sysml2/model/build-mark/self-test.sysml create mode 100644 docs/sysml2/model/build-mark/self-test/validation.sysml create mode 100644 docs/sysml2/model/build-mark/utilities.sysml create mode 100644 docs/sysml2/model/build-mark/utilities/path-helpers.sysml create mode 100644 docs/sysml2/model/build-mark/utilities/process-runner.sysml create mode 100644 docs/sysml2/model/build-mark/utilities/temporary-directory.sysml create mode 100644 docs/sysml2/model/build-mark/version.sysml create mode 100644 docs/sysml2/model/build-mark/version/version-commit-tag.sysml create mode 100644 docs/sysml2/model/build-mark/version/version-comparable.sysml create mode 100644 docs/sysml2/model/build-mark/version/version-interval-set.sysml create mode 100644 docs/sysml2/model/build-mark/version/version-interval.sysml create mode 100644 docs/sysml2/model/build-mark/version/version-semantic.sysml create mode 100644 docs/sysml2/model/build-mark/version/version-tag.sysml create mode 100644 docs/sysml2/model/ots.sysml create mode 100644 docs/sysml2/views/design-views.sysml diff --git a/docs/sysml2/model/build-mark.sysml b/docs/sysml2/model/build-mark.sysml new file mode 100644 index 0000000..dd42721 --- /dev/null +++ b/docs/sysml2/model/build-mark.sysml @@ -0,0 +1,28 @@ +package BuildMark { + import OtsDependencies::*; + + doc + /* + * BuildMark is a .NET command-line tool that generates markdown build notes from + * Git repository metadata, including GitHub and Azure DevOps repositories. + */ + + part def BuildMarkSystem { + doc /* The BuildMark system as a whole. */ + + comment testRef /* Test: test/DemaConsulting.BuildMark.Tests/IntegrationTests.cs */ + comment designRef /* Design: docs/design/build-mark.md */ + comment verificationRef /* Verification: docs/verification/build-mark.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark.yaml */ + + part program : Program; + part cli : CliSubsystem; + part buildNotes : BuildNotesSubsystem; + part selfTest : SelfTestSubsystem; + part utilities : UtilitiesSubsystem; + part version : VersionSubsystem; + part configuration : ConfigurationSubsystem; + part repoConnectors : RepoConnectorsSubsystem; + part yamlDotNet : YamlDotNet; + } +} diff --git a/docs/sysml2/model/build-mark/build-notes.sysml b/docs/sysml2/model/build-mark/build-notes.sysml new file mode 100644 index 0000000..917053d --- /dev/null +++ b/docs/sysml2/model/build-mark/build-notes.sysml @@ -0,0 +1,14 @@ +package BuildMark { + part def BuildNotesSubsystem { + doc /* Build notes data models: build information, item info, and web links. */ + + comment testRef /* Test: test/DemaConsulting.BuildMark.Tests/BuildNotes/BuildNotesTests.cs */ + comment designRef /* Design: docs/design/build-mark/build-notes.md */ + comment verificationRef /* Verification: docs/verification/build-mark/build-notes.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/build-notes.yaml */ + + part buildInformation : BuildInformation; + part itemInfo : ItemInfo; + part webLink : WebLink; + } +} diff --git a/docs/sysml2/model/build-mark/build-notes/build-information.sysml b/docs/sysml2/model/build-mark/build-notes/build-information.sysml new file mode 100644 index 0000000..72d2908 --- /dev/null +++ b/docs/sysml2/model/build-mark/build-notes/build-information.sysml @@ -0,0 +1,11 @@ +package BuildMark { + part def BuildInformation { + doc /* Build information data model. */ + + comment sourceRef /* Source: src/DemaConsulting.BuildMark/BuildNotes/BuildInformation.cs */ + comment testRef /* Test: test/DemaConsulting.BuildMark.Tests/BuildNotes/BuildInformationTests.cs */ + comment designRef /* Design: docs/design/build-mark/build-notes/build-information.md */ + comment verificationRef /* Verification: docs/verification/build-mark/build-notes/build-information.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/build-notes/build-information.yaml */ + } +} diff --git a/docs/sysml2/model/build-mark/build-notes/item-info.sysml b/docs/sysml2/model/build-mark/build-notes/item-info.sysml new file mode 100644 index 0000000..c5def90 --- /dev/null +++ b/docs/sysml2/model/build-mark/build-notes/item-info.sysml @@ -0,0 +1,11 @@ +package BuildMark { + part def ItemInfo { + doc /* Item information data model. */ + + comment sourceRef /* Source: src/DemaConsulting.BuildMark/BuildNotes/ItemInfo.cs */ + comment designRef /* Design: docs/design/build-mark/build-notes/item-info.md */ + comment verificationRef /* Verification: docs/verification/build-mark/build-notes/item-info.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/build-notes/item-info.yaml */ + // Note: no testRef - no dedicated test file exists (exercised only indirectly). + } +} diff --git a/docs/sysml2/model/build-mark/build-notes/web-link.sysml b/docs/sysml2/model/build-mark/build-notes/web-link.sysml new file mode 100644 index 0000000..b751345 --- /dev/null +++ b/docs/sysml2/model/build-mark/build-notes/web-link.sysml @@ -0,0 +1,11 @@ +package BuildMark { + part def WebLink { + doc /* Web link helper. */ + + comment sourceRef /* Source: src/DemaConsulting.BuildMark/BuildNotes/WebLink.cs */ + comment designRef /* Design: docs/design/build-mark/build-notes/web-link.md */ + comment verificationRef /* Verification: docs/verification/build-mark/build-notes/web-link.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/build-notes/web-link.yaml */ + // Note: no testRef - no dedicated test file exists (exercised only indirectly). + } +} diff --git a/docs/sysml2/model/build-mark/cli.sysml b/docs/sysml2/model/build-mark/cli.sysml new file mode 100644 index 0000000..16f8513 --- /dev/null +++ b/docs/sysml2/model/build-mark/cli.sysml @@ -0,0 +1,12 @@ +package BuildMark { + part def CliSubsystem { + doc /* Command-line argument parsing and I/O ownership. */ + + comment testRef /* Test: test/DemaConsulting.BuildMark.Tests/Cli/CliTests.cs */ + comment designRef /* Design: docs/design/build-mark/cli.md */ + comment verificationRef /* Verification: docs/verification/build-mark/cli.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/cli.yaml */ + + part context : Context; + } +} diff --git a/docs/sysml2/model/build-mark/cli/context.sysml b/docs/sysml2/model/build-mark/cli/context.sysml new file mode 100644 index 0000000..a68702e --- /dev/null +++ b/docs/sysml2/model/build-mark/cli/context.sysml @@ -0,0 +1,11 @@ +package BuildMark { + part def Context { + doc /* Command-line argument parser and I/O owner. */ + + comment sourceRef /* Source: src/DemaConsulting.BuildMark/Cli/Context.cs */ + comment testRef /* Test: test/DemaConsulting.BuildMark.Tests/Cli/ContextTests.cs */ + comment designRef /* Design: docs/design/build-mark/cli/context.md */ + comment verificationRef /* Verification: docs/verification/build-mark/cli/context.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/cli/context.yaml */ + } +} diff --git a/docs/sysml2/model/build-mark/configuration.sysml b/docs/sysml2/model/build-mark/configuration.sysml new file mode 100644 index 0000000..2416f48 --- /dev/null +++ b/docs/sysml2/model/build-mark/configuration.sysml @@ -0,0 +1,22 @@ +package BuildMark { + part def ConfigurationSubsystem { + doc /* Configuration data models and .buildmark.yaml loading/parsing. */ + + comment testRef /* Test: test/DemaConsulting.BuildMark.Tests/Configuration/ConfigurationSubsystemTests.cs */ + comment designRef /* Design: docs/design/build-mark/configuration.md */ + comment verificationRef /* Verification: docs/verification/build-mark/configuration.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/configuration.yaml */ + + part buildMarkConfig : BuildMarkConfig; + part buildMarkConfigReader : BuildMarkConfigReader; + part configurationLoadResult : ConfigurationLoadResult; + part configurationIssue : ConfigurationIssue; + part connectorConfig : ConnectorConfig; + part gitHubConnectorConfig : GitHubConnectorConfig; + part azureDevOpsConnectorConfig : AzureDevOpsConnectorConfig; + part reportConfig : ReportConfig; + part sectionConfig : SectionConfig; + part ruleConfig : RuleConfig; + part ruleMatchConfig : RuleMatchConfig; + } +} diff --git a/docs/sysml2/model/build-mark/configuration/azure-devops-connector-config.sysml b/docs/sysml2/model/build-mark/configuration/azure-devops-connector-config.sysml new file mode 100644 index 0000000..2a3a6ed --- /dev/null +++ b/docs/sysml2/model/build-mark/configuration/azure-devops-connector-config.sysml @@ -0,0 +1,11 @@ +package BuildMark { + part def AzureDevOpsConnectorConfig { + doc /* Azure DevOps connector settings data model. */ + + comment sourceRef /* Source: src/DemaConsulting.BuildMark/Configuration/AzureDevOpsConnectorConfig.cs */ + comment designRef /* Design: docs/design/build-mark/configuration/azure-devops-connector-config.md */ + comment verificationRef /* Verification: docs/verification/build-mark/configuration/azure-devops-connector-config.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/configuration.yaml (documented exception: no dedicated per-unit reqstream file exists for Configuration units) */ + // Note: no testRef - no dedicated test file exists (exercised only indirectly). + } +} diff --git a/docs/sysml2/model/build-mark/configuration/build-mark-config-reader.sysml b/docs/sysml2/model/build-mark/configuration/build-mark-config-reader.sysml new file mode 100644 index 0000000..3937cff --- /dev/null +++ b/docs/sysml2/model/build-mark/configuration/build-mark-config-reader.sysml @@ -0,0 +1,11 @@ +package BuildMark { + part def BuildMarkConfigReader { + doc /* Reads and parses .buildmark.yaml using YamlDotNet. */ + + comment sourceRef /* Source: src/DemaConsulting.BuildMark/Configuration/BuildMarkConfigReader.cs */ + comment designRef /* Design: docs/design/build-mark/configuration/build-mark-config-reader.md */ + comment verificationRef /* Verification: docs/verification/build-mark/configuration/build-mark-config-reader.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/configuration.yaml (documented exception: no dedicated per-unit reqstream file exists for Configuration units) */ + // Note: no testRef - no dedicated test file exists (exercised only indirectly). + } +} diff --git a/docs/sysml2/model/build-mark/configuration/build-mark-config.sysml b/docs/sysml2/model/build-mark/configuration/build-mark-config.sysml new file mode 100644 index 0000000..86d7425 --- /dev/null +++ b/docs/sysml2/model/build-mark/configuration/build-mark-config.sysml @@ -0,0 +1,11 @@ +package BuildMark { + part def BuildMarkConfig { + doc /* Top-level configuration data model. */ + + comment sourceRef /* Source: src/DemaConsulting.BuildMark/Configuration/BuildMarkConfig.cs */ + comment designRef /* Design: docs/design/build-mark/configuration/build-mark-config.md */ + comment verificationRef /* Verification: docs/verification/build-mark/configuration/build-mark-config.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/configuration.yaml (documented exception: no dedicated per-unit reqstream file exists for Configuration units) */ + // Note: no testRef - no dedicated test file exists (exercised only indirectly). + } +} diff --git a/docs/sysml2/model/build-mark/configuration/configuration-issue.sysml b/docs/sysml2/model/build-mark/configuration/configuration-issue.sysml new file mode 100644 index 0000000..05f530b --- /dev/null +++ b/docs/sysml2/model/build-mark/configuration/configuration-issue.sysml @@ -0,0 +1,11 @@ +package BuildMark { + part def ConfigurationIssue { + doc /* Single issue with location and severity. */ + + comment sourceRef /* Source: src/DemaConsulting.BuildMark/Configuration/ConfigurationIssue.cs */ + comment designRef /* Design: docs/design/build-mark/configuration/configuration-issue.md */ + comment verificationRef /* Verification: docs/verification/build-mark/configuration/configuration-issue.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/configuration.yaml (documented exception: no dedicated per-unit reqstream file exists for Configuration units) */ + // Note: no testRef - no dedicated test file exists (exercised only indirectly). + } +} diff --git a/docs/sysml2/model/build-mark/configuration/configuration-load-result.sysml b/docs/sysml2/model/build-mark/configuration/configuration-load-result.sysml new file mode 100644 index 0000000..24d0ca4 --- /dev/null +++ b/docs/sysml2/model/build-mark/configuration/configuration-load-result.sysml @@ -0,0 +1,11 @@ +package BuildMark { + part def ConfigurationLoadResult { + doc /* Holds config and any load issues. */ + + comment sourceRef /* Source: src/DemaConsulting.BuildMark/Configuration/ConfigurationLoadResult.cs */ + comment designRef /* Design: docs/design/build-mark/configuration/configuration-load-result.md */ + comment verificationRef /* Verification: docs/verification/build-mark/configuration/configuration-load-result.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/configuration.yaml (documented exception: no dedicated per-unit reqstream file exists for Configuration units) */ + // Note: no testRef - no dedicated test file exists (exercised only indirectly). + } +} diff --git a/docs/sysml2/model/build-mark/configuration/connector-config.sysml b/docs/sysml2/model/build-mark/configuration/connector-config.sysml new file mode 100644 index 0000000..b51b64a --- /dev/null +++ b/docs/sysml2/model/build-mark/configuration/connector-config.sysml @@ -0,0 +1,11 @@ +package BuildMark { + part def ConnectorConfig { + doc /* Connector envelope data model. */ + + comment sourceRef /* Source: src/DemaConsulting.BuildMark/Configuration/ConnectorConfig.cs */ + comment designRef /* Design: docs/design/build-mark/configuration/connector-config.md */ + comment verificationRef /* Verification: docs/verification/build-mark/configuration/connector-config.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/configuration.yaml (documented exception: no dedicated per-unit reqstream file exists for Configuration units) */ + // Note: no testRef - no dedicated test file exists (exercised only indirectly). + } +} diff --git a/docs/sysml2/model/build-mark/configuration/github-connector-config.sysml b/docs/sysml2/model/build-mark/configuration/github-connector-config.sysml new file mode 100644 index 0000000..25aa47b --- /dev/null +++ b/docs/sysml2/model/build-mark/configuration/github-connector-config.sysml @@ -0,0 +1,13 @@ +package BuildMark { + part def GitHubConnectorConfig { + doc /* GitHub connector settings data model. */ + + comment sourceRef /* Source: src/DemaConsulting.BuildMark/Configuration/GitHubConnectorConfig.cs */ + comment designRef /* Design: docs/design/build-mark/configuration/github-connector-config.md */ + comment verificationRef /* Verification: docs/verification/build-mark/configuration/git-hub-connector-config.md */ + // Note: verificationRef uses a different kebab-case split than designRef for the + // same PascalCase name (pre-existing casing inconsistency, used verbatim, not fixed). + comment reqRef /* Requirements: docs/reqstream/build-mark/configuration.yaml (documented exception: no dedicated per-unit reqstream file exists for Configuration units) */ + // Note: no testRef - no dedicated test file exists (exercised only indirectly). + } +} diff --git a/docs/sysml2/model/build-mark/configuration/report-config.sysml b/docs/sysml2/model/build-mark/configuration/report-config.sysml new file mode 100644 index 0000000..27d917c --- /dev/null +++ b/docs/sysml2/model/build-mark/configuration/report-config.sysml @@ -0,0 +1,11 @@ +package BuildMark { + part def ReportConfig { + doc /* Report output settings data model. */ + + comment sourceRef /* Source: src/DemaConsulting.BuildMark/Configuration/ReportConfig.cs */ + comment designRef /* Design: docs/design/build-mark/configuration/report-config.md */ + comment verificationRef /* Verification: docs/verification/build-mark/configuration/report-config.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/configuration.yaml (documented exception: no dedicated per-unit reqstream file exists for Configuration units) */ + // Note: no testRef - no dedicated test file exists (exercised only indirectly). + } +} diff --git a/docs/sysml2/model/build-mark/configuration/rule-config.sysml b/docs/sysml2/model/build-mark/configuration/rule-config.sysml new file mode 100644 index 0000000..0829d52 --- /dev/null +++ b/docs/sysml2/model/build-mark/configuration/rule-config.sysml @@ -0,0 +1,11 @@ +package BuildMark { + part def RuleConfig { + doc /* Routing rule data model. */ + + comment sourceRef /* Source: src/DemaConsulting.BuildMark/Configuration/RuleConfig.cs */ + comment designRef /* Design: docs/design/build-mark/configuration/rule-config.md */ + comment verificationRef /* Verification: docs/verification/build-mark/configuration/rule-config.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/configuration.yaml (documented exception: no dedicated per-unit reqstream file exists for Configuration units) */ + // Note: no testRef - no dedicated test file exists (exercised only indirectly). + } +} diff --git a/docs/sysml2/model/build-mark/configuration/rule-match-config.sysml b/docs/sysml2/model/build-mark/configuration/rule-match-config.sysml new file mode 100644 index 0000000..b08d4b3 --- /dev/null +++ b/docs/sysml2/model/build-mark/configuration/rule-match-config.sysml @@ -0,0 +1,11 @@ +package BuildMark { + part def RuleMatchConfig { + doc /* Rule-match condition data model (companion record defined alongside RuleConfig). */ + + comment sourceRef /* Source: src/DemaConsulting.BuildMark/Configuration/RuleConfig.cs (companion record defined in the same source file) */ + comment designRef /* Design: docs/design/build-mark/configuration/rule-config.md (documented as a supporting value type) */ + comment verificationRef /* Verification: docs/verification/build-mark/configuration/rule-match-config.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/configuration.yaml (documented exception: no dedicated per-unit reqstream file exists for Configuration units) */ + // Note: no testRef - no dedicated test file exists (exercised only indirectly). + } +} diff --git a/docs/sysml2/model/build-mark/configuration/section-config.sysml b/docs/sysml2/model/build-mark/configuration/section-config.sysml new file mode 100644 index 0000000..bc128db --- /dev/null +++ b/docs/sysml2/model/build-mark/configuration/section-config.sysml @@ -0,0 +1,11 @@ +package BuildMark { + part def SectionConfig { + doc /* Report section definition data model. */ + + comment sourceRef /* Source: src/DemaConsulting.BuildMark/Configuration/SectionConfig.cs */ + comment designRef /* Design: docs/design/build-mark/configuration/section-config.md */ + comment verificationRef /* Verification: docs/verification/build-mark/configuration/section-config.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/configuration.yaml (documented exception: no dedicated per-unit reqstream file exists for Configuration units) */ + // Note: no testRef - no dedicated test file exists (exercised only indirectly). + } +} diff --git a/docs/sysml2/model/build-mark/program.sysml b/docs/sysml2/model/build-mark/program.sysml new file mode 100644 index 0000000..f66be1d --- /dev/null +++ b/docs/sysml2/model/build-mark/program.sysml @@ -0,0 +1,11 @@ +package BuildMark { + part def Program { + doc /* Entry point and execution orchestrator. */ + + comment sourceRef /* Source: src/DemaConsulting.BuildMark/Program.cs */ + comment testRef /* Test: test/DemaConsulting.BuildMark.Tests/ProgramTests.cs */ + comment designRef /* Design: docs/design/build-mark/program.md */ + comment verificationRef /* Verification: docs/verification/build-mark/program.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/program.yaml */ + } +} diff --git a/docs/sysml2/model/build-mark/repo-connectors.sysml b/docs/sysml2/model/build-mark/repo-connectors.sysml new file mode 100644 index 0000000..8e66500 --- /dev/null +++ b/docs/sysml2/model/build-mark/repo-connectors.sysml @@ -0,0 +1,20 @@ +package BuildMark { + part def RepoConnectorsSubsystem { + doc /* Repository connector abstraction, routing, and provider-specific integrations. */ + + comment testRef /* Test: test/DemaConsulting.BuildMark.Tests/RepoConnectors/RepoConnectorsTests.cs */ + comment designRef /* Design: docs/design/build-mark/repo-connectors.md */ + comment verificationRef /* Verification: docs/verification/build-mark/repo-connectors.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/repo-connectors.yaml */ + + part iRepoConnector : IRepoConnector; + part repoConnectorBase : RepoConnectorBase; + part repoConnectorFactory : RepoConnectorFactory; + part itemRouter : ItemRouter; + part itemControlsInfo : ItemControlsInfo; + part itemControlsParser : ItemControlsParser; + part github : GitHubSubsystem; + part azureDevOps : AzureDevOpsSubsystem; + part mock : MockSubsystem; + } +} diff --git a/docs/sysml2/model/build-mark/repo-connectors/azure-devops.sysml b/docs/sysml2/model/build-mark/repo-connectors/azure-devops.sysml new file mode 100644 index 0000000..62cf388 --- /dev/null +++ b/docs/sysml2/model/build-mark/repo-connectors/azure-devops.sysml @@ -0,0 +1,15 @@ +package BuildMark { + part def AzureDevOpsSubsystem { + doc /* Azure DevOps repository connector, REST client, and work item mapping. */ + + comment testRef /* Test: test/DemaConsulting.BuildMark.Tests/RepoConnectors/AzureDevOps/AzureDevOpsTests.cs */ + comment designRef /* Design: docs/design/build-mark/repo-connectors/azure-devops.md */ + comment verificationRef /* Verification: docs/verification/build-mark/repo-connectors/azure-devops.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/repo-connectors/azure-devops.yaml */ + + part azureDevOpsRepoConnector : AzureDevOpsRepoConnector; + part azureDevOpsRestClient : AzureDevOpsRestClient; + part azureDevOpsApiTypes : AzureDevOpsApiTypes; + part workItemMapper : WorkItemMapper; + } +} diff --git a/docs/sysml2/model/build-mark/repo-connectors/azure-devops/azure-devops-api-types.sysml b/docs/sysml2/model/build-mark/repo-connectors/azure-devops/azure-devops-api-types.sysml new file mode 100644 index 0000000..54d62a0 --- /dev/null +++ b/docs/sysml2/model/build-mark/repo-connectors/azure-devops/azure-devops-api-types.sysml @@ -0,0 +1,11 @@ +package BuildMark { + part def AzureDevOpsApiTypes { + doc /* REST API type definitions. */ + + comment sourceRef /* Source: src/DemaConsulting.BuildMark/RepoConnectors/AzureDevOps/AzureDevOpsApiTypes.cs */ + comment designRef /* Design: docs/design/build-mark/repo-connectors/azure-devops/azure-devops-api-types.md */ + comment verificationRef /* Verification: docs/verification/build-mark/repo-connectors/azure-devops/azure-devops-api-types.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/repo-connectors/azure-devops.yaml (documented exception: no dedicated per-unit reqstream file exists) */ + // Note: no testRef - no dedicated test file exists (exercised only indirectly). + } +} diff --git a/docs/sysml2/model/build-mark/repo-connectors/azure-devops/azure-devops-repo-connector.sysml b/docs/sysml2/model/build-mark/repo-connectors/azure-devops/azure-devops-repo-connector.sysml new file mode 100644 index 0000000..e1a8f0b --- /dev/null +++ b/docs/sysml2/model/build-mark/repo-connectors/azure-devops/azure-devops-repo-connector.sysml @@ -0,0 +1,11 @@ +package BuildMark { + part def AzureDevOpsRepoConnector { + doc /* Azure DevOps API integration. */ + + comment sourceRef /* Source: src/DemaConsulting.BuildMark/RepoConnectors/AzureDevOps/AzureDevOpsRepoConnector.cs */ + comment testRef /* Test: test/DemaConsulting.BuildMark.Tests/RepoConnectors/AzureDevOps/AzureDevOpsRepoConnectorTests.cs */ + comment designRef /* Design: docs/design/build-mark/repo-connectors/azure-devops/azure-devops-repo-connector.md */ + comment verificationRef /* Verification: docs/verification/build-mark/repo-connectors/azure-devops/azure-devops-repo-connector.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/repo-connectors/azure-devops/azure-devops-repo-connector.yaml */ + } +} diff --git a/docs/sysml2/model/build-mark/repo-connectors/azure-devops/azure-devops-rest-client.sysml b/docs/sysml2/model/build-mark/repo-connectors/azure-devops/azure-devops-rest-client.sysml new file mode 100644 index 0000000..279b310 --- /dev/null +++ b/docs/sysml2/model/build-mark/repo-connectors/azure-devops/azure-devops-rest-client.sysml @@ -0,0 +1,11 @@ +package BuildMark { + part def AzureDevOpsRestClient { + doc /* REST API client. */ + + comment sourceRef /* Source: src/DemaConsulting.BuildMark/RepoConnectors/AzureDevOps/AzureDevOpsRestClient.cs */ + comment testRef /* Test: test/DemaConsulting.BuildMark.Tests/RepoConnectors/AzureDevOps/AzureDevOpsRestClientTests.cs */ + comment designRef /* Design: docs/design/build-mark/repo-connectors/azure-devops/azure-devops-rest-client.md */ + comment verificationRef /* Verification: docs/verification/build-mark/repo-connectors/azure-devops/azure-devops-rest-client.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/repo-connectors/azure-devops/azure-devops-rest-client.yaml */ + } +} diff --git a/docs/sysml2/model/build-mark/repo-connectors/azure-devops/work-item-mapper.sysml b/docs/sysml2/model/build-mark/repo-connectors/azure-devops/work-item-mapper.sysml new file mode 100644 index 0000000..9187a1c --- /dev/null +++ b/docs/sysml2/model/build-mark/repo-connectors/azure-devops/work-item-mapper.sysml @@ -0,0 +1,11 @@ +package BuildMark { + part def WorkItemMapper { + doc /* Work item to ItemInfo mapper. */ + + comment sourceRef /* Source: src/DemaConsulting.BuildMark/RepoConnectors/AzureDevOps/WorkItemMapper.cs */ + comment testRef /* Test: test/DemaConsulting.BuildMark.Tests/RepoConnectors/AzureDevOps/WorkItemMapperTests.cs */ + comment designRef /* Design: docs/design/build-mark/repo-connectors/azure-devops/work-item-mapper.md */ + comment verificationRef /* Verification: docs/verification/build-mark/repo-connectors/azure-devops/work-item-mapper.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/repo-connectors/azure-devops/work-item-mapper.yaml */ + } +} diff --git a/docs/sysml2/model/build-mark/repo-connectors/github.sysml b/docs/sysml2/model/build-mark/repo-connectors/github.sysml new file mode 100644 index 0000000..13c350f --- /dev/null +++ b/docs/sysml2/model/build-mark/repo-connectors/github.sysml @@ -0,0 +1,14 @@ +package BuildMark { + part def GitHubSubsystem { + doc /* GitHub repository connector, GraphQL client, and GraphQL type definitions. */ + + comment testRef /* Test: test/DemaConsulting.BuildMark.Tests/RepoConnectors/GitHub/GitHubTests.cs */ + comment designRef /* Design: docs/design/build-mark/repo-connectors/github.md */ + comment verificationRef /* Verification: docs/verification/build-mark/repo-connectors/github.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/repo-connectors/github.yaml */ + + part gitHubRepoConnector : GitHubRepoConnector; + part gitHubGraphQLClient : GitHubGraphQLClient; + part gitHubGraphQLTypes : GitHubGraphQLTypes; + } +} diff --git a/docs/sysml2/model/build-mark/repo-connectors/github/github-graphql-client.sysml b/docs/sysml2/model/build-mark/repo-connectors/github/github-graphql-client.sysml new file mode 100644 index 0000000..fec1fa9 --- /dev/null +++ b/docs/sysml2/model/build-mark/repo-connectors/github/github-graphql-client.sysml @@ -0,0 +1,13 @@ +package BuildMark { + part def GitHubGraphQLClient { + doc /* GraphQL API client. */ + + comment sourceRef /* Source: src/DemaConsulting.BuildMark/RepoConnectors/GitHub/GitHubGraphQLClient.cs */ + comment testRef /* Test: test/DemaConsulting.BuildMark.Tests/RepoConnectors/GitHub/GitHubGraphQLClient*Tests.cs (split across 6 per-method test files: FindIssueIds, GetAllIssues, GetAllTags, GetCommits, GetPullRequests, GetReleases) */ + comment designRef /* Design: docs/design/build-mark/repo-connectors/github/github-graphql-client.md */ + comment verificationRef /* Verification: docs/verification/build-mark/repo-connectors/github/git-hub-graph-ql-client.md */ + // Note: verificationRef uses a different kebab-case split than designRef for the + // same PascalCase name (pre-existing casing inconsistency, used verbatim, not fixed). + comment reqRef /* Requirements: docs/reqstream/build-mark/repo-connectors/github/github-graphql-client.yaml */ + } +} diff --git a/docs/sysml2/model/build-mark/repo-connectors/github/github-graphql-types.sysml b/docs/sysml2/model/build-mark/repo-connectors/github/github-graphql-types.sysml new file mode 100644 index 0000000..20c37a1 --- /dev/null +++ b/docs/sysml2/model/build-mark/repo-connectors/github/github-graphql-types.sysml @@ -0,0 +1,13 @@ +package BuildMark { + part def GitHubGraphQLTypes { + doc /* GraphQL type definitions. */ + + comment sourceRef /* Source: src/DemaConsulting.BuildMark/RepoConnectors/GitHub/GitHubGraphQLTypes.cs */ + comment designRef /* Design: docs/design/build-mark/repo-connectors/github/github-graphql-types.md */ + comment verificationRef /* Verification: docs/verification/build-mark/repo-connectors/github/git-hub-graph-ql-types.md */ + // Note: verificationRef uses a different kebab-case split than designRef for the + // same PascalCase name (pre-existing casing inconsistency, used verbatim, not fixed). + comment reqRef /* Requirements: docs/reqstream/build-mark/repo-connectors/github.yaml (documented exception: no dedicated per-unit reqstream file exists) */ + // Note: no testRef - no dedicated test file exists (exercised only indirectly). + } +} diff --git a/docs/sysml2/model/build-mark/repo-connectors/github/github-repo-connector.sysml b/docs/sysml2/model/build-mark/repo-connectors/github/github-repo-connector.sysml new file mode 100644 index 0000000..3339437 --- /dev/null +++ b/docs/sysml2/model/build-mark/repo-connectors/github/github-repo-connector.sysml @@ -0,0 +1,13 @@ +package BuildMark { + part def GitHubRepoConnector { + doc /* GitHub API integration. */ + + comment sourceRef /* Source: src/DemaConsulting.BuildMark/RepoConnectors/GitHub/GitHubRepoConnector.cs */ + comment testRef /* Test: test/DemaConsulting.BuildMark.Tests/RepoConnectors/GitHub/GitHubRepoConnectorTests.cs */ + comment designRef /* Design: docs/design/build-mark/repo-connectors/github/github-repo-connector.md */ + comment verificationRef /* Verification: docs/verification/build-mark/repo-connectors/github/git-hub-repo-connector.md */ + // Note: verificationRef uses a different kebab-case split than designRef for the + // same PascalCase name (pre-existing casing inconsistency, used verbatim, not fixed). + comment reqRef /* Requirements: docs/reqstream/build-mark/repo-connectors/github/github-repo-connector.yaml */ + } +} diff --git a/docs/sysml2/model/build-mark/repo-connectors/i-repo-connector.sysml b/docs/sysml2/model/build-mark/repo-connectors/i-repo-connector.sysml new file mode 100644 index 0000000..66c32ca --- /dev/null +++ b/docs/sysml2/model/build-mark/repo-connectors/i-repo-connector.sysml @@ -0,0 +1,11 @@ +package BuildMark { + part def IRepoConnector { + doc /* Repository connector interface (the connector contract). */ + + comment sourceRef /* Source: src/DemaConsulting.BuildMark/RepoConnectors/IRepoConnector.cs */ + comment designRef /* Design: docs/design/build-mark/repo-connectors.md (documented as the connector contract, no dedicated design file) */ + comment verificationRef /* Verification: docs/verification/build-mark/repo-connectors/i-repo-connector.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/repo-connectors.yaml (documented exception: no dedicated per-unit reqstream file exists) */ + // Note: no testRef - no dedicated test file exists (exercised only indirectly). + } +} diff --git a/docs/sysml2/model/build-mark/repo-connectors/item-controls-info.sysml b/docs/sysml2/model/build-mark/repo-connectors/item-controls-info.sysml new file mode 100644 index 0000000..8e39e1c --- /dev/null +++ b/docs/sysml2/model/build-mark/repo-connectors/item-controls-info.sysml @@ -0,0 +1,11 @@ +package BuildMark { + part def ItemControlsInfo { + doc /* Item controls data model. */ + + comment sourceRef /* Source: src/DemaConsulting.BuildMark/RepoConnectors/ItemControlsInfo.cs */ + comment designRef /* Design: docs/design/build-mark/repo-connectors/item-controls-info.md */ + comment verificationRef /* Verification: docs/verification/build-mark/repo-connectors/item-controls-info.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/repo-connectors.yaml (documented exception: no dedicated per-unit reqstream file exists) */ + // Note: no testRef - no dedicated test file exists (exercised only indirectly). + } +} diff --git a/docs/sysml2/model/build-mark/repo-connectors/item-controls-parser.sysml b/docs/sysml2/model/build-mark/repo-connectors/item-controls-parser.sysml new file mode 100644 index 0000000..51dc3bf --- /dev/null +++ b/docs/sysml2/model/build-mark/repo-connectors/item-controls-parser.sysml @@ -0,0 +1,11 @@ +package BuildMark { + part def ItemControlsParser { + doc /* BuildMark control-block parser. */ + + comment sourceRef /* Source: src/DemaConsulting.BuildMark/RepoConnectors/ItemControlsParser.cs */ + comment testRef /* Test: test/DemaConsulting.BuildMark.Tests/ItemControls/ItemControlsParserTests.cs */ + comment designRef /* Design: docs/design/build-mark/repo-connectors/item-controls-parser.md */ + comment verificationRef /* Verification: docs/verification/build-mark/repo-connectors/item-controls-parser.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/repo-connectors/item-controls-parser.yaml */ + } +} diff --git a/docs/sysml2/model/build-mark/repo-connectors/item-router.sysml b/docs/sysml2/model/build-mark/repo-connectors/item-router.sysml new file mode 100644 index 0000000..d954dba --- /dev/null +++ b/docs/sysml2/model/build-mark/repo-connectors/item-router.sysml @@ -0,0 +1,11 @@ +package BuildMark { + part def ItemRouter { + doc /* Shared item routing logic. */ + + comment sourceRef /* Source: src/DemaConsulting.BuildMark/RepoConnectors/ItemRouter.cs */ + comment testRef /* Test: test/DemaConsulting.BuildMark.Tests/RepoConnectors/ItemRouterTests.cs */ + comment designRef /* Design: docs/design/build-mark/repo-connectors/item-router.md */ + comment verificationRef /* Verification: docs/verification/build-mark/repo-connectors/item-router.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/repo-connectors/item-router.yaml */ + } +} diff --git a/docs/sysml2/model/build-mark/repo-connectors/mock.sysml b/docs/sysml2/model/build-mark/repo-connectors/mock.sysml new file mode 100644 index 0000000..7eed763 --- /dev/null +++ b/docs/sysml2/model/build-mark/repo-connectors/mock.sysml @@ -0,0 +1,12 @@ +package BuildMark { + part def MockSubsystem { + doc /* Mock repository connector used for self-test. */ + + comment testRef /* Test: test/DemaConsulting.BuildMark.Tests/RepoConnectors/Mock/MockTests.cs */ + comment designRef /* Design: docs/design/build-mark/repo-connectors/mock.md */ + comment verificationRef /* Verification: docs/verification/build-mark/repo-connectors/mock.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/repo-connectors/mock.yaml */ + + part mockRepoConnector : MockRepoConnector; + } +} diff --git a/docs/sysml2/model/build-mark/repo-connectors/mock/mock-repo-connector.sysml b/docs/sysml2/model/build-mark/repo-connectors/mock/mock-repo-connector.sysml new file mode 100644 index 0000000..cff8c97 --- /dev/null +++ b/docs/sysml2/model/build-mark/repo-connectors/mock/mock-repo-connector.sysml @@ -0,0 +1,11 @@ +package BuildMark { + part def MockRepoConnector { + doc /* Mock repository connector for self-test. */ + + comment sourceRef /* Source: src/DemaConsulting.BuildMark/RepoConnectors/Mock/MockRepoConnector.cs */ + comment testRef /* Test: test/DemaConsulting.BuildMark.Tests/RepoConnectors/Mock/MockRepoConnectorTests.cs */ + comment designRef /* Design: docs/design/build-mark/repo-connectors/mock/mock-repo-connector.md */ + comment verificationRef /* Verification: docs/verification/build-mark/repo-connectors/mock/mock-repo-connector.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/repo-connectors/mock/mock-repo-connector.yaml */ + } +} diff --git a/docs/sysml2/model/build-mark/repo-connectors/repo-connector-base.sysml b/docs/sysml2/model/build-mark/repo-connectors/repo-connector-base.sysml new file mode 100644 index 0000000..06849cd --- /dev/null +++ b/docs/sysml2/model/build-mark/repo-connectors/repo-connector-base.sysml @@ -0,0 +1,11 @@ +package BuildMark { + part def RepoConnectorBase { + doc /* Repository connector base class. */ + + comment sourceRef /* Source: src/DemaConsulting.BuildMark/RepoConnectors/RepoConnectorBase.cs */ + comment testRef /* Test: test/DemaConsulting.BuildMark.Tests/RepoConnectors/RepoConnectorBaseTests.cs */ + comment designRef /* Design: docs/design/build-mark/repo-connectors/repo-connector-base.md */ + comment verificationRef /* Verification: docs/verification/build-mark/repo-connectors/repo-connector-base.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/repo-connectors/repo-connector-base.yaml */ + } +} diff --git a/docs/sysml2/model/build-mark/repo-connectors/repo-connector-factory.sysml b/docs/sysml2/model/build-mark/repo-connectors/repo-connector-factory.sysml new file mode 100644 index 0000000..389852c --- /dev/null +++ b/docs/sysml2/model/build-mark/repo-connectors/repo-connector-factory.sysml @@ -0,0 +1,11 @@ +package BuildMark { + part def RepoConnectorFactory { + doc /* Repository connector factory. */ + + comment sourceRef /* Source: src/DemaConsulting.BuildMark/RepoConnectors/RepoConnectorFactory.cs */ + comment testRef /* Test: test/DemaConsulting.BuildMark.Tests/RepoConnectors/RepoConnectorFactoryTests.cs */ + comment designRef /* Design: docs/design/build-mark/repo-connectors/repo-connector-factory.md */ + comment verificationRef /* Verification: docs/verification/build-mark/repo-connectors/repo-connector-factory.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/repo-connectors/repo-connector-factory.yaml */ + } +} diff --git a/docs/sysml2/model/build-mark/self-test.sysml b/docs/sysml2/model/build-mark/self-test.sysml new file mode 100644 index 0000000..ed45b6f --- /dev/null +++ b/docs/sysml2/model/build-mark/self-test.sysml @@ -0,0 +1,12 @@ +package BuildMark { + part def SelfTestSubsystem { + doc /* Self-validation test runner using the Mock repo connector. */ + + comment testRef /* Test: test/DemaConsulting.BuildMark.Tests/SelfTest/SelfTestTests.cs */ + comment designRef /* Design: docs/design/build-mark/self-test.md */ + comment verificationRef /* Verification: docs/verification/build-mark/self-test.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/self-test.yaml */ + + part validation : Validation; + } +} diff --git a/docs/sysml2/model/build-mark/self-test/validation.sysml b/docs/sysml2/model/build-mark/self-test/validation.sysml new file mode 100644 index 0000000..4b736e5 --- /dev/null +++ b/docs/sysml2/model/build-mark/self-test/validation.sysml @@ -0,0 +1,11 @@ +package BuildMark { + part def Validation { + doc /* Self-validation test runner. */ + + comment sourceRef /* Source: src/DemaConsulting.BuildMark/SelfTest/Validation.cs */ + comment testRef /* Test: test/DemaConsulting.BuildMark.Tests/SelfTest/ValidationTests.cs */ + comment designRef /* Design: docs/design/build-mark/self-test/validation.md */ + comment verificationRef /* Verification: docs/verification/build-mark/self-test/validation.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/self-test/validation.yaml */ + } +} diff --git a/docs/sysml2/model/build-mark/utilities.sysml b/docs/sysml2/model/build-mark/utilities.sysml new file mode 100644 index 0000000..df46a7f --- /dev/null +++ b/docs/sysml2/model/build-mark/utilities.sysml @@ -0,0 +1,14 @@ +package BuildMark { + part def UtilitiesSubsystem { + doc /* Shared utility helpers: path handling, process execution, and temp directories. */ + + comment testRef /* Test: test/DemaConsulting.BuildMark.Tests/Utilities/UtilitiesTests.cs */ + comment designRef /* Design: docs/design/build-mark/utilities.md */ + comment verificationRef /* Verification: docs/verification/build-mark/utilities.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/utilities.yaml */ + + part pathHelpers : PathHelpers; + part processRunner : ProcessRunner; + part temporaryDirectory : TemporaryDirectory; + } +} diff --git a/docs/sysml2/model/build-mark/utilities/path-helpers.sysml b/docs/sysml2/model/build-mark/utilities/path-helpers.sysml new file mode 100644 index 0000000..9f5f43e --- /dev/null +++ b/docs/sysml2/model/build-mark/utilities/path-helpers.sysml @@ -0,0 +1,11 @@ +package BuildMark { + part def PathHelpers { + doc /* Safe path combination utilities. */ + + comment sourceRef /* Source: src/DemaConsulting.BuildMark/Utilities/PathHelpers.cs */ + comment testRef /* Test: test/DemaConsulting.BuildMark.Tests/Utilities/PathHelpersTests.cs */ + comment designRef /* Design: docs/design/build-mark/utilities/path-helpers.md */ + comment verificationRef /* Verification: docs/verification/build-mark/utilities/path-helpers.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/utilities/path-helpers.yaml */ + } +} diff --git a/docs/sysml2/model/build-mark/utilities/process-runner.sysml b/docs/sysml2/model/build-mark/utilities/process-runner.sysml new file mode 100644 index 0000000..6fc7feb --- /dev/null +++ b/docs/sysml2/model/build-mark/utilities/process-runner.sysml @@ -0,0 +1,11 @@ +package BuildMark { + part def ProcessRunner { + doc /* Process runner for Git commands. */ + + comment sourceRef /* Source: src/DemaConsulting.BuildMark/Utilities/ProcessRunner.cs */ + comment testRef /* Test: test/DemaConsulting.BuildMark.Tests/Utilities/ProcessRunnerTests.cs */ + comment designRef /* Design: docs/design/build-mark/utilities/process-runner.md */ + comment verificationRef /* Verification: docs/verification/build-mark/utilities/process-runner.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/utilities/process-runner.yaml */ + } +} diff --git a/docs/sysml2/model/build-mark/utilities/temporary-directory.sysml b/docs/sysml2/model/build-mark/utilities/temporary-directory.sysml new file mode 100644 index 0000000..87058bb --- /dev/null +++ b/docs/sysml2/model/build-mark/utilities/temporary-directory.sysml @@ -0,0 +1,11 @@ +package BuildMark { + part def TemporaryDirectory { + doc /* Temporary directory lifecycle management. */ + + comment sourceRef /* Source: src/DemaConsulting.BuildMark/Utilities/TemporaryDirectory.cs */ + comment testRef /* Test: test/DemaConsulting.BuildMark.Tests/Utilities/TemporaryDirectoryTests.cs */ + comment designRef /* Design: docs/design/build-mark/utilities/temporary-directory.md */ + comment verificationRef /* Verification: docs/verification/build-mark/utilities/temporary-directory.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/utilities/temporary-directory.yaml */ + } +} diff --git a/docs/sysml2/model/build-mark/version.sysml b/docs/sysml2/model/build-mark/version.sysml new file mode 100644 index 0000000..471f2f5 --- /dev/null +++ b/docs/sysml2/model/build-mark/version.sysml @@ -0,0 +1,17 @@ +package BuildMark { + part def VersionSubsystem { + doc /* Version comparison, semantic versioning, tag parsing, and version intervals. */ + + comment testRef /* Test: test/DemaConsulting.BuildMark.Tests/Version/VersionTests.cs */ + comment designRef /* Design: docs/design/build-mark/version.md */ + comment verificationRef /* Verification: docs/verification/build-mark/version.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/version.yaml */ + + part versionComparable : VersionComparable; + part versionSemantic : VersionSemantic; + part versionTag : VersionTag; + part versionInterval : VersionInterval; + part versionIntervalSet : VersionIntervalSet; + part versionCommitTag : VersionCommitTag; + } +} diff --git a/docs/sysml2/model/build-mark/version/version-commit-tag.sysml b/docs/sysml2/model/build-mark/version/version-commit-tag.sysml new file mode 100644 index 0000000..d538805 --- /dev/null +++ b/docs/sysml2/model/build-mark/version/version-commit-tag.sysml @@ -0,0 +1,11 @@ +package BuildMark { + part def VersionCommitTag { + doc /* Version commit tag representation. */ + + comment sourceRef /* Source: src/DemaConsulting.BuildMark/Version/VersionCommitTag.cs */ + comment designRef /* Design: docs/design/build-mark/version/version-commit-tag.md */ + comment verificationRef /* Verification: docs/verification/build-mark/version/version-commit-tag.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/version/version-commit-tag.yaml */ + // Note: no testRef - no dedicated test file exists (exercised only indirectly). + } +} diff --git a/docs/sysml2/model/build-mark/version/version-comparable.sysml b/docs/sysml2/model/build-mark/version/version-comparable.sysml new file mode 100644 index 0000000..d09f4f9 --- /dev/null +++ b/docs/sysml2/model/build-mark/version/version-comparable.sysml @@ -0,0 +1,11 @@ +package BuildMark { + part def VersionComparable { + doc /* Core integer-based version comparison. */ + + comment sourceRef /* Source: src/DemaConsulting.BuildMark/Version/VersionComparable.cs */ + comment testRef /* Test: test/DemaConsulting.BuildMark.Tests/Version/VersionComparableTests.cs */ + comment designRef /* Design: docs/design/build-mark/version/version-comparable.md */ + comment verificationRef /* Verification: docs/verification/build-mark/version/version-comparable.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/version/version-comparable.yaml */ + } +} diff --git a/docs/sysml2/model/build-mark/version/version-interval-set.sysml b/docs/sysml2/model/build-mark/version/version-interval-set.sysml new file mode 100644 index 0000000..24ca804 --- /dev/null +++ b/docs/sysml2/model/build-mark/version/version-interval-set.sysml @@ -0,0 +1,11 @@ +package BuildMark { + part def VersionIntervalSet { + doc /* Ordered set of version intervals. */ + + comment sourceRef /* Source: src/DemaConsulting.BuildMark/Version/VersionIntervalSet.cs */ + comment testRef /* Test: test/DemaConsulting.BuildMark.Tests/Version/VersionIntervalSetTests.cs */ + comment designRef /* Design: docs/design/build-mark/version/version-interval-set.md */ + comment verificationRef /* Verification: docs/verification/build-mark/version/version-interval-set.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/version/version-interval-set.yaml */ + } +} diff --git a/docs/sysml2/model/build-mark/version/version-interval.sysml b/docs/sysml2/model/build-mark/version/version-interval.sysml new file mode 100644 index 0000000..9d1335f --- /dev/null +++ b/docs/sysml2/model/build-mark/version/version-interval.sysml @@ -0,0 +1,11 @@ +package BuildMark { + part def VersionInterval { + doc /* Single version interval model and parser. */ + + comment sourceRef /* Source: src/DemaConsulting.BuildMark/Version/VersionInterval.cs */ + comment testRef /* Test: test/DemaConsulting.BuildMark.Tests/Version/VersionIntervalTests.cs */ + comment designRef /* Design: docs/design/build-mark/version/version-interval.md */ + comment verificationRef /* Verification: docs/verification/build-mark/version/version-interval.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/version/version-interval.yaml */ + } +} diff --git a/docs/sysml2/model/build-mark/version/version-semantic.sysml b/docs/sysml2/model/build-mark/version/version-semantic.sysml new file mode 100644 index 0000000..be63252 --- /dev/null +++ b/docs/sysml2/model/build-mark/version/version-semantic.sysml @@ -0,0 +1,11 @@ +package BuildMark { + part def VersionSemantic { + doc /* Semantic version with build metadata. */ + + comment sourceRef /* Source: src/DemaConsulting.BuildMark/Version/VersionSemantic.cs */ + comment testRef /* Test: test/DemaConsulting.BuildMark.Tests/Version/VersionSemanticTests.cs */ + comment designRef /* Design: docs/design/build-mark/version/version-semantic.md */ + comment verificationRef /* Verification: docs/verification/build-mark/version/version-semantic.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/version/version-semantic.yaml */ + } +} diff --git a/docs/sysml2/model/build-mark/version/version-tag.sysml b/docs/sysml2/model/build-mark/version/version-tag.sysml new file mode 100644 index 0000000..4752a87 --- /dev/null +++ b/docs/sysml2/model/build-mark/version/version-tag.sysml @@ -0,0 +1,11 @@ +package BuildMark { + part def VersionTag { + doc /* Repository tag parsing and normalization. */ + + comment sourceRef /* Source: src/DemaConsulting.BuildMark/Version/VersionTag.cs */ + comment testRef /* Test: test/DemaConsulting.BuildMark.Tests/Version/VersionTagTests.cs */ + comment designRef /* Design: docs/design/build-mark/version/version-tag.md */ + comment verificationRef /* Verification: docs/verification/build-mark/version/version-tag.md */ + comment reqRef /* Requirements: docs/reqstream/build-mark/version/version-tag.yaml */ + } +} diff --git a/docs/sysml2/model/ots.sysml b/docs/sysml2/model/ots.sysml new file mode 100644 index 0000000..903a1b2 --- /dev/null +++ b/docs/sysml2/model/ots.sysml @@ -0,0 +1,11 @@ +package OtsDependencies { + doc /* OTS dependencies used by BuildMark. */ + + part def YamlDotNet { + doc /* OTS: YAML parsing library used to read/write .buildmark.yaml configuration. */ + + comment designRef /* Design: docs/design/ots/yaml-dot-net.md */ + // Note: no verificationRef/reqRef - docs/verification/ots/ and docs/reqstream/ots/ + // do not contain a yaml-dot-net entry (discovered pre-existing gap, not fabricated). + } +} diff --git a/docs/sysml2/views/design-views.sysml b/docs/sysml2/views/design-views.sysml new file mode 100644 index 0000000..b9e278f --- /dev/null +++ b/docs/sysml2/views/design-views.sysml @@ -0,0 +1,66 @@ +// Views rendered into docs/design/generated/ for the Design document. +// Reopens the BuildMark 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 BuildMark { + view SoftwareStructureView { + expose BuildMark; + render asTreeDiagram; + } + + view BuildMarkView { + expose BuildMarkSystem; + render asTreeDiagram; + } + + view CliView { + expose CliSubsystem; + render asTreeDiagram; + } + + view BuildNotesView { + expose BuildNotesSubsystem; + render asTreeDiagram; + } + + view SelfTestView { + expose SelfTestSubsystem; + render asTreeDiagram; + } + + view UtilitiesView { + expose UtilitiesSubsystem; + render asTreeDiagram; + } + + view VersionView { + expose VersionSubsystem; + render asTreeDiagram; + } + + view ConfigurationView { + expose ConfigurationSubsystem; + render asTreeDiagram; + } + + view RepoConnectorsView { + expose RepoConnectorsSubsystem; + render asTreeDiagram; + } + + view GitHubView { + expose GitHubSubsystem; + render asTreeDiagram; + } + + view AzureDevOpsView { + expose AzureDevOpsSubsystem; + render asTreeDiagram; + } + + view MockView { + expose MockSubsystem; + render asTreeDiagram; + } +} From f981be3d3ca374f60db32b7ebbb1ed8970bd460d Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Tue, 7 Jul 2026 22:14:16 -0400 Subject: [PATCH 03/12] Wire SysML2Tools into build/lint pipeline - .config/dotnet-tools.json: add demaconsulting.sysml2tools.tool 0.1.0-beta.5 - lint.ps1: run 'dotnet sysml2tools lint' over docs/sysml2/**/*.sysml - .github/workflows/build.yaml: render docs/sysml2 views to SVG before Pandoc in the build-docs job, and capture sysml2tools' version - .versionmark.yaml: capture sysml2tools version from 'dotnet tool list' - .cspell.yaml: add 'sysml' word (additive only) Co-authored-by: GitHub Copilot <198982749+Copilot@users.noreply.github.com> --- .config/dotnet-tools.json | 6 ++++++ .cspell.yaml | 1 + .github/workflows/build.yaml | 11 ++++++++++- .versionmark.yaml | 5 +++++ lint.ps1 | 5 +++++ 5 files changed, 27 insertions(+), 1 deletion(-) diff --git a/.config/dotnet-tools.json b/.config/dotnet-tools.json index 708b445..490a518 100644 --- a/.config/dotnet-tools.json +++ b/.config/dotnet-tools.json @@ -73,6 +73,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 70bace4..07e0b62 100644 --- a/.cspell.yaml +++ b/.cspell.yaml @@ -32,6 +32,7 @@ words: - sarifmark - Sarif - sonarmark + - sysml - versionmark - Weasyprint - mylib diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml index 7720071..75472d9 100644 --- a/.github/workflows/build.yaml +++ b/.github/workflows/build.yaml @@ -484,7 +484,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 === @@ -743,6 +743,15 @@ jobs: shell: bash run: mkdir -p docs/design/generated + - 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/.versionmark.yaml b/.versionmark.yaml index 7073e08..80627af 100644 --- a/.versionmark.yaml +++ b/.versionmark.yaml @@ -75,3 +75,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/lint.ps1 b/lint.ps1 index e4d68ac..58a6fae 100644 --- a/lint.ps1 +++ b/lint.ps1 @@ -114,6 +114,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. From 985ab57750f2ba8e683b558d1ad70bbcf11432da Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Tue, 7 Jul 2026 22:14:22 -0400 Subject: [PATCH 04/12] Embed rendered SysML2 structure diagrams in design docs Adds ![... Structure](...View.svg) images directly under the top-level heading of every design doc, per sysml2-modeling.md's Diagram Embedding rule: SoftwareStructureView in introduction.md, BuildMarkView in build-mark.md and program.md, and each {SubsystemName}View in its subsystem doc and every unit doc nested under that subsystem (including the nested GitHub/AzureDevOps/Mock repo-connector sub-subsystems). Co-authored-by: GitHub Copilot <198982749+Copilot@users.noreply.github.com> --- docs/design/build-mark.md | 2 ++ docs/design/build-mark/build-notes.md | 2 ++ docs/design/build-mark/build-notes/build-information.md | 2 ++ docs/design/build-mark/build-notes/item-info.md | 2 ++ docs/design/build-mark/build-notes/web-link.md | 2 ++ docs/design/build-mark/cli.md | 2 ++ docs/design/build-mark/cli/context.md | 2 ++ docs/design/build-mark/configuration.md | 2 ++ .../build-mark/configuration/azure-devops-connector-config.md | 2 ++ .../design/build-mark/configuration/build-mark-config-reader.md | 2 ++ docs/design/build-mark/configuration/build-mark-config.md | 2 ++ docs/design/build-mark/configuration/configuration-issue.md | 2 ++ .../build-mark/configuration/configuration-load-result.md | 2 ++ docs/design/build-mark/configuration/connector-config.md | 2 ++ docs/design/build-mark/configuration/github-connector-config.md | 2 ++ docs/design/build-mark/configuration/report-config.md | 2 ++ docs/design/build-mark/configuration/rule-config.md | 2 ++ docs/design/build-mark/configuration/section-config.md | 2 ++ docs/design/build-mark/program.md | 2 ++ docs/design/build-mark/repo-connectors.md | 2 ++ docs/design/build-mark/repo-connectors/azure-devops.md | 2 ++ .../repo-connectors/azure-devops/azure-devops-api-types.md | 2 ++ .../repo-connectors/azure-devops/azure-devops-repo-connector.md | 2 ++ .../repo-connectors/azure-devops/azure-devops-rest-client.md | 2 ++ .../build-mark/repo-connectors/azure-devops/work-item-mapper.md | 2 ++ docs/design/build-mark/repo-connectors/github.md | 2 ++ .../build-mark/repo-connectors/github/github-graphql-client.md | 2 ++ .../build-mark/repo-connectors/github/github-graphql-types.md | 2 ++ .../build-mark/repo-connectors/github/github-repo-connector.md | 2 ++ docs/design/build-mark/repo-connectors/item-controls-info.md | 2 ++ docs/design/build-mark/repo-connectors/item-controls-parser.md | 2 ++ docs/design/build-mark/repo-connectors/item-router.md | 2 ++ docs/design/build-mark/repo-connectors/mock.md | 2 ++ .../build-mark/repo-connectors/mock/mock-repo-connector.md | 2 ++ docs/design/build-mark/repo-connectors/repo-connector-base.md | 2 ++ .../design/build-mark/repo-connectors/repo-connector-factory.md | 2 ++ docs/design/build-mark/self-test.md | 2 ++ docs/design/build-mark/self-test/validation.md | 2 ++ docs/design/build-mark/utilities.md | 2 ++ docs/design/build-mark/utilities/path-helpers.md | 2 ++ docs/design/build-mark/utilities/process-runner.md | 2 ++ docs/design/build-mark/utilities/temporary-directory.md | 2 ++ docs/design/build-mark/version.md | 2 ++ docs/design/build-mark/version/version-commit-tag.md | 2 ++ docs/design/build-mark/version/version-comparable.md | 2 ++ docs/design/build-mark/version/version-interval-set.md | 2 ++ docs/design/build-mark/version/version-interval.md | 2 ++ docs/design/build-mark/version/version-semantic.md | 2 ++ docs/design/build-mark/version/version-tag.md | 2 ++ docs/design/introduction.md | 2 ++ 50 files changed, 100 insertions(+) diff --git a/docs/design/build-mark.md b/docs/design/build-mark.md index 66876e2..fe8b591 100644 --- a/docs/design/build-mark.md +++ b/docs/design/build-mark.md @@ -1,5 +1,7 @@ # BuildMark +![BuildMark Structure](generated/BuildMarkView.svg) + ## Architecture BuildMark is composed of seven subsystems and a top-level entry-point unit. The diagram below diff --git a/docs/design/build-mark/build-notes.md b/docs/design/build-mark/build-notes.md index d1b8f8e..b39de98 100644 --- a/docs/design/build-mark/build-notes.md +++ b/docs/design/build-mark/build-notes.md @@ -1,5 +1,7 @@ ## BuildNotes Subsystem +![BuildNotes Structure](../generated/BuildNotesView.svg) + ### Overview The BuildNotes subsystem holds the shared output data model consumed by all repository diff --git a/docs/design/build-mark/build-notes/build-information.md b/docs/design/build-mark/build-notes/build-information.md index b7eeb86..347ea52 100644 --- a/docs/design/build-mark/build-notes/build-information.md +++ b/docs/design/build-mark/build-notes/build-information.md @@ -1,5 +1,7 @@ ### BuildInformation +![BuildNotes Structure](../../generated/BuildNotesView.svg) + #### Purpose `BuildInformation` is the top-level data record in the BuildNotes subsystem that holds all diff --git a/docs/design/build-mark/build-notes/item-info.md b/docs/design/build-mark/build-notes/item-info.md index ffb817a..96b6f2c 100644 --- a/docs/design/build-mark/build-notes/item-info.md +++ b/docs/design/build-mark/build-notes/item-info.md @@ -1,5 +1,7 @@ ### ItemInfo +![BuildNotes Structure](../../generated/BuildNotesView.svg) + #### Purpose `ItemInfo` is a record in the BuildNotes subsystem that represents a single issue or pull diff --git a/docs/design/build-mark/build-notes/web-link.md b/docs/design/build-mark/build-notes/web-link.md index 755f425..e245ea3 100644 --- a/docs/design/build-mark/build-notes/web-link.md +++ b/docs/design/build-mark/build-notes/web-link.md @@ -1,5 +1,7 @@ ### WebLink +![BuildNotes Structure](../../generated/BuildNotesView.svg) + #### Purpose `WebLink` is a record in the BuildNotes subsystem that represents a hyperlink. It is used by diff --git a/docs/design/build-mark/cli.md b/docs/design/build-mark/cli.md index 884902e..41dbdcb 100644 --- a/docs/design/build-mark/cli.md +++ b/docs/design/build-mark/cli.md @@ -1,5 +1,7 @@ ## Cli Subsystem +![Cli Structure](../generated/CliView.svg) + ### Overview The Cli subsystem provides the command-line interface layer for BuildMark. It parses arguments diff --git a/docs/design/build-mark/cli/context.md b/docs/design/build-mark/cli/context.md index f0d281f..c625fb3 100644 --- a/docs/design/build-mark/cli/context.md +++ b/docs/design/build-mark/cli/context.md @@ -1,5 +1,7 @@ ### Context +![Cli Structure](../../generated/CliView.svg) + #### Purpose `Context` is the sole unit in the Cli subsystem. It owns the lifecycle of command-line argument diff --git a/docs/design/build-mark/configuration.md b/docs/design/build-mark/configuration.md index 2c968e1..2a93bdd 100644 --- a/docs/design/build-mark/configuration.md +++ b/docs/design/build-mark/configuration.md @@ -1,5 +1,7 @@ ## Configuration +![Configuration Structure](../generated/ConfigurationView.svg) + ### Overview The Configuration subsystem is responsible for reading and parsing the optional `.buildmark.yaml` diff --git a/docs/design/build-mark/configuration/azure-devops-connector-config.md b/docs/design/build-mark/configuration/azure-devops-connector-config.md index 523ec0b..2a4c881 100644 --- a/docs/design/build-mark/configuration/azure-devops-connector-config.md +++ b/docs/design/build-mark/configuration/azure-devops-connector-config.md @@ -1,5 +1,7 @@ ### AzureDevOpsConnectorConfig +![Configuration Structure](../../generated/ConfigurationView.svg) + #### Purpose `AzureDevOpsConnectorConfig` is an immutable record that carries Azure DevOps-specific connector diff --git a/docs/design/build-mark/configuration/build-mark-config-reader.md b/docs/design/build-mark/configuration/build-mark-config-reader.md index 3b738fc..3edd46f 100644 --- a/docs/design/build-mark/configuration/build-mark-config-reader.md +++ b/docs/design/build-mark/configuration/build-mark-config-reader.md @@ -1,5 +1,7 @@ ### BuildMarkConfigReader +![Configuration Structure](../../generated/ConfigurationView.svg) + #### Purpose `BuildMarkConfigReader` is a static utility class responsible for reading and deserializing diff --git a/docs/design/build-mark/configuration/build-mark-config.md b/docs/design/build-mark/configuration/build-mark-config.md index bd9c7b0..390cab7 100644 --- a/docs/design/build-mark/configuration/build-mark-config.md +++ b/docs/design/build-mark/configuration/build-mark-config.md @@ -1,5 +1,7 @@ ### BuildMarkConfig +![Configuration Structure](../../generated/ConfigurationView.svg) + #### Purpose `BuildMarkConfig` is the top-level configuration data model for BuildMark. It holds all diff --git a/docs/design/build-mark/configuration/configuration-issue.md b/docs/design/build-mark/configuration/configuration-issue.md index 351fcc6..eef3e0e 100644 --- a/docs/design/build-mark/configuration/configuration-issue.md +++ b/docs/design/build-mark/configuration/configuration-issue.md @@ -1,5 +1,7 @@ ### ConfigurationIssue +![Configuration Structure](../../generated/ConfigurationView.svg) + #### Purpose `ConfigurationIssue` is an immutable positional record representing a single problem found diff --git a/docs/design/build-mark/configuration/configuration-load-result.md b/docs/design/build-mark/configuration/configuration-load-result.md index beeae4d..b324d24 100644 --- a/docs/design/build-mark/configuration/configuration-load-result.md +++ b/docs/design/build-mark/configuration/configuration-load-result.md @@ -1,5 +1,7 @@ ### ConfigurationLoadResult +![Configuration Structure](../../generated/ConfigurationView.svg) + #### Purpose `ConfigurationLoadResult` is an immutable positional record that carries the output of diff --git a/docs/design/build-mark/configuration/connector-config.md b/docs/design/build-mark/configuration/connector-config.md index 777fdc1..feeae9e 100644 --- a/docs/design/build-mark/configuration/connector-config.md +++ b/docs/design/build-mark/configuration/connector-config.md @@ -1,5 +1,7 @@ ### ConnectorConfig +![Configuration Structure](../../generated/ConfigurationView.svg) + #### Purpose `ConnectorConfig` is an immutable record that serves as the connector envelope read from the diff --git a/docs/design/build-mark/configuration/github-connector-config.md b/docs/design/build-mark/configuration/github-connector-config.md index 01d4630..f1eb24f 100644 --- a/docs/design/build-mark/configuration/github-connector-config.md +++ b/docs/design/build-mark/configuration/github-connector-config.md @@ -1,5 +1,7 @@ ### GitHubConnectorConfig +![Configuration Structure](../../generated/ConfigurationView.svg) + #### Purpose `GitHubConnectorConfig` is an immutable record that carries GitHub-specific connector settings diff --git a/docs/design/build-mark/configuration/report-config.md b/docs/design/build-mark/configuration/report-config.md index 0193f5d..8e20e64 100644 --- a/docs/design/build-mark/configuration/report-config.md +++ b/docs/design/build-mark/configuration/report-config.md @@ -1,5 +1,7 @@ ### ReportConfig +![Configuration Structure](../../generated/ConfigurationView.svg) + #### Purpose `ReportConfig` is an immutable record holding optional report output settings read from the diff --git a/docs/design/build-mark/configuration/rule-config.md b/docs/design/build-mark/configuration/rule-config.md index cb6e914..0de09b7 100644 --- a/docs/design/build-mark/configuration/rule-config.md +++ b/docs/design/build-mark/configuration/rule-config.md @@ -1,5 +1,7 @@ ### RuleConfig +![Configuration Structure](../../generated/ConfigurationView.svg) + #### Purpose `RuleConfig` is an immutable record representing a single item routing rule read from the diff --git a/docs/design/build-mark/configuration/section-config.md b/docs/design/build-mark/configuration/section-config.md index 2a3bf9d..0884056 100644 --- a/docs/design/build-mark/configuration/section-config.md +++ b/docs/design/build-mark/configuration/section-config.md @@ -1,5 +1,7 @@ ### SectionConfig +![Configuration Structure](../../generated/ConfigurationView.svg) + #### Purpose `SectionConfig` is an immutable record representing a single report section definition read diff --git a/docs/design/build-mark/program.md b/docs/design/build-mark/program.md index c0372f6..7853eb9 100644 --- a/docs/design/build-mark/program.md +++ b/docs/design/build-mark/program.md @@ -1,5 +1,7 @@ ## Program +![BuildMark Structure](../generated/BuildMarkView.svg) + ### Purpose `Program` is the top-level unit of BuildMark. It owns the application entry point, creates diff --git a/docs/design/build-mark/repo-connectors.md b/docs/design/build-mark/repo-connectors.md index 85d8303..5d0985b 100644 --- a/docs/design/build-mark/repo-connectors.md +++ b/docs/design/build-mark/repo-connectors.md @@ -1,5 +1,7 @@ ## RepoConnectors +![RepoConnectors Structure](../generated/RepoConnectorsView.svg) + ### Overview The RepoConnectors subsystem abstracts access to repository metadata for BuildMark. It defines the diff --git a/docs/design/build-mark/repo-connectors/azure-devops.md b/docs/design/build-mark/repo-connectors/azure-devops.md index 2718ece..ad31573 100644 --- a/docs/design/build-mark/repo-connectors/azure-devops.md +++ b/docs/design/build-mark/repo-connectors/azure-devops.md @@ -1,5 +1,7 @@ ### AzureDevOps +![AzureDevOps Structure](../../generated/AzureDevOpsView.svg) + #### Overview The AzureDevOps subsystem groups the units responsible for querying the Azure DevOps REST API. It diff --git a/docs/design/build-mark/repo-connectors/azure-devops/azure-devops-api-types.md b/docs/design/build-mark/repo-connectors/azure-devops/azure-devops-api-types.md index 7bc6104..26754e7 100644 --- a/docs/design/build-mark/repo-connectors/azure-devops/azure-devops-api-types.md +++ b/docs/design/build-mark/repo-connectors/azure-devops/azure-devops-api-types.md @@ -1,5 +1,7 @@ #### AzureDevOpsApiTypes +![AzureDevOps Structure](../../../generated/AzureDevOpsView.svg) + ##### Purpose `AzureDevOpsApiTypes` is the collection of internal C# record types used by the AzureDevOps diff --git a/docs/design/build-mark/repo-connectors/azure-devops/azure-devops-repo-connector.md b/docs/design/build-mark/repo-connectors/azure-devops/azure-devops-repo-connector.md index e4a66b6..c1b4fb8 100644 --- a/docs/design/build-mark/repo-connectors/azure-devops/azure-devops-repo-connector.md +++ b/docs/design/build-mark/repo-connectors/azure-devops/azure-devops-repo-connector.md @@ -1,5 +1,7 @@ #### AzureDevOpsRepoConnector +![AzureDevOps Structure](../../../generated/AzureDevOpsView.svg) + ##### Purpose `AzureDevOpsRepoConnector` is the production connector in the AzureDevOps subsystem. It implements diff --git a/docs/design/build-mark/repo-connectors/azure-devops/azure-devops-rest-client.md b/docs/design/build-mark/repo-connectors/azure-devops/azure-devops-rest-client.md index 934b795..8c1203c 100644 --- a/docs/design/build-mark/repo-connectors/azure-devops/azure-devops-rest-client.md +++ b/docs/design/build-mark/repo-connectors/azure-devops/azure-devops-rest-client.md @@ -1,5 +1,7 @@ #### AzureDevOpsRestClient +![AzureDevOps Structure](../../../generated/AzureDevOpsView.svg) + ##### Purpose `AzureDevOpsRestClient` is the unit responsible for issuing paginated HTTP requests to the Azure diff --git a/docs/design/build-mark/repo-connectors/azure-devops/work-item-mapper.md b/docs/design/build-mark/repo-connectors/azure-devops/work-item-mapper.md index 0d86471..4a401b8 100644 --- a/docs/design/build-mark/repo-connectors/azure-devops/work-item-mapper.md +++ b/docs/design/build-mark/repo-connectors/azure-devops/work-item-mapper.md @@ -1,5 +1,7 @@ #### WorkItemMapper +![AzureDevOps Structure](../../../generated/AzureDevOpsView.svg) + ##### Purpose `WorkItemMapper` maps `AzureDevOpsWorkItem` records from the Azure DevOps REST API into `ItemInfo` diff --git a/docs/design/build-mark/repo-connectors/github.md b/docs/design/build-mark/repo-connectors/github.md index b621a7e..a139f16 100644 --- a/docs/design/build-mark/repo-connectors/github.md +++ b/docs/design/build-mark/repo-connectors/github.md @@ -1,5 +1,7 @@ ### GitHub +![GitHub Structure](../../generated/GitHubView.svg) + #### Overview The GitHub subsystem groups the units responsible for querying the GitHub GraphQL API. It sits diff --git a/docs/design/build-mark/repo-connectors/github/github-graphql-client.md b/docs/design/build-mark/repo-connectors/github/github-graphql-client.md index 0632ebf..6f33dc8 100644 --- a/docs/design/build-mark/repo-connectors/github/github-graphql-client.md +++ b/docs/design/build-mark/repo-connectors/github/github-graphql-client.md @@ -1,5 +1,7 @@ #### GitHubGraphQLClient +![GitHub Structure](../../../generated/GitHubView.svg) + ##### Purpose `GitHubGraphQLClient` is the unit responsible for issuing paginated GraphQL requests to the GitHub diff --git a/docs/design/build-mark/repo-connectors/github/github-graphql-types.md b/docs/design/build-mark/repo-connectors/github/github-graphql-types.md index 7c29612..8c35315 100644 --- a/docs/design/build-mark/repo-connectors/github/github-graphql-types.md +++ b/docs/design/build-mark/repo-connectors/github/github-graphql-types.md @@ -1,5 +1,7 @@ #### GitHubGraphQLTypes +![GitHub Structure](../../../generated/GitHubView.svg) + ##### Purpose `GitHubGraphQLTypes` is the collection of internal C# record types used by the GitHub subsystem diff --git a/docs/design/build-mark/repo-connectors/github/github-repo-connector.md b/docs/design/build-mark/repo-connectors/github/github-repo-connector.md index 7b77ef4..633c745 100644 --- a/docs/design/build-mark/repo-connectors/github/github-repo-connector.md +++ b/docs/design/build-mark/repo-connectors/github/github-repo-connector.md @@ -1,5 +1,7 @@ #### GitHubRepoConnector +![GitHub Structure](../../../generated/GitHubView.svg) + ##### Purpose `GitHubRepoConnector` is the production connector in the GitHub subsystem. It implements diff --git a/docs/design/build-mark/repo-connectors/item-controls-info.md b/docs/design/build-mark/repo-connectors/item-controls-info.md index a7430da..731103d 100644 --- a/docs/design/build-mark/repo-connectors/item-controls-info.md +++ b/docs/design/build-mark/repo-connectors/item-controls-info.md @@ -1,5 +1,7 @@ ### ItemControlsInfo +![RepoConnectors Structure](../../generated/RepoConnectorsView.svg) + #### Purpose `ItemControlsInfo` is an immutable data record used by the RepoConnectors subsystem to carry the diff --git a/docs/design/build-mark/repo-connectors/item-controls-parser.md b/docs/design/build-mark/repo-connectors/item-controls-parser.md index 77e2905..4b2e2dd 100644 --- a/docs/design/build-mark/repo-connectors/item-controls-parser.md +++ b/docs/design/build-mark/repo-connectors/item-controls-parser.md @@ -1,5 +1,7 @@ ### ItemControlsParser +![RepoConnectors Structure](../../generated/RepoConnectorsView.svg) + #### Purpose `ItemControlsParser` is a static utility class that extracts a `buildmark` fenced code block from diff --git a/docs/design/build-mark/repo-connectors/item-router.md b/docs/design/build-mark/repo-connectors/item-router.md index c4f28c9..a64ce16 100644 --- a/docs/design/build-mark/repo-connectors/item-router.md +++ b/docs/design/build-mark/repo-connectors/item-router.md @@ -1,5 +1,7 @@ ### ItemRouter +![RepoConnectors Structure](../../generated/RepoConnectorsView.svg) + #### Purpose `ItemRouter` is a static utility class that routes a list of `ItemInfo` objects into report diff --git a/docs/design/build-mark/repo-connectors/mock.md b/docs/design/build-mark/repo-connectors/mock.md index 83da8c1..fc63760 100644 --- a/docs/design/build-mark/repo-connectors/mock.md +++ b/docs/design/build-mark/repo-connectors/mock.md @@ -1,5 +1,7 @@ ### Mock +![Mock Structure](../../generated/MockView.svg) + #### Overview The Mock subsystem groups the in-memory connector used by the built-in `--validate` self-test. It diff --git a/docs/design/build-mark/repo-connectors/mock/mock-repo-connector.md b/docs/design/build-mark/repo-connectors/mock/mock-repo-connector.md index d30e94e..068c212 100644 --- a/docs/design/build-mark/repo-connectors/mock/mock-repo-connector.md +++ b/docs/design/build-mark/repo-connectors/mock/mock-repo-connector.md @@ -1,5 +1,7 @@ #### MockRepoConnector +![Mock Structure](../../../generated/MockView.svg) + ##### Purpose `MockRepoConnector` is an in-memory implementation of `IRepoConnector` used for self-validation diff --git a/docs/design/build-mark/repo-connectors/repo-connector-base.md b/docs/design/build-mark/repo-connectors/repo-connector-base.md index 8094ca4..0249b77 100644 --- a/docs/design/build-mark/repo-connectors/repo-connector-base.md +++ b/docs/design/build-mark/repo-connectors/repo-connector-base.md @@ -1,5 +1,7 @@ ### RepoConnectorBase +![RepoConnectors Structure](../../generated/RepoConnectorsView.svg) + #### Purpose `RepoConnectorBase` is an abstract class that implements `IRepoConnector` and provides shared diff --git a/docs/design/build-mark/repo-connectors/repo-connector-factory.md b/docs/design/build-mark/repo-connectors/repo-connector-factory.md index f4d30aa..c935d2f 100644 --- a/docs/design/build-mark/repo-connectors/repo-connector-factory.md +++ b/docs/design/build-mark/repo-connectors/repo-connector-factory.md @@ -1,5 +1,7 @@ ### RepoConnectorFactory +![RepoConnectors Structure](../../generated/RepoConnectorsView.svg) + #### Purpose `RepoConnectorFactory` is a static factory class that creates the appropriate `IRepoConnector` diff --git a/docs/design/build-mark/self-test.md b/docs/design/build-mark/self-test.md index d98bfad..cbf318d 100644 --- a/docs/design/build-mark/self-test.md +++ b/docs/design/build-mark/self-test.md @@ -1,5 +1,7 @@ ## SelfTest Subsystem +![SelfTest Structure](../generated/SelfTestView.svg) + ### Overview The SelfTest subsystem provides a self-validation capability for BuildMark. When the user passes `--validate`, diff --git a/docs/design/build-mark/self-test/validation.md b/docs/design/build-mark/self-test/validation.md index 7e2e192..db01dec 100644 --- a/docs/design/build-mark/self-test/validation.md +++ b/docs/design/build-mark/self-test/validation.md @@ -1,5 +1,7 @@ ### Validation +![SelfTest Structure](../../generated/SelfTestView.svg) + #### Purpose `Validation` is the sole unit in the SelfTest subsystem. It runs a fixed set of self-tests that exercise diff --git a/docs/design/build-mark/utilities.md b/docs/design/build-mark/utilities.md index 944ec28..61ab12e 100644 --- a/docs/design/build-mark/utilities.md +++ b/docs/design/build-mark/utilities.md @@ -1,5 +1,7 @@ ## Utilities Subsystem +![Utilities Structure](../generated/UtilitiesView.svg) + ### Overview The Utilities subsystem provides the shared helper classes used across the BuildMark system. It diff --git a/docs/design/build-mark/utilities/path-helpers.md b/docs/design/build-mark/utilities/path-helpers.md index ea66510..85f1f9e 100644 --- a/docs/design/build-mark/utilities/path-helpers.md +++ b/docs/design/build-mark/utilities/path-helpers.md @@ -1,5 +1,7 @@ ### PathHelpers +![Utilities Structure](../../generated/UtilitiesView.svg) + #### Purpose `PathHelpers` is a static utility class that provides a safe path-combination method. It protects callers diff --git a/docs/design/build-mark/utilities/process-runner.md b/docs/design/build-mark/utilities/process-runner.md index 6b2edcd..6bce80f 100644 --- a/docs/design/build-mark/utilities/process-runner.md +++ b/docs/design/build-mark/utilities/process-runner.md @@ -1,5 +1,7 @@ ### ProcessRunner +![Utilities Structure](../../generated/UtilitiesView.svg) + #### Purpose `ProcessRunner` is a static helper class in the Utilities subsystem that executes external shell commands diff --git a/docs/design/build-mark/utilities/temporary-directory.md b/docs/design/build-mark/utilities/temporary-directory.md index 275aba3..c00a190 100644 --- a/docs/design/build-mark/utilities/temporary-directory.md +++ b/docs/design/build-mark/utilities/temporary-directory.md @@ -1,5 +1,7 @@ ### TemporaryDirectory +![Utilities Structure](../../generated/UtilitiesView.svg) + #### Purpose `TemporaryDirectory` is an `internal sealed` class implementing `IDisposable` that creates a diff --git a/docs/design/build-mark/version.md b/docs/design/build-mark/version.md index 02874e3..da17fbd 100644 --- a/docs/design/build-mark/version.md +++ b/docs/design/build-mark/version.md @@ -1,5 +1,7 @@ ## Version Subsystem +![Version Structure](../generated/VersionView.svg) + ### Overview The Version subsystem provides semantic version processing for BuildMark. It handles all diff --git a/docs/design/build-mark/version/version-commit-tag.md b/docs/design/build-mark/version/version-commit-tag.md index 3d5a29c..2f5895b 100644 --- a/docs/design/build-mark/version/version-commit-tag.md +++ b/docs/design/build-mark/version/version-commit-tag.md @@ -1,5 +1,7 @@ ### VersionCommitTag +![Version Structure](../../generated/VersionView.svg) + #### Purpose `VersionCommitTag` pairs a parsed `VersionTag` with the Git commit hash at which that tag diff --git a/docs/design/build-mark/version/version-comparable.md b/docs/design/build-mark/version/version-comparable.md index 221dfbb..c550406 100644 --- a/docs/design/build-mark/version/version-comparable.md +++ b/docs/design/build-mark/version/version-comparable.md @@ -1,5 +1,7 @@ ### VersionComparable +![Version Structure](../../generated/VersionView.svg) + #### Purpose `VersionComparable` represents the comparable portion of a semantic version — diff --git a/docs/design/build-mark/version/version-interval-set.md b/docs/design/build-mark/version/version-interval-set.md index 84dbcdf..386b738 100644 --- a/docs/design/build-mark/version/version-interval-set.md +++ b/docs/design/build-mark/version/version-interval-set.md @@ -1,5 +1,7 @@ ### VersionIntervalSet +![Version Structure](../../generated/VersionView.svg) + #### Purpose `VersionIntervalSet` is an ordered, immutable collection of one or more `VersionInterval` diff --git a/docs/design/build-mark/version/version-interval.md b/docs/design/build-mark/version/version-interval.md index 26b94e6..a67649a 100644 --- a/docs/design/build-mark/version/version-interval.md +++ b/docs/design/build-mark/version/version-interval.md @@ -1,5 +1,7 @@ ### VersionInterval +![Version Structure](../../generated/VersionView.svg) + #### Purpose `VersionInterval` represents a single mathematical version interval with optional inclusive diff --git a/docs/design/build-mark/version/version-semantic.md b/docs/design/build-mark/version/version-semantic.md index e7dfb9d..54de190 100644 --- a/docs/design/build-mark/version/version-semantic.md +++ b/docs/design/build-mark/version/version-semantic.md @@ -1,5 +1,7 @@ ### VersionSemantic +![Version Structure](../../generated/VersionView.svg) + #### Purpose `VersionSemantic` is a record that extends version comparison with optional build metadata diff --git a/docs/design/build-mark/version/version-tag.md b/docs/design/build-mark/version/version-tag.md index 72b0e82..d52e11b 100644 --- a/docs/design/build-mark/version/version-tag.md +++ b/docs/design/build-mark/version/version-tag.md @@ -1,5 +1,7 @@ ### VersionTag +![Version Structure](../../generated/VersionView.svg) + #### Purpose `VersionTag` parses a raw repository tag string and extracts the embedded semantic version. diff --git a/docs/design/introduction.md b/docs/design/introduction.md index aec409f..3a29bd0 100644 --- a/docs/design/introduction.md +++ b/docs/design/introduction.md @@ -1,5 +1,7 @@ # Introduction +![Software Structure](generated/SoftwareStructureView.svg) + This document provides the detailed design for BuildMark — a .NET command-line tool that generates markdown build notes from Git repository metadata, including GitHub and Azure DevOps repositories. It covers local software items (systems, subsystems, and units) and the OTS From d9aa198744fd2b1cbfb2370dd31adf21b6a2b53c Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Tue, 7 Jul 2026 22:32:29 -0400 Subject: [PATCH 05/12] Fix docs/design/introduction.md to conform to template Replace the hand-maintained ASCII Software Structure tree with the SysML2-model pointer paragraph and rendered diagram per sysml2-modeling.md, and condense the Folder Layout section to a folders-only bullet list per the template's directive. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/design/introduction.md | 146 ++++++++---------------------------- 1 file changed, 31 insertions(+), 115 deletions(-) diff --git a/docs/design/introduction.md b/docs/design/introduction.md index 3a29bd0..75ec296 100644 --- a/docs/design/introduction.md +++ b/docs/design/introduction.md @@ -36,124 +36,40 @@ The following topics are out of scope: ## Software Structure -The following tree shows how the BuildMark software items are organized across the -system, subsystem, and unit levels: - -```text -BuildMark (System) -├── Program (Unit) -├── Cli (Subsystem) -│ └── Context (Unit) -├── BuildNotes (Subsystem) -│ ├── BuildInformation (Unit) -│ ├── ItemInfo (Unit) -│ └── WebLink (Unit) -├── SelfTest (Subsystem) -│ └── Validation (Unit) -├── Utilities (Subsystem) -│ ├── PathHelpers (Unit) -│ ├── ProcessRunner (Unit) -│ └── TemporaryDirectory (Unit) -├── Version (Subsystem) -│ ├── VersionComparable (Unit) -│ ├── VersionSemantic (Unit) -│ ├── VersionTag (Unit) -│ ├── VersionInterval (Unit) -│ ├── VersionIntervalSet (Unit) -│ └── VersionCommitTag (Unit) -├── Configuration (Subsystem) -│ ├── BuildMarkConfig (Unit) -│ ├── BuildMarkConfigReader (Unit) -│ ├── ConfigurationLoadResult (Unit) -│ ├── ConfigurationIssue (Unit) -│ ├── ConnectorConfig (Unit) -│ ├── GitHubConnectorConfig (Unit) -│ ├── AzureDevOpsConnectorConfig (Unit) -│ ├── ReportConfig (Unit) -│ ├── SectionConfig (Unit) -│ ├── RuleConfig (Unit) -│ └── RuleMatchConfig (Unit) -└── RepoConnectors (Subsystem) - ├── IRepoConnector (Unit) - ├── RepoConnectorBase (Unit) - ├── RepoConnectorFactory (Unit) - ├── ItemRouter (Unit) - ├── ItemControlsInfo (Unit) - ├── ItemControlsParser (Unit) - ├── GitHub (Subsystem) - │ ├── GitHubRepoConnector (Unit) - │ ├── GitHubGraphQLClient (Unit) - │ └── GitHubGraphQLTypes (Unit) - ├── AzureDevOps (Subsystem) - │ ├── AzureDevOpsRepoConnector (Unit) - │ ├── AzureDevOpsRestClient (Unit) - │ ├── AzureDevOpsApiTypes (Unit) - │ └── WorkItemMapper (Unit) - └── Mock (Subsystem) - └── MockRepoConnector (Unit) -``` - -Each unit is described in detail in its own chapter within this document. +The software structure is modeled in SysML2 under `docs/sysml2/` and rendered to the +diagram below by SysML2Tools as part of the build pipeline. AI agents should query the +SysML2 model directly (see the `sysml2tools-query` skill) rather than parsing this +diagram or the prose below. + +![Software Structure](generated/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.BuildMark/ -├── Program.cs - entry point and execution orchestrator -├── BuildNotes/ -│ ├── BuildInformation.cs - build information data model -│ ├── ItemInfo.cs - item information data model -│ └── WebLink.cs - web link helper -├── Cli/ -│ └── Context.cs - command-line argument parser and I/O owner -├── SelfTest/ -│ └── Validation.cs - self-validation test runner -├── Utilities/ -│ ├── PathHelpers.cs - safe path combination utilities -│ ├── ProcessRunner.cs - process runner for Git commands -│ └── TemporaryDirectory.cs - temporary directory lifecycle management -├── Version/ -│ ├── VersionComparable.cs - core integer-based version comparison -│ ├── VersionSemantic.cs - semantic version with build metadata -│ ├── VersionTag.cs - repository tag parsing and normalization -│ ├── VersionInterval.cs - single version interval model and parser -│ ├── VersionIntervalSet.cs - ordered set of version intervals -│ └── VersionCommitTag.cs - version commit tag representation -├── Configuration/ -│ ├── BuildMarkConfig.cs - top-level configuration data model -│ ├── BuildMarkConfigReader.cs - reads and parses .buildmark.yaml using YamlDotNet -│ ├── ConfigurationLoadResult.cs - holds config and any load issues -│ ├── ConfigurationIssue.cs - single issue with location and severity -│ ├── ConnectorConfig.cs - connector envelope data model -│ ├── GitHubConnectorConfig.cs - GitHub connector settings data model -│ ├── AzureDevOpsConnectorConfig.cs - Azure DevOps connector settings data model -│ ├── ReportConfig.cs - report output settings data model -│ ├── SectionConfig.cs - report section definition data model -│ └── RuleConfig.cs - routing rule and rule-match condition data models -└── RepoConnectors/ - ├── IRepoConnector.cs - repository connector interface - ├── RepoConnectorBase.cs - repository connector base class - ├── RepoConnectorFactory.cs - repository connector factory - ├── ItemRouter.cs - shared item routing logic - ├── ItemControlsInfo.cs - item controls data model - ├── ItemControlsParser.cs - buildmark block parser - ├── GitHub/ - │ ├── GitHubRepoConnector.cs - GitHub API integration - │ ├── GitHubGraphQLClient.cs - GraphQL API client - │ └── GitHubGraphQLTypes.cs - GraphQL type definitions - ├── AzureDevOps/ - │ ├── AzureDevOpsRepoConnector.cs - Azure DevOps API integration - │ ├── AzureDevOpsRestClient.cs - REST API client - │ ├── AzureDevOpsApiTypes.cs - REST API type definitions - │ └── WorkItemMapper.cs - work item to ItemInfo mapper - └── Mock/ - └── MockRepoConnector.cs - mock repository connector for self-test -``` - -The test project mirrors the same layout under `test/DemaConsulting.BuildMark.Tests/`. +- **src/** - source files and projects + - **DemaConsulting.BuildMark/** - BuildMark system source + - **Cli/** - Cli subsystem + - **BuildNotes/** - BuildNotes subsystem + - **SelfTest/** - SelfTest subsystem + - **Utilities/** - Utilities subsystem + - **Version/** - Version subsystem + - **Configuration/** - Configuration subsystem + - **RepoConnectors/** - RepoConnectors subsystem + - **GitHub/** - GitHub subsystem + - **AzureDevOps/** - AzureDevOps subsystem + - **Mock/** - Mock subsystem +- **test/** - test projects + - **DemaConsulting.BuildMark.Tests/** - BuildMark test source + - **Cli/** - Cli subsystem tests + - **BuildNotes/** - BuildNotes subsystem tests + - **SelfTest/** - SelfTest subsystem tests + - **Utilities/** - Utilities subsystem tests + - **Version/** - Version subsystem tests + - **Configuration/** - Configuration subsystem tests + - **RepoConnectors/** - RepoConnectors subsystem tests + - **GitHub/** - GitHub subsystem tests + - **AzureDevOps/** - AzureDevOps subsystem tests + - **Mock/** - Mock subsystem tests + - **ItemControls/** - RepoConnectors item-controls parsing tests ## Companion Artifact Structure From d53fcd32cf0088aced0d6385f0149b01f647dccd Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Tue, 7 Jul 2026 22:39:12 -0400 Subject: [PATCH 06/12] Align docs/design/introduction.md fully with template - Remove duplicate SoftwareStructureView.svg embed under the top-level Introduction heading (image belongs only in the Software Structure section per the template). - Remove the test/ tree from Folder Layout: the template directive is explicit that this section documents 'your actual source folder layout' only. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/design/introduction.md | 15 --------------- 1 file changed, 15 deletions(-) diff --git a/docs/design/introduction.md b/docs/design/introduction.md index 75ec296..3eb7184 100644 --- a/docs/design/introduction.md +++ b/docs/design/introduction.md @@ -1,7 +1,5 @@ # Introduction -![Software Structure](generated/SoftwareStructureView.svg) - This document provides the detailed design for BuildMark — a .NET command-line tool that generates markdown build notes from Git repository metadata, including GitHub and Azure DevOps repositories. It covers local software items (systems, subsystems, and units) and the OTS @@ -57,19 +55,6 @@ diagram or the prose below. - **GitHub/** - GitHub subsystem - **AzureDevOps/** - AzureDevOps subsystem - **Mock/** - Mock subsystem -- **test/** - test projects - - **DemaConsulting.BuildMark.Tests/** - BuildMark test source - - **Cli/** - Cli subsystem tests - - **BuildNotes/** - BuildNotes subsystem tests - - **SelfTest/** - SelfTest subsystem tests - - **Utilities/** - Utilities subsystem tests - - **Version/** - Version subsystem tests - - **Configuration/** - Configuration subsystem tests - - **RepoConnectors/** - RepoConnectors subsystem tests - - **GitHub/** - GitHub subsystem tests - - **AzureDevOps/** - AzureDevOps subsystem tests - - **Mock/** - Mock subsystem tests - - **ItemControls/** - RepoConnectors item-controls parsing tests ## Companion Artifact Structure From eb218a3dfd5c14991bc56e3a850b035913708230 Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Tue, 7 Jul 2026 23:04:42 -0400 Subject: [PATCH 07/12] Fix broken SysML2 diagram embeds in compiled design document MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Pandoc does not rewrite image src paths when merging multiple markdown files (from different source directories) into a single output document — it passes each markdown image reference through literally. Since the compiled docs/design/generated/design.html always sits in the same directory as the rendered SVGs (docs/design/generated/), the only path that resolves correctly for every source file, regardless of its own folder depth, is a bare filename with no directory prefix. The relative paths added when the SysML2 model was introduced (generated/X.svg, ../generated/X.svg, ../../generated/X.svg, etc., computed per source file's folder depth) were wrong: they only coincidentally resolved for source files one level deep, and were broken everywhere else, including the top-level introduction.md and build-mark.md. As a result, no SysML2 diagrams rendered in the CI-built PDF. Verified locally: rebuilt design.html + PDF with WeasyPrint before and after this fix. Before: 51 embedded vector Form XObjects, 657KB PDF. After: 433 Form XObjects, 880KB PDF — confirming the diagrams are now genuinely embedded. pwsh ./lint.ps1 passes clean (0 errors). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/design/build-mark.md | 2 +- docs/design/build-mark/build-notes.md | 2 +- docs/design/build-mark/build-notes/build-information.md | 2 +- docs/design/build-mark/build-notes/item-info.md | 2 +- docs/design/build-mark/build-notes/web-link.md | 2 +- docs/design/build-mark/cli.md | 2 +- docs/design/build-mark/cli/context.md | 2 +- docs/design/build-mark/configuration.md | 2 +- .../build-mark/configuration/azure-devops-connector-config.md | 2 +- .../design/build-mark/configuration/build-mark-config-reader.md | 2 +- docs/design/build-mark/configuration/build-mark-config.md | 2 +- docs/design/build-mark/configuration/configuration-issue.md | 2 +- .../build-mark/configuration/configuration-load-result.md | 2 +- docs/design/build-mark/configuration/connector-config.md | 2 +- docs/design/build-mark/configuration/github-connector-config.md | 2 +- docs/design/build-mark/configuration/report-config.md | 2 +- docs/design/build-mark/configuration/rule-config.md | 2 +- docs/design/build-mark/configuration/section-config.md | 2 +- docs/design/build-mark/program.md | 2 +- docs/design/build-mark/repo-connectors.md | 2 +- docs/design/build-mark/repo-connectors/azure-devops.md | 2 +- .../repo-connectors/azure-devops/azure-devops-api-types.md | 2 +- .../repo-connectors/azure-devops/azure-devops-repo-connector.md | 2 +- .../repo-connectors/azure-devops/azure-devops-rest-client.md | 2 +- .../build-mark/repo-connectors/azure-devops/work-item-mapper.md | 2 +- docs/design/build-mark/repo-connectors/github.md | 2 +- .../build-mark/repo-connectors/github/github-graphql-client.md | 2 +- .../build-mark/repo-connectors/github/github-graphql-types.md | 2 +- .../build-mark/repo-connectors/github/github-repo-connector.md | 2 +- docs/design/build-mark/repo-connectors/item-controls-info.md | 2 +- docs/design/build-mark/repo-connectors/item-controls-parser.md | 2 +- docs/design/build-mark/repo-connectors/item-router.md | 2 +- docs/design/build-mark/repo-connectors/mock.md | 2 +- .../build-mark/repo-connectors/mock/mock-repo-connector.md | 2 +- docs/design/build-mark/repo-connectors/repo-connector-base.md | 2 +- .../design/build-mark/repo-connectors/repo-connector-factory.md | 2 +- docs/design/build-mark/self-test.md | 2 +- docs/design/build-mark/self-test/validation.md | 2 +- docs/design/build-mark/utilities.md | 2 +- docs/design/build-mark/utilities/path-helpers.md | 2 +- docs/design/build-mark/utilities/process-runner.md | 2 +- docs/design/build-mark/utilities/temporary-directory.md | 2 +- docs/design/build-mark/version.md | 2 +- docs/design/build-mark/version/version-commit-tag.md | 2 +- docs/design/build-mark/version/version-comparable.md | 2 +- docs/design/build-mark/version/version-interval-set.md | 2 +- docs/design/build-mark/version/version-interval.md | 2 +- docs/design/build-mark/version/version-semantic.md | 2 +- docs/design/build-mark/version/version-tag.md | 2 +- docs/design/introduction.md | 2 +- 50 files changed, 50 insertions(+), 50 deletions(-) diff --git a/docs/design/build-mark.md b/docs/design/build-mark.md index fe8b591..6acf5c1 100644 --- a/docs/design/build-mark.md +++ b/docs/design/build-mark.md @@ -1,6 +1,6 @@ # BuildMark -![BuildMark Structure](generated/BuildMarkView.svg) +![BuildMark Structure](BuildMarkView.svg) ## Architecture diff --git a/docs/design/build-mark/build-notes.md b/docs/design/build-mark/build-notes.md index b39de98..6d67cab 100644 --- a/docs/design/build-mark/build-notes.md +++ b/docs/design/build-mark/build-notes.md @@ -1,6 +1,6 @@ ## BuildNotes Subsystem -![BuildNotes Structure](../generated/BuildNotesView.svg) +![BuildNotes Structure](BuildNotesView.svg) ### Overview diff --git a/docs/design/build-mark/build-notes/build-information.md b/docs/design/build-mark/build-notes/build-information.md index 347ea52..61f5dff 100644 --- a/docs/design/build-mark/build-notes/build-information.md +++ b/docs/design/build-mark/build-notes/build-information.md @@ -1,6 +1,6 @@ ### BuildInformation -![BuildNotes Structure](../../generated/BuildNotesView.svg) +![BuildNotes Structure](BuildNotesView.svg) #### Purpose diff --git a/docs/design/build-mark/build-notes/item-info.md b/docs/design/build-mark/build-notes/item-info.md index 96b6f2c..290fbea 100644 --- a/docs/design/build-mark/build-notes/item-info.md +++ b/docs/design/build-mark/build-notes/item-info.md @@ -1,6 +1,6 @@ ### ItemInfo -![BuildNotes Structure](../../generated/BuildNotesView.svg) +![BuildNotes Structure](BuildNotesView.svg) #### Purpose diff --git a/docs/design/build-mark/build-notes/web-link.md b/docs/design/build-mark/build-notes/web-link.md index e245ea3..b5a684e 100644 --- a/docs/design/build-mark/build-notes/web-link.md +++ b/docs/design/build-mark/build-notes/web-link.md @@ -1,6 +1,6 @@ ### WebLink -![BuildNotes Structure](../../generated/BuildNotesView.svg) +![BuildNotes Structure](BuildNotesView.svg) #### Purpose diff --git a/docs/design/build-mark/cli.md b/docs/design/build-mark/cli.md index 41dbdcb..29df756 100644 --- a/docs/design/build-mark/cli.md +++ b/docs/design/build-mark/cli.md @@ -1,6 +1,6 @@ ## Cli Subsystem -![Cli Structure](../generated/CliView.svg) +![Cli Structure](CliView.svg) ### Overview diff --git a/docs/design/build-mark/cli/context.md b/docs/design/build-mark/cli/context.md index c625fb3..a440131 100644 --- a/docs/design/build-mark/cli/context.md +++ b/docs/design/build-mark/cli/context.md @@ -1,6 +1,6 @@ ### Context -![Cli Structure](../../generated/CliView.svg) +![Cli Structure](CliView.svg) #### Purpose diff --git a/docs/design/build-mark/configuration.md b/docs/design/build-mark/configuration.md index 2a93bdd..734cbee 100644 --- a/docs/design/build-mark/configuration.md +++ b/docs/design/build-mark/configuration.md @@ -1,6 +1,6 @@ ## Configuration -![Configuration Structure](../generated/ConfigurationView.svg) +![Configuration Structure](ConfigurationView.svg) ### Overview diff --git a/docs/design/build-mark/configuration/azure-devops-connector-config.md b/docs/design/build-mark/configuration/azure-devops-connector-config.md index 2a4c881..9185a31 100644 --- a/docs/design/build-mark/configuration/azure-devops-connector-config.md +++ b/docs/design/build-mark/configuration/azure-devops-connector-config.md @@ -1,6 +1,6 @@ ### AzureDevOpsConnectorConfig -![Configuration Structure](../../generated/ConfigurationView.svg) +![Configuration Structure](ConfigurationView.svg) #### Purpose diff --git a/docs/design/build-mark/configuration/build-mark-config-reader.md b/docs/design/build-mark/configuration/build-mark-config-reader.md index 3edd46f..dabad23 100644 --- a/docs/design/build-mark/configuration/build-mark-config-reader.md +++ b/docs/design/build-mark/configuration/build-mark-config-reader.md @@ -1,6 +1,6 @@ ### BuildMarkConfigReader -![Configuration Structure](../../generated/ConfigurationView.svg) +![Configuration Structure](ConfigurationView.svg) #### Purpose diff --git a/docs/design/build-mark/configuration/build-mark-config.md b/docs/design/build-mark/configuration/build-mark-config.md index 390cab7..e5ccf63 100644 --- a/docs/design/build-mark/configuration/build-mark-config.md +++ b/docs/design/build-mark/configuration/build-mark-config.md @@ -1,6 +1,6 @@ ### BuildMarkConfig -![Configuration Structure](../../generated/ConfigurationView.svg) +![Configuration Structure](ConfigurationView.svg) #### Purpose diff --git a/docs/design/build-mark/configuration/configuration-issue.md b/docs/design/build-mark/configuration/configuration-issue.md index eef3e0e..b4b837c 100644 --- a/docs/design/build-mark/configuration/configuration-issue.md +++ b/docs/design/build-mark/configuration/configuration-issue.md @@ -1,6 +1,6 @@ ### ConfigurationIssue -![Configuration Structure](../../generated/ConfigurationView.svg) +![Configuration Structure](ConfigurationView.svg) #### Purpose diff --git a/docs/design/build-mark/configuration/configuration-load-result.md b/docs/design/build-mark/configuration/configuration-load-result.md index b324d24..779acba 100644 --- a/docs/design/build-mark/configuration/configuration-load-result.md +++ b/docs/design/build-mark/configuration/configuration-load-result.md @@ -1,6 +1,6 @@ ### ConfigurationLoadResult -![Configuration Structure](../../generated/ConfigurationView.svg) +![Configuration Structure](ConfigurationView.svg) #### Purpose diff --git a/docs/design/build-mark/configuration/connector-config.md b/docs/design/build-mark/configuration/connector-config.md index feeae9e..dafd2a4 100644 --- a/docs/design/build-mark/configuration/connector-config.md +++ b/docs/design/build-mark/configuration/connector-config.md @@ -1,6 +1,6 @@ ### ConnectorConfig -![Configuration Structure](../../generated/ConfigurationView.svg) +![Configuration Structure](ConfigurationView.svg) #### Purpose diff --git a/docs/design/build-mark/configuration/github-connector-config.md b/docs/design/build-mark/configuration/github-connector-config.md index f1eb24f..658e610 100644 --- a/docs/design/build-mark/configuration/github-connector-config.md +++ b/docs/design/build-mark/configuration/github-connector-config.md @@ -1,6 +1,6 @@ ### GitHubConnectorConfig -![Configuration Structure](../../generated/ConfigurationView.svg) +![Configuration Structure](ConfigurationView.svg) #### Purpose diff --git a/docs/design/build-mark/configuration/report-config.md b/docs/design/build-mark/configuration/report-config.md index 8e20e64..0d60b2d 100644 --- a/docs/design/build-mark/configuration/report-config.md +++ b/docs/design/build-mark/configuration/report-config.md @@ -1,6 +1,6 @@ ### ReportConfig -![Configuration Structure](../../generated/ConfigurationView.svg) +![Configuration Structure](ConfigurationView.svg) #### Purpose diff --git a/docs/design/build-mark/configuration/rule-config.md b/docs/design/build-mark/configuration/rule-config.md index 0de09b7..c12402c 100644 --- a/docs/design/build-mark/configuration/rule-config.md +++ b/docs/design/build-mark/configuration/rule-config.md @@ -1,6 +1,6 @@ ### RuleConfig -![Configuration Structure](../../generated/ConfigurationView.svg) +![Configuration Structure](ConfigurationView.svg) #### Purpose diff --git a/docs/design/build-mark/configuration/section-config.md b/docs/design/build-mark/configuration/section-config.md index 0884056..5193ec7 100644 --- a/docs/design/build-mark/configuration/section-config.md +++ b/docs/design/build-mark/configuration/section-config.md @@ -1,6 +1,6 @@ ### SectionConfig -![Configuration Structure](../../generated/ConfigurationView.svg) +![Configuration Structure](ConfigurationView.svg) #### Purpose diff --git a/docs/design/build-mark/program.md b/docs/design/build-mark/program.md index 7853eb9..5125dbd 100644 --- a/docs/design/build-mark/program.md +++ b/docs/design/build-mark/program.md @@ -1,6 +1,6 @@ ## Program -![BuildMark Structure](../generated/BuildMarkView.svg) +![BuildMark Structure](BuildMarkView.svg) ### Purpose diff --git a/docs/design/build-mark/repo-connectors.md b/docs/design/build-mark/repo-connectors.md index 5d0985b..bb38066 100644 --- a/docs/design/build-mark/repo-connectors.md +++ b/docs/design/build-mark/repo-connectors.md @@ -1,6 +1,6 @@ ## RepoConnectors -![RepoConnectors Structure](../generated/RepoConnectorsView.svg) +![RepoConnectors Structure](RepoConnectorsView.svg) ### Overview diff --git a/docs/design/build-mark/repo-connectors/azure-devops.md b/docs/design/build-mark/repo-connectors/azure-devops.md index ad31573..15ca8fb 100644 --- a/docs/design/build-mark/repo-connectors/azure-devops.md +++ b/docs/design/build-mark/repo-connectors/azure-devops.md @@ -1,6 +1,6 @@ ### AzureDevOps -![AzureDevOps Structure](../../generated/AzureDevOpsView.svg) +![AzureDevOps Structure](AzureDevOpsView.svg) #### Overview diff --git a/docs/design/build-mark/repo-connectors/azure-devops/azure-devops-api-types.md b/docs/design/build-mark/repo-connectors/azure-devops/azure-devops-api-types.md index 26754e7..717f2a6 100644 --- a/docs/design/build-mark/repo-connectors/azure-devops/azure-devops-api-types.md +++ b/docs/design/build-mark/repo-connectors/azure-devops/azure-devops-api-types.md @@ -1,6 +1,6 @@ #### AzureDevOpsApiTypes -![AzureDevOps Structure](../../../generated/AzureDevOpsView.svg) +![AzureDevOps Structure](AzureDevOpsView.svg) ##### Purpose diff --git a/docs/design/build-mark/repo-connectors/azure-devops/azure-devops-repo-connector.md b/docs/design/build-mark/repo-connectors/azure-devops/azure-devops-repo-connector.md index c1b4fb8..922e883 100644 --- a/docs/design/build-mark/repo-connectors/azure-devops/azure-devops-repo-connector.md +++ b/docs/design/build-mark/repo-connectors/azure-devops/azure-devops-repo-connector.md @@ -1,6 +1,6 @@ #### AzureDevOpsRepoConnector -![AzureDevOps Structure](../../../generated/AzureDevOpsView.svg) +![AzureDevOps Structure](AzureDevOpsView.svg) ##### Purpose diff --git a/docs/design/build-mark/repo-connectors/azure-devops/azure-devops-rest-client.md b/docs/design/build-mark/repo-connectors/azure-devops/azure-devops-rest-client.md index 8c1203c..c8a3618 100644 --- a/docs/design/build-mark/repo-connectors/azure-devops/azure-devops-rest-client.md +++ b/docs/design/build-mark/repo-connectors/azure-devops/azure-devops-rest-client.md @@ -1,6 +1,6 @@ #### AzureDevOpsRestClient -![AzureDevOps Structure](../../../generated/AzureDevOpsView.svg) +![AzureDevOps Structure](AzureDevOpsView.svg) ##### Purpose diff --git a/docs/design/build-mark/repo-connectors/azure-devops/work-item-mapper.md b/docs/design/build-mark/repo-connectors/azure-devops/work-item-mapper.md index 4a401b8..e0aa048 100644 --- a/docs/design/build-mark/repo-connectors/azure-devops/work-item-mapper.md +++ b/docs/design/build-mark/repo-connectors/azure-devops/work-item-mapper.md @@ -1,6 +1,6 @@ #### WorkItemMapper -![AzureDevOps Structure](../../../generated/AzureDevOpsView.svg) +![AzureDevOps Structure](AzureDevOpsView.svg) ##### Purpose diff --git a/docs/design/build-mark/repo-connectors/github.md b/docs/design/build-mark/repo-connectors/github.md index a139f16..a0c812d 100644 --- a/docs/design/build-mark/repo-connectors/github.md +++ b/docs/design/build-mark/repo-connectors/github.md @@ -1,6 +1,6 @@ ### GitHub -![GitHub Structure](../../generated/GitHubView.svg) +![GitHub Structure](GitHubView.svg) #### Overview diff --git a/docs/design/build-mark/repo-connectors/github/github-graphql-client.md b/docs/design/build-mark/repo-connectors/github/github-graphql-client.md index 6f33dc8..9261b1b 100644 --- a/docs/design/build-mark/repo-connectors/github/github-graphql-client.md +++ b/docs/design/build-mark/repo-connectors/github/github-graphql-client.md @@ -1,6 +1,6 @@ #### GitHubGraphQLClient -![GitHub Structure](../../../generated/GitHubView.svg) +![GitHub Structure](GitHubView.svg) ##### Purpose diff --git a/docs/design/build-mark/repo-connectors/github/github-graphql-types.md b/docs/design/build-mark/repo-connectors/github/github-graphql-types.md index 8c35315..bf7cadb 100644 --- a/docs/design/build-mark/repo-connectors/github/github-graphql-types.md +++ b/docs/design/build-mark/repo-connectors/github/github-graphql-types.md @@ -1,6 +1,6 @@ #### GitHubGraphQLTypes -![GitHub Structure](../../../generated/GitHubView.svg) +![GitHub Structure](GitHubView.svg) ##### Purpose diff --git a/docs/design/build-mark/repo-connectors/github/github-repo-connector.md b/docs/design/build-mark/repo-connectors/github/github-repo-connector.md index 633c745..80d145e 100644 --- a/docs/design/build-mark/repo-connectors/github/github-repo-connector.md +++ b/docs/design/build-mark/repo-connectors/github/github-repo-connector.md @@ -1,6 +1,6 @@ #### GitHubRepoConnector -![GitHub Structure](../../../generated/GitHubView.svg) +![GitHub Structure](GitHubView.svg) ##### Purpose diff --git a/docs/design/build-mark/repo-connectors/item-controls-info.md b/docs/design/build-mark/repo-connectors/item-controls-info.md index 731103d..ff0d5b1 100644 --- a/docs/design/build-mark/repo-connectors/item-controls-info.md +++ b/docs/design/build-mark/repo-connectors/item-controls-info.md @@ -1,6 +1,6 @@ ### ItemControlsInfo -![RepoConnectors Structure](../../generated/RepoConnectorsView.svg) +![RepoConnectors Structure](RepoConnectorsView.svg) #### Purpose diff --git a/docs/design/build-mark/repo-connectors/item-controls-parser.md b/docs/design/build-mark/repo-connectors/item-controls-parser.md index 4b2e2dd..abf8880 100644 --- a/docs/design/build-mark/repo-connectors/item-controls-parser.md +++ b/docs/design/build-mark/repo-connectors/item-controls-parser.md @@ -1,6 +1,6 @@ ### ItemControlsParser -![RepoConnectors Structure](../../generated/RepoConnectorsView.svg) +![RepoConnectors Structure](RepoConnectorsView.svg) #### Purpose diff --git a/docs/design/build-mark/repo-connectors/item-router.md b/docs/design/build-mark/repo-connectors/item-router.md index a64ce16..c3d0dd6 100644 --- a/docs/design/build-mark/repo-connectors/item-router.md +++ b/docs/design/build-mark/repo-connectors/item-router.md @@ -1,6 +1,6 @@ ### ItemRouter -![RepoConnectors Structure](../../generated/RepoConnectorsView.svg) +![RepoConnectors Structure](RepoConnectorsView.svg) #### Purpose diff --git a/docs/design/build-mark/repo-connectors/mock.md b/docs/design/build-mark/repo-connectors/mock.md index fc63760..73ba9dd 100644 --- a/docs/design/build-mark/repo-connectors/mock.md +++ b/docs/design/build-mark/repo-connectors/mock.md @@ -1,6 +1,6 @@ ### Mock -![Mock Structure](../../generated/MockView.svg) +![Mock Structure](MockView.svg) #### Overview diff --git a/docs/design/build-mark/repo-connectors/mock/mock-repo-connector.md b/docs/design/build-mark/repo-connectors/mock/mock-repo-connector.md index 068c212..108be74 100644 --- a/docs/design/build-mark/repo-connectors/mock/mock-repo-connector.md +++ b/docs/design/build-mark/repo-connectors/mock/mock-repo-connector.md @@ -1,6 +1,6 @@ #### MockRepoConnector -![Mock Structure](../../../generated/MockView.svg) +![Mock Structure](MockView.svg) ##### Purpose diff --git a/docs/design/build-mark/repo-connectors/repo-connector-base.md b/docs/design/build-mark/repo-connectors/repo-connector-base.md index 0249b77..eb228b4 100644 --- a/docs/design/build-mark/repo-connectors/repo-connector-base.md +++ b/docs/design/build-mark/repo-connectors/repo-connector-base.md @@ -1,6 +1,6 @@ ### RepoConnectorBase -![RepoConnectors Structure](../../generated/RepoConnectorsView.svg) +![RepoConnectors Structure](RepoConnectorsView.svg) #### Purpose diff --git a/docs/design/build-mark/repo-connectors/repo-connector-factory.md b/docs/design/build-mark/repo-connectors/repo-connector-factory.md index c935d2f..11ec37a 100644 --- a/docs/design/build-mark/repo-connectors/repo-connector-factory.md +++ b/docs/design/build-mark/repo-connectors/repo-connector-factory.md @@ -1,6 +1,6 @@ ### RepoConnectorFactory -![RepoConnectors Structure](../../generated/RepoConnectorsView.svg) +![RepoConnectors Structure](RepoConnectorsView.svg) #### Purpose diff --git a/docs/design/build-mark/self-test.md b/docs/design/build-mark/self-test.md index cbf318d..6031381 100644 --- a/docs/design/build-mark/self-test.md +++ b/docs/design/build-mark/self-test.md @@ -1,6 +1,6 @@ ## SelfTest Subsystem -![SelfTest Structure](../generated/SelfTestView.svg) +![SelfTest Structure](SelfTestView.svg) ### Overview diff --git a/docs/design/build-mark/self-test/validation.md b/docs/design/build-mark/self-test/validation.md index db01dec..de9fde9 100644 --- a/docs/design/build-mark/self-test/validation.md +++ b/docs/design/build-mark/self-test/validation.md @@ -1,6 +1,6 @@ ### Validation -![SelfTest Structure](../../generated/SelfTestView.svg) +![SelfTest Structure](SelfTestView.svg) #### Purpose diff --git a/docs/design/build-mark/utilities.md b/docs/design/build-mark/utilities.md index 61ab12e..4909414 100644 --- a/docs/design/build-mark/utilities.md +++ b/docs/design/build-mark/utilities.md @@ -1,6 +1,6 @@ ## Utilities Subsystem -![Utilities Structure](../generated/UtilitiesView.svg) +![Utilities Structure](UtilitiesView.svg) ### Overview diff --git a/docs/design/build-mark/utilities/path-helpers.md b/docs/design/build-mark/utilities/path-helpers.md index 85f1f9e..03735f7 100644 --- a/docs/design/build-mark/utilities/path-helpers.md +++ b/docs/design/build-mark/utilities/path-helpers.md @@ -1,6 +1,6 @@ ### PathHelpers -![Utilities Structure](../../generated/UtilitiesView.svg) +![Utilities Structure](UtilitiesView.svg) #### Purpose diff --git a/docs/design/build-mark/utilities/process-runner.md b/docs/design/build-mark/utilities/process-runner.md index 6bce80f..97246f9 100644 --- a/docs/design/build-mark/utilities/process-runner.md +++ b/docs/design/build-mark/utilities/process-runner.md @@ -1,6 +1,6 @@ ### ProcessRunner -![Utilities Structure](../../generated/UtilitiesView.svg) +![Utilities Structure](UtilitiesView.svg) #### Purpose diff --git a/docs/design/build-mark/utilities/temporary-directory.md b/docs/design/build-mark/utilities/temporary-directory.md index c00a190..db2efc2 100644 --- a/docs/design/build-mark/utilities/temporary-directory.md +++ b/docs/design/build-mark/utilities/temporary-directory.md @@ -1,6 +1,6 @@ ### TemporaryDirectory -![Utilities Structure](../../generated/UtilitiesView.svg) +![Utilities Structure](UtilitiesView.svg) #### Purpose diff --git a/docs/design/build-mark/version.md b/docs/design/build-mark/version.md index da17fbd..b5c9c54 100644 --- a/docs/design/build-mark/version.md +++ b/docs/design/build-mark/version.md @@ -1,6 +1,6 @@ ## Version Subsystem -![Version Structure](../generated/VersionView.svg) +![Version Structure](VersionView.svg) ### Overview diff --git a/docs/design/build-mark/version/version-commit-tag.md b/docs/design/build-mark/version/version-commit-tag.md index 2f5895b..8049af7 100644 --- a/docs/design/build-mark/version/version-commit-tag.md +++ b/docs/design/build-mark/version/version-commit-tag.md @@ -1,6 +1,6 @@ ### VersionCommitTag -![Version Structure](../../generated/VersionView.svg) +![Version Structure](VersionView.svg) #### Purpose diff --git a/docs/design/build-mark/version/version-comparable.md b/docs/design/build-mark/version/version-comparable.md index c550406..9026d72 100644 --- a/docs/design/build-mark/version/version-comparable.md +++ b/docs/design/build-mark/version/version-comparable.md @@ -1,6 +1,6 @@ ### VersionComparable -![Version Structure](../../generated/VersionView.svg) +![Version Structure](VersionView.svg) #### Purpose diff --git a/docs/design/build-mark/version/version-interval-set.md b/docs/design/build-mark/version/version-interval-set.md index 386b738..cdc5f8c 100644 --- a/docs/design/build-mark/version/version-interval-set.md +++ b/docs/design/build-mark/version/version-interval-set.md @@ -1,6 +1,6 @@ ### VersionIntervalSet -![Version Structure](../../generated/VersionView.svg) +![Version Structure](VersionView.svg) #### Purpose diff --git a/docs/design/build-mark/version/version-interval.md b/docs/design/build-mark/version/version-interval.md index a67649a..b662f56 100644 --- a/docs/design/build-mark/version/version-interval.md +++ b/docs/design/build-mark/version/version-interval.md @@ -1,6 +1,6 @@ ### VersionInterval -![Version Structure](../../generated/VersionView.svg) +![Version Structure](VersionView.svg) #### Purpose diff --git a/docs/design/build-mark/version/version-semantic.md b/docs/design/build-mark/version/version-semantic.md index 54de190..f6899be 100644 --- a/docs/design/build-mark/version/version-semantic.md +++ b/docs/design/build-mark/version/version-semantic.md @@ -1,6 +1,6 @@ ### VersionSemantic -![Version Structure](../../generated/VersionView.svg) +![Version Structure](VersionView.svg) #### Purpose diff --git a/docs/design/build-mark/version/version-tag.md b/docs/design/build-mark/version/version-tag.md index d52e11b..34edd28 100644 --- a/docs/design/build-mark/version/version-tag.md +++ b/docs/design/build-mark/version/version-tag.md @@ -1,6 +1,6 @@ ### VersionTag -![Version Structure](../../generated/VersionView.svg) +![Version Structure](VersionView.svg) #### Purpose diff --git a/docs/design/introduction.md b/docs/design/introduction.md index 3eb7184..a0421d0 100644 --- a/docs/design/introduction.md +++ b/docs/design/introduction.md @@ -39,7 +39,7 @@ diagram below by SysML2Tools as part of the build pipeline. AI agents should que SysML2 model directly (see the `sysml2tools-query` skill) rather than parsing this diagram or the prose below. -![Software Structure](generated/SoftwareStructureView.svg) +![Software Structure](SoftwareStructureView.svg) ## Folder Layout From 3f38f6d7d943ccea0c3d9583cd8c07307215331e Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Tue, 7 Jul 2026 23:37:00 -0400 Subject: [PATCH 08/12] Remove erroneous 'render asTreeDiagram;' entries from design-views.sysml Verified the full design-document build.yaml pipeline locally after this change: sysml2tools render (12 views), Pandoc HTML generation, WeasyPrint PDF generation, and FileAssert both passed (Pandoc_DesignHtml, WeasyPrint_DesignPdf). Diagrams remain embedded in the compiled PDF. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/sysml2/views/design-views.sysml | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/docs/sysml2/views/design-views.sysml b/docs/sysml2/views/design-views.sysml index b9e278f..6fb737d 100644 --- a/docs/sysml2/views/design-views.sysml +++ b/docs/sysml2/views/design-views.sysml @@ -6,61 +6,49 @@ package BuildMark { view SoftwareStructureView { expose BuildMark; - render asTreeDiagram; } view BuildMarkView { expose BuildMarkSystem; - render asTreeDiagram; } view CliView { expose CliSubsystem; - render asTreeDiagram; } view BuildNotesView { expose BuildNotesSubsystem; - render asTreeDiagram; } view SelfTestView { expose SelfTestSubsystem; - render asTreeDiagram; } view UtilitiesView { expose UtilitiesSubsystem; - render asTreeDiagram; } view VersionView { expose VersionSubsystem; - render asTreeDiagram; } view ConfigurationView { expose ConfigurationSubsystem; - render asTreeDiagram; } view RepoConnectorsView { expose RepoConnectorsSubsystem; - render asTreeDiagram; } view GitHubView { expose GitHubSubsystem; - render asTreeDiagram; } view AzureDevOpsView { expose AzureDevOpsSubsystem; - render asTreeDiagram; } view MockView { expose MockSubsystem; - render asTreeDiagram; } } From 961ee74a55e287521cda1c0bea266690ed43dcd9 Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Tue, 7 Jul 2026 23:50:54 -0400 Subject: [PATCH 09/12] Update sysml standard for render option. --- .github/standards/sysml2-modeling.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/.github/standards/sysml2-modeling.md b/.github/standards/sysml2-modeling.md index 60f7b96..c5558e1 100644 --- a/.github/standards/sysml2-modeling.md +++ b/.github/standards/sysml2-modeling.md @@ -127,17 +127,14 @@ Views control what gets rendered into diagrams for the design document. Use name package {SystemName} { view SoftwareStructureView { expose {SystemName}; // whole package: system + subsystems + units - render asTreeDiagram; } view {SystemName}View { expose {SystemName}System; // system def only, not expanded into subsystems - render asTreeDiagram; } view {SubsystemName}View { expose {SubsystemName}; // one subsystem def only - render asTreeDiagram; } } ``` @@ -145,7 +142,7 @@ package {SystemName} { **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. -`asTreeDiagram`) — it has **no effect on scope**. `expose` is only legal inside a named +`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;`). From 5232a6bbd69e352b7503086083b8a4f7cec25299 Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Wed, 8 Jul 2026 00:02:40 -0400 Subject: [PATCH 10/12] Add SysML2 model files to .reviewmark.yaml review coverage docs/sysml2/**/*.sysml was missing from the top-level needs-review patterns and from every review-set's paths, so the model was never flagged for review despite being the authoritative structural source per sysml2-modeling.md. Add the pattern to needs-review and to BuildMark-Architecture (the closest existing analog to the standard's Decomposition review-set, which this repo's older .reviewmark.yaml predates). Verified: dotnet reviewmark --lint passes; dotnet reviewmark --plan --enforce confirms all 53 docs/sysml2/**/*.sysml files are now captured by BuildMark-Architecture (previously 0). One pre-existing, unrelated uncovered file remains (docs/design/ots/yaml-dot-net.md) - out of scope for this change. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .reviewmark.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.reviewmark.yaml b/.reviewmark.yaml index 551b493..00707a7 100644 --- a/.reviewmark.yaml +++ b/.reviewmark.yaml @@ -10,6 +10,7 @@ needs-review: - "requirements.yaml" # Root requirements file - "**/*.cs" # All C# source and test files - "docs/reqstream/**/*.yaml" # Requirements files + - "docs/sysml2/**/*.sysml" # SysML2 architecture model files - "docs/design/**/*.md" # Design documentation files - "docs/verification/**/*.md" # Verification documentation files - "docs/user_guide/**/*.md" # User guide documentation @@ -46,6 +47,7 @@ reviews: - "docs/reqstream/build-mark.yaml" - "docs/design/introduction.md" - "docs/design/build-mark.md" + - "docs/sysml2/**/*.sysml" - "docs/verification/introduction.md" - "docs/verification/build-mark.md" - "test/**/IntegrationTests.cs" From 72c78ade8d8e7bb9c97aafed72c756d700a8e610 Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Wed, 8 Jul 2026 00:05:00 -0400 Subject: [PATCH 11/12] Add missing OTS-YamlDotNet review-set to achieve full ReviewMark coverage docs/design/ots/yaml-dot-net.md existed but had no review-set at all (every other OTS item has an OTS-{Name} review-set), leaving it uncovered and causing 'dotnet reviewmark --plan --enforce' to fail the CI merge-gate. Add OTS-YamlDotNet covering the existing design doc. Note: unlike other OTS items, YamlDotNet has no docs/reqstream/ots/ or docs/verification/ots/ file and is not included in requirements.yaml - a separate, pre-existing ReqStream traceability gap, out of scope for this change (this fix addresses only ReviewMark file coverage). Verified: dotnet reviewmark --lint passes; dotnet reviewmark --plan --enforce now exits 0 with zero uncovered files (previously 1). Full lint.ps1 passes clean. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .reviewmark.yaml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.reviewmark.yaml b/.reviewmark.yaml index 00707a7..1e898c8 100644 --- a/.reviewmark.yaml +++ b/.reviewmark.yaml @@ -451,6 +451,11 @@ reviews: - "test/**/RepoConnectors/AzureDevOps/MockableAzureDevOpsRepoConnector.cs" # OTS Items + - id: OTS-YamlDotNet + title: Review that YamlDotNet Provides Required Functionality + paths: + - "docs/design/ots/yaml-dot-net.md" + - id: OTS-BuildMark title: Review of BuildMark OTS verification evidence paths: From 4c8308d8e281b1adf86f6cac782a1015f661972a Mon Sep 17 00:00:00 2001 From: Malcolm Nixon Date: Wed, 8 Jul 2026 09:14:42 -0400 Subject: [PATCH 12/12] Remediate .reviewmark.yaml per template-sync audit - Add top-level context key and Decomposition review-set - Add 9 OTS-* review-set titles fixed to standard wording; OTS-BuildMark title fixed - Fix Purpose title/scope, BuildMark-Architecture scope (remove sysml2 model) - Fix BuildMark-AllRequirements scope and title - Fix 30 title-wording deviations across system/subsystem/unit review-sets - Add per-review-set context entries per Context Files table - Fix depth-1 subsystem docs/design and docs/reqstream path references from nested to flat form to match actual files on disk and depth-2 convention Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com> --- .reviewmark.yaml | 293 ++++++++++++++++++++++++++++++++++++----------- 1 file changed, 226 insertions(+), 67 deletions(-) diff --git a/.reviewmark.yaml b/.reviewmark.yaml index 1e898c8..15f3eba 100644 --- a/.reviewmark.yaml +++ b/.reviewmark.yaml @@ -27,27 +27,41 @@ evidence-source: type: url location: https://raw.githubusercontent.com/demaconsulting/BuildMark/reviews/index.json +# Global context shown to every reviewer for orientation (not fingerprinted). +context: + - docs/design/introduction.md + # Review sets following hierarchical scope principles. # Each review-set focuses on a single compliance question with manageable file counts. reviews: # Purpose - 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/build-mark.yaml" + + # Decomposition + - id: Decomposition + title: Review that BuildMark Decomposition Addresses the Stated Purpose + context: + - "README.md" + - "docs/user_guide/**/*.md" + paths: + - "requirements.yaml" - "docs/design/introduction.md" - - "docs/design/build-mark.md" + - "docs/sysml2/**/*.sysml" # BuildMark - Specials - id: BuildMark-Architecture - title: Review of BuildMark system architecture and operational validation + title: Review that BuildMark Architecture Satisfies Requirements + context: + - "README.md" + - "docs/user_guide/**/*.md" paths: - "docs/reqstream/build-mark.yaml" - "docs/design/introduction.md" - "docs/design/build-mark.md" - - "docs/sysml2/**/*.sysml" - "docs/verification/introduction.md" - "docs/verification/build-mark.md" - "test/**/IntegrationTests.cs" @@ -55,7 +69,9 @@ reviews: - "test/**/AssemblyInfo.cs" - id: BuildMark-Design - title: Review of BuildMark architectural and design consistency + title: Review that BuildMark Design is Consistent and Complete + context: + - "docs/reqstream/build-mark.yaml" paths: - "docs/reqstream/build-mark.yaml" - "docs/reqstream/build-mark/platform-requirements.yaml" @@ -65,6 +81,8 @@ reviews: - id: BuildMark-Verification title: Review that BuildMark Verification is Consistent and Complete + context: + - "docs/reqstream/build-mark.yaml" paths: - "docs/reqstream/build-mark.yaml" - "docs/verification/introduction.md" @@ -73,16 +91,19 @@ reviews: - "docs/verification/ots.md" - id: BuildMark-AllRequirements - title: Review of All BuildMark requirements quality and traceability - paths: - - "requirements.yaml" + title: Review that All BuildMark Requirements are Complete + context: + - "docs/design/build-mark.md" - "docs/reqstream/build-mark.yaml" + paths: - "docs/reqstream/build-mark/**/*.yaml" - - "docs/reqstream/ots/**/*.yaml" # BuildMark - Program - id: BuildMark-Program - title: Review of BuildMark Program unit implementation + title: Review that BuildMark Program Implementation is Correct + context: + - "docs/design/build-mark.md" + - "docs/reqstream/build-mark.yaml" paths: - "docs/reqstream/build-mark/program.yaml" - "docs/design/build-mark/program.md" @@ -92,15 +113,21 @@ reviews: # BuildMark - Cli - id: BuildMark-Cli - title: Review of BuildMark Cli subsystem architecture and interfaces + title: Review that BuildMark Cli Satisfies Subsystem Requirements + context: + - "docs/design/build-mark.md" + - "docs/reqstream/build-mark.yaml" paths: - - "docs/reqstream/build-mark/cli/cli.yaml" - - "docs/design/build-mark/cli/cli.md" + - "docs/reqstream/build-mark/cli.yaml" + - "docs/design/build-mark/cli.md" - "docs/verification/build-mark/cli.md" - "test/**/Cli/CliTests.cs" - id: BuildMark-Cli-Context - title: Review of BuildMark Cli Context unit implementation + title: Review that BuildMark Cli Context Implementation is Correct + context: + - "docs/design/build-mark.md" + - "docs/reqstream/build-mark.yaml" paths: - "docs/reqstream/build-mark/cli/context.yaml" - "docs/design/build-mark/cli/context.md" @@ -111,14 +138,20 @@ reviews: # BuildMark - SelfTest - id: BuildMark-SelfTest title: Review that BuildMark SelfTest Satisfies Subsystem Requirements + context: + - "docs/design/build-mark.md" + - "docs/reqstream/build-mark.yaml" paths: - - "docs/reqstream/build-mark/self-test/self-test.yaml" - - "docs/design/build-mark/self-test/self-test.md" + - "docs/reqstream/build-mark/self-test.yaml" + - "docs/design/build-mark/self-test.md" - "docs/verification/build-mark/self-test.md" - "test/**/SelfTest/SelfTestTests.cs" - id: BuildMark-SelfTest-Validation - title: Review of BuildMark SelfTest Validation unit implementation + title: Review that BuildMark SelfTest Validation Implementation is Correct + context: + - "docs/design/build-mark.md" + - "docs/reqstream/build-mark.yaml" paths: - "docs/reqstream/build-mark/self-test/validation.yaml" - "docs/design/build-mark/self-test/validation.md" @@ -129,14 +162,20 @@ reviews: # BuildMark - Utilities - id: BuildMark-Utilities title: Review that BuildMark Utilities Satisfies Subsystem Requirements + context: + - "docs/design/build-mark.md" + - "docs/reqstream/build-mark.yaml" paths: - - "docs/reqstream/build-mark/utilities/utilities.yaml" - - "docs/design/build-mark/utilities/utilities.md" + - "docs/reqstream/build-mark/utilities.yaml" + - "docs/design/build-mark/utilities.md" - "docs/verification/build-mark/utilities.md" - "test/**/Utilities/UtilitiesTests.cs" - id: BuildMark-Utilities-PathHelpers - title: Review of BuildMark Utilities PathHelpers unit implementation + title: Review that BuildMark Utilities PathHelpers Implementation is Correct + context: + - "docs/design/build-mark.md" + - "docs/reqstream/build-mark.yaml" paths: - "docs/reqstream/build-mark/utilities/path-helpers.yaml" - "docs/design/build-mark/utilities/path-helpers.md" @@ -145,7 +184,10 @@ reviews: - "test/**/Utilities/PathHelpersTests.cs" - id: BuildMark-Utilities-ProcessRunner - title: Review of BuildMark Utilities ProcessRunner unit implementation + title: Review that BuildMark Utilities ProcessRunner Implementation is Correct + context: + - "docs/design/build-mark.md" + - "docs/reqstream/build-mark.yaml" paths: - "docs/reqstream/build-mark/utilities/process-runner.yaml" - "docs/design/build-mark/utilities/process-runner.md" @@ -154,7 +196,10 @@ reviews: - "test/**/Utilities/ProcessRunnerTests.cs" - id: BuildMark-Utilities-TemporaryDirectory - title: Review of BuildMark Utilities TemporaryDirectory unit implementation + title: Review that BuildMark Utilities TemporaryDirectory Implementation is Correct + context: + - "docs/design/build-mark.md" + - "docs/reqstream/build-mark.yaml" paths: - "docs/reqstream/build-mark/utilities/temporary-directory.yaml" - "docs/design/build-mark/utilities/temporary-directory.md" @@ -165,14 +210,20 @@ reviews: # BuildMark - Version - id: BuildMark-Version title: Review that BuildMark Version Satisfies Subsystem Requirements + context: + - "docs/design/build-mark.md" + - "docs/reqstream/build-mark.yaml" paths: - - "docs/reqstream/build-mark/version/version.yaml" - - "docs/design/build-mark/version/version.md" + - "docs/reqstream/build-mark/version.yaml" + - "docs/design/build-mark/version.md" - "docs/verification/build-mark/version.md" - "test/**/Version/VersionTests.cs" - id: BuildMark-Version-VersionComparable - title: Review of BuildMark Version VersionComparable unit implementation + title: Review that BuildMark Version VersionComparable Implementation is Correct + context: + - "docs/design/build-mark.md" + - "docs/reqstream/build-mark.yaml" paths: - "docs/reqstream/build-mark/version/version-comparable.yaml" - "docs/design/build-mark/version/version-comparable.md" @@ -181,7 +232,10 @@ reviews: - "test/**/Version/VersionComparableTests.cs" - id: BuildMark-Version-VersionSemantic - title: Review of BuildMark Version VersionSemantic unit implementation + title: Review that BuildMark Version VersionSemantic Implementation is Correct + context: + - "docs/design/build-mark.md" + - "docs/reqstream/build-mark.yaml" paths: - "docs/reqstream/build-mark/version/version-semantic.yaml" - "docs/design/build-mark/version/version-semantic.md" @@ -190,7 +244,10 @@ reviews: - "test/**/Version/VersionSemanticTests.cs" - id: BuildMark-Version-VersionTag - title: Review of BuildMark Version VersionTag unit implementation + title: Review that BuildMark Version VersionTag Implementation is Correct + context: + - "docs/design/build-mark.md" + - "docs/reqstream/build-mark.yaml" paths: - "docs/reqstream/build-mark/version/version-tag.yaml" - "docs/design/build-mark/version/version-tag.md" @@ -199,7 +256,10 @@ reviews: - "test/**/Version/VersionTagTests.cs" - id: BuildMark-Version-VersionInterval - title: Review of BuildMark Version VersionInterval unit implementation + title: Review that BuildMark Version VersionInterval Implementation is Correct + context: + - "docs/design/build-mark.md" + - "docs/reqstream/build-mark.yaml" paths: - "docs/reqstream/build-mark/version/version-interval.yaml" - "docs/design/build-mark/version/version-interval.md" @@ -211,7 +271,10 @@ reviews: - "test/**/Version/VersionIntervalSetTests.cs" - id: BuildMark-Version-VersionCommitTag - title: Review of BuildMark Version VersionCommitTag unit implementation + title: Review that BuildMark Version VersionCommitTag Implementation is Correct + context: + - "docs/design/build-mark.md" + - "docs/reqstream/build-mark.yaml" paths: - "docs/reqstream/build-mark/version/version-commit-tag.yaml" - "docs/design/build-mark/version/version-commit-tag.md" @@ -222,14 +285,20 @@ reviews: # BuildMark - BuildNotes - id: BuildMark-BuildNotes title: Review that BuildMark BuildNotes Satisfies Subsystem Requirements + context: + - "docs/design/build-mark.md" + - "docs/reqstream/build-mark.yaml" paths: - - "docs/reqstream/build-mark/build-notes/build-notes.yaml" - - "docs/design/build-mark/build-notes/build-notes.md" + - "docs/reqstream/build-mark/build-notes.yaml" + - "docs/design/build-mark/build-notes.md" - "docs/verification/build-mark/build-notes.md" - "test/**/BuildNotes/BuildNotesTests.cs" - id: BuildMark-BuildNotes-BuildInformation - title: Review of BuildMark BuildNotes BuildInformation unit implementation + title: Review that BuildMark BuildNotes BuildInformation Implementation is Correct + context: + - "docs/design/build-mark.md" + - "docs/reqstream/build-mark.yaml" paths: - "docs/reqstream/build-mark/build-notes/build-information.yaml" - "docs/design/build-mark/build-notes/build-information.md" @@ -238,7 +307,10 @@ reviews: - "test/**/BuildNotes/BuildInformationTests.cs" - id: BuildMark-BuildNotes-ItemInfo - title: Review of BuildMark BuildNotes ItemInfo unit implementation + title: Review that BuildMark BuildNotes ItemInfo Implementation is Correct + context: + - "docs/design/build-mark.md" + - "docs/reqstream/build-mark.yaml" paths: - "docs/reqstream/build-mark/build-notes/item-info.yaml" - "docs/design/build-mark/build-notes/item-info.md" @@ -246,7 +318,10 @@ reviews: - "src/**/BuildNotes/ItemInfo.cs" - id: BuildMark-BuildNotes-WebLink - title: Review of BuildMark BuildNotes WebLink unit implementation + title: Review that BuildMark BuildNotes WebLink Implementation is Correct + context: + - "docs/design/build-mark.md" + - "docs/reqstream/build-mark.yaml" paths: - "docs/reqstream/build-mark/build-notes/web-link.yaml" - "docs/design/build-mark/build-notes/web-link.md" @@ -257,14 +332,20 @@ reviews: # BuildMark - Configuration - id: BuildMark-Configuration title: Review that BuildMark Configuration Satisfies Subsystem Requirements + context: + - "docs/design/build-mark.md" + - "docs/reqstream/build-mark.yaml" paths: - - "docs/reqstream/build-mark/configuration/configuration.yaml" - - "docs/design/build-mark/configuration/configuration.md" + - "docs/reqstream/build-mark/configuration.yaml" + - "docs/design/build-mark/configuration.md" - "docs/verification/build-mark/configuration.md" - "test/**/Configuration/ConfigurationSubsystemTests.cs" - id: BuildMark-Configuration-BuildMarkConfigReader - title: Review of BuildMark Configuration BuildMarkConfigReader unit implementation + title: Review that BuildMark Configuration BuildMarkConfigReader Implementation is Correct + context: + - "docs/design/build-mark.md" + - "docs/reqstream/build-mark.yaml" paths: - "docs/reqstream/build-mark/configuration/configuration.yaml" - "docs/design/build-mark/configuration/configuration.md" @@ -273,7 +354,10 @@ reviews: - "test/**/Configuration/ConfigurationTests.cs" - id: BuildMark-Configuration-ConfigurationLoadResult - title: Review of BuildMark Configuration ConfigurationLoadResult unit implementation + title: Review that BuildMark Configuration ConfigurationLoadResult Implementation is Correct + context: + - "docs/design/build-mark.md" + - "docs/reqstream/build-mark.yaml" paths: - "docs/reqstream/build-mark/configuration/configuration.yaml" - "docs/design/build-mark/configuration/configuration.md" @@ -284,7 +368,10 @@ reviews: - "test/**/Configuration/ConfigurationTests.cs" - id: BuildMark-Configuration-ConnectorConfig - title: Review of BuildMark Configuration ConnectorConfig unit implementation + title: Review that BuildMark Configuration ConnectorConfig Implementation is Correct + context: + - "docs/design/build-mark.md" + - "docs/reqstream/build-mark.yaml" paths: - "docs/reqstream/build-mark/configuration/configuration.yaml" - "docs/design/build-mark/configuration/configuration.md" @@ -308,14 +395,20 @@ reviews: # BuildMark - RepoConnectors - id: BuildMark-RepoConnectors title: Review that BuildMark RepoConnectors Satisfies Subsystem Requirements + context: + - "docs/design/build-mark.md" + - "docs/reqstream/build-mark.yaml" paths: - - "docs/reqstream/build-mark/repo-connectors/repo-connectors.yaml" - - "docs/design/build-mark/repo-connectors/repo-connectors.md" + - "docs/reqstream/build-mark/repo-connectors.yaml" + - "docs/design/build-mark/repo-connectors.md" - "docs/verification/build-mark/repo-connectors.md" - "test/**/RepoConnectors/RepoConnectorsTests.cs" - id: BuildMark-RepoConnectors-RepoConnectorBase - title: Review of BuildMark RepoConnectors RepoConnectorBase unit implementation + title: Review that BuildMark RepoConnectors RepoConnectorBase Implementation is Correct + context: + - "docs/design/build-mark.md" + - "docs/reqstream/build-mark.yaml" paths: - "docs/reqstream/build-mark/repo-connectors/repo-connector-base.yaml" - "docs/design/build-mark/repo-connectors/repo-connector-base.md" @@ -326,7 +419,10 @@ reviews: - "test/**/RepoConnectors/RepoConnectorBaseTests.cs" - id: BuildMark-RepoConnectors-RepoConnectorFactory - title: Review of BuildMark RepoConnectors RepoConnectorFactory unit implementation + title: Review that BuildMark RepoConnectors RepoConnectorFactory Implementation is Correct + context: + - "docs/design/build-mark.md" + - "docs/reqstream/build-mark.yaml" paths: - "docs/reqstream/build-mark/repo-connectors/repo-connector-factory.yaml" - "docs/design/build-mark/repo-connectors/repo-connector-factory.md" @@ -335,7 +431,10 @@ reviews: - "test/**/RepoConnectors/RepoConnectorFactoryTests.cs" - id: BuildMark-RepoConnectors-ItemControlsParser - title: Review of BuildMark RepoConnectors ItemControlsParser unit implementation + title: Review that BuildMark RepoConnectors ItemControlsParser Implementation is Correct + context: + - "docs/design/build-mark.md" + - "docs/reqstream/build-mark.yaml" paths: - "docs/reqstream/build-mark/repo-connectors/item-controls-parser.yaml" - "docs/design/build-mark/repo-connectors/item-controls-info.md" @@ -348,7 +447,10 @@ reviews: - "test/**/ItemControls/ItemControlsTests.cs" - id: BuildMark-RepoConnectors-ItemRouter - title: Review of BuildMark RepoConnectors ItemRouter unit implementation + title: Review that BuildMark RepoConnectors ItemRouter Implementation is Correct + context: + - "docs/design/build-mark.md" + - "docs/reqstream/build-mark.yaml" paths: - "docs/reqstream/build-mark/repo-connectors/item-router.yaml" - "docs/design/build-mark/repo-connectors/item-router.md" @@ -357,15 +459,27 @@ reviews: - "test/**/RepoConnectors/ItemRouterTests.cs" - id: BuildMark-RepoConnectors-Mock - title: Review that BuildMark RepoConnectors Mock Satisfies Sub-Subsystem Requirements + title: Review that BuildMark RepoConnectors Mock Satisfies Subsystem Requirements + context: + - "docs/design/build-mark.md" + - "docs/reqstream/build-mark.yaml" + - "docs/design/build-mark/repo-connectors.md" + - "docs/reqstream/build-mark/repo-connectors.yaml" paths: - - "docs/reqstream/build-mark/repo-connectors/mock/mock.yaml" + - "docs/reqstream/build-mark/repo-connectors/mock.yaml" - "docs/design/build-mark/repo-connectors/mock.md" - "docs/verification/build-mark/repo-connectors/mock.md" - "test/**/RepoConnectors/Mock/MockTests.cs" - id: BuildMark-RepoConnectors-Mock-MockRepoConnector - title: Review of BuildMark RepoConnectors Mock MockRepoConnector unit implementation + title: Review that BuildMark RepoConnectors Mock MockRepoConnector Implementation is Correct + context: + - "docs/design/build-mark.md" + - "docs/reqstream/build-mark.yaml" + - "docs/design/build-mark/repo-connectors.md" + - "docs/reqstream/build-mark/repo-connectors.yaml" + - "docs/design/build-mark/repo-connectors/mock.md" + - "docs/reqstream/build-mark/repo-connectors/mock.yaml" paths: - "docs/reqstream/build-mark/repo-connectors/mock/mock-repo-connector.yaml" - "docs/design/build-mark/repo-connectors/mock/mock-repo-connector.md" @@ -374,15 +488,27 @@ reviews: - "test/**/RepoConnectors/Mock/MockRepoConnectorTests.cs" - id: BuildMark-RepoConnectors-GitHub - title: Review that BuildMark RepoConnectors GitHub Satisfies Sub-Subsystem Requirements + title: Review that BuildMark RepoConnectors GitHub Satisfies Subsystem Requirements + context: + - "docs/design/build-mark.md" + - "docs/reqstream/build-mark.yaml" + - "docs/design/build-mark/repo-connectors.md" + - "docs/reqstream/build-mark/repo-connectors.yaml" paths: - - "docs/reqstream/build-mark/repo-connectors/github/github.yaml" + - "docs/reqstream/build-mark/repo-connectors/github.yaml" - "docs/design/build-mark/repo-connectors/github.md" - "docs/verification/build-mark/repo-connectors/github.md" - "test/**/RepoConnectors/GitHub/GitHubTests.cs" - id: BuildMark-RepoConnectors-GitHub-GitHubGraphQLClient - title: Review of BuildMark RepoConnectors GitHub GitHubGraphQLClient unit implementation + title: Review that BuildMark RepoConnectors GitHub GitHubGraphQLClient Implementation is Correct + context: + - "docs/design/build-mark.md" + - "docs/reqstream/build-mark.yaml" + - "docs/design/build-mark/repo-connectors.md" + - "docs/reqstream/build-mark/repo-connectors.yaml" + - "docs/design/build-mark/repo-connectors/github.md" + - "docs/reqstream/build-mark/repo-connectors/github.yaml" paths: - "docs/reqstream/build-mark/repo-connectors/github/github-graphql-client.yaml" - "docs/design/build-mark/repo-connectors/github/github-graphql-client.md" @@ -401,7 +527,14 @@ reviews: - "test/**/RepoConnectors/GitHub/MockGitHubGraphQLHttpMessageHandlerTests.cs" - id: BuildMark-RepoConnectors-GitHub-GitHubRepoConnector - title: Review of BuildMark RepoConnectors GitHub GitHubRepoConnector unit implementation + title: Review that BuildMark RepoConnectors GitHub GitHubRepoConnector Implementation is Correct + context: + - "docs/design/build-mark.md" + - "docs/reqstream/build-mark.yaml" + - "docs/design/build-mark/repo-connectors.md" + - "docs/reqstream/build-mark/repo-connectors.yaml" + - "docs/design/build-mark/repo-connectors/github.md" + - "docs/reqstream/build-mark/repo-connectors/github.yaml" paths: - "docs/reqstream/build-mark/repo-connectors/github/github-repo-connector.yaml" - "docs/design/build-mark/repo-connectors/github/github-repo-connector.md" @@ -411,7 +544,12 @@ reviews: - "test/**/RepoConnectors/GitHub/MockableGitHubRepoConnector.cs" - id: BuildMark-RepoConnectors-AzureDevOps - title: Review that BuildMark RepoConnectors AzureDevOps Satisfies Sub-Subsystem Requirements + title: Review that BuildMark RepoConnectors AzureDevOps Satisfies Subsystem Requirements + context: + - "docs/design/build-mark.md" + - "docs/reqstream/build-mark.yaml" + - "docs/design/build-mark/repo-connectors.md" + - "docs/reqstream/build-mark/repo-connectors.yaml" paths: - "docs/reqstream/build-mark/repo-connectors/azure-devops.yaml" - "docs/design/build-mark/repo-connectors/azure-devops.md" @@ -419,7 +557,14 @@ reviews: - "test/**/RepoConnectors/AzureDevOps/AzureDevOpsTests.cs" - id: BuildMark-RepoConnectors-AzureDevOps-AzureDevOpsRestClient - title: Review of BuildMark RepoConnectors AzureDevOps AzureDevOpsRestClient unit implementation + title: Review that BuildMark RepoConnectors AzureDevOps AzureDevOpsRestClient Implementation is Correct + context: + - "docs/design/build-mark.md" + - "docs/reqstream/build-mark.yaml" + - "docs/design/build-mark/repo-connectors.md" + - "docs/reqstream/build-mark/repo-connectors.yaml" + - "docs/design/build-mark/repo-connectors/azure-devops.md" + - "docs/reqstream/build-mark/repo-connectors/azure-devops.yaml" paths: - "docs/reqstream/build-mark/repo-connectors/azure-devops/azure-devops-rest-client.yaml" - "docs/design/build-mark/repo-connectors/azure-devops/azure-devops-rest-client.md" @@ -432,7 +577,14 @@ reviews: - "test/**/RepoConnectors/AzureDevOps/AzureDevOpsRestClientTests.cs" - id: BuildMark-RepoConnectors-AzureDevOps-WorkItemMapper - title: Review of BuildMark RepoConnectors AzureDevOps WorkItemMapper unit implementation + title: Review that BuildMark RepoConnectors AzureDevOps WorkItemMapper Implementation is Correct + context: + - "docs/design/build-mark.md" + - "docs/reqstream/build-mark.yaml" + - "docs/design/build-mark/repo-connectors.md" + - "docs/reqstream/build-mark/repo-connectors.yaml" + - "docs/design/build-mark/repo-connectors/azure-devops.md" + - "docs/reqstream/build-mark/repo-connectors/azure-devops.yaml" paths: - "docs/reqstream/build-mark/repo-connectors/azure-devops/work-item-mapper.yaml" - "docs/design/build-mark/repo-connectors/azure-devops/work-item-mapper.md" @@ -441,7 +593,14 @@ reviews: - "test/**/RepoConnectors/AzureDevOps/WorkItemMapperTests.cs" - id: BuildMark-RepoConnectors-AzureDevOps-AzureDevOpsRepoConnector - title: Review of BuildMark RepoConnectors AzureDevOps AzureDevOpsRepoConnector unit implementation + title: Review that BuildMark RepoConnectors AzureDevOps AzureDevOpsRepoConnector Implementation is Correct + context: + - "docs/design/build-mark.md" + - "docs/reqstream/build-mark.yaml" + - "docs/design/build-mark/repo-connectors.md" + - "docs/reqstream/build-mark/repo-connectors.yaml" + - "docs/design/build-mark/repo-connectors/azure-devops.md" + - "docs/reqstream/build-mark/repo-connectors/azure-devops.yaml" paths: - "docs/reqstream/build-mark/repo-connectors/azure-devops/azure-devops-repo-connector.yaml" - "docs/design/build-mark/repo-connectors/azure-devops/azure-devops-repo-connector.md" @@ -457,61 +616,61 @@ reviews: - "docs/design/ots/yaml-dot-net.md" - 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-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-VersionMark - title: Review of VersionMark OTS verification evidence + title: Review that VersionMark Provides Required Functionality paths: - "docs/reqstream/ots/versionmark.yaml" - "docs/verification/ots/versionmark.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-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"