diff --git a/.squad/agents/aragorn/history.md b/.squad/agents/aragorn/history.md index 433806b..4b1284c 100644 --- a/.squad/agents/aragorn/history.md +++ b/.squad/agents/aragorn/history.md @@ -366,3 +366,91 @@ Full structured investigation (20 ideas, prioritised) written to: **Key Decisions:** Approved — aligns with VSA abstraction principles. Boromir to review Phase 3. Frodo to document public generic skill. **Merged to decisions.md:** 2026-04-12T19:37:30Z + +--- + +### 2026-04-13 — Feasibility Assessment: dev/main Two-Branch Strategy + +**Context:** Matthew Paulosky requested a read-only feasibility assessment of switching from single-branch (`main`) to two-branch (`dev` + `main`) model. Aragorn led comprehensive analysis across all documentation, workflows, squad conventions, release processes, and CI/CD pipelines. + +**Scope:** 8 documentation files, 7 GitHub Actions workflows, GitVersion.yml, pre-push hook, 4 squad skills, release playbook, squad-promote pipeline, branch protection configuration. + +**Prior Team Audits Reviewed:** +- Boromir (DevOps): Workflow/infrastructure audit — verdict: FEASIBLE, ~30 min effort, LOW risk +- Frodo (Tech Writer): Documentation audit — verdict: MODERATE impact, FEASIBLE, 3-4 hours + 15 min workflow + +**Aragorn's Lead Assessment — Key Findings:** + +1. **Infrastructure is pre-built.** `squad-promote.yml` already implements `dev → preview → main` flow. `squad-ci.yml` already triggers on `dev`. Tag-based release flow (`squad-release.yml`) is branch-agnostic. The `.copilot/skills/git-workflow/SKILL.md` already documents the three-branch model with dev-first workflow. + +2. **Three discovery areas of concern:** + - **GitVersion.yml gap:** No `dev` branch definition exists. Needs new branch config block with `is-release-branch: false`, appropriate pre-release label (e.g., `alpha`), and `source-branches: [main]`. Feature branches need `dev` added to their `source-branches`. + - **squad-promote.yml Node.js artifact:** Lines 57, 90, 95, 114 reference `package.json` for version extraction. This is a .NET project using NBGV — these lines will fail. Must be replaced with `nbgv get-version -v NuGetPackageVersion` or `dotnet nbgv get-version -v Version`. + - **squad-preview.yml is a stub:** Contains TODO placeholders. If going two-branch (skip preview), this is irrelevant. If going three-branch, it needs implementation. + +3. **Recommendation: ADOPT WITH ADJUSTMENTS — Two-branch model (`dev` + `main`), defer `preview` tier.** + +**Changes Required (by category):** + +| Category | Item | Effort | Priority | +|----------|------|--------|----------| +| Branch creation | Create `dev` branch from `main` HEAD | 1 min | P0 | +| GitVersion.yml | Add `dev` branch config, update feature source-branches | 10 min | P0 | +| Pre-push hook | Gate 0: block `dev` AND `main` | 2 min | P0 | +| squad-test.yml | Add `dev` to push trigger | 2 min | P0 | +| CONTRIBUTING.md | 3 line changes + new release section | 30 min | P1 | +| New Work process.md | 3 line changes + release flow section | 30 min | P1 | +| squad-promote.yml | Fix `package.json` → NBGV version extraction | 15 min | P1 | +| GitHub branch protection | Protect `dev` (squash-only, required checks) | 5 min | P0 | +| Dependabot config | Verify targeting `dev` not `main` | 5 min | P1 | +| merged-pr-guard skill | Update "sync to main" → "sync to dev" | 5 min | P2 | +| release playbook | Update single-branch references → two-branch | 20 min | P2 | + +**Risk Assessment:** 🟢 LOW — All three auditors (Aragorn, Boromir, Frodo) independently reached FEASIBLE verdict. No architectural blockers. Framework is 80% pre-built. + +**Decision:** Filed to `.squad/decisions/inbox/aragorn-dev-main-branching.md` + +**Learnings:** +- Squad infrastructure was designed for multi-branch from the start (promote, ci, preview workflows all pre-positioned) +- The `.copilot/skills/git-workflow/SKILL.md` already documents the target model — it was aspirational, not descriptive +- GitVersion.yml is the most technically nuanced change — pre-release labeling strategy affects SemVer output for all builds on `dev` +- squad-promote.yml contains Node.js artifacts (`package.json` version reads) that will fail in this .NET project — template debt from original squad framework +- Three prior assessments (Aragorn, Boromir, Frodo) converged on same verdict independently — strong signal + +--- + +### 2026-04-12 — dev/main Branching Model Review (Architectural Lead) + +**Context:** Matthew Paulosky requested team review of adopting `dev` as active development branch and `main` as release-only. Three-agent concurrent review: Aragorn (full), Aragorn (fast), Boromir (CI/CD), Frodo (docs). + +**Aragorn's Role:** Full architectural and governance review (claude-opus-4.6, background). + +**Analysis Scope:** +- Repository structure impact (branch naming, protection rules, role contract) +- CI/CD workflow implications (multi-branch triggers, promote flow, release gating) +- Release process alignment (tag-based triggers, version numbering, production deployment) +- Team collaboration patterns (PR routing, review expectations, developer workflows) +- Risk assessment and contingency planning + +**Key Recommendations:** +1. **Adopt** — branch model is architecturally sound and alignment with squad framework +2. Treat `dev` as default PR merge target (change from `main`) +3. Update pre-push protection rules to gate on BOTH `dev` and `main` +4. Simplify preview/promotion assumptions in workflows — use explicit branch gating, not heuristics +5. Clear team communication on branch contracts: dev = "unstable", main = "production-ready" + +**Architectural Findings:** +- Squad infrastructure was designed for multi-branch from the start; promote/ci/preview workflows pre-positioned +- `.copilot/skills/git-workflow/SKILL.md` already documents the target model — was aspirational, now descriptive +- GitVersion.yml pre-release labeling strategy is key nuance for dev builds (affects SemVer output) +- squad-promote.yml contains Node.js artifacts that will fail in this .NET project — template debt + +**Coordination:** +- Fast verdict (Haiku) confirmed adoption path +- Boromir validated CI/CD feasibility with minimal friction +- Frodo assessed moderate documentation impact +- Coordinator synthesis: trending toward adoption with workflow/docs adjustments + +**Output:** Detailed technical analysis, risk matrix, implementation roadmap filed to `.squad/orchestration-log/2026-04-12T20-17-00Z-aragorn-full-review.md` and `.squad/decisions.md`. + +**Status:** ✅ Complete — Recommendation merged to team decisions. diff --git a/.squad/agents/boromir/history.md b/.squad/agents/boromir/history.md index 862027b..b295f8b 100644 --- a/.squad/agents/boromir/history.md +++ b/.squad/agents/boromir/history.md @@ -173,3 +173,66 @@ **Key Learning:** Combine three discovery tiers (gh metadata, filesystem patterns, user interaction) for robust, flexible runtime inference. **Merged to decisions.md:** 2026-04-12T19:37:30Z + +--- + +### 2026-04-13 — Branch Strategy Audit: `dev` / `main` Model Feasibility + +**By:** Boromir (DevOps) + +**Request:** Matthew Paulosky asked team to evaluate shifting to `dev` (active development, squash merge) and `main` (releases only, merge commit) model. + +**Audit Scope:** Read-only audit of workflows, pre-push hook, branch protection, release tagging, documentation, edge cases. + +**Key Findings:** + +1. **Workflows already multi-branch capable** — squad-promote.yml (dev→preview→main), squad-ci.yml (PR to dev/preview/main/insider), squad-test.yml (any branch). +2. **Pre-push hook Gate 0 currently blocks only `main`** — must extend to block both `dev` and `main` (one-line change in `.github/hooks/pre-push`). +3. **.squad/ path guard already in squad-promote** — .squad/ files correctly stripped on dev→preview merge; never reach main. +4. **Release flow (tag-based) branch-agnostic** — squad-release.yml triggers on `v*.*.*` tags (detached from branch). +5. **Documentation needs updates** — CONTRIBUTING.md: "Create branch from dev" (not main), "PR targets dev" (not main), add release section explaining dev→main flow. +6. **GitHub branch protection must be configured on `dev`** — squash-only merge, required checks, same gates as main. +7. **Dependabot configuration** — if Dependabot targets main, must reconfigure to target dev (avoid bypassing integration branch). +8. **Coverage & blog workflows** — already main-only; remain unchanged (release artifacts). + +**Risk Assessment:** 🟢 **LOW** — Framework already built for multi-branch; activating one more integration branch. + +**Effort:** ~30 min (pre-push hook, docs, GitHub settings). + +**Verdict:** **FEASIBLE WITH MINOR CHANGES** — No architectural blockers, no workflow rewrites, minimal config changes. + +**Decision file:** `.squad/decisions/inbox/boromir-dev-main-workflows.md` + +--- + +### 2026-04-12 — dev/main Branching Model Review (CI/CD Assessment) + +**Context:** Matthew Paulosky requested team review of adopting `dev` as active development branch and `main` as release-only. Three-agent concurrent review coordinated by Aragorn. + +**Boromir's Role:** CI/CD and workflow feasibility assessment (claude-haiku-4.5, background). + +**Audit Scope:** Read-only audit of existing workflows, pre-push hook, branch protection, release tagging, documentation, edge cases. + +**Key Findings:** +1. **Workflows already multi-branch capable** — squad-promote.yml (dev→preview→main), squad-ci.yml (PR to dev/preview/main/insider), squad-test.yml (any branch push/PR) +2. **Pre-push hook Gate 0 blocks only `main` currently** — must extend to block both `dev` and `main` (one-line change in `.github/hooks/pre-push`) +3. **.squad/ path guard already in squad-promote** — .squad/ files correctly stripped on dev→preview merge; never reach main +4. **Release flow (tag-based) is branch-agnostic** — squad-release.yml triggers on `v*.*.*` tags detached from branch +5. **GitHub branch protection must be configured on `dev`** — squash-only merge, required checks, matching main rules +6. **Dependabot configuration** — if targeting main, must reconfigure to target dev (avoid bypassing integration branch) +7. **Coverage & blog workflows** — already main-only; remain unchanged (release artifacts only) + +**Risk Assessment:** 🟢 **LOW** — Framework already built for multi-branch; activating one more integration branch with no architectural blockers. + +**Effort:** ~30 min (pre-push hook, docs, GitHub settings). + +**Verdict:** **FEASIBLE WITH MINIMAL FRICTION** — No workflow rewrites, minimal config changes, all changes well-understood. + +**Coordination:** +- Aligns with Aragorn's full architectural review +- Frodo handling documentation updates +- Three independent audits converged on same verdict — strong signal + +**Output:** Technical feasibility document filed to `.squad/orchestration-log/2026-04-12T20-17-00Z-boromir-workflows.md` and `.squad/decisions.md`. + +**Status:** ✅ Complete — Recommendation merged to team decisions. diff --git a/.squad/decisions.md b/.squad/decisions.md index e3cf859..afa7c2d 100644 --- a/.squad/decisions.md +++ b/.squad/decisions.md @@ -1860,3 +1860,224 @@ Replaced the content of `.squad/skills/release-process/SKILL.md` with a concise - `.squad/playbooks/release-issuetracker.md` — IssueTrackerApp playbook (already exists) **Source:** `.squad/decisions/inbox/frodo-release-process-legacy-stub.md` (merged 2026-04-12) + +--- + +## Branch Strategy: dev/main Two-Branch Model + +**Author:** Boromir (DevOps) +**Date:** 2026-04-13 +**Status:** ✅ Audit Complete — Feasible + +### Proposal + +Implement a two-branch release model: +- **dev**: Active development branch — all feature/squad branches merge via **squash merge** +- **main**: Release-only branch — dev merges into main via **merge commit**, then tag + GitHub Release + +### Current State + +Repository already operates a **multi-branch model**: +- main — protected, squash-only merge +- preview — staging, manually promoted from dev +- insider — canary, auto-promoted on push +- squad/* — feature branches (current integration point: PR to main) + +**Key infrastructure already in place:** +- squad-promote.yml workflow (dev → preview → main promotions) +- .squad/ path stripping on preview merge (forbidden paths never reach main) +- Tag-based release flow (squad-release.yml triggers on v*.*.*) +- Multi-branch CI (squad-ci.yml runs on dev/preview/main/insider) + +### Audit Findings + +**No Workflow Rewrites Needed** — Existing infrastructure supports this model. + +**Pre-Push Hook Gate 0: One-Line Change** +- Current: blocks main only +- Required: block both dev and main + +**.squad/ Path Guard Already Correct** — Already strips on dev → preview merge. + +**Documentation Updates Required** (CONTRIBUTING.md): +1. Line 101 — Branch naming section +2. Line 120 — Create branch section (from dev, not main) +3. Line 431 — PR process section (target dev) +4. New section — Add release flow documentation + +**GitHub Branch Protection Configuration** (admin task): +- Protect dev branch with same rules as main +- Require status checks, squash-only merges, auto-delete head branches + +### Risk Assessment + +| Risk | Severity | Mitigation | +|------|----------|-----------| +| Gate 0 pre-push hook not updated | Medium | One-line change | +| dev branch not protected | Medium | Admin configures | +| Dependabot bypasses dev | Low | Verify config | +| Release tagged from dev | Low | Enforce discipline | +| Documentation out of date | Low | Update CONTRIBUTING.md | + +### Verdict + +**✅ FEASIBLE** — Effort ~30 minutes; Risk: LOW. Framework already built for this. + +**Source:** .squad/decisions/inbox/boromir-dev-main-workflows.md (merged 2026-04-12) + +--- + +## MCP Configuration Commit Safety + +**Author:** Boromir (DevOps) +**Date:** 2026-04-12 +**Decision:** Committed MCP configuration files to squad/scribe-log-mcp-export +**Verdict:** ✅ SAFE + +### Files Committed + +- .copilot/mcp-config.json (modified) +- .mcp.json (new, untracked) +- squad-export.json (modified) + +### Safety Assessment + +All three files are **safe to commit**: + +- **.copilot/mcp-config.json and .mcp.json:** MCP server configurations reference CONTEXT7_API_KEY only via input:CONTEXT7_API_KEY (VS Code input prompt). No hardcoded credentials. +- **squad-export.json:** Team metadata (agent charters, capabilities, decisions). No secrets embedded. + +### Commit Hash + +e8b1c22 on squad/scribe-log-mcp-export + +**Security:** 🟢 No exposure risk; no credential leakage. + +**Source:** .squad/decisions/inbox/boromir-mcp-config-commit.md (merged 2026-04-12) + +--- + +## Documentation Audit: dev/main Branch Strategy + +**Author:** Frodo (Tech Writer) +**Date:** 2026-04-12 +**Status:** ✅ Recommended + +### Executive Summary + +Reviewed 8 documentation files and 22 GitHub workflows to assess dev/main branch model impact. **Verdict: MODERATE documentation impact, FEASIBLE to implement.** + +### Critical Updates (Must-do) + +1. CONTRIBUTING.md Line 122 — Create branch from dev (not main) +2. CONTRIBUTING.md Lines 150–156 — Gate 0 protects dev AND main +3. CONTRIBUTING.md Line 431 — PR targets dev (features) or main (releases) +4. docs/New Work process.md Line 30 — Branch from origin/dev +5. docs/New Work process.md Line 115 — Merge to dev before sprint +6. docs/New Work process.md New Section — Add Release Flow documentation +7. squad-test.yml Workflow — Add dev to push trigger branches + +### Impact Classification + +| Metric | Assessment | +|--------|-----------| +| Severity | MODERATE | +| Files to update | 4 primary; 1 optional | +| Workflow updates | 1 (squad-test.yml) | +| Breaking changes | None | +| Estimated effort | 3–4 hours (docs) + 15 min (workflow) | +| Risk | Low | +| Recommendation | **PROCEED** with dev/main model | + +### Implementation Roadmap + +**Phase 1:** Update CONTRIBUTING.md (root) and docs/New Work process.md +**Phase 2:** Update squad-test.yml (add dev to push triggers) +**Phase 3:** Polish docs/CONTRIBUTING.md (optional) + +### Conclusion + +Dev/main branch model is documentation-feasible. Overhead is moderate and manageable. + +**Source:** .squad/decisions/inbox/frodo-dev-main-docs-audit.md (merged 2026-04-12) + + +--- + +## Adoption Decision: dev/main Two-Branch Strategy + +**Author:** Aragorn (Lead Developer) +**Date:** 2026-04-13 +**Status:** Recommended +**Prior Audits:** Boromir (DevOps — FEASIBLE), Frodo (Tech Writer — FEASIBLE) + +### Verdict: ADOPT WITH ADJUSTMENTS + +Recommend adopting the two-branch model (dev + main), deferring the preview tier. The existing squad infrastructure is ~80% pre-built for this transition. + +### Model + +| Branch | Purpose | Merge Strategy | Protection | +|--------|---------|----------------|------------| +| dev | Integration — all squad/* branches land here | Squash merge | PR-only, CI required | +| main | Releases — tagged, published, production-ready | Merge commit (from dev) | PR-only, CI required | + +Flow: squad/{issue}-{slug} → PR → dev (squash) → release PR → main (merge commit) → git tag v*.*.* → GitHub Release + +### Evidence Summary + +Already Built (no changes needed): +- squad-ci.yml — Multi-branch (PR: dev, preview, main, insider; Push: dev, insider) +- squad-release.yml — Tag-based (v*.*.* branch-agnostic) +- squad-promote.yml — Promotion pipeline (dev→preview→main with .squad/ stripping) +- .copilot/skills/git-workflow/SKILL.md — Documents target model +- squad-milestone-release.yml — Tags from main (correct for releases) +- Release-only workflows — Main-only (blog-readme-sync, static, sync-readme) + +Requires Changes: +- Create dev branch (1 min) +- GitVersion.yml: Add dev config, add dev to feature source-branches (10 min) +- .github/hooks/pre-push: Gate 0 blocks dev AND main (2 min) +- squad-test.yml: Add dev to push triggers (2 min) +- GitHub branch protection: Protect dev (5 min, admin action) +- CONTRIBUTING.md: Update 3 sections + new release flow (30 min) +- docs/New Work process.md: Update 2 sections + release flow (30 min) +- squad-promote.yml: Replace package.json reads with NBGV (15 min) +- Dependabot: Verify targets dev (5 min) +- merged-pr-guard skill: Update refs (5 min) +- Release playbook: Update single-branch refs (20 min) + +Total estimated effort: ~2 hours (implementation + testing) + +### Key Risks + +1. GitVersion pre-release labeling: Builds on dev produce versions like 0.7.0-alpha.3. Ensure CI and consumers handle this. + +2. squad-promote.yml Node.js artifact: package.json version extraction will fail. Must replace with nbgv get-version. + +3. Stale dev after hotfix: If hotfix goes directly to main, dev must be synced back. + +4. Preview tier deferred: squad-preview.yml is stub. Recommend starting two-branch, add preview when needed. + +### Recommendation + +Proceed with implementation in two phases: + +Phase 1 — Infrastructure (P0, ~30 min): +- Create dev branch +- Update GitVersion.yml +- Update pre-push hook Gate 0 +- Update squad-test.yml +- Configure GitHub branch protection for dev + +Phase 2 — Documentation & Polish (P1, ~1.5 hours): +- Update CONTRIBUTING.md +- Update docs/New Work process.md +- Fix squad-promote.yml +- Update release playbook +- Update merged-pr-guard skill +- Verify Dependabot + +**Approval Required:** Matthew Paulosky (repository owner) + +**Source:** .squad/decisions/inbox/aragorn-dev-main-branching.md (merged 2026-04-12)