docs

Author: KSemenenko

AGENTS.md

@@ -21,6 +21,7 @@ This file defines how AI agents work in this solution.
 - Solution root: `.` (`DotPilot.slnx`)
 - Projects or modules with local `AGENTS.md` files:
   - `DotPilot`
+  - `DotPilot.ReleaseTool`
   - `DotPilot.Tests`
   - `DotPilot.UITests`
 - Shared solution artifacts:
@@ -141,7 +142,11 @@ For this app:
 - `global.json` pins the .NET SDK and Uno SDK version used by the app and tests
 - `DotPilot/DotPilot.csproj` keeps `GenerateDocumentationFile=true` with `CS1591` suppressed so `IDE0005` stays enforceable in CI across all target frameworks without inventing command-line-only build flags
 - GitHub Actions workflows must use descriptive names and filenames that reflect their purpose; do not use a generic `ci.yml` catch-all because build validation and release automation are separate operator flows
-- GitHub Actions must be split into at least one validation workflow for normal builds/tests and one release workflow for version bumping, release-note generation, desktop publishing, and GitHub Release publication
+- GitHub Actions must be split into at least one validation workflow for normal builds/tests and one release workflow for CI-driven version resolution, release-note generation, desktop publishing, and GitHub Release publication
+- the release workflow must run automatically on pushes to `main`, build desktop apps, and publish the GitHub Release without requiring a manual dispatch
+- desktop release versions must use the `ApplicationDisplayVersion` value in `DotPilot/DotPilot.csproj` as a manually maintained two-segment prefix, with CI appending the final segment from the build number (for example `0.0.<build-number>`)
+- the release workflow must not take ownership of the first two version segments; those remain manually edited in source, while CI supplies only the last numeric segment and matching release tag/application version values
+- for CI and release automation in this solution, prefer existing `dotnet` and `MSBuild` capabilities plus small workflow-native steps over Python or adding a separate helper project for simple versioning and release-note tasks
 - prefer MIT-licensed GitHub and NuGet dependencies when they materially accelerate delivery and align with the current architecture
 - prefer official `.NET` AI evaluation libraries under `Microsoft.Extensions.AI.Evaluation*` for response-quality, tool-usage, and safety evaluation instead of custom or third-party evaluation stacks by default
 - prefer `Microsoft Agent Framework` telemetry and observability patterns with OpenTelemetry-first instrumentation and optional Azure Monitor or Foundry export later
@@ -313,6 +318,7 @@ Ask first:
 ### Likes
 
 - Follow the canonical MCAF tutorial when bootstrapping or upgrading the agent workflow.
+- Commit cohesive code-change batches promptly while debugging, especially before switching focus or starting long verification runs, so the branch state stays inspectable and pushable.
 - Keep the root `AGENTS.md` at the repository root.
 - Keep the repo-local agent skill directory limited to current `mcaf-*` skills.
 - Keep the solution file name cased as `DotPilot.slnx`.

docs/ADR/ADR-0002-split-github-actions-build-and-release.md

@@ -16,7 +16,7 @@ That shape no longer matches the repository workflow:
 
 - normal validation should stay focused on build and test feedback
 - release publishing has different permissions, side effects, and operator intent
-- the release path now needs version bumping in `DotPilot/DotPilot.csproj`
+- the release path now needs CI-derived version resolution from `DotPilot/DotPilot.csproj`
 - desktop releases must publish platform artifacts and create a GitHub Release with feature-oriented notes
 
 Keeping all of that in one catch-all workflow makes the automation harder to reason about, harder to secure, and harder to operate safely.
@@ -30,23 +30,22 @@ We will split GitHub Actions into two explicit workflows:
    - runs on normal integration events
    - does not publish desktop artifacts or create releases
 2. `release-publish.yml`
