Add pre-push and merge playbooks, fix process documentation by mpaulosky · Pull Request #251 · mpaulosky/IssueTrackerApp

mpaulosky · 2026-04-12T22:34:54Z

Summary

Formalizes pre-push and merge processes into agent-executable playbooks and fixes stale/contradictory documentation.

New Playbooks

.squad/playbooks/pre-push-process.md — Full 5-gate pre-push walkthrough with pre-flight checklist, troubleshooting, and Docker requirements
.squad/playbooks/pr-merge-process.md — 8-step PR merge lifecycle (open → CI → gate → review → merge → cleanup)

Fixed / Rewritten

.copilot/skills/pre-push-test-gate/SKILL.md — Complete rewrite covering all 5 gates, 10 test projects, retry behavior
.squad/playbooks/release-issuetracker.md — Fixed 12+ contradictions (NBGV→GitVersion, single→two-branch model)

Flagged as Squad CLI Only

squad-conventions, ci-validation-gates, release-process — ⚠️ warnings so agents don't follow Node.js/npm patterns

Config Updated

.squad/routing.md — New "Playbook-Aware Routing" section replacing stale skill references
.squad/ceremonies.md — Playbook cross-references added to Build Repair Check, PR Review Gate, Standard Task Workflow

Test Results

All 5 pre-push gates passed: 0 warnings, 2,365 tests (2,026 unit + 339 integration) ✅

Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

- Add .squad/playbooks/pre-push-process.md (5-gate walkthrough) - Add .squad/playbooks/pr-merge-process.md (8-step merge lifecycle) - Fix release-issuetracker.md (NBGV→GitVersion, two-branch model) - Rewrite pre-push-test-gate skill (all 5 gates, 10 test projects) - Flag 3 Squad CLI skills as non-applicable to IssueTrackerApp - Update routing.md with playbook-aware routing section - Add playbook cross-references to ceremonies.md Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

github-actions · 2026-04-12T22:38:46Z

Test Results Summary

2 365 tests ±0 2 365 ✅ +1 1m 24s ⏱️ -29s
10 suites ±0 0 💤 ±0
10 files ±0 0 ❌ - 1

Results for commit d5171ed. ± Comparison against base commit 4587eae.

♻️ This comment has been updated with latest results.

Copilot

Pull request overview

Adds agent-executable playbooks for pre-push and PR merge workflows, and updates existing Squad routing/ceremony/skill documentation to reference these playbooks and clarify which skills apply to IssueTrackerApp vs Squad CLI.

Changes:

Introduces new playbooks for the 5-gate pre-push process and the PR review/merge lifecycle.
Rewrites/updates process docs (routing, ceremonies, pre-push skill, release playbook) to cross-reference playbooks and remove stale guidance.
Flags several Copilot skills as “Squad CLI Only” to prevent agents from applying npm/Node guidance to this .NET repo.

Reviewed changes

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

Show a summary per file

File	Description
`.squad/routing.md`	Reformats routing table and replaces “Skill-Aware Routing” with playbook-aware routing links.
`.squad/playbooks/pre-push-process.md`	New step-by-step pre-push checklist and troubleshooting guide for the 5 hook gates.
`.squad/playbooks/pr-merge-process.md`	New end-to-end PR review/merge playbook including reviewer routing and cleanup steps.
`.squad/playbooks/release-issuetracker.md`	Updates release process docs to reflect current tooling/branching/versioning workflows.
`.squad/ceremonies.md`	Adds cross-references to new playbooks and improves formatting/structure of several ceremony sections.
`.copilot/skills/pre-push-test-gate/SKILL.md`	Rewrites the skill to describe the current 5-gate hook and link to the new playbook.
`.copilot/skills/squad-conventions/SKILL.md`	Adds “Squad CLI Only” warning banner.
`.copilot/skills/release-process/SKILL.md`	Adds “Squad CLI Only” warning banner and points IssueTrackerApp readers to the playbook.
`.copilot/skills/ci-validation-gates/SKILL.md`	Adds “Squad CLI Only” warning banner and points IssueTrackerApp readers to the correct gates/playbook.

Copilot · 2026-04-12T22:38:51Z

