Skip to content

chore: scribe log and decisions export #247

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mpaulosky merged 2 commits into from
Apr 12, 2026
Merged

chore: scribe log and decisions export #247

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4c49275
scribe: Log PR flow and merge decisions inbox
mpaulosky Apr 12, 2026
72a6e6d
scribe: Add Aragorn adoption decision to decisions.md
mpaulosky Apr 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
88 changes: 88 additions & 0 deletions .squad/agents/aragorn/history.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
63 changes: 63 additions & 0 deletions .squad/agents/boromir/history.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
221 changes: 221 additions & 0 deletions .squad/decisions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Copilot AI Apr 12, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This decision text says .mcp.json is "new, untracked", but this PR adds and commits .mcp.json to the repo. Please update the wording so the decision record matches the actual state (tracked vs untracked).

Suggested change
- .mcp.json (new, untracked)
- .mcp.json (new, tracked)

Copilot uses AI. Check for mistakes.
- 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)
Loading