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/agents/developer.agent.md b/.github/agents/developer.agent.md index 5f208eb..5f2b988 100644 --- a/.github/agents/developer.agent.md +++ b/.github/agents/developer.agent.md @@ -19,7 +19,7 @@ Perform software development tasks by determining and applying appropriate stand If one exists, fetch it as the starting point; adjust placeholder names and heading depth to match the target path before writing the file - For each modified file, identify which companion artifacts need updating - (requirements, design docs, tests, review-sets) + (requirements, design docs, verification docs, tests, review-sets, README.md, user guides) - Include companion artifact updates in the work plan 4. **Execute work** following standards requirements and quality checks 5. **Formatting**: Run `pwsh ./fix.ps1` to silently apply all @@ -35,8 +35,7 @@ Perform software development tasks by determining and applying appropriate stand # Developer Agent Report **Result**: (SUCCEEDED|FAILED) - -## Work Summary +**Report**: `.agent-logs/developer-{subject}-{unique-id}.md` - **Files Modified**: {List of files created/modified/deleted} - **Languages Detected**: {Languages identified} diff --git a/.github/agents/formal-review.agent.md b/.github/agents/formal-review.agent.md index 7dd8e84..cb78ddf 100644 --- a/.github/agents/formal-review.agent.md +++ b/.github/agents/formal-review.agent.md @@ -31,12 +31,14 @@ standards from the selection matrix in AGENTS.md. 1. Download the review checklist from . If the download fails, report the failure rather than proceeding without the template. -2. Use `dotnet reviewmark --elaborate {review-set}` to get the files to review -3. Review all files holistically, checking for cross-file consistency and - compliance with the review checklist -4. Save the populated review checklist to `.agent-logs/reviews/review-report-{review-set}.md`. +2. Run `dotnet reviewmark --elaborate {review-set}`. Read all files listed under + `## Context` first — these are reference material, not under review — then review + all files listed under `## Files` holistically, using the context to understand + the intended role and scope within the broader system, and checking for cross-file + consistency and compliance with the review checklist. +3. Save the populated review checklist to `.agent-logs/reviews/review-report-{review-set}.md`. This directory holds formal review artifacts, not agent logs. -5. Generate a completion report per the AGENTS.md reporting requirements. +4. Generate a completion report per the AGENTS.md reporting requirements. # Report Template @@ -44,6 +46,7 @@ standards from the selection matrix in AGENTS.md. # Formal Review Report **Result**: (SUCCEEDED|FAILED) +**Report**: `.agent-logs/formal-review-{subject}-{unique-id}.md` ## Review Summary diff --git a/.github/agents/implementation.agent.md b/.github/agents/implementation.agent.md index 7cc0352..d94e880 100644 --- a/.github/agents/implementation.agent.md +++ b/.github/agents/implementation.agent.md @@ -28,36 +28,18 @@ The state-transitions include retrying a limited number of times: ## PLANNING State (start) -Call the **explore** agent as a sub-agent (built-in agent type) with: +Call the **planning** agent as a sub-agent (custom agent from `.github/agents/`) with: - **context**: the user's request + any previous quality findings + retry context -- **goal**: produce a verified implementation plan through these steps: - - 1. Investigate the codebase and develop a concrete implementation plan that - addresses the request - 2. **Identify companion artifact deliverables**: for every code change in the - plan, list the requirements files, design documents, and review-set entries - that must be created or updated - traceability must flow requirements → - design → code, so these are mandatory deliverables, not optional extras - 3. Review the plan for assumptions, weaknesses, and gaps - identify up to 5 - key assumptions and rate each as: - - **VERIFIED**: confirmed by codebase evidence - - **LIKELY**: consistent with codebase patterns but not directly confirmed - - **UNVERIFIED**: not confirmed by any evidence - 4. For any assumption rated UNVERIFIED or LIKELY, attempt to resolve it - through additional investigation and revise the plan to address identified - weaknesses - repeat the critique-and-strengthen cycle up to 2 additional - times if unresolved issues remain, but stop as soon as the plan is stable - 5. List up to 5 risks to the implementation - 6. Assess feasibility: can this be implemented in a single development pass? - 7. State a **recommendation**: GO or INCOMPLETE - GO if the plan is sound, or - INCOMPLETE if critical unknowns remain that only the user can resolve - -Once the explore sub-agent finishes: - -- IF recommendation is INCOMPLETE: Transition to REPORT with Result: INCOMPLETE, +- **goal**: produce a verified implementation plan, or a targeted plan to address + the identified quality issues if this is a retry + +Once the planning sub-agent finishes: + +- IF Result is FAILED: Transition to REPORT with Result: FAILED +- IF Result is INCOMPLETE: Transition to REPORT with Result: INCOMPLETE, listing the unknowns and what CAN be implemented once they are resolved -- OTHERWISE (GO): Transition to DEVELOPMENT +- OTHERWISE (SUCCEEDED): Transition to DEVELOPMENT ## DEVELOPMENT State @@ -76,7 +58,8 @@ Once the developer sub-agent finishes: Call the **quality** agent as a sub-agent (custom agent from `.github/agents/`) with: -- **context**: the user's request + development summary + files changed + previous issues (if any) +- **context**: the user's request + development summary + files changed + planning companion artifact table + + previous issues (if any) - **goal**: check the quality of the work performed for any issues Once the quality sub-agent finishes: @@ -92,6 +75,9 @@ Once the quality sub-agent finishes: this agent may report INCOMPLETE when the request cannot be implemented without information only the user can provide. +For full planning details (assumptions, risks, feasibility), read the planning +report file referenced in the planning agent's response. + Generate the completion report using the template below, then save it to `.agent-logs/{agent-name}-{subject}-{unique-id}.md` per the AGENTS.md reporting requirements, and return the summary to the caller. @@ -102,19 +88,20 @@ requirements, and return the summary to the caller. # Implementation Orchestration Report **Result**: (SUCCEEDED|FAILED|INCOMPLETE) -**Final State**: (PLANNING|DEVELOPMENT|QUALITY|REPORT) +**Report**: `.agent-logs/implementation-{subject}-{unique-id}.md` +**Last Active State**: (PLANNING|DEVELOPMENT|QUALITY) **Retry Count**: ## State Machine Execution -- **Planning Results**: {Implementation plan, assumption ratings, risks, and recommendation} +- **Planning Results**: {Planning report path; plan summary and SUCCEEDED/INCOMPLETE/FAILED result} - **Development Results**: {Summary of developer agent results} - **Quality Results**: {Summary of quality agent results} - **State Transitions**: {Log of state changes and decisions} ## Sub-Agent Coordination -- **Explore Agent (Planning)**: {Plan, assumption verdicts, top risks, GO/INCOMPLETE recommendation} +- **Planning Agent**: {Report file path, SUCCEEDED/INCOMPLETE/FAILED result, plan summary} - **Developer Agent**: {Development status and files modified} - **Quality Agent**: {Validation results and compliance status} @@ -123,4 +110,9 @@ requirements, and return the summary to the caller. - **Implementation Success**: {Overall completion status} - **Quality Compliance**: {Final quality validation status} - **Issues Resolved**: {Problems encountered and resolution attempts} + +## Unknowns (only when Result is INCOMPLETE) + +- **Unresolved Questions**: {List each question the user must answer} +- **What Can Proceed**: {Work that can be done without the missing information} ``` diff --git a/.github/agents/lint-fix.agent.md b/.github/agents/lint-fix.agent.md index 549e751..36d3ca1 100644 --- a/.github/agents/lint-fix.agent.md +++ b/.github/agents/lint-fix.agent.md @@ -68,8 +68,7 @@ submission, not during normal development. # Lint Fix Report **Result**: (SUCCEEDED|FAILED) - -## Summary +**Report**: `.agent-logs/lint-fix-{subject}-{unique-id}.md` - **Iterations**: {Number of fix-loop iterations performed} - **Files Modified**: {List of all files changed} diff --git a/.github/agents/planning.agent.md b/.github/agents/planning.agent.md new file mode 100644 index 0000000..20e75ee --- /dev/null +++ b/.github/agents/planning.agent.md @@ -0,0 +1,134 @@ +--- +name: planning +description: Planning agent that investigates the codebase, develops a verified implementation plan, and identifies all companion artifact deliverables. +user-invocable: true +--- + +# Planning Agent + +Investigate the codebase and produce a verified implementation plan with all +companion artifact deliverables. + +## Step 1 — Load Standards + +Read the relevant standards from `.github/standards/` using the selection matrix +in `AGENTS.md` based on the artifact types in scope for the request (requirements, +design, verification, documentation, code). + +## Step 2 — Investigate and Plan + +Read `docs/design/introduction.md` first (if present), then investigate the +codebase to develop a concrete implementation plan: + +- Identify all files to create, modify, or delete +- Describe the change required for each file + +## Step 3 — Identify Companion Artifact Deliverables + +For each planned change, assess the mandatory companion artifacts below (create/update/N/A +with justification): + +- **Requirements** — functional changes require a requirement entry +- **Design Documentation** — new or changed components require design docs +- **Verification Documentation** — new or changed components require verification docs +- **Tests** — functional changes require test coverage +- **Review Sets** — changes to the software item hierarchy (units or subsystems + added, removed, or reorganized) require review-set updates +- **README.md** — user-facing changes require README updates +- **User Guide** — user-facing features require user guide updates + +## Step 4 — Critique and Strengthen + +Identify up to 5 key assumptions and rate each: + +- **VERIFIED**: confirmed by codebase evidence +- **LIKELY**: consistent with codebase patterns but not directly confirmed +- **UNVERIFIED**: not confirmed by any evidence + +For UNVERIFIED or LIKELY assumptions, investigate further and revise the plan. +Repeat up to 2 more times, stopping when the plan is stable. + +## Step 5 — Risk Assessment + +List up to 5 risks with a brief mitigation for each. + +## Step 6 — Feasibility Assessment + +State whether this can be implemented in a single development pass and any +preconditions that affect feasibility. + +## Step 7 — Recommendation + +- **SUCCEEDED** — the plan is sound and the developer agent can proceed +- **INCOMPLETE** — critical unknowns remain that only the user can resolve; + list each unknown explicitly +- **FAILED** — investigation could not produce a viable plan + +# REPORT Phase + +Save the full analysis to `.agent-logs/planning-{subject}-{unique-id}.md` per +the AGENTS.md reporting requirements. + +Then respond to the caller with ONLY the lean structured summary below. + +# Report Template + +```markdown +# Planning Report + +**Result**: (SUCCEEDED|INCOMPLETE|FAILED) +**Request Summary**: {Brief restatement of the task as understood} +**Report**: `.agent-logs/planning-{subject}-{unique-id}.md` + +## Implementation Plan + +| File | Action | Description | +|------|--------|-------------| +| {path} | create/modify/delete | {what changes and why} | + +## Companion Artifact Deliverables + +| Category | File | Action | +|----------|------|--------| +| Requirements | {path} | create/update/N/A — {justification} | +| Design Documentation | {path} | create/update/N/A — {justification} | +| Verification Documentation | {path} | create/update/N/A — {justification} | +| Tests | {path} | create/update/N/A — {justification} | +| Review Sets | {path} | create/update/N/A — {justification} | +| README.md | {path} | create/update/N/A — {justification} | +| User Guide | {path} | create/update/N/A — {justification} | + +## Assumption Analysis + +| # | Assumption | Rating | Resolution | +|---|-----------|--------|------------| +| 1 | {assumption} | VERIFIED/LIKELY/UNVERIFIED | {resolution or N/A} | + +## Risk Assessment + +1. **[severity]** {risk} — {mitigation} + +## Feasibility Assessment + +{Single-pass or not, and why. Any preconditions.} + +## Unknowns + +{Only present when Result is INCOMPLETE. List each question the user must +resolve before implementation can proceed.} +``` + +# Lean Structured Response (returned to caller) + +```markdown +**Result**: (SUCCEEDED|INCOMPLETE|FAILED) +**Report**: `.agent-logs/planning-{subject}-{unique-id}.md` + +**Plan**: +{Repeat the Implementation Plan table} + +**Companion Artifacts**: +{Repeat the Companion Artifact Deliverables table} + +**Unknowns**: {Only if INCOMPLETE — list questions for the user} +``` diff --git a/.github/agents/quality.agent.md b/.github/agents/quality.agent.md index 380d11f..26fd251 100644 --- a/.github/agents/quality.agent.md +++ b/.github/agents/quality.agent.md @@ -13,14 +13,23 @@ Grade and validate software development work by ensuring compliance with project 1. **Analyze the task request AND completed work** to determine scope: identify which artifact categories were changed, and which *should have been changed* given the task - new user-visible features always require requirements, - design, and review-set coverage regardless of whether those files were touched; - test-only additions (corner-case tests, defensive boundary tests, regression - tests) do not require a corresponding requirement + design, verification docs, and README/user guide updates regardless of + whether those files were touched; Review Sets are always in scope when + the software item hierarchy changes (units or subsystems added, removed, or + reorganized); test-only additions (corner-case tests, defensive boundary + tests, regression tests) do not require a corresponding requirement; if a + planning companion artifact table is provided in context, cross-reference it + — any artifact listed as create/update must be covered in the evaluation and + FAIL if the artifact was not produced 2. **Read relevant standards** using the selection matrix in AGENTS.md 3. **Evaluate all in-scope categories** - N/A only when the task genuinely cannot affect a category; if the task introduces new user-visible features or - structural changes then Requirements, Design Documentation, and Review - Management are always in scope and FAIL if the artifacts were not updated + structural changes then Requirements, Design Documentation, and Verification + Documentation are always in scope and FAIL if the artifacts were not updated; + Documentation (README/user guide) is always in scope for user-facing changes + and FAIL if not updated; Review Sets are always in scope when the + software item hierarchy changes (units or subsystems added, removed, or + reorganized) and FAIL if review-sets were not updated 4. **Validate tool compliance** using ReqStream, ReviewMark, and build tools 5. **Generate focused quality report** per the AGENTS.md reporting requirements - save to `.agent-logs/{agent-name}-{subject}-{unique-id}.md` and return the summary to the caller @@ -36,6 +45,7 @@ For each checklist item in the template below, record as `(PASS|FAIL|N/A) - {one # Quality Assessment Report **Result**: (SUCCEEDED|FAILED) +**Report**: `.agent-logs/quality-{subject}-{unique-id}.md` **Overall Grade**: (PASS|FAIL) ## Required Fixes (only when Result is FAILED) @@ -50,13 +60,13 @@ Priority-ordered list of issues that MUST be resolved for the next retry: - **Evaluated**: {List sections assessed and why} - **Skipped**: {One-line per skipped section with reason, e.g., "Design - Documentation: N/A - no design files modified"} + Documentation: N/A - no component behavior, structure, or interface changed"} ## Requirements Compliance: (PASS|FAIL|N/A) - Were requirements created/updated for all functional changes? - Were source filters applied for platform-specific requirements? -- Is requirements traceability maintained to tests? +- Is forward traceability from requirements to verification artifacts preserved? ## Design Documentation Compliance: (PASS|FAIL|N/A) @@ -80,7 +90,14 @@ Priority-ordered list of issues that MUST be resolved for the next retry: - Are cross-hierarchy test dependencies documented in design docs? - Do all tests pass? -## Review Management Compliance: (PASS|FAIL|N/A) +## Verification Documentation Compliance: (PASS|FAIL|N/A) + +- Were verification documents created/updated for all new or changed components? +- Do verification documents include all mandatory sections (Verification Approach, Test Environment, + Acceptance Criteria, Test Scenarios)? +- Is requirements-to-test coverage tracked via the ReqStream trace matrix (not embedded in verification docs)? + +## Review Sets Compliance: (PASS|FAIL|N/A) - Were review-sets updated for structural changes? - Is review scope appropriate for change magnitude? diff --git a/.github/agents/template-sync.agent.md b/.github/agents/template-sync.agent.md index c013503..baf5fa8 100644 --- a/.github/agents/template-sync.agent.md +++ b/.github/agents/template-sync.agent.md @@ -21,13 +21,21 @@ Delegate each group to a sub-agent. # Work Groups - **Root config files** - all non-collection files at the repository root +- **`docs/sysml2/`** - SysML2 model files and rendered views (root-level flat folder, + not a Pandoc collection) - **One group per flat `docs/` folder** - e.g. `docs/build_notes/`, `docs/user_guide/` +- **One group for root files in each of `docs/design/`, `docs/verification/`, + `docs/reqstream/`** - e.g. `docs/design/introduction.md` — separate from the + system subtrees beneath them - **One group per system subtree** in `docs/design/`, `docs/verification/`, `docs/reqstream/` - each subtree and all its descendants is one group # Orchestration -For each group intersecting the requested scope, call a sub-agent with: +For Audit mode, call an **explore** sub-agent (built-in) per group. +For Sync, Scaffold, and Recreate modes, call a **general-purpose** sub-agent (built-in) per group. + +For each group intersecting the requested scope, call the appropriate sub-agent with: - **context**: - Group scope and template URL from the `# Reference Template` section in `AGENTS.md` @@ -40,7 +48,10 @@ For each group intersecting the requested scope, call a sub-agent with: each item is a subsystem or unit, then select the appropriate template (`subsystem-name.*` or `unit-name.*`) regardless of the item's folder depth — do not infer item type from path depth alone - - If a template counterpart cannot be fetched, skip the file and report it + - If a file has no template counterpart, skip it and report it as + "No template found" — this is not a failure + - If a file appears in `repository-map.md` but its template cannot be fetched, + report Result: FAILED and list the affected files - **goal**: - Based on the given mode: - **Audit** - fetch each template counterpart; compare headings; report missing @@ -78,9 +89,25 @@ For each group intersecting the requested scope, call a sub-agent with: `TODO:` placeholders in YAML string values (e.g. `title:`, `justification:`) are content placeholders — always resolve them to real content; infer from README, related files, sibling docs, and path; if confident write directly; - if ambiguous offer 2–3 concrete options and ask the user; keep asking until - they answer - never leave a TODO or TEMPLATE-DIRECTIVE in the output unless - the user explicitly requests it + if ambiguous, **do not ask interactively** — return the unresolved questions + in the result so the orchestrator can ask the user and re-invoke; never leave + a TODO or TEMPLATE-DIRECTIVE in the output unless the user explicitly requests it + - Return results in this format for each file in the group: + + ```markdown + ### {file-path} + + - **Template**: {template path or "not found"} + - **Missing sections**: {list or "none"} + - **Heading depth issues**: {list or "none"} + - **Content format issues**: {list or "none"} *(Recreate only)* + - **Action**: (Reported | Sections added | Created | Rebuilt | No template found) + - **Unresolved Questions**: {list or "none"} + ``` + +If any sub-agent returns unresolved questions, collect them, ask the user, then +re-invoke the affected sub-agent(s) with the answers before assembling the final report. +If questions remain unresolved after asking the user, report Result: INCOMPLETE. Collect sub-agent results and assemble the final report. @@ -89,7 +116,8 @@ Collect sub-agent results and assemble the final report. ```markdown # Template Sync Report -**Result**: (SUCCEEDED|FAILED) +**Result**: (SUCCEEDED|FAILED|INCOMPLETE) +**Report**: `.agent-logs/template-sync-{subject}-{unique-id}.md` **Mode**: (Audit|Sync|Scaffold|Recreate) ## Files @@ -102,8 +130,13 @@ Collect sub-agent results and assemble the final report. - **Content format issues**: {list of sections where intra-section content did not match the template comment's prescribed format, or "none"} *(Recreate only)* - **Action**: (Reported | Sections added | Created | Rebuilt | No template found) +- **Unresolved Questions**: {list or "none"} ## Summary - **Conformant**: {count} | **Deviations**: {count} | **Updated**: {count} + +## Unknowns (only when Result is INCOMPLETE) + +- **Unresolved Questions**: {List each placeholder or ambiguity the user must resolve} ``` diff --git a/.github/skills/sysml2tools-query/SKILL.md b/.github/skills/sysml2tools-query/SKILL.md new file mode 100644 index 0000000..f754338 --- /dev/null +++ b/.github/skills/sysml2tools-query/SKILL.md @@ -0,0 +1,145 @@ +--- +name: sysml2tools-query +description: Query this repository's SysML2 architecture model (docs/sysml2/) to understand software structure, purpose, and relationships before deep-diving into source code. Use this when asked to understand the codebase, find which unit implements something, assess the impact of a change, or trace requirements to code. +--- + +# SysML2Tools Query Skill + +This repository models its software structure in SysML2 under `docs/sysml2/`. Prefer +querying this model over grepping/reading source files when you need to understand +*what* a piece of the system is, *why* it exists, or *what it depends on*. + +## Prerequisites + +The `sysml2tools` CLI is a local .NET tool pinned in `.config/dotnet-tools.json`. +Restore it once per session if not already available: + +```pwsh +dotnet tool restore +``` + +## Model files + +- `docs/sysml2/model/{system-name}.sysml` — system-level `part def` only (no subsystems/units + inline). A repository may contain more than one system. +- `docs/sysml2/model/{system-name}/{subsystem-name}.sysml` and + `docs/sysml2/model/{system-name}/{subsystem-name}/{unit-name}.sysml` — one file per + Subsystem/Unit, nested to mirror the same folder depth as that item's companion + `docs/design/`, `docs/reqstream/`, and `docs/verification/` files. +- `docs/sysml2/model/ots.sysml` — off-the-shelf (OTS) dependency parts (present when OTS items + exist). +- `docs/sysml2/model/shared.sysml` — Shared Package parts (present when Shared Package items + exist). +- `docs/sysml2/views/design-views.sysml` — named views rendered for the design document; a + sibling of `model/`, not nested inside it. Not usually needed for query workflows, but + useful to see how diagrams are scoped. + +Always pass all `.sysml` files (or a glob covering them) to every `sysml2tools` +invocation — the model spans multiple files and cross-references between them; files that +reopen the same `package Name { ... }` from different files merge into one namespace +automatically, no `import` required. As of `sysml2tools` 0.1.0-beta.5, every subcommand +(`lint`, `render`, `query`) expands `*`/`**` glob patterns internally and recurses +correctly — pass a single **quoted** glob string and let the tool resolve it, rather than +relying on the shell (quoting works identically in both PowerShell and bash): + +```pwsh +dotnet sysml2tools query list 'docs/sysml2/model/**/*.sysml' +``` + +## Artifact-location metadata + +Every System/Subsystem/Unit `part def` carries named `comment` elements pointing at its +companion artifacts (source, test, design, verification, and — for repositories that still +use ReqStream — requirements file). `query describe` returns every comment attached to +an element, so one query gets you every artifact location for that item without grepping the +source tree: + +```pwsh +dotnet sysml2tools query describe -e {SystemName}::{UnitName} 'docs/sysml2/model/**/*.sysml' +``` + +```text +- Documentation: One-line purpose statement for the unit. +- Comment: Source: src/{Project}/{Subsystem}/{UnitName}.cs +- Comment: Test: test/{Project}.Tests/{Subsystem}/{UnitName}Tests.cs +- Comment: Design: docs/design/{system-name}/{subsystem-name}/{unit-name}.md +- Comment: Verification: docs/verification/{system-name}/{subsystem-name}/{unit-name}.md +- Comment: Requirements: docs/reqstream/{system-name}/{subsystem-name}/{unit-name}.yaml +``` + +Not every item has all five comments — Systems/Subsystems have no `Source` comment, and +units without a dedicated companion doc point at their parent's doc instead (see the +Artifact-Location Comments section of `sysml2-modeling.md` for the full rules). Prefer these +paths over guessing a file location from the unit name; fall back to `grep`/`glob` only when +a comment is missing or the model is stale. + +## Recommended workflow + +1. **Discover the system(s) present** — do not assume a fixed name: + + ```pwsh + dotnet sysml2tools query list --kind "part def" 'docs/sysml2/model/**/*.sysml' + ``` + + Look for the top-level part def with no containing part (or the one with the most + children) to identify each system's qualified name. + +2. **Get the full hierarchy** (subsystems and units) for a system found above: + + ```pwsh + dotnet sysml2tools query describe -e 'docs/sysml2/model/**/*.sysml' + ``` + + `describe` lists direct children and every artifact-location comment; repeat on each + child to walk deeper, or use `query list` to see the full flat inventory. + +3. **Understand a specific unit's purpose and find its files** before opening its source + file — `describe` returns both the purpose `doc` and every `Comment:` artifact-location + line in one call (see Artifact-location metadata above): + + ```pwsh + dotnet sysml2tools query describe -e 'docs/sysml2/model/**/*.sysml' + ``` + +4. **Assess impact before editing a unit** — see what depends on it: + + ```pwsh + dotnet sysml2tools query used-by -e 'docs/sysml2/model/**/*.sysml' + dotnet sysml2tools query impact -e 'docs/sysml2/model/**/*.sysml' + ``` + + Note: this only surfaces structural (typing/containment) references modeled in + `.sysml` — not full call-graph/behavioral dependencies. Confirm actual usage in source + before making impact-sensitive changes. + +5. **Trace requirements** linked to a unit, if modeled: + + ```pwsh + dotnet sysml2tools query requirements -e 'docs/sysml2/model/**/*.sysml' + ``` + +6. **Search by name or kind** when the qualified name is unknown: + + ```pwsh + dotnet sysml2tools query find --name 'docs/sysml2/model/**/*.sysml' + dotnet sysml2tools query list --kind "part def" 'docs/sysml2/model/**/*.sysml' + ``` + +Use `--format json` on any query verb for machine-parsed output. + +## Fallback + +If the model is stale, doesn't yet cover a unit, or a query returns nothing useful, fall +back to `grep`/`glob`/reading source directly. When you finish work that adds or changes a +Unit/Subsystem, update the corresponding `.sysml` model file (including its artifact-location +comments) in the same change (mirrors the existing requirement to keep `docs/design/*.md` and +`docs/reqstream/*.yaml` companion artifacts in sync). See the `sysml2-modeling.md` +standard for full modeling and view-authoring conventions. + +## Validating changes to the model + +Before committing changes to any `.sysml` file, lint it: + +```pwsh +dotnet sysml2tools lint 'docs/sysml2/**/*.sysml' +``` diff --git a/.github/standards/design-documentation.md b/.github/standards/design-documentation.md index e5b7bf9..c6f107f 100644 --- a/.github/standards/design-documentation.md +++ b/.github/standards/design-documentation.md @@ -8,6 +8,8 @@ globs: ["docs/design/**/*.md"] - **`technical-documentation.md`** - General technical documentation standards - **`software-items.md`** - Software categorization (System/Subsystem/Unit/OTS/Shared Package) +- **`sysml2-modeling.md`** - SysML2 model and view conventions feeding the Software Structure + section # Folder Structure @@ -30,7 +32,6 @@ docs/design/ All sections in every file are mandatory; write "N/A - {justification}" rather than removing any. Determine subsystem vs. unit classification from `docs/design/introduction.md` — folder depth does not determine classification. -Do not record version numbers anywhere in design documentation — version information is managed in SBOMs. # introduction.md (MANDATORY) @@ -38,7 +39,8 @@ Must include: - **Purpose**: audience and compliance drivers - **Scope**: items covered and explicitly excluded (no test projects) -- **Software Structure**: text tree showing all Systems/Subsystems/Units/OTS/Shared items +- **Software Structure**: diagram(s) rendered from the SysML2 model under `docs/sysml2/`, + per `sysml2-modeling.md` — not a hand-maintained text tree - **Folder Layout**: text tree showing source folder structure - **Companion Artifact Structure**: parallel paths for requirements, design, verification, source, tests - **References** _(if applicable)_: external standards or specifications - only in `introduction.md` @@ -98,6 +100,12 @@ For each Shared Package, create `docs/design/shared/{package-name}.md` (`##` hea - Use Mermaid diagrams to supplement (not replace) text - Use verbal cross-references ("see _Parser Design_") - not markdown hyperlinks (break in PDF) - Provide sufficient detail for formal code review +- Do not record version numbers in design documentation — they go stale with dependency updates and + are managed in SBOMs. Version numbers are pinned release versions (e.g., `1.2.3`, `v2.0.1`). + The following are **not** version numbers and are permitted: + - Language/platform standards: `netstandard2.0`, `net10.0`, `C++20`, `C# 12` (stable standard identifiers) + - Protocol standards: `TLS 1.3`, `HTTP/2` (stable specifications) + - Placeholders: `0.0.0` (signals "not yet assigned") # Quality Checks diff --git a/.github/standards/reviewmark-usage.md b/.github/standards/reviewmark-usage.md index b521433..bc73da6 100644 --- a/.github/standards/reviewmark-usage.md +++ b/.github/standards/reviewmark-usage.md @@ -21,71 +21,86 @@ review, organizes them into review-sets, and generates review plans and reports. - **Lint Configuration**: `dotnet reviewmark --lint` - **Elaborate Review-Set**: `dotnet reviewmark --elaborate {review-set}` - **Generate Plan**: `dotnet reviewmark --plan docs/code_review_plan/generated/plan.md --enforce` - -> **Note**: `--enforce` causes the plan to fail with a non-zero exit code if any repository -> files are not covered by a review-set. Uncovered files indicate a gap in review-set -> configuration that should be addressed. + (exits non-zero if any files are uncovered) ## Repository Structure -Required repository items for ReviewMark operation: - - `.reviewmark.yaml` - Configuration for review-sets, file-patterns, and review evidence-source. -- `docs/code_review_plan/generated/` - Generated review plan (build output, do not edit) -- `docs/code_review_report/generated/` - Generated review report (build output, do not edit) # Review Definition Structure Configure reviews in `.reviewmark.yaml` at repository root: ```yaml -# Patterns identifying all files that require review needs-review: - # Include source code (adjust file extensions for your repo) - - "**/*.cs" # C# source files - - "**/*.cpp" # C++ source files - - "**/*.hpp" # C++ header files - - "!**/bin/**" # Generated source in build outputs - - "!**/obj/**" # Generated source in build intermediates - - # Include requirement files - - "requirements.yaml" # Root requirements file - - "docs/reqstream/**/*.yaml" # Requirements files - - # Include critical documentation files - - "README.md" # Root level README - - "docs/user_guide/**/*.md" # User guide - - "docs/design/**/*.md" # Design documentation - - "docs/verification/**/*.md" # Verification design documentation - -# Source of review evidence + - "**/*.cs" + - "**/*.cpp" + - "**/*.hpp" + - "!**/bin/**" + - "!**/obj/**" + - "requirements.yaml" + - "docs/reqstream/**/*.yaml" + - "docs/sysml2/**/*.sysml" + - "README.md" + - "docs/user_guide/**/*.md" + - "docs/design/**/*.md" + - "docs/verification/**/*.md" + evidence-source: type: none -# Review-sets (each focuses on a single compliance question) +context: + - docs/design/introduction.md + reviews: - id: Purpose - title: Review of user-facing capabilities and system promises + title: Review that README and User Guide are Coherent and Complete paths: - "README.md" - "docs/user_guide/**/*.md" - - "docs/reqstream/{system-name}.yaml" + - id: Decomposition + title: Review that {SystemName} Decomposition Addresses the Stated Purpose + context: + - "README.md" + - "docs/user_guide/**/*.md" + paths: + - "requirements.yaml" - "docs/design/introduction.md" - - "docs/design/{system-name}.md" ``` -# Review-Set Design Principles +For a complete annotated example with template directives, see `.reviewmark.yaml` in the +reference template (`{template-url}/.reviewmark.yaml` per `AGENTS.md`). -When constructing review-sets, follow these principles to maintain manageable scope and effective compliance evidence: +# Review-Set Design Principles - **Hierarchical Scope**: Higher-level reviews exclude lower-level implementation details, relying instead on design documents to describe what components they use. System reviews exclude subsystem/unit details, subsystem reviews exclude unit source code, only unit reviews include actual implementation. - **Single Focus**: Each review-set proves one specific compliance question (user promises, system architecture, design consistency, etc.) +- **Parent Context**: Unit and subsystem reviews include parent design and requirements as + context so reviewers understand the intended role and scope; see the Context Files section. - **Context Management**: Keep file counts manageable to prevent context overflow while maintaining complete coverage through the hierarchy +# Context Files + +Context files are shown to reviewers for orientation but not fingerprinted. Add a top-level +`context:` key for global context (every reviewer) and a per-review-set `context:` between +`title:` and `paths:` for review-specific context. Always include `docs/design/introduction.md` +as global context. + +| Review Type | Context to add | +| :---------- | :------------- | +| `Decomposition` | `README.md`, `docs/user_guide/**/*.md` | +| `{SystemName}-Architecture` | `README.md`, `docs/user_guide/**/*.md` | +| `{SystemName}-Design` | `docs/reqstream/{system-name}.yaml` | +| `{SystemName}-Verification` | `docs/reqstream/{system-name}.yaml` | +| `{SystemName}-AllRequirements` | Parent system design doc + `docs/reqstream/{system-name}.yaml` | +| `{SystemName}-{UnitName}` (direct unit) | Parent system design doc + parent system requirements | +| `{SystemName}-{SubsystemName}` (subsystem) | Parent system design doc + parent system requirements | +| `{SystemName}-{SubsystemName}-{UnitName}` (unit under subsystem) | System + subsystem design docs + requirements | + # Review-Set Organization **Naming conventions**: Placeholders in documentation, requirements, design, and @@ -96,23 +111,30 @@ placeholders are always PascalCase (e.g., `{SystemName}`). ## `Purpose` Review (only one per repository) -Reviews user-facing capabilities and system promises: - -- **Purpose**: Proves that the systems provide the capabilities the user is being told about -- **Title**: "Review that Advertised Features Match System Design" -- **Scope**: Excludes subsystem and unit files, relying on system-level design documents - to describe what subsystems and units they use +- **Purpose**: Proves that the user-facing docs are coherent and complete — the north-star for the hierarchy +- **Title**: "Review that README and User Guide are Coherent and Complete" +- **ID**: `Purpose` (no system prefix — one per repository) +- **Scope**: README and user_guide only; no requirements or design files - **File Path Patterns**: - README: `README.md` - User guide: `docs/user_guide/**/*.md` - - System requirements: `docs/reqstream/{system-name}.yaml` + +## `Decomposition` Review (only one per repository) + +- **Purpose**: Proves that the software items tree breakdown logically addresses the user-facing + promise; the structural mirror of the decomposition decision +- **Title**: "Review that {SystemName} Decomposition Addresses the Stated Purpose" +- **ID**: `Decomposition` (no system prefix — one per repository) +- **Scope**: introduction.md (the decomposition narrative), the SysML2 model (the + authoritative structural tree), and requirements.yaml; no system-level detail +- **File Path Patterns**: + - Root requirements: `requirements.yaml` - Design introduction: `docs/design/introduction.md` - - System design: `docs/design/{system-name}.md` + - SysML2 model: `docs/sysml2/**/*.sysml` +- **Context Files**: `README.md`, `docs/user_guide/**/*.md` ## `{SystemName}-Architecture` Review (one per system) -Reviews system architecture and operational validation: - - **Purpose**: Proves that the system is designed and tested to satisfy its requirements - **Title**: "Review that {SystemName} Architecture Satisfies Requirements" - **Scope**: Excludes subsystem and unit files, relying on system-level design to describe @@ -124,16 +146,15 @@ Reviews system architecture and operational validation: - Verification introduction: `docs/verification/introduction.md` - System verification design: `docs/verification/{system-name}.md` - System integration tests: `test/{SystemName}.Tests/{SystemName}Tests.{ext}` +- **Context Files**: `README.md`, `docs/user_guide/**/*.md` ## `{SystemName}-Design` Review (one per system) -Reviews architectural and design consistency: - - **Purpose**: Proves the system design is consistent and complete - **Title**: "Review that {SystemName} Design is Consistent and Complete" - **Scope**: Only brings in top-level requirements and relies on brevity of design documentation +- **Context Files**: `docs/reqstream/{system-name}.yaml` - **File Path Patterns**: - - System requirements: `docs/reqstream/{system-name}.yaml` - Platform requirements: `docs/reqstream/{system-name}/platform-requirements.yaml` - Design introduction: `docs/design/introduction.md` - System design: `docs/design/{system-name}.md` @@ -143,13 +164,11 @@ Reviews architectural and design consistency: ## `{SystemName}-Verification` Review (one per system) -Reviews verification completeness and consistency: - - **Purpose**: Proves the system verification design is consistent and covers all requirements - **Title**: "Review that {SystemName} Verification is Consistent and Complete" - **Scope**: Only brings in top-level requirements and all verification docs for the system +- **Context Files**: `docs/reqstream/{system-name}.yaml` - **File Path Patterns**: - - System requirements: `docs/reqstream/{system-name}.yaml` - Verification introduction: `docs/verification/introduction.md` - System verification: `docs/verification/{system-name}.md` - System verification files: `docs/verification/{system-name}/**/*.md` @@ -158,20 +177,15 @@ Reviews verification completeness and consistency: ## `{SystemName}-AllRequirements` Review (one per system) -Reviews requirements quality and traceability: - - **Purpose**: Proves the requirements are consistent and complete - **Title**: "Review that All {SystemName} Requirements are Complete" - **Scope**: Only brings in requirements files to keep review manageable - **File Path Patterns**: - - Root requirements: `requirements.yaml` - - System requirements: `docs/reqstream/{system-name}.yaml` - Subsystem/unit requirements: `docs/reqstream/{system-name}/**/*.yaml` +- **Context Files**: `docs/design/{system-name}.md`, `docs/reqstream/{system-name}.yaml` ## `{SystemName}-{SubsystemName}[-{SubsystemName}...]` Review (one per subsystem at any depth) -Reviews subsystem architecture and interfaces: - - **Purpose**: Proves that the subsystem is designed and tested to satisfy its requirements - **Title**: "Review that {SystemName} {SubsystemName} Satisfies Subsystem Requirements" - **Scope**: Excludes units under the subsystem, relying on subsystem design to describe @@ -181,11 +195,10 @@ Reviews subsystem architecture and interfaces: - Design: `docs/design/{system-name}[/{subsystem-name}...]/{subsystem-name}.md` - Verification design: `docs/verification/{system-name}[/{subsystem-name}...]/{subsystem-name}.md` - Tests: `test/{SystemName}.Tests[/{SubsystemName}...]/{SubsystemName}Tests.{ext}` +- **Context Files**: `docs/design/{system-name}.md`, `docs/reqstream/{system-name}.yaml` ## `{SystemName}-{SubsystemName}[-{SubsystemName}...]-{UnitName}` Review (one per unit) -Reviews individual software unit implementation: - - **Purpose**: Proves the unit is designed, implemented, and tested to satisfy its requirements - **Title**: "Review that {SystemName} {SubsystemName} {UnitName} Implementation is Correct" - **Scope**: Complete unit review including all artifacts @@ -197,11 +210,11 @@ Reviews individual software unit implementation: - Tests (C# example): `test/{SystemName}.Tests[/{SubsystemName}...]/{UnitName}Tests.cs` - Source (snake_case C++ example): `src/{system_name}[/{subsystem_name}...]/{unit_name}.cpp` - Tests (snake_case C++ example): `test/{system_name}_tests[/{subsystem_name}...]/{unit_name}_tests.cpp` +- **Context Files**: Parent system design + requirements; add subsystem design + + requirements for each subsystem level above the unit. ## `OTS-{OtsName}` Review (one per OTS item) -Reviews OTS item integration design, requirements, and verification evidence: - - **Purpose**: Proves that the OTS item provides the required functionality and is correctly integrated - **Title**: "Review that {OtsName} Provides Required Functionality" - **Scope**: No local source code; review covers integration design, requirements, and verification evidence @@ -214,8 +227,6 @@ Reviews OTS item integration design, requirements, and verification evidence: ## `Shared-{PackageName}` Review (one per Shared Package) -Reviews Shared Package integration design, requirements, and verification evidence: - - **Purpose**: Proves that the Shared Package provides the required advertised features and is correctly integrated - **Title**: "Review that {PackageName} Provides Required Features" - **Scope**: No local source code; review covers integration design, requirements, and verification evidence @@ -229,10 +240,9 @@ extensions (`.cs`, `.cpp`/`.hpp`, `.py`, etc.). Adapt to your repository's langu # Quality Checks -Before submitting ReviewMark configuration, verify: - - [ ] `.reviewmark.yaml` exists at repository root with proper structure - [ ] Review-set organization follows the standard hierarchy patterns - [ ] Each review-set focuses on a single compliance question (single focus principle) - [ ] File patterns use correct glob syntax and match intended files - [ ] Review-set file counts remain manageable (context management principle) +- [ ] Context configured per the Context Files section diff --git a/.github/standards/software-items.md b/.github/standards/software-items.md index 6c29525..3514228 100644 --- a/.github/standards/software-items.md +++ b/.github/standards/software-items.md @@ -130,3 +130,8 @@ the item is correct, well-designed, and proven to work: - **Verification Design** - HOW the requirements will be tested (applies to all item types) - **Source code** - The implementation of the design (local units only; not applicable to OTS or Shared Package) - **Tests** - PROOF the item does WHAT it is required to do (applies to all item types) + +Where the repository models its software structure in SysML2, each item's part def carries +`comment` metadata pointing at these same artifact locations (`sourceRef`/`testRef`/ +`designRef`/`verificationRef`/`reqRef`) so agents can query them directly — see +`sysml2-modeling.md`. diff --git a/.github/standards/sysml2-modeling.md b/.github/standards/sysml2-modeling.md new file mode 100644 index 0000000..c5558e1 --- /dev/null +++ b/.github/standards/sysml2-modeling.md @@ -0,0 +1,232 @@ +--- +name: SysML2 Modeling +description: Follow these standards when creating or modifying the SysML2 architecture + model, its rendered views, or the software structure it feeds into design documentation. +globs: ["docs/sysml2/**/*.sysml"] +--- + +# SysML2 Modeling Standard + +## Required Standards + +Read these standards first before applying this standard: + +- **`software-items.md`** - Software categorization (System/Subsystem/Unit/OTS/Shared Package) +- **`design-documentation.md`** - Design document structure that embeds the diagrams this + standard produces + +## Purpose + +The repository's software structure is modeled in SysML2 under `docs/sysml2/` rather than +hand-maintained as prose or an ASCII tree. The model is the authoritative, machine-queryable +source of structure; rendered diagrams and `docs/design/introduction.md`'s narrative are +generated/derived artifacts. AI agents should query the model (see `sysml2tools-query` +skill) before deep-diving into source code to understand what a piece of the system is, +why it exists, and what it depends on. + +## Repository Structure + +```text +docs/sysml2/ +├── model/ +│ ├── {system-name}.sysml # system-level part def only (no subsystems/units inline) +│ ├── {system-name}/ +│ │ ├── {subsystem-name}.sysml # subsystem part def; nests further for sub-subsystems +│ │ └── {subsystem-name}/ +│ │ └── {unit-name}.sysml # one file per unit +│ ├── ots.sysml # OTS dependency parts (optional; if OTS items exist) +│ └── shared.sysml # Shared Package parts (optional; if Shared Packages exist) +└── views/ + └── design-views.sysml # named view usages rendered for the design document +``` + +`docs/sysml2/model/` mirrors the same folder shape as `docs/design/`, `docs/reqstream/`, and +`docs/verification/` — one `.sysml` file per System/Subsystem/Unit, at the same nesting depth +as that item's companion design/requirements/verification files. This keeps each file small +and keeps PRs that touch one unit's model from producing unrelated diffs in unrelated units. +`docs/sysml2/views/` is a sibling of `model/`, not nested inside it, so a single +`docs/sysml2/model/**/*.sysml` glob never needs to exclude view files (`sysml2tools` has no +exclude-glob syntax). + +There is no separate "stable entry point" file — a repository may contain multiple systems, +so no single alias name would generalize. Agents discover the system(s) present by running +`query list --kind "part def"` or `query find` (see the `sysml2tools-query` skill) over +`docs/sysml2/model/**/*.sysml`, not by assuming a fixed name. + +Always pass the full set of `.sysml` files (or an equivalent glob) to every `sysml2tools` +invocation — the model spans multiple files and cross-references between them; files sharing +the same `package Name { ... }` merge into one namespace automatically with no `import` +required, as long as all files are passed together. As of `sysml2tools` 0.1.0-beta.5, +`lint` and `render` both expand `*`/`**` glob patterns internally (recursing correctly into +subdirectories), so pass a single **quoted** glob string (e.g. `'docs/sysml2/**/*.sysml'`) +and let the tool resolve it — do not rely on the shell to expand it, and do not quote-strip +the pattern before it reaches the tool. Quoting keeps the behavior identical across +PowerShell and bash, since neither shell needs to (or reliably does) expand `**` itself. + +## Model Content + +- `{system-name}.sysml` defines one `part def` for the System only, with `part` usages + referencing its direct Subsystems/Units (defined in their own files, see below). +- Each `{subsystem-name}.sysml` / `{unit-name}.sysml` defines exactly one `part def`, with a + `doc /* ... */` comment stating its purpose — mirroring what would otherwise be written as + prose in `docs/design/introduction.md`'s Software Structure section. Subsystem files add + `part` usages for their own direct children (nested subsystems or units), matching the + Software Item Hierarchy in `software-items.md`. +- `ots.sysml` / `shared.sysml` define one `part def` per OTS item / Shared Package, referenced + as `part` usages from the system(s) that depend on them. + +## Artifact-Location Comments + +Every System/Subsystem/Unit `part def` records where its companion artifacts live, as named +`comment` elements — not `attribute`s (attribute values are not surfaced by `sysml2tools query +describe`, even in JSON output; comments are). Comments have zero effect on rendered diagrams +(verified: a part def with several comments attached renders with no extra nodes or size +change) and are fully returned by `query describe`, in declaration order, as +`Comment: ...` summary lines — this is how an agent gets every artifact location for a unit +in a single query, without grepping the source tree. + +Use these comment names, in this order, when applicable to the item: + +```sysml +part def {UnitName} { + doc /* One-line purpose statement. */ + + comment sourceRef /* Source: {path to the unit's source file} */ + comment testRef /* Test: {path to the unit's test file} */ + comment designRef /* Design: {path to the unit's design doc} */ + comment verificationRef /* Verification: {path to the unit's verification doc} */ + comment reqRef /* Requirements: {path to the unit's reqstream file} */ +} +``` + +Not every item has all five: + +- **Systems and Subsystems** have no `sourceRef` (no single source file represents a whole + system or subsystem) — use `testRef` for the subsystem-level test file when one exists. +- **Units without a dedicated companion doc** (e.g. small data-model types documented inline + within their subsystem's design doc rather than in their own file) point `designRef` / + `verificationRef` / `reqRef` at the subsystem-level doc, with a short parenthetical note, + e.g. `/* Design: docs/design/{system}/{subsystem}.md (documented as a supporting value type) */`. +- **Units without a dedicated test file** (exercised only indirectly through another unit's + tests) omit `testRef` entirely rather than pointing at an unrelated test file. +- **OTS items** have no `sourceRef`/`testRef` (no local integration code); use `designRef` + (when the optional design doc exists) / `verificationRef` / `reqRef` only. + +This is prose-searchable metadata only — it is not a substitute for the authoritative +requirements/design/verification artifacts, and it does not replace ReqStream as the +requirements source of truth. (This repository currently keeps requirements traceability in +ReqStream; a future migration to native SysML2 `requirement`/`satisfy` modeling is a separate, +not-yet-scheduled change.) + +## Views (`docs/sysml2/views/design-views.sysml`) + +Views control what gets rendered into diagrams for the design document. Use named `view` +**usages** (not `view def` **definitions**) — `expose` is only valid inside a usage: + +```sysml +package {SystemName} { + view SoftwareStructureView { + expose {SystemName}; // whole package: system + subsystems + units + } + + view {SystemName}View { + expose {SystemName}System; // system def only, not expanded into subsystems + } + + view {SubsystemName}View { + expose {SubsystemName}; // one subsystem def only + } +} +``` + +**Critical distinction** (do not confuse these — this cost significant trial-and-error to +discover): `expose ;` is what scopes a rendered diagram's content (the union of the +named element's containment subtree). `render ;` selects a rendering *style* (e.g. +`asInterconnectionDiagram`) — it has **no effect on scope**. `expose` is only legal inside a named +`view Name { ... }` **usage**; it is a syntax/semantic error inside a `view def Name { ... }` +**definition**. `expose` targets must be `::`-qualified or locally-resolvable names, not +dotted member-access chains (`expose foo.bar;` is invalid — use `expose Bar;`). + +**Naming convention** — one `View` suffix per rendered diagram, no `System`/`Subsystem` +suffix duplication: + +- `SoftwareStructureView` - full detail: every system, subsystem, and unit in one diagram +- `{SystemName}View` - one per system, direct members only (not expanded into subsystems) +- `{SubsystemName}View` - one per subsystem (at any nesting depth), that subsystem's own + members only + +When a repository has multiple systems, `SoftwareStructureView` may expose each system's +package individually (`expose {SystemNameA}; expose {SystemNameB};`) or the whole workspace, +whichever produces a single coherent overview diagram. + +## Diagram Embedding + +Render with a single quoted recursive glob for the model tree, plus the views file +(`sysml2tools` 0.1.0-beta.5+ expands and recurses `**` internally, so no shell-side globbing +or explicit per-file listing is needed): + +```pwsh +dotnet sysml2tools render ` + --output docs/design/generated --format svg ` + 'docs/sysml2/model/**/*.sysml' ` + 'docs/sysml2/views/design-views.sysml' +``` + +With multiple views declared and no `--view` flag, `sysml2tools` renders every declared view +in one invocation, one file per view, using each view's own name as the filename +(`{ViewName}.svg`) — no post-render rename step is needed. + +Embed diagrams in `docs/design/` per this rule: every design doc for an item embeds the +diagram for the narrowest view that still shows that item's own immediate structure — + +- `docs/design/introduction.md` — `SoftwareStructureView.svg` (the full-detail overview) +- `docs/design/{system-name}.md` and every unit doc for a unit directly under the system + (no subsystem parent) — `{SystemName}View.svg` +- `docs/design/{system-name}/{subsystem-name}.md` and every unit doc nested under that + subsystem (at any depth) — `{SubsystemName}View.svg` + +Place the image directly under the file's top-level heading, before its first prose +subsection, e.g. `![{Name} Structure]({ViewName}.svg)`. + +## Build and Lint Integration + +- `sysml2tools lint` belongs in `lint.ps1`'s compliance-tools section, **not** as a separate + step in the CI design-document job — `lint.ps1` gates every later job (including document + generation) transitively, so linting the model there is both earlier and non-duplicated. + Pass a single quoted recursive glob, e.g. `dotnet sysml2tools lint 'docs/sysml2/**/*.sysml'` + — `sysml2tools` (0.1.0-beta.5+) expands and recurses this itself, so no + `Get-ChildItem`/shell-side globbing is needed. +- The CI design-document job renders the views (see the render command above) before running + Pandoc, so generated SVGs exist before HTML generation. Rename/stable-filename workarounds + are unnecessary since view names are stable by definition. Pass the model and views globs as + separate quoted arguments (e.g. `'docs/sysml2/model/**/*.sysml' 'docs/sysml2/views/design-views.sysml'`) + — plain PowerShell (the default shell) is sufficient; no `shell: bash`/`shopt -s globstar` + workaround is needed. +- Add `sysml2tools` to `.config/dotnet-tools.json` (`demaconsulting.sysml2tools.tool`) and to + `.versionmark.yaml`'s captured tool list. + +## Fallback + +If the model is stale, doesn't yet cover an item, or a query returns nothing useful, fall +back to `grep`/`glob`/reading source directly. When work adds or changes a Unit/Subsystem, +update the corresponding `.sysml` model file in the same change — this mirrors the existing +requirement to keep `docs/design/*.md` and `docs/reqstream/*.yaml` companion artifacts in +sync. + +## Quality Checks + +- [ ] Every System/Subsystem/Unit in `docs/design/introduction.md` has a matching `part def` + in its own file under `docs/sysml2/model/`, at the same folder depth as its companion + design/reqstream/verification files, with a purpose `doc` comment +- [ ] Every Unit-level `part def` has `sourceRef`/`testRef`/`designRef`/`verificationRef`/ + `reqRef` comments where applicable (see Artifact-Location Comments for documented + exceptions); System/Subsystem `part def`s have `testRef`/`designRef`/`verificationRef`/ + `reqRef` but no `sourceRef` +- [ ] `docs/sysml2/views/design-views.sysml` uses `view Name { expose ...; }` usages, not + `view def` definitions +- [ ] View names follow the `SoftwareStructureView` / `{SystemName}View` / + `{SubsystemName}View` convention +- [ ] `sysml2tools lint` passes on all `.sysml` files +- [ ] Rendered diagrams are embedded in every design doc per the Diagram Embedding rule +- [ ] `sysml2tools` is present in `lint.ps1`, `.config/dotnet-tools.json`, and + `.versionmark.yaml` diff --git a/.github/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/.reviewmark.yaml b/.reviewmark.yaml index 551b493..15f3eba 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 @@ -26,22 +27,37 @@ 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" @@ -53,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" @@ -63,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" @@ -71,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" @@ -90,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" @@ -109,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" @@ -127,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" @@ -143,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" @@ -152,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" @@ -163,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" @@ -179,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" @@ -188,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" @@ -197,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" @@ -209,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" @@ -220,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" @@ -236,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" @@ -244,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" @@ -255,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" @@ -271,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" @@ -282,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" @@ -306,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" @@ -324,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" @@ -333,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" @@ -346,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" @@ -355,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" @@ -372,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" @@ -399,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" @@ -409,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" @@ -417,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" @@ -430,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" @@ -439,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" @@ -449,62 +610,67 @@ 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 + 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" 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/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) diff --git a/docs/design/build-mark.md b/docs/design/build-mark.md index 66876e2..6acf5c1 100644 --- a/docs/design/build-mark.md +++ b/docs/design/build-mark.md @@ -1,5 +1,7 @@ # BuildMark +![BuildMark Structure](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..6d67cab 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](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..61f5dff 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](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..290fbea 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](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..b5a684e 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](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..29df756 100644 --- a/docs/design/build-mark/cli.md +++ b/docs/design/build-mark/cli.md @@ -1,5 +1,7 @@ ## Cli Subsystem +![Cli Structure](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..a440131 100644 --- a/docs/design/build-mark/cli/context.md +++ b/docs/design/build-mark/cli/context.md @@ -1,5 +1,7 @@ ### Context +![Cli Structure](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..734cbee 100644 --- a/docs/design/build-mark/configuration.md +++ b/docs/design/build-mark/configuration.md @@ -1,5 +1,7 @@ ## Configuration +![Configuration Structure](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..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,5 +1,7 @@ ### AzureDevOpsConnectorConfig +![Configuration Structure](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..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,5 +1,7 @@ ### BuildMarkConfigReader +![Configuration Structure](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..e5ccf63 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](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..b4b837c 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](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..779acba 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](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..dafd2a4 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](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..658e610 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](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..0d60b2d 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](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..c12402c 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](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..5193ec7 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](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..5125dbd 100644 --- a/docs/design/build-mark/program.md +++ b/docs/design/build-mark/program.md @@ -1,5 +1,7 @@ ## Program +![BuildMark Structure](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..bb38066 100644 --- a/docs/design/build-mark/repo-connectors.md +++ b/docs/design/build-mark/repo-connectors.md @@ -1,5 +1,7 @@ ## RepoConnectors +![RepoConnectors Structure](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..15ca8fb 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](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..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,5 +1,7 @@ #### AzureDevOpsApiTypes +![AzureDevOps Structure](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..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,5 +1,7 @@ #### AzureDevOpsRepoConnector +![AzureDevOps Structure](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..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,5 +1,7 @@ #### AzureDevOpsRestClient +![AzureDevOps Structure](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..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,5 +1,7 @@ #### WorkItemMapper +![AzureDevOps Structure](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..a0c812d 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](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..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,5 +1,7 @@ #### GitHubGraphQLClient +![GitHub Structure](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..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,5 +1,7 @@ #### GitHubGraphQLTypes +![GitHub Structure](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..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,5 +1,7 @@ #### GitHubRepoConnector +![GitHub Structure](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..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,5 +1,7 @@ ### ItemControlsInfo +![RepoConnectors Structure](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..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,5 +1,7 @@ ### ItemControlsParser +![RepoConnectors Structure](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..c3d0dd6 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](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..73ba9dd 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](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..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,5 +1,7 @@ #### MockRepoConnector +![Mock Structure](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..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,5 +1,7 @@ ### RepoConnectorBase +![RepoConnectors Structure](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..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,5 +1,7 @@ ### RepoConnectorFactory +![RepoConnectors Structure](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..6031381 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](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..de9fde9 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](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..4909414 100644 --- a/docs/design/build-mark/utilities.md +++ b/docs/design/build-mark/utilities.md @@ -1,5 +1,7 @@ ## Utilities Subsystem +![Utilities Structure](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..03735f7 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](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..97246f9 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](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..db2efc2 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](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..b5c9c54 100644 --- a/docs/design/build-mark/version.md +++ b/docs/design/build-mark/version.md @@ -1,5 +1,7 @@ ## Version Subsystem +![Version Structure](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..8049af7 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](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..9026d72 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](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..cdc5f8c 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](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..b662f56 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](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..f6899be 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](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..34edd28 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](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..a0421d0 100644 --- a/docs/design/introduction.md +++ b/docs/design/introduction.md @@ -34,124 +34,27 @@ 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](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 ## Companion Artifact Structure 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..6fb737d --- /dev/null +++ b/docs/sysml2/views/design-views.sysml @@ -0,0 +1,54 @@ +// 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; + } + + view BuildMarkView { + expose BuildMarkSystem; + } + + view CliView { + expose CliSubsystem; + } + + view BuildNotesView { + expose BuildNotesSubsystem; + } + + view SelfTestView { + expose SelfTestSubsystem; + } + + view UtilitiesView { + expose UtilitiesSubsystem; + } + + view VersionView { + expose VersionSubsystem; + } + + view ConfigurationView { + expose ConfigurationSubsystem; + } + + view RepoConnectorsView { + expose RepoConnectorsSubsystem; + } + + view GitHubView { + expose GitHubSubsystem; + } + + view AzureDevOpsView { + expose AzureDevOpsSubsystem; + } + + view MockView { + expose MockSubsystem; + } +} 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.