+1. **You are on a `squad/*` branch** — Gate 0 blocks pushes to `main` and `dev`
+
+   ```bash
+   git symbolic-ref --short HEAD
+   # Must show: squad/{issue}-{slug}
+   ```


The pre-push hook currently blocks direct pushes only when the current branch is main (see .github/hooks/pre-push, Gate 0). This line says Gate 0 blocks pushes to main and dev, which doesn’t match the actual hook behavior. Please either update the wording to match the hook, or update the hook to also block dev if that’s intended policy.

Copilot · 2026-04-12T22:38:52Z

+| Gate  | What                   | Blocks Push If                                                           |
+| ----- | ---------------------- | ------------------------------------------------------------------------ |
+| **0** | Branch protection      | Current branch is `main`                                                 |
+| **1** | Untracked source files | `.razor`/`.cs` files not staged (prompts y/N)                            |
+| **2** | Release build          | `dotnet build --configuration Release` fails (3 attempts)                |
+| **3** | Unit/Arch/bUnit tests  | Any of 6 test projects fail (3 attempts)                                 |
+| **4** | Integration tests      | Any of 4 integration test projects fail; Docker not running (3 attempts) |


Gate 4’s description implies Docker-not-running gets 3 attempts, but the hook exits immediately when docker info fails (no retries). Consider updating the Gate 4 row to reflect that retries apply to the integration test run loop only, and that missing Docker blocks the push immediately.

Suggested change

| Gate | What | Blocks Push If |

| ----- | ---------------------- | ------------------------------------------------------------------------ |

| **0** | Branch protection | Current branch is `main` |

| **1** | Untracked source files | `.razor`/`.cs` files not staged (prompts y/N) |

| **2** | Release build | `dotnet build --configuration Release` fails (3 attempts) |

| **3** | Unit/Arch/bUnit tests | Any of 6 test projects fail (3 attempts) |

| **4** | Integration tests | Any of 4 integration test projects fail; Docker not running (3 attempts) |

| Gate | What | Blocks Push If |

| ----- | ---------------------- | ------------------------------------------------------------------------------------------------ |

| **0** | Branch protection | Current branch is `main` |

| **1** | Untracked source files | `.razor`/`.cs` files not staged (prompts y/N) |

| **2** | Release build | `dotnet build --configuration Release` fails (3 attempts) |

| **3** | Unit/Arch/bUnit tests | Any of 6 test projects fail (3 attempts) |

| **4** | Integration tests | Docker not running; or any of 4 integration test projects fail after 3 attempts |

Copilot · 2026-04-12T22:38:52Z


-**Last Updated:** 2026-04-12  
-**Ref:** `.squad/skills/release-process-base/SKILL.md`  
+**Last Updated:** 2025-07-17  


Last Updated is set to 2025-07-17, but this playbook also states Last Reviewed: 2026-04-12 later in the document (and this PR updates the content). These metadata fields look inconsistent; please align them (or remove one) to avoid confusion about freshness.

Suggested change

**Last Updated:** 2025-07-17

**Last Updated:** 2026-04-12

Copilot · 2026-04-12T22:38:52Z

+| **Build Verification** | release published | `.github/workflows/build.yml`             | (logs only)        |
+| **Unit Tests**         | release published | `.github/workflows/build.yml`             | (logs only)        |
+| **Integration Tests**  | release published | `.github/workflows/integration-tests.yml` | (logs only)        |


Copilot · 2026-04-12T22:38:53Z

-**Note:** After release tag, NBGV will auto-increment to `1.0.1-preview.X` on main. No manual update needed.
+**Note:** No manual version file edits needed. GitVersion derives the version from git history, branch names, and tags.

 ### Phase 2 — Create Release PR


Phase 2 is titled “Create Release PR”, but the steps describe promoting dev to main via workflow dispatch or a direct merge commit. If this phase is no longer a PR-based promotion, the heading should be renamed (or the instructions should be adjusted to actually create a PR) to avoid process ambiguity.

Suggested change

### Phase 2 — Create Release PR

### Phase 2 — Promote `dev` to `main`

Copilot · 2026-04-12T22:38:53Z

+# Sync local
+git checkout main && git pull origin main && git fetch --prune
+
+# Remove merged remote squad/ branches
+git branch -r --merged origin/main \
+  | grep 'origin/squad/' \
+  | sed 's|origin/||' \
+  | xargs -r -I{} git push origin --delete {}
+
+# Remove merged local squad/ branches
+git branch --merged main \
+  | grep -E '^\s+squad/' \


