docs/ci: add PR template, CONTRIBUTING, Copilot review gate; fix Codecov conditions, quality-gates publish handling, TFM check efficiency; update branch protection guidance

Author: ooples

.github/BRANCH_PROTECTION.md

@@ -1,6 +1,6 @@
 # Branch Protection Guidance for AiDotNet
 
-We recommend enabling branch protection on `master` with these required status checks:
+We recommend enabling branch protection on both `merge-dev2-to-master` (active base) and `master` (release) with these required status checks:
 
 - CI (.NET) / Lint and Format Check
 - CI (.NET) / Build
@@ -15,5 +15,6 @@ Also enable:
 - Dismiss stale approvals on new commits (optional)
 - Require status checks to pass before merging
 - Require branches to be up to date before merging
+- Require CODEOWNERS review
 
 Note: The exact names shown in GitHub’s UI may include the workflow/job prefixes. Use the checks as they appear on a PR to configure the protection rules.

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,8 +1,27 @@
-Please ensure your pull request adheres to the following guidelines:
+## User Story / Context
+- Reference: [US-XXX] (if applicable)
+- Base branch: `merge-dev2-to-master`
 
-- [ ] I have built my code and there are no build errors.
-- [ ] I have run all unit tests and all unit tests passed.
-- [ ] I have included positive flow unit tests for any method or class I added.
-- [ ] I have inluded negative flow unit tests for any method or class I added.
+## Summary
+- What changed and why (scoped strictly to the user story / PR intent)
+
+## Verification
+- [ ] Builds succeed (scoped to changed projects)
+- [ ] Unit tests pass locally
+- [ ] Code coverage ≥ 90% for touched code
+- [ ] Codecov upload succeeded (if token configured)
+- [ ] TFM verification (net46, net6.0, net8.0) passes (if packaging)
+- [ ] No unresolved Copilot comments on HEAD
+
+## Copilot Review Loop (Outcome-Based)
+Record counts before/after your last push:
+- Comments on HEAD BEFORE: [N]
+- Comments on HEAD AFTER (60s): [M]
+- Final HEAD SHA: [sha]
+
+## Files Modified
+- [ ] List files changed (must align with scope)
+
+## Notes
+- Any follow-ups, caveats, or migration details
 
-Thanks for contributing!

.github/workflows/ci.yml

@@ -60,7 +60,7 @@ jobs:
         run: dotnet test AiDotNet.sln -c Release --no-build --collect:"XPlat Code Coverage" --results-directory ./TestResults
 
       - name: Upload coverage to Codecov
-        if: secrets.CODECOV_TOKEN != ''
+        if: ${{ secrets.CODECOV_TOKEN != '' }}
         uses: codecov/codecov-action@v4
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
@@ -109,14 +109,15 @@ jobs:
           dotnet test AiDotNet.sln --configuration Release --collect:"XPlat Code Coverage" --results-directory ./TestResults
 
       - name: Upload coverage to Codecov (only if token set)
-        if: ${{ secrets.CODECOV_TOKEN != '' }}
-        uses: codecov/codecov-action@v4
-        with:
-          token: ${{ secrets.CODECOV_TOKEN }}
-          files: |
-            ./TestResults/**/coverage.cobertura.xml
-          flags: unittests
-          fail_ci_if_error: false
+        run: |
+          if [ -n "${CODECOV_TOKEN}" ]; then
+            echo "Uploading coverage to Codecov..."
+            npx codecov -t "${CODECOV_TOKEN}" -f "./TestResults/**/coverage.cobertura.xml" -F unittests || echo "Codecov upload failed"
+          else
+            echo "CODECOV_TOKEN not set; skipping Codecov upload."
+          fi
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
   integration-test:
     name: Integration Tests

.github/workflows/copilot-review-gate.yml

@@ -0,0 +1,29 @@
+name: Copilot Review Gate
+
+on:
+  pull_request:
+    branches: [ merge-dev2-to-master ]
+
+permissions:
+  pull-requests: read
+  contents: read
+
+jobs:
+  gate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check unresolved Copilot comments on HEAD
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -e
+          REPO="${{ github.repository }}"
+          PR_NUMBER="${{ github.event.pull_request.number }}"
+          HEAD=$(gh pr view "$PR_NUMBER" --repo "$REPO" --json headRefOid --jq .headRefOid)
+          COUNT=$(gh api repos/$REPO/pulls/$PR_NUMBER/comments --paginate \
+            --jq "[ .[] | select((.user.login|test(\"copilot\|advanced\|security\|bot\";\"i\")) and .commit_id == \"$HEAD\") ] | length")
+          echo "Unresolved Copilot comments on HEAD: $COUNT"
+          if [ "$COUNT" -gt 0 ]; then
+            echo "Found $COUNT unresolved Copilot comments on HEAD $HEAD"
+            exit 1
+          fi

