Add THEORY-OF-OPERATIONS.md and GITHUB_TOKEN authentication support

[Copilot]

Adds a top-level THEORY-OF-OPERATIONS.md modeled after the ReviewMark equivalent, explaining how BuildMark works end-to-end. Also updates README.md to reference the new document from the Overview section, and updates the GitHub connector to support GITHUB_TOKEN as a fallback authentication source.

Description

New file: THEORY-OF-OPERATIONS.md with the following sections:

• Introduction — the problem BuildMark solves
• How It Works
  • Version Tag Recognition — tag pattern with recognition table
  • Pulling Repository Information
    • Connector Selection (generic) — environment-based connector selection; notes Azure DevOps as planned
    • GitHub (specialized subsection) — four steps: identify repo via git remote, authenticate via GH_TOKEN/GITHUB_TOKEN/gh auth token, fetch commits/tags/releases/PRs/issues via GraphQL in parallel, filter to current branch
  • Baseline Version Selection — release vs. pre-release rules, re-tagging scenario
  • Change Collection — commit range, PR label → bug/feature classification table
  • Report Generation — six output sections, --report-depth behavior
• Output — annotated example of the generated markdown report
• CI/CD Integration — GitHub Actions snippet
• Self-Validation — --validate mode and TRX/JUnit output

Updated: README.md — added a link to the Theory of Operations document in the Overview section.

Updated: GitHubRepoConnector.cs — GitHub authentication now checks GH_TOKEN first, then GITHUB_TOKEN, then falls back to gh auth token CLI. If no token can be obtained from any source, the tool fails with an error.

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

Pre-Submission Checklist

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

• 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

The repository information section deliberately uses a two-level structure (generic connector selection + GitHub-specific subsection) to make it straightforward to add an Azure DevOps subsection later without restructuring the document.

The GITHUB_TOKEN support was added to align the tool with the documented authentication flow and to support standard GitHub Actions environments where GITHUB_TOKEN is the conventional secret name.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[Malcolmnixon]

@copilot Consider referencing the THEORY-OF-OPERATIONS.md in the README.md

[Copilot]

@copilot Consider referencing the THEORY-OF-OPERATIONS.md in the README.md

Added a link to the Theory of Operations in the Overview section of README.md (commit 0f5f40b).

[Copilot]

Pull request overview

Adds a top-level “Theory of Operations” document to explain BuildMark’s end-to-end behavior, and links to it from the README Overview so users can find the deeper internal walkthrough.

Changes:

• Added THEORY-OF-OPERATIONS.md describing version/tag recognition, GitHub data collection, baseline selection, change collection, report output, CI usage, and self-validation.
• Updated README.md Overview section to link to the new document.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
THEORY-OF-OPERATIONS.md	New end-to-end operational documentation for how BuildMark determines versions, collects changes, and produces reports.
README.md	Adds a prominent link to the Theory of Operations from the Overview section.

---

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

You can also share your feedback on Copilot code review. Take the survey.

[Malcolmnixon]

@copilot The tool should be updated to match the THEORY-OF-OPERATIONS.md description of trying both 'GH_TOKEN' and 'GITHUB_TOKEN', and only then falling back to 'gh auth token'.

[Copilot]

@copilot The tool should be updated to match the THEORY-OF-OPERATIONS.md description of trying both 'GH_TOKEN' and 'GITHUB_TOKEN', and only then falling back to 'gh auth token'.

Updated the connector in commit 3899559 to check GH_TOKEN → GITHUB_TOKEN → gh auth token CLI in that order. Also updated the THEORY-OF-OPERATIONS.md authentication description to accurately reflect the failure behavior (throws if no token can be obtained, rather than falling back to unauthenticated requests).