The cleanup commands use origin/main / local main as the merge base when identifying merged squad/* branches. Since this playbook’s workflow has PRs squash-merged into dev (Step 1 uses --base dev), merged branches may not appear as merged into main until promotion, so the cleanup can miss recently merged branches. Consider switching these commands to use dev (or check both dev and main).

Suggested change

# Sync local

git checkout main && git pull origin main && git fetch --prune

# Remove merged remote squad/ branches

git branch -r --merged origin/main \

| grep 'origin/squad/' \

| sed 's|origin/||' \

| xargs -r -I{} git push origin --delete {}

# Remove merged local squad/ branches

git branch --merged main \

| grep -E '^\s+squad/' \

# Sync local integration and release branches

git fetch --prune origin

git checkout dev && git pull origin dev

git checkout main && git pull origin main

# Remove merged remote squad/ branches (merged to dev or already promoted to main)

(

git branch -r --merged origin/dev

git branch -r --merged origin/main

) \

| grep 'origin/squad/' \

| sed 's|origin/||' \

| sort -u \

| xargs -r -I{} git push origin --delete {}

# Remove merged local squad/ branches (merged to dev or already promoted to main)

(

git branch --merged dev

git branch --merged main

) \

| grep -E '^\s+squad/' \

| sed 's/^[[:space:]]*//' \

| sort -u \

Copilot · 2026-04-12T22:38:53Z

@@ -219,6 +233,7 @@ Fix agent: please push corrections to `{branch}` and comment when ready for re-r
   git commit -m "chore: resolve merge conflicts with main\n\nCo-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>"


This conflict-resolution procedure merges origin/main into the PR branch, but the documented PR base branch elsewhere is dev. For conflicts that arise because the base branch advanced, the merge target should typically be origin/dev (or whatever the PR base is), otherwise you may resolve the wrong set of conflicts and still fail to merge.

Copilot · 2026-04-12T22:38:53Z

@@ -253,7 +268,7 @@ git fetch --prune

 `--prune` removes local tracking refs (`origin/squad/*`) for branches already deleted on origin.

-**Step 2 — Delete merged remote branches (origin)**
+#### **Step 2 — Delete merged remote branches (origin)**

 Catches any `squad/*` branches not removed by `--delete-branch` at merge time:

@@ -264,15 +279,15 @@ git branch -r --merged origin/main \
  | xargs -r -I{} git push origin --delete {}
 ```


Orphan branch cleanup uses origin/main / main to detect merged squad/* branches. With the two-branch model (feature → dev squash, then dev → main promote), branches merged into dev won’t necessarily be considered merged into main yet, so this can leave orphan branches around longer than intended. Consider using origin/dev / dev here (or checking both).

Copilot · 2026-04-12T22:38:54Z

+**GitVersion.yml reference** (actual repo config):
+
+```yaml
+mode: ContinuousDeployment
+tag-prefix: '[vV]?'
+branches:
+  main:
+    regex: ^main$
+    tag: ''
+    increment: Minor
+  develop:
+    regex: ^dev$
+    tag: preview
+    increment: Minor
+  feature:
+    regex: ^(feature|squad)[/-]
+    tag: alpha.{BranchName}
+    increment: Inherit
 ```



The embedded GitVersion.yml reference snippet doesn’t match the actual GitVersion.yml in the repo (e.g., real file uses mode: ContinuousDelivery, tag-prefix: '[vV]', and does not define a dev/develop branch section). Since this playbook claims the snippet reflects the “actual repo config”, it should be updated to mirror the current GitVersion.yml (or the playbook should stop inlining the config and link to the file only).

Suggested change

**GitVersion.yml reference** (actual repo config):

```yaml

mode: ContinuousDeployment

tag-prefix: '[vV]?'

branches:

main:

regex: ^main$

tag: ''

increment: Minor

develop:

regex: ^dev$

tag: preview

increment: Minor

feature:

regex: ^(feature|squad)[/-]

tag: alpha.{BranchName}

increment: Inherit

