Apply literate coding style to C# source files

[Copilot]

Pull Request

Description

Implements literate programming style across all C# source files. Each logical code block now has a leading comment explaining its purpose, with blank lines separating paragraphs. Method logic is deducible from comments alone.

Key improvements:

• Added leading comments to every logical code paragraph
• Blank lines now only separate distinct logical paragraphs (removed unnecessary blank lines after variable declarations)
• Enhanced external tool comments to document command arguments and output formats

Before:

public override async Task<List<Version>> GetTagHistoryAsync()
{
    var output = await RunCommandAsync("git", "tag --sort=creatordate --merged HEAD");
    var tagNames = output
        .Split('\n', StringSplitOptions.RemoveEmptyEntries)
        .Select(t => t.Trim())
        .ToList();
    return tagNames
        .Select(Version.TryCreate)
        .Where(t => t != null)
        .Cast<Version>()
        .ToList();
}

After:

public override async Task<List<Version>> GetTagHistoryAsync()
{
    // Get all tags merged into current branch, sorted by creation date
    // Arguments: --sort=creatordate (chronological order), --merged HEAD (reachable from HEAD)
    // Output format: one tag name per line
    var output = await RunCommandAsync("git", "tag --sort=creatordate --merged HEAD");

    // Split output into individual tag names
    var tagNames = output
        .Split('\n', StringSplitOptions.RemoveEmptyEntries)
        .Select(t => t.Trim())
        .ToList();

    // Parse and filter to valid version tags only
    return tagNames
        .Select(Version.TryCreate)
        .Where(t => t != null)
        .Cast<Version>()
        .ToList();
}

Files Updated:

• 7 source files in src/DemaConsulting.BuildMark/
• 6 test files in test/DemaConsulting.BuildMark.Tests/

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
• 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:

• Spell checker passes: cspell "**/*.{md,cs}"
• Markdown linter passes: markdownlint "**/*.md"
• YAML linter passes: yamllint '**/*.{yml,yaml}'

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

All existing XML documentation comments preserved. Changes are purely additive to improve code readability. Zero functional changes—all 63 tests pass.

Refinements based on feedback:

• Removed unnecessary blank lines after variable declarations to ensure blank lines only mark logical paragraph boundaries
• Expanded comments for all external tool calls (git, gh CLI) to document command arguments, expected output formats, and data flow
• Applied consistent literate coding style where each paragraph starts with a comment explaining its purpose

Original prompt

Please review the XmlDoc and inline comments for the code. I would like the code to follow a literate coding style where every "paragraph" of code starts with a leading comment explaining what it does, and one blank line separarates paragraphs. Essentially the concept of a methods logic should be deducable from the comments.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.