General improvements: built-in defaults, config-file report options, doc restructuring

[Copilot]

Pull Request

Description

BuildMark lacked sensible defaults when no .buildmark.yaml was present and required all report options via CLI. Documentation was spread across a redundant THEORY-OF-OPERATIONS.md, an oversized README, and a monolithic 932-line user guide.

Built-in default configuration

BuildMarkConfig.CreateDefault() provides three sections (Changes, Bugs Fixed, Dependency Updates) and six routing rules covering dependency-manager labels, bug labels/types, internal suppression, and a catch-all. Applied automatically when no config file exists.

Config-file report options

New report top-level section in .buildmark.yaml with CLI override:

report:
  file: docs/build_notes.md
  depth: 2
  include-known-issues: true

ReportDepth is nullable (int?) in both the argument parser and context, so --report-depth 1 on the CLI correctly overrides a config-file depth value. The default of 1 is applied only at resolution time. Empty or whitespace report.file values produce a configuration error via GetOptionalScalarValue.

Connector type normalization

GitHub LabelTypeMap now includes dependencies/renovate/dependabot → "dependencies" and internal/chore → "internal", so the default routing rules match items with those labels. Azure DevOps WorkItemMapper no longer normalizes Epic to "feature" — it retains the raw type "Epic" so the default suppression rule WorkItemType: ["Task", "Epic"] matches correctly.

Documentation restructuring

• Deleted THEORY-OF-OPERATIONS.md
• Trimmed README from 453→283 lines; detailed content moved to User Guide
• Shortened README feature bullets so all fit on a single line without wrapping
• Split monolithic user guide into five focused files: introduction.md, configuration.md, cli-reference.md, item-controls.md, advanced-topics.md
• Added CLI quick-reference table, documented built-in defaults and report config options
• Updated feature bullets (added Configurable Routing, Dependency Updates)
• Fixed Azure Pipelines CI example to use $(GitVersion.SemVer) instead of $(Build.BuildNumber) which is not a valid semantic version
• Corrected Version Information example to match actual output format (table with Version, Commit Hash, Previous Version, Previous Commit Hash — no Commit Date)
• Added Dependency Updates section to report format documentation and Azure DevOps configuration example
• Added path-based prefix examples (release/1.2.3, builds/release/1.2.3) to version tag format documentation
• Added Azure DevOps Integration best practices section (PAT scopes, SYSTEM_ACCESSTOKEN, Entra ID token expiry, on-premises URL)

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Code quality improvement

Related Issues

Pre-Submission Checklist

Before submitting this pull request, ensure you have completed the following:

Build and Test

• Code builds successfully: dotnet build --configuration Release
• All tests pass: dotnet test --configuration Release
• Self-validation tests pass:
  dotnet run --project src/DemaConsulting.BuildMark --configuration Release --framework net10.0
--no-build -- --validate
• Code produces zero warnings

Code Quality

• Code formatting is correct: dotnet format --verify-no-changes
• New code has appropriate XML documentation comments
• Static analyzer warnings have been addressed

Quality Checks

Please run the following checks before submitting:

• All linters pass: ./lint.sh (Unix/macOS) or cmd /c lint.bat / ./lint.bat (Windows)

Testing

• Added unit tests for new functionality
• Updated existing tests if behavior changed
• All tests follow the AAA (Arrange, Act, Assert) pattern
• Test coverage is maintained or improved

Documentation

• Updated README.md (if applicable)
• Updated ARCHITECTURE.md (if applicable)
• Added code examples for new features (if applicable)
• Updated requirements.yaml (if applicable)

Additional Notes

467 tests pass (464 existing + 3 new) across .NET 8, 9, and 10. Markdownlint and cspell clean on all changed files. CodeQL security scan passes with no alerts. The definition.yaml for Pandoc-based user guide generation has been updated to include the new split files in reading order.