```

**GitVersion.yml reference:** See the canonical repo configuration in

[`GitVersion.yml`](../../GitVersion.yml).

Verified current highlights:

- `mode: ContinuousDelivery`

- `tag-prefix: '[vV]'`

- No explicit `dev`/`develop` branch section is defined in the current file

For release decisions, treat the root `GitVersion.yml` as the source of truth

rather than this playbook.

codecov · 2026-04-12T22:38:59Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 78.52%. Comparing base (4587eae) to head (d5171ed).
⚠️ Report is 1 commits behind head on dev.

Additional details and impacted files

@@           Coverage Diff           @@
##              dev     #251   +/-   ##
=======================================
  Coverage   78.52%   78.52%           
=======================================
  Files         228      228           
  Lines        8481     8481           
  Branches     1166     1166           
=======================================
  Hits         6660     6660           
  Misses       1284     1284           
  Partials      537      537

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

* chore: Sync dev with main (2 missing commits) (#248) Sync dev with main: brings in commits b529234 (#246) and 1c3b613 (#247). Establishes clean baseline for dev/main branching model. * chore: Sync dev with main (2 missing commits — #246, #247) (#249) * chore: Update MCP server configurations and squad export (#246) * chore: merge release-process skill review decisions, update agent histories, archive aged decisions - Merged three inbox decision entries (Aragorn/Boromir/Frodo) into decisions.md - Updated agent history files with 2026-04-12 team sync learnings - Archived pre-April-1 decisions to decisions-archive.md for operational clarity - Released context by condensing aged decision records Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * .squad: Scribe logs for Frodo release-process legacy stub Session: 2026-04-12T19:57:04Z Tasks completed: 1. Orchestration log: frodo agent release-process deprecation task 2. Session log: release-skill-legacy-stub work summary 3. Decision inbox merged: frodo-release-process-legacy-stub.md → decisions.md 4. Frodo history.md updated: Added legacy stub deprecation entry 5. Inbox file deleted after merge Outputs: - .squad/orchestration-log/2026-04-12T19-57-04Z-frodo.md (new) - .squad/log/2026-04-12T19-57-04Z-release-skill-legacy-stub.md (new) - .squad/decisions.md (appended, 92896 bytes) - .squad/agents/frodo/history.md (updated with team context) No archival needed (92896 bytes < 20KB threshold would trigger archive, but this represents 2026-04 additions; all old decisions within 30d window). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * .squad: History file summarization (aragorn, frodo, legolas, pippin) Task 7: Summarized old entries (>30d) to '## Core Context' section. Files: - aragorn: 29KB → 21KB (kept March 28+ recent entries) - frodo: 16KB → 6KB (kept April 12+ recent entries) - legolas: 14KB → 4KB (consolidated CSS, styling, theme learnings) - pippin: 12KB → 4KB (consolidated Aspire, Playwright, team rule learnings) All summarized files now <12KB threshold except Aragorn (21KB still acceptable with Core Context structure). Maintains full context while improving readability. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Update MCP server configurations and squad export - Update .copilot/mcp-config.json with enhanced MCP server definitions - Add .mcp.json for MCP client integration (untracked) - Update squad-export.json with latest team metadata Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * chore: update frodo agent history --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * chore: scribe log and decisions export (#247) * scribe: Log PR flow and merge decisions inbox - Added orchestration log for Boromir PR creation/merge attempt (PR #246) - Added session log for PR workflow (squad/scribe-log-mcp-export) - Merged 3 decision inbox files into decisions.md: * Boromir: Branch strategy (dev/main model) feasibility audit * Boromir: MCP config commit safety assessment * Frodo: Documentation audit for dev/main branch model - Cleared .squad/decisions/inbox/ (all inbox files processed) This completes the spawn manifest processing for Boromir's two-pass PR flow attempt. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * scribe: Add Aragorn adoption decision to decisions.md - Merged Aragorn's comprehensive two-branch strategy assessment - Includes GitVersion.yml configuration recommendations - Provides phased implementation roadmap (Phase 1 infrastructure, Phase 2 docs) - Clearcut approval gate: requires Matthew Paulosky sign-off - All decision inbox files now processed and cleared Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * chore: Update MCP server configurations and squad export (#246) (#250) Adopts dev/main two-branch model across all infrastructure (workflows, dependabot, pre-push, GitVersion, docs, skills). Replaces squad-promote from Node.js to .NET/GitVersion. * Add pre-push and merge playbooks, fix process documentation (#251) Add pre-push and merge playbooks, fix process documentation - New .squad/playbooks/pre-push-process.md (5-gate walkthrough) - New .squad/playbooks/pr-merge-process.md (8-step merge lifecycle) - Fix release-issuetracker.md (NBGV→GitVersion, two-branch model) - Rewrite pre-push-test-gate skill (all 5 gates, 10 test projects) - Flag 3 Squad CLI skills as non-applicable to IssueTrackerApp - Update routing.md with playbook-aware routing - Add playbook cross-references to ceremonies.md Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>" * chore: disable prerelease SDK in global.json (#254) Set allowPrerelease to false to use stable .NET SDK only. * fix: upgrade gittools/actions to v4.5.0 for GitVersion 6.7.0 compat v3.1.11 and v3 tags only support GitVersion <6.1.0, but 6.x now resolves to 6.7.0 which is out of range. Upgrade all four release workflows to gittools/actions@v4.5.0. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: upgrade gittools/actions to v4.5.0 for GitVersion 6.7.0 compat (#255) v3.1.11 and v3 tags only support GitVersion <6.1.0, but 6.x now resolves to 6.7.0 which is out of range. Upgrade all four release workflows to gittools/actions@v4.5.0. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: address 10 Copilot review items on PR #257 - Add configFilePath: GitVersion.yml to squad-promote.yml execute step - Fix shell-escaping risk: use --body-file instead of inline --body with command substitution - Replace stale embedded GitVersion YAML with link to actual file - Update Last Updated dates to 2026-04-13 - Fix Gate 0 docs: blocks main AND dev, not just main - Fix branch cleanup: reference origin/dev not origin/main (squad PRs merge to dev) - Fix conflict resolution: merge origin/dev not origin/main - Clarify tag prefix: lowercase v only triggers release workflow Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings April 12, 2026 22:34

Copilot started reviewing on behalf of mpaulosky April 12, 2026 22:35 View session

Copilot AI reviewed Apr 12, 2026

View reviewed changes

Merge branch 'dev' into squad/process-formalization-playbooks

d5171ed

mpaulosky merged commit 32cfc43 into dev Apr 12, 2026
20 checks passed

mpaulosky deleted the squad/process-formalization-playbooks branch April 12, 2026 22:46

mpaulosky mentioned this pull request Apr 13, 2026

chore: promote dev → main (v0.8.0) #256

Closed

github-actions Bot mentioned this pull request May 1, 2026

chore: promote dev → main (v0.9.0-alpha.13) #267

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add pre-push and merge playbooks, fix process documentation#251

Add pre-push and merge playbooks, fix process documentation#251
mpaulosky merged 2 commits into
devfrom
squad/process-formalization-playbooks

mpaulosky commented Apr 12, 2026

Uh oh!

github-actions Bot commented Apr 12, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 12, 2026

Uh oh!

Copilot AI Apr 12, 2026

Uh oh!

Copilot AI Apr 12, 2026

Uh oh!

Copilot AI Apr 12, 2026

Uh oh!

Copilot AI Apr 12, 2026

Uh oh!

Copilot AI Apr 12, 2026

Uh oh!

Copilot AI Apr 12, 2026

Uh oh!

Copilot AI Apr 12, 2026

Uh oh!

Copilot AI Apr 12, 2026

Uh oh!

codecov Bot commented Apr 12, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	### Phase 2 — Create Release PR
	### Phase 2 — Promote `dev` to `main`

		@@ -219,6 +233,7 @@ Fix agent: please push corrections to `{branch}` and comment when ready for re-r
		git commit -m "chore: resolve merge conflicts with main\n\nCo-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>"

Conversation

mpaulosky commented Apr 12, 2026

Summary

New Playbooks

Fixed / Rewritten

Flagged as Squad CLI Only

Config Updated

Test Results

Uh oh!

github-actions Bot commented Apr 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test Results Summary

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 12, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 12, 2026

Choose a reason for hiding this comment

Uh oh!

codecov Bot commented Apr 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

github-actions Bot commented Apr 12, 2026 •

edited

Loading

codecov Bot commented Apr 12, 2026 •

edited

Loading