-   - runs only from explicit release intent through `workflow_dispatch`
-   - may run only from `main` or `release/*`
-   - bumps `ApplicationDisplayVersion` and `ApplicationVersion` in `DotPilot/DotPilot.csproj`
-   - tags the release, publishes desktop outputs for macOS, Windows, and Linux, and creates the GitHub Release
+   - runs automatically on pushes to `main`
+   - resolves the release version from the two-segment `ApplicationDisplayVersion` prefix in `DotPilot/DotPilot.csproj` plus the GitHub Actions build number
+   - publishes desktop outputs for macOS, Windows, and Linux, and creates the GitHub Release
    - prepends repo-owned feature summaries and feature-doc links to GitHub-generated release notes
 
 ## Decision Diagram
 
 ```mermaid
 flowchart LR
   Change["Push or pull request"]
-  ReleaseIntent["Manual release dispatch"]
+  ReleaseIntent["Push to main"]
   Validation["build-validation.yml"]
   Release["release-publish.yml"]
   Quality["Format + build + analyze"]
   Tests["Unit + coverage + UI tests"]
-  Version["Version bump in DotPilot.csproj"]
+  Version["Version resolved from DotPilot.csproj prefix + CI build number"]
   Publish["Desktop publish matrix"]
   GitHubRelease["GitHub Release with feature notes"]
 
@@ -72,7 +71,7 @@ This keeps unrelated concerns coupled and makes ordinary CI runs carry release-s
 
 Rejected.
 
-The repository needs the release version recorded in `DotPilot/DotPilot.csproj`, not only in Git tags or GitHub Release metadata.
+The repository still needs a manual source-of-truth prefix in `DotPilot/DotPilot.csproj`, but the final build segment should be CI-derived so every `main` release is unique without generating a release-only source commit.
 
 ### 3. Store release notes entirely as manual workflow input
 
@@ -85,19 +84,20 @@ That makes release quality depend on operator memory instead of repo-owned histo
 ### Positive
 
 - Validation runs are easier to understand and remain side-effect free.
-- Release automation has a clear permission boundary and operator trigger.
+- Release automation has a clear permission boundary and automatic `main` trigger.
 - Desktop publish artifacts move to the workflow that actually needs them.
 - Release notes now combine GitHub-generated notes with repo-owned feature context.
+- Release numbers stay predictable: humans own the major/minor prefix in source and CI owns the last segment.
 
 ### Negative
 
-- Release automation now depends on branch write permissions for the workflow token or an equivalent release credential strategy.
-- The repository gains dedicated helper scripts for version bumping and release-note generation that must stay aligned with `DotPilot.csproj`.
+- Release automation now depends on the GitHub Actions run number remaining a suitable build-number source for releases.
+- The repository gains workflow-owned release logic that must stay aligned with `DotPilot.csproj`, git history, and `docs/Features/`.
 
 ## Implementation Impact
 
 - Rename the old validation workflow to `build-validation.yml`.
-- Add `release-publish.yml` plus repo-owned scripts for version bumping and release-summary generation.
+- Add `release-publish.yml` with workflow-native `dotnet`/`git` steps for release-version resolution and release-summary generation.
 - Update `docs/Architecture.md` and root governance rules to reference the split workflow model.
 
 ## References

docs/Architecture.md

@@ -10,7 +10,7 @@ This file is the required start-here architecture map for non-trivial tasks.
 - **Current product shell:** [../DotPilot/](../DotPilot/) already contains the visual workbench concepts that future work must preserve: a left navigation shell, a central session surface, a right-side inspector, and a separate agent-builder surface.
 - **Target runtime direction:** the planned product architecture uses an embedded `Orleans` silo, `Microsoft Agent Framework` orchestration, provider adapters for external agent runtimes, local runtime adapters, `MCPGateway` for tool federation, `RagSharp` for repo intelligence, and OpenTelemetry-first observability.
 - **Planning artifacts:** the control-plane direction is captured in [ADR-0001](./ADR/ADR-0001-agent-control-plane-architecture.md), the CI/release workflow split is captured in [ADR-0002](./ADR/ADR-0002-split-github-actions-build-and-release.md), and the operator experience is captured in [agent-control-plane-experience.md](./Features/agent-control-plane-experience.md).
-- **Automated verification today:** [../DotPilot.Tests/](../DotPilot.Tests/) contains in-process `NUnit` tests, [../DotPilot.UITests/](../DotPilot.UITests/) contains browser-driven `Uno.UITest` UI coverage, GitHub Actions `Build Validation` gates normal changes, and `Desktop Release` owns version bumping, desktop publishing, and GitHub Release publication.
+- **Automated verification today:** [../DotPilot.Tests/](../DotPilot.Tests/) contains in-process `NUnit` tests, [../DotPilot.UITests/](../DotPilot.UITests/) contains browser-driven `Uno.UITest` UI coverage, GitHub Actions `Build Validation` gates normal changes, and `Desktop Release` runs automatically on pushes to `main` to publish desktop artifacts and create the GitHub Release.
 
 ## Scoping
 
@@ -161,7 +161,8 @@ flowchart TD
 - The preferred runtime direction is an embedded `Orleans` host with `Microsoft Agent Framework`.
 - Provider integrations are SDK-first where viable.
 - Evaluation should use `Microsoft.Extensions.AI.Evaluation*`, and observability should be OpenTelemetry-first.
-- GitHub Actions now separates validation from release so normal CI stays fast and side-effect free while release automation owns versioning, desktop publishing, and GitHub Release publication.
+- GitHub Actions now separates validation from release so normal CI stays fast and side-effect free while release automation owns desktop publishing and GitHub Release publication on `main`.
+- Desktop release versions are derived from the two-segment `ApplicationDisplayVersion` prefix in `DotPilot.csproj` plus the CI build number as the final segment.
 
 ## Known Repository Risks