[Copilot]

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• https://api.github.com/graphql
  • Triggering command: /usr/share/dotnet/dotnet /usr/share/dotnet/dotnet exec --runtimeconfig /home/REDACTED/work/BuildMark/BuildMark/test/DemaConsulting.BuildMark.Tests/bin/Debug/net10.0/DemaConsulting.BuildMark.Tests.runtimeconfig.json --depsfile /home/REDACTED/work/BuildMark/BuildMark/test/DemaConsulting.BuildMark.Tests/bin/Debug/net10.0/DemaConsulting.BuildMark.Tests.deps.json /home/REDACTED/work/BuildMark/BuildMark/test/DemaConsulting.BuildMark.Tests/bin/Debug/net10.0/testhost.dll --port 42803 --endpoint 127.0.0.1:042803 --role client --parentprocessid 4144 --telemetryoptedin false (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[Copilot]

Pull request overview

Adds built-in defaults and config-driven report options to reduce required CLI/config boilerplate, and restructures the documentation into a multi-file user guide.

Changes:

• Add BuildMarkConfig.CreateDefault() and apply it automatically when no .buildmark.yaml exists.
• Introduce a new top-level report: config section (file/depth/include-known-issues) with CLI override behavior.
• Restructure docs (remove THEORY-OF-OPERATIONS, trim README, split user guide into focused pages).

Reviewed changes

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

Show a summary per file

File	Description
THEORY-OF-OPERATIONS.md	Removes redundant internal/how-it-works doc in favor of user guide structure.
test/DemaConsulting.BuildMark.Tests/Configuration/ConfigurationTests.cs	Adds unit tests for default config and parsing of the new report section.
src/DemaConsulting.BuildMark/Program.cs	Applies default config when missing and resolves effective report options from CLI + config.
src/DemaConsulting.BuildMark/Configuration/ReportConfig.cs	Introduces a model for report options in .buildmark.yaml.
src/DemaConsulting.BuildMark/Configuration/BuildMarkConfigReader.cs	Parses the new top-level report section.
src/DemaConsulting.BuildMark/Configuration/BuildMarkConfig.cs	Adds Report property and CreateDefault() built-in sections/rules.
README.md	Updates feature list and points readers to the new user guide docs.
docs/user_guide/introduction.md	Updates feature bullets and trims content moved into split guide pages.
docs/user_guide/configuration.md	New dedicated configuration reference (connector/sections/rules/report + defaults).
docs/user_guide/cli-reference.md	New dedicated CLI option reference page.
docs/user_guide/item-controls.md	New dedicated page for embedded buildmark item controls and ADO custom fields.
docs/user_guide/advanced-topics.md	New page for CI/CD examples, report format, version/tag rules, troubleshooting, best practices.
docs/user_guide/definition.yaml	Updates Pandoc input ordering to include the newly split guide files.

---

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

[Malcolmnixon]

@copilot apply changes based on the comments in this thread

[Copilot]

@copilot apply changes based on the comments in this thread

All three items from that review thread addressed in f3ae1b0:

• ReportDepth is now nullable with default applied only at resolution
• GitHub LabelTypeMap expanded with dependency/internal labels; ADO Epic kept as raw type
• report.file validated via GetOptionalScalarValue with error on empty/whitespace

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• https://api.github.com/graphql
  • Triggering command: /usr/share/dotnet/dotnet /usr/share/dotnet/dotnet exec --runtimeconfig /home/REDACTED/work/BuildMark/BuildMark/test/DemaConsulting.BuildMark.Tests/bin/Release/net9.0/DemaConsulting.BuildMark.Tests.runtimeconfig.json --depsfile /home/REDACTED/work/BuildMark/BuildMark/test/DemaConsulting.BuildMark.Tests/bin/Release/net9.0/DemaConsulting.BuildMark.Tests.deps.json /home/REDACTED/work/BuildMark/BuildMark/test/DemaConsulting.BuildMark.Tests/bin/Release/net9.0/testhost.dll --port 38377 --endpoint 127.0.0.1:038377 --role client --parentprocessid 4646 --telemetryoptedin false (http block)
  • Triggering command: /usr/share/dotnet/dotnet /usr/share/dotnet/dotnet exec --runtimeconfig /home/REDACTED/work/BuildMark/BuildMark/test/DemaConsulting.BuildMark.Tests/bin/Release/net10.0/DemaConsulting.BuildMark.Tests.runtimeconfig.json --depsfile /home/REDACTED/work/BuildMark/BuildMark/test/DemaConsulting.BuildMark.Tests/bin/Release/net10.0/DemaConsulting.BuildMark.Tests.deps.json /home/REDACTED/work/BuildMark/BuildMark/test/DemaConsulting.BuildMark.Tests/bin/Release/net10.0/testhost.dll --port 37905 --endpoint 127.0.0.1:037905 --role client --parentprocessid 4688 --telemetryoptedin false (http block)
  • Triggering command: /usr/share/dotnet/dotnet /usr/share/dotnet/dotnet exec --runtimeconfig /home/REDACTED/work/BuildMark/BuildMark/test/DemaConsulting.BuildMark.Tests/bin/Release/net8.0/DemaConsulting.BuildMark.Tests.runtimeconfig.json --depsfile /home/REDACTED/work/BuildMark/BuildMark/test/DemaConsulting.BuildMark.Tests/bin/Release/net8.0/DemaConsulting.BuildMark.Tests.deps.json /home/REDACTED/work/BuildMark/BuildMark/test/DemaConsulting.BuildMark.Tests/bin/Release/net8.0/testhost.dll --port 42707 --endpoint 127.0.0.1:042707 --role client --parentprocessid 4655 --telemetryoptedin false (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)