.github/workflows/quality-gates.yml

@@ -31,8 +31,19 @@ jobs:
           if [ -f "src/AiDotNet.csproj" ]; then
             dotnet publish src/AiDotNet.csproj -c Release -o publish
           else
-            # fallback: publish all projects in src
-            for p in src/*.csproj; do dotnet publish "$p" -c Release -o publish || true; done
+            failed_projects=""
+            shopt -s nullglob
+            for p in src/*.csproj; do
+              dotnet publish "$p" -c Release -o publish
+              if [ $? -ne 0 ]; then
+                echo "Publish failed for $p"
+                failed_projects="$failed_projects $p"
+              fi
+            done
+            if [ -n "$failed_projects" ]; then
+              echo "Error: The following projects failed to publish:$failed_projects"
+              exit 1
+            fi
           fi
 
       - name: Analyze size vs baseline

.github/workflows/release.yml

@@ -62,9 +62,9 @@ jobs:
           for pkg in "${pkgs[@]}"; do
             echo "Inspecting $pkg"
             files=$(unzip -Z1 "$pkg")
-            echo "$files" | grep -qE '^lib/net46/.+\.dll$' || { echo "Missing net46 lib in package"; exit 1; }
-            echo "$files" | grep -qE '^lib/net6\.0/.+\.dll$' || { echo "Missing net6.0 lib in package"; exit 1; }
-            echo "$files" | grep -qE '^lib/net8\.0/.+\.dll$' || { echo "Missing net8.0 lib in package"; exit 1; }
+            for tfm in net46 net6.0 net8.0; do
+              echo "$files" | grep -qE "^lib/${tfm}/.+\\.dll$" || { echo "Missing ${tfm} lib in package"; exit 1; }
+            done
           done
 
       - name: Upload package artifact

CONTRIBUTING.md

@@ -1,39 +1,26 @@
-## Contributing
+# Contributing
 
-[fork]: /fork
-[pr]: /compare
-[code-of-conduct]: CODE_OF_CONDUCT.md
+## Base Branch
+- Use `merge-dev2-to-master` as the working base for CI and PRs.
 
-Hi there! We're thrilled that you'd like to contribute to this project. Your help is essential for keeping it great.
+## Copilot Review Loop (Mandatory)
+1. Get the PR `headRefOid` (HEAD SHA).
+2. Retrieve review comments and filter to those where `commit_id == headRefOid` and author matches "copilot".
+3. Apply suggestions exactly (or implement an equivalent real fix).
+4. Commit (no force push), wait 30–60s for re-review, re-check unresolved count.
+5. Iterate until unresolved count = 0.
 
-Please note that this project is released with a [Contributor Code of Conduct][code-of-conduct]. By participating in this project you agree to abide by its terms.
+## CI/CD Expectations
+- Multi-TFM: net46, net6.0, net8.0.
+- Coverage ≥ 90% for modified code paths; upload to Codecov if `CODECOV_TOKEN` is set.
+- Release workflow validates packaged TFMs before publishing.
 
-## Issues and PRs
+## Scope Discipline
+- Only modify files relevant to the user story or bug.
+- Don’t introduce unrelated refactors.
 
-If you have suggestions for how this project could be improved, or want to report a bug, open an issue! We'd love all and any contributions. If you have questions, too, we'd love to hear them.
+## YAML Hygiene
+- No literal `\n` in names; correct indentation; steps under `steps`.
+- Shell `if` blocks must close with `fi` before next step.
+- Use `${{ ... }}` expression syntax for job/step `if` where supported.
 
-We'd also love PRs. If you're thinking of a large PR, we advise opening up an issue first to talk about it, though! Look at the links below if you're not sure how to open a PR.
-
-## Submitting a pull request
-
-1. [Fork][fork] and clone the repository.
-1. Install the .NET 8 SDK if you don't have it installed already.
-1. Make sure the unit tests pass on your machine (make sure to run all unit tests inside the unit test project).
-1. Create a new branch: `git checkout -b my-branch-name`.
-1. Make your change, add tests, and make sure the tests still pass.
-1. Push to your fork and [submit a pull request][pr].
-1. Pat your self on the back and wait for your pull request to be reviewed and merged.
-
-Here are a few things you can do that will increase the likelihood of your pull request being accepted:
-
-- Write and update unit tests.
-- Keep your changes as focused as possible. If there are multiple changes you would like to make that are not dependent upon each other, consider submitting them as separate pull requests.
-- Write a [good commit message](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
-
-Work in Progress pull requests are also welcome to get feedback early on, or if there is something blocked you.
-
-## Resources
-
-- [How to Contribute to Open Source](https://opensource.guide/how-to-contribute/)
-- [Using Pull Requests](https://help.github.com/articles/about-pull-requests/)
-- [GitHub Help](https://help.github.com)