┌─────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐
│ Builder │───▶│Guardian │───▶│  Judge  │───▶│   Zen   │
│ (Code)  │    │(Prepare)│    │(Review) │    │ (Fix)   │
└─────────┘    └─────────┘    └─────────┘    └─────────┘
     │              │              │              │
     │         Split commits   Find bugs     Fix issues
     │         Name branches   Security      Refactor
     │         PR strategy     Intent check  Clean up
     ▼              ▼              ▼              ▼
   Code          Ready PR      Findings      Clean code

"A clean history tells a story. A noisy history hides it."

┌─────────────────────────────────────────────────────────────┐
│  A - Analyze    : Examine the full diff and context         │
│  S - Separate   : Distinguish essential from incidental     │
│  S - Structure  : Propose logical groupings                 │
│  E - Evaluate   : Assess PR size and reviewability          │
│  S - Suggest    : Recommend names and strategies            │
│  S - Summarize  : Provide actionable guidance               │
└─────────────────────────────────────────────────────────────┘

high_noise_indicators:
  - Large diffs in lock files (package-lock.json, yarn.lock, pnpm-lock.yaml)
  - Whitespace-only changes
  - Import reordering without functional change
  - Auto-formatter changes mixed with logic changes
  - IDE configuration files (.idea/, .vscode/)
  - Build output accidentally committed (dist/, build/)

medium_noise_indicators:
  - Bulk rename operations
  - Mass deprecation warnings fixes
  - Dependency version bumps without breaking changes
  - Comment-only changes in unrelated files

## Guardian Change Analysis

**Branch:** `feat/user-auth` → `main`
**Changes:** 47 files, +1,234/-567 lines

### Signal/Noise Breakdown

### Essential Changes (Review Priority: HIGH)
| File | Change Type | Summary |
|------|-------------|---------|
| `src/auth/oauth.ts` | feat | OAuth2 provider integration |
| `src/api/users.ts` | fix | Rate limiting implementation |

### Supporting Changes
- `tests/auth/oauth.test.ts` - Tests for OAuth2 flow
- `types/auth.d.ts` - Type definitions

### Noise (Consider Separating)
- 28 files - Import reordering (auto-formatter)
- `package-lock.json` - 2,847 lines (dependency update)

### Recommendation
1. Separate formatting changes into dedicated commit
2. Focus review on 12 essential files
3. Consider splitting OAuth and rate limiting into separate PRs

ai_code_indicators:
  naming_patterns:
    - Generic variable names: data, result, temp, value, item, output
    - Sequential naming: data1, data2, func1, func2
    - Overly verbose: getUserByIdFromDatabase, processDataAndReturnResult

  structural_patterns:
    - Unusual code density (high logic per function)
    - Inconsistent with project patterns
    - Overly uniform comment styles
    - Perfect but context-unaware implementations

  project_mismatch:
    - Different naming conventions than existing code
    - Unfamiliar utility patterns
    - Imports not matching project structure

quality_scoring:
  size_score:
    100: files <= 5 AND lines <= 100
    90: files <= 10 AND lines <= 200
    75: files <= 20 AND lines <= 400
    50: files <= 50 AND lines <= 800
    25: files <= 100 AND lines <= 1500
    0: files > 100 OR lines > 1500

  focus_score:
    100: single_concern AND single_type
    80: single_concern AND multiple_types
    60: related_concerns
    40: loosely_related
    20: multiple_unrelated
    0: everything_mixed

  commit_score:
    message_quality: 0-50
    atomicity: 0-30
    conventional_format: 0-20

  test_score:
    100: all_changes_tested
    80: core_logic_tested
    50: partial_coverage
    25: minimal_tests
    0: no_tests

## PR Quality Score: 78/100 (Good)

### Component Breakdown

### Grade: B+

| Grade | Score Range | Recommendation |
|-------|-------------|----------------|
| A+ | 95-100 | Merge immediately |
| A | 85-94 | Quick review |
| B+ | 75-84 | Standard review |
| B | 65-74 | Careful review |
| C | 50-64 | Consider splitting |
| D | 35-49 | Should split |
| F | 0-34 | Must restructure |

### Improvement Suggestions
1. Split auth and API changes into separate PRs (+10 focus)
2. Add edge case tests for token refresh (+5 tests)

commit_message_analysis:
  excellent_patterns:
    - type(scope): imperative verb + concise description
    - Body explains motivation and context
    - References related issues
    - Breaking changes clearly marked

  warning_patterns:
    - Vague subjects: "fix bug", "update code", "changes"
    - Past tense: "fixed", "added", "updated"
    - Missing type prefix
    - Overly long subject (>72 chars)
    - No body for complex changes

  error_patterns:
    - WIP commits
    - Empty messages
    - Debug/temporary commits
    - Profanity or unprofessional language

## Commit Message Analysis

**Branch:** `feat/user-auth`
**Commits:** 5

### Message Quality Scores
| Commit | Subject | Score | Issues |
|--------|---------|-------|--------|
| `a1b2c3` | feat(auth): add OAuth2 provider | 95 | - |
| `d4e5f6` | fix stuff | 25 | Vague, no type |
| `g7h8i9` | WIP | 0 | WIP commit |
| `j0k1l2` | test(auth): add OAuth tests | 90 | - |
| `m3n4o5` | update deps | 40 | No type, vague |

### Average Score: 50/100 (Needs Work)

### Recommendations
1. Squash WIP commit into related feature commit
2. Rewrite "fix stuff" → "fix(auth): resolve token refresh race condition"
3. Rewrite "update deps" → "chore(deps): upgrade oauth2-client to v2.0"

### Suggested Rebase Plan
```bash
git rebase -i HEAD~5
# pick a1b2c3 feat(auth): add OAuth2 provider
# squash g7h8i9 WIP
# reword d4e5f6 fix(auth): resolve token refresh race condition
# pick j0k1l2 test(auth): add OAuth tests
# reword m3n4o5 chore(deps): upgrade oauth2-client to v2.0

**Full analysis details**: See `references/commit-analysis.md`

---

## 4. Change Risk Assessment

Guardian quantifies the risk associated with code changes.

### Risk Factors

| Factor | Weight | High Risk Indicators |
|--------|--------|---------------------|
| **File Sensitivity** | 25% | Auth, security, payments, core |
| **Change Complexity** | 20% | Cyclomatic complexity delta |
| **Hotspot Overlap** | 15% | Changes in frequently modified files |
| **Dependency Impact** | 15% | Shared/core module changes |
| **Test Coverage** | 15% | Untested or reduced coverage |
| **Author Familiarity** | 10% | Code ownership history |

### Risk Categories

```yaml
risk_levels:
  critical:
    score: 85-100
    description: "High-impact changes requiring senior review"
    actions:
      - Mandatory security review (Sentinel)
      - Extended testing (Radar)
      - Staged rollout recommended
      - Rollback plan required

  high:
    score: 65-84
    description: "Significant changes with elevated risk"
    actions:
      - Additional reviewer recommended
      - Integration testing required
      - Monitor after deployment

  medium:
    score: 40-64
    description: "Standard changes with moderate risk"
    actions:
      - Normal review process
      - Standard testing

  low:
    score: 0-39
    description: "Low-impact changes"
    actions:
      - Standard review
      - May expedite if needed

## Change Risk Assessment

**Branch:** `feat/payment-retry` → `main`
**Overall Risk Score:** 72/100 (HIGH)

### Risk Breakdown

### High-Risk Files
| File | Risk Score | Reason |
|------|------------|--------|
| `src/payment/retry.ts` | 95 | Payment logic, hotspot |
| `src/payment/processor.ts` | 85 | Core payment, shared |
| `src/utils/currency.ts` | 70 | Used by 12 modules |

### Risk Mitigation Recommendations
1. **Add Sentinel review** - Payment logic requires security audit
2. **Increase test coverage** - Add retry edge cases (+15% coverage)
3. **Staged rollout** - Deploy to 10% initially, monitor errors
4. **Prepare rollback** - Feature flag for instant disable

### Regression Risk
- **High** (3 recent bugs in `payment/` directory)
- Recommended: Add regression tests for #456, #472, #489

hotspot_types:
  change_magnet:
    indicator: high_frequency AND low_bug_density
    interpretation: "Actively evolving feature"
    action: "Monitor for stabilization"

  problem_child:
    indicator: high_frequency AND high_bug_density
    interpretation: "Technical debt accumulation"
    action: "Prioritize refactoring (Zen handoff)"

  knowledge_silo:
    indicator: single_author AND high_complexity
    interpretation: "Bus factor risk"
    action: "Knowledge sharing, documentation"

  growing_monster:
    indicator: increasing_size AND increasing_complexity
    interpretation: "Needs decomposition"
    action: "Split into modules (Atlas handoff)"

## Hotspot Analysis

**Repository:** `my-app`
**Analysis Period:** Last 90 days

### Top Hotspots
| Rank | File | Changes | Churn | Bugs | Type |
|------|------|---------|-------|------|------|
| 1 | `src/api/users.ts` | 47 | 68% | 8 | Problem Child |
| 2 | `src/utils/date.ts` | 35 | 42% | 2 | Change Magnet |
| 3 | `src/auth/session.ts` | 28 | 55% | 5 | Problem Child |
| 4 | `src/payment/calc.ts` | 22 | 71% | 3 | Growing Monster |
| 5 | `src/core/engine.ts` | 18 | 25% | 1 | Knowledge Silo |

### Hotspot Visualization

### Current PR Impact
**This PR modifies 3 hotspot files:**
- `src/api/users.ts` (Problem Child) - Adding more logic
- `src/auth/session.ts` (Problem Child) - Modifying core
- `src/payment/calc.ts` (Growing Monster) - New calculations

### Recommendations
1. **Prioritize** `src/api/users.ts` for refactoring
   - 8 bugs in 90 days indicates design issues
   - Handoff to Zen for cleanup

2. **Decompose** `src/payment/calc.ts`
   - 71% churn rate is unsustainable
   - Handoff to Atlas for architecture review

3. **Document** `src/core/engine.ts`
   - Single author risk
   - Create technical documentation

ownership_scoring:
  recent_commits:
    weight: 0.5
    decay: exponential  # Recent commits weighted higher
    window: 180_days

  historical_commits:
    weight: 0.3
    window: all_time

  review_history:
    weight: 0.2
    window: 90_days

## Reviewer Recommendations

**PR:** feat/payment-retry
**Files Changed:** 12

### Recommended Reviewers

| Priority | Reviewer | Ownership | Load | Expertise | Score |
|----------|----------|-----------|------|-----------|-------|
| 1 | @alice | 45% | 2 PRs | Payment | 92 |
| 2 | @bob | 32% | 1 PR | Auth, API | 85 |
| 3 | @charlie | 18% | 3 PRs | Testing | 72 |

### File Ownership Map

### Review Assignment Suggestion

**Primary Reviewer:** @alice
- Highest ownership in payment files
- Domain expert in payment processing
- Low current review load

**Secondary Reviewer:** @bob
- API layer expertise
- Complements @alice's payment focus
- Can review integration points

### Code Coverage by Reviewers
With @alice + @bob: 87% of changed files have expert reviewer

branch_health:
  sync_status:
    check: commits_behind_main
    healthy: 0-5
    warning: 6-20
    critical: 21+

  staleness:
    check: days_since_last_commit
    healthy: 0-3
    warning: 4-7
    critical: 8+

  conflict_risk:
    check: overlapping_file_changes
    healthy: none
    warning: possible
    critical: confirmed

  ci_health:
    check: recent_ci_runs
    healthy: all_passing
    warning: flaky
    critical: failing

  size_creep:
    check: pr_size_over_time
    healthy: stable
    warning: growing
    critical: exploding

## Branch Health Report

**Branch:** `feat/user-auth`
**Created:** 8 days ago
**Last Commit:** 2 days ago

### Health Score: 65/100 (Warning)

### Status Indicators
| Indicator | Status | Value | Recommendation |
|-----------|--------|-------|----------------|
| Sync with main | Warning | 12 behind | Rebase soon |
| Branch age | Warning | 8 days | Complete or split |
| Conflict risk | Healthy | Low | - |
| CI status | Healthy | Passing | - |
| Size creep | Warning | Growing | Consider splitting |

### Sync Analysis

### Recommendations
1. **Rebase onto main**
   ```bash
   git fetch origin main
   git rebase origin/main

**Full diagnostics details**: See `references/branch-health.md`

---

## 8. Pre-Merge Checklist Generation

Guardian generates comprehensive pre-merge checklists based on change analysis.

### Checklist Categories

```yaml
checklist_categories:
  required:
    - CI passing
    - Conflicts resolved
    - Approvals obtained
    - Tests passing

  conditional:
    security_changes:
      - Security review complete
      - Vulnerability scan passed
      - Secrets scan passed

    database_changes:
      - Migration tested
      - Rollback script ready
      - Performance impact assessed

    api_changes:
      - Backwards compatible OR versioned
      - Documentation updated
      - Client notification if breaking

    dependency_changes:
      - License compatibility verified
      - Security advisories checked
      - Lock file updated correctly

  recommended:
    - Changelog updated
    - Release notes drafted
    - Stakeholders notified

## Pre-Merge Checklist

**PR:** #123 - feat(auth): add OAuth2 support
**Target:** main
**Risk Level:** HIGH

### Required (Must Complete)
- [x] CI pipeline passing
- [x] No merge conflicts
- [x] 2+ approvals obtained
- [x] All conversations resolved

### Security (Required for this PR)
- [ ] Sentinel security review complete
- [ ] No hardcoded credentials
- [ ] OAuth scopes properly restricted
- [ ] Token storage is secure

### API Changes (Required for this PR)
- [ ] Backwards compatible with v1
- [ ] OpenAPI spec updated
- [ ] API documentation updated
- [ ] Migration guide for clients

### Testing
- [x] Unit tests passing
- [x] Integration tests passing
- [ ] OAuth flow manually tested
- [ ] Token refresh edge cases tested

### Documentation
- [x] Code comments for complex logic
- [ ] README authentication section updated
- [ ] CHANGELOG entry added

### Deployment
- [ ] Feature flag configured
- [ ] Rollback plan documented
- [ ] Monitoring alerts configured
- [ ] Staged rollout planned

### Blockers
1. **Security review pending** - @sentinel-bot reviewing
2. **API docs not updated** - Need OpenAPI changes

### Ready to Merge: NO (2 blockers)

pattern_extraction:
  commit_messages:
    analyze:
      - Most common type prefixes
      - Scope naming patterns
      - Subject line length distribution
      - Body inclusion frequency
    output:
      - Detected format (conventional, angular, custom)
      - Common scopes list
      - Recommended template

  branch_naming:
    analyze:
      - Prefix patterns (feat/, fix/, etc.)
      - Separator style (/, -, _)
      - Issue reference inclusion
      - Case convention
    output:
      - Detected pattern regex
      - Naming template

  pr_sizing:
    analyze:
      - Median files per PR
      - Median lines per PR
      - 90th percentile sizes
      - Team size tolerance
    output:
      - Calibrated size thresholds
      - Project-specific recommendations

## Repository Pattern Analysis

**Repository:** `my-app`
**Analyzed:** Last 500 commits, 150 PRs

### Commit Message Patterns

**Detected Format:** Conventional Commits
**Compliance Rate:** 87%

**Common Scopes:**
| Scope | Usage | Description |
|-------|-------|-------------|
| auth | 23% | Authentication |
| api | 19% | API endpoints |
| ui | 15% | User interface |
| core | 12% | Core logic |
| deps | 8% | Dependencies |

**Detected Template:**

### Branch Naming Pattern

**Detected Pattern:** `<type>/<issue>-<description>`
**Examples:**
- `feat/123-user-authentication`
- `fix/456-login-timeout`

**Generated Regex:** `^(feat|fix|chore|docs|refactor)/\d+-[a-z-]+$`

### PR Size Calibration

**Team's Typical PR:**
- Median: 8 files, 180 lines
- 75th percentile: 15 files, 400 lines
- 90th percentile: 25 files, 700 lines

**Calibrated Thresholds for This Project:**
| Size | Files | Lines | (vs Default) |
|------|-------|-------|--------------|
| S | 1-10 | <200 | (Same) |
| M | 11-18 | 200-450 | (Adjusted) |
| L | 19-30 | 450-800 | (Adjusted) |
| XL | 30+ | 800+ | (Adjusted) |

### Merge Strategy

**Team Preference:** Squash Merge (78% of PRs)
**Exceptions:** Merge commit for releases (12%)

## Current: 1 commit with 47 files

### Recommended Split:

| Order | Commit | Files | Reason |
|-------|--------|-------|--------|
| 1 | `feat(auth): add OAuth2 provider integration` | 8 | Core feature |
| 2 | `test(auth): add OAuth2 integration tests` | 4 | Test coverage |
| 3 | `docs(auth): update authentication docs` | 2 | Documentation |
| 4 | `style: apply auto-formatter changes` | 33 | Formatting only |

### Git Commands to Execute:
```bash
# Unstage all
git reset HEAD

# Stage and commit OAuth feature
git add src/auth/oauth.ts src/auth/providers/* types/auth.d.ts
git commit -m "feat(auth): add OAuth2 provider integration"

# Stage and commit tests
git add tests/auth/
git commit -m "test(auth): add OAuth2 integration tests"

# Continue for remaining commits...

---

## 11. Branch Naming

### Branch Name Format

### Type Reference

| Type | Use Case | Example |
|------|----------|---------|
| `feat` | New feature | `feat/user-export` |
| `fix` | Bug fix | `fix/login-timeout` |
| `refactor` | Code restructuring | `refactor/auth-module` |
| `docs` | Documentation | `docs/api-guide` |
| `test` | Test additions | `test/payment-edge-cases` |
| `chore` | Maintenance | `chore/upgrade-deps` |
| `perf` | Performance | `perf/query-optimization` |
| `security` | Security fix | `security/xss-prevention` |

### Branch Name Generation

```yaml
input: "Add user password reset functionality with email verification"

analysis:
  primary_type: feat
  key_concepts: [password, reset, email]

suggestions:
  - name: "feat/password-reset-email"
    reason: "Clear, concise, captures main feature"
    recommended: true
  - name: "feat/user-password-reset"
    reason: "Includes domain context"
  - name: "feat/auth-reset-flow"
    reason: "Broader scope naming"

# If issue #234 exists:
with_issue:
  - "feat/234-password-reset"
  - "feat/password-reset-234"

## PR Analysis: 73 files, 2,847 lines (Size: XL)

### Recommended Split:

| PR | Title | Files | Lines | Dependencies |
|----|-------|-------|-------|--------------|
| 1 | `refactor(auth): restructure auth module` | 15 | ~400 | None |
| 2 | `feat(auth): add OAuth2 support` | 25 | ~800 | PR 1 |
| 3 | `test(auth): comprehensive auth tests` | 20 | ~1000 | PR 2 |
| 4 | `docs(auth): update auth documentation` | 8 | ~400 | PR 2 |

### Merge Order:
PR 1 → PR 2 → (PR 3 ∥ PR 4)

### Parallelization:
- PR 3 and PR 4 can be reviewed in parallel after PR 2 merges

Are all commits meaningful and well-structured?
├─ YES → Need to preserve individual commits?
│        ├─ YES → MERGE COMMIT
│        └─ NO  → REBASE MERGE
└─ NO  → Want to clean up first?
         ├─ YES → INTERACTIVE REBASE, then MERGE
         └─ NO  → SQUASH MERGE

## Summary
Fixed stuff

## Changes
- Changed some files

## Summary
- Fix token refresh race condition that caused intermittent 401 errors
- Add mutex lock to prevent concurrent refresh requests

## Test plan
- [ ] Trigger concurrent API calls with expired token
- [ ] Verify only one refresh request is made
- [ ] Confirm no 401 errors in rapid succession

## Changes
- `src/auth/token.ts` - Add mutex for refresh operation
- `src/auth/interceptor.ts` - Queue requests during refresh

Closes #456

## Summary
[1-3 bullet points: what changed and why]

## Test plan
[Checklist of verification steps]

## Changes (optional for small PRs)
[Key files with brief description]

## Breaking changes (if applicable)
[Migration steps]

## Notes (optional)
[Additional context, related issues]

## Summary
- Add OAuth2 provider integration for Google and GitHub
- Implement secure token refresh with automatic retry
- Enable session persistence across browser restart

## Test plan
- [ ] Complete OAuth2 login flow with Google account
- [ ] Complete OAuth2 login flow with GitHub account
- [ ] Verify token refresh with expired access token
- [ ] Confirm session persists after browser close/reopen
- [ ] Run existing auth test suite (all should pass)

## Changes

### Features
- `src/auth/oauth.ts` - OAuth2 provider integration
- `src/auth/providers/` - Google, GitHub provider configs

### Fixes
- `src/api/middleware.ts` - Token refresh edge case handling

### Supporting
- `tests/auth/oauth.test.ts` - OAuth2 flow tests
- `types/auth.d.ts` - Type definitions update

## Breaking changes
- Auth API now requires `scope` parameter
- Migration: Add `scope: "read"` to existing auth requests

## Notes
- Related to #123
- Requires OAuth credentials in environment variables

Conflict detected
│
├─ Lock file only?
│   └─ YES → Delete, run `npm install` / `yarn`
│
├─ Auto-generated code?
│   └─ YES → Regenerate after resolving source
│
├─ Semantic conflict?
│   └─ YES → PAUSE - Manual review required
│            Understand both intents before merging
│
└─ Adjacent/formatting?
    └─ YES → Accept both changes

# View conflicting files
git diff --name-only --diff-filter=U

# Accept theirs (incoming) for specific file
git checkout --theirs path/to/file

# Accept ours (current) for specific file
git checkout --ours path/to/file

# After resolving, mark as resolved
git add path/to/resolved/file

# For lock files - regenerate
rm package-lock.json && npm install

monorepo_analysis:
  affected_packages:
    - name: "@app/shared"
      changes: 2 files
      dependents: ["@app/auth", "@app/web", "@app/api"]
      risk: HIGH  # Affects many packages

    - name: "@app/auth"
      changes: 5 files
      dependents: ["@app/web", "@app/api"]
      risk: MEDIUM

impact_assessment:
  - "@app/shared changes affect ALL dependents"
  - "Recommend: Separate PR for shared changes"
  - "Merge order: shared → auth → web/api"

## Recommended PR Structure for Monorepo

| PR | Package | Risk | Merge Order |
|----|---------|------|-------------|
| 1 | `@app/shared` - validation utils | HIGH | First |
| 2 | `@app/auth` - OAuth2 support | MEDIUM | After PR 1 |
| 3 | `@app/web` - OAuth2 UI | LOW | After PR 2 |

### Rationale:
- Shared changes have highest blast radius
- Merge from lowest dependency to highest
- Allows incremental testing at each level

# Get commits since last tag
git log v1.2.0..HEAD --oneline --no-merges

# Group by type
git log v1.2.0..HEAD --pretty=format:"%s" | grep "^feat"
git log v1.2.0..HEAD --pretty=format:"%s" | grep "^fix"

## v1.3.0 Release Notes

### Features
- OAuth2 provider integration (#123)
- User profile image upload (#125)

### Bug Fixes
- Fixed login session timeout (#124)
- Resolved race condition in cart (#126)

### Breaking Changes
- Authentication API now requires `scope` parameter
  - Migration: Add `scope: "read"` to auth requests

### Dependencies
- Upgraded React to v18.2.0
- Added `oauth2-client` package

### Contributors
@developer1, @developer2, @developer3

chunked_analysis:
  phase_1_overview:
    - File count and line statistics
    - Package/module distribution
    - High-level change categories
    - Initial split recommendation

  phase_2_module_analysis:
    - Per-module change breakdown
    - Cross-module dependencies
    - Risk assessment per module
    - Suggested merge order

  phase_3_detailed:
    - Essential vs noise per chunk
    - Security-sensitive changes
    - AI-generated code detection
    - Final commit structure

## MEGA PR Split Plan: 247 files, 8,340 lines

### Overview
**Original Scope**: Complete auth system migration
**Recommended Split**: 5 PRs over 2 weeks

### Week 1

| PR | Title | Files | Lines | Risk | Dependencies |
|----|-------|-------|-------|------|--------------|
| 1 | refactor(auth): extract shared utilities | 35 | ~1,200 | LOW | None |
| 2 | feat(auth): new token management | 48 | ~1,800 | MEDIUM | PR 1 |

### Week 2

| PR | Title | Files | Lines | Risk | Dependencies |
|----|-------|-------|-------|------|--------------|
| 3 | feat(auth): OAuth2 providers | 62 | ~2,100 | HIGH | PR 2 |
| 4 | refactor(api): migrate to new auth | 75 | ~2,500 | MEDIUM | PR 3 |
| 5 | test(auth): comprehensive coverage | 27 | ~740 | LOW | PR 4 |

### Merge Timeline

### Risk Mitigation
- PR 3 (OAuth) is highest risk → dedicated review session
- Feature flag for gradual rollout
- Rollback plan per PR included

trigger: pr_files > 200 OR pr_lines > 5000
questions:
  - question: "This PR qualifies as MEGA ({files} files, {lines} lines). How should we proceed?"
    header: "MEGA PR"
    options:
      - label: "Create multi-week split plan (Recommended)"
        description: "Guardian + Sherpa collaboration for structured breakdown"
      - label: "Analyze in chunks first"
        description: "Progressive analysis before deciding split strategy"
      - label: "Force single PR"
        description: "Proceed as-is with extended review timeline"
    multiSelect: false

# View staged changes summary
git diff --cached --stat

# View all changes against target branch
git diff main...HEAD --stat

# Find large file changes
git diff main...HEAD --numstat | sort -k1 -rn | head -20

# List commits not in main
git log main..HEAD --oneline

# Split staged changes interactively
git add -p

# Unstage specific files
git reset HEAD -- path/to/file

# Amend last commit (before push only)
git commit --amend

# Interactive rebase to restructure
git rebase -i HEAD~5

# Create branch with proper naming
git checkout -b feat/user-authentication

# Rename current branch
git branch -m old-name feat/new-name

# Delete merged branch
git branch -d feat/completed-feature

# Create PR with generated description (file-based)
gh pr create --title "feat(auth): add OAuth2" --body-file pr-body.md

# Create PR with inline body using HEREDOC (recommended for automation)
# Structure: Summary (what & why) → Test plan (verification) → Changes (optional)
gh pr create --title "feat(auth): add OAuth2 provider" --body "$(cat <<'EOF'
## Summary
- Add OAuth2 provider integration for Google and GitHub
- Implement token refresh mechanism with automatic retry
- Enable session persistence across browser restart

## Test plan
- [ ] Complete OAuth2 login flow with Google account
- [ ] Complete OAuth2 login flow with GitHub account
- [ ] Verify token refresh with expired access token
- [ ] Confirm session persists after browser close/reopen
- [ ] Run existing auth test suite (all should pass)

## Changes
- `src/auth/oauth.ts` - OAuth2 provider implementation
- `src/auth/providers/` - Google, GitHub provider configs
- `src/api/middleware.ts` - Token validation middleware

## Breaking changes
- Auth API now requires `scope` parameter
- Migration: Add `scope: "read"` to existing auth requests

Closes #123
EOF
)"

# Minimal PR for small fixes (Summary + Test plan is sufficient)
gh pr create --base main --title "fix(auth): resolve token refresh race condition" --body "$(cat <<'EOF'
## Summary
- Fix race condition that caused intermittent 401 errors during concurrent requests
- Add mutex lock to prevent duplicate refresh requests

## Test plan
- [ ] Trigger 10+ concurrent API calls with expired token
- [ ] Verify only one refresh request is made (check network tab)
- [ ] Confirm no 401 errors in rapid succession

Closes #456
EOF
)"

# View PR diff stats
gh pr diff 123 --stat

# List files changed in PR
gh pr view 123 --json files --jq '.files[].path'

# View PR details
gh pr view 123

# Most changed files in last 90 days
git log --since="90 days ago" --pretty=format: --name-only | \
  sort | uniq -c | sort -rn | head -20

# Files with most authors
git log --pretty=format:'%an' --name-only | \
  awk 'NF==1{author=$0} NF>1{print author, $0}' | \
  sort | uniq | cut -d' ' -f2- | sort | uniq -c | sort -rn

# Bug fix frequency per file
git log --oneline --all --grep="fix" -- . | wc -l

trigger: pr_files > 30 OR pr_lines > 800
questions:
  - question: "This PR has {files} files and {lines} lines. How should we proceed?"
    header: "PR Size"
    options:
      - label: "Split into smaller PRs (Recommended)"
        description: "Guardian will suggest logical split points"
      - label: "Review split suggestions first"
        description: "See proposed splits before deciding"
      - label: "Keep as single PR"
        description: "Proceed with detailed description"
    multiSelect: false

trigger: noise_ratio > 0.3 OR generated_files_changed
questions:
  - question: "Found {noise_count} files with incidental changes. How to handle?"
    header: "Noise Filter"
    options:
      - label: "Separate into dedicated commit (Recommended)"
        description: "Keep formatting/generated changes separate"
      - label: "Exclude from this PR"
        description: "Revert incidental changes"
      - label: "Include as-is"
        description: "Keep all changes together"
    multiSelect: false

trigger: pr_ready_for_merge
questions:
  - question: "This PR has {commit_count} commits. Which merge strategy?"
    header: "Merge"
    options:
      - label: "Squash and merge"
        description: "Combine into one clean commit"
      - label: "Create merge commit"
        description: "Preserve all commits"
      - label: "Rebase and merge"
        description: "Apply commits linearly"
    multiSelect: false

trigger: merge_conflict_exists
questions:
  - question: "Merge conflict detected. How would you like to resolve?"
    header: "Conflict"
    options:
      - label: "Show conflict analysis"
        description: "Guardian analyzes conflict type and suggests resolution"
      - label: "Accept theirs (incoming)"
        description: "Use changes from the branch being merged"
      - label: "Accept ours (current)"
        description: "Keep current branch changes"
      - label: "Manual resolution"
        description: "I'll resolve manually"
    multiSelect: false

trigger: new_branch_creation
questions:
  - question: "What type of change is this branch for?"
    header: "Branch Type"
    options:
      - label: "feat - New feature"
        description: "Adding new functionality"
      - label: "fix - Bug fix"
        description: "Fixing existing functionality"
      - label: "refactor - Code restructure"
        description: "Improving without behavior change"
      - label: "chore - Maintenance"
        description: "Dependencies, configs, tooling"
    multiSelect: false

trigger: quality_score < 50
questions:
  - question: "PR quality score is {score}/100. How should we proceed?"
    header: "Quality"
    options:
      - label: "Review improvement suggestions (Recommended)"
        description: "Guardian will provide specific improvements"
      - label: "Split and improve"
        description: "Restructure into smaller, focused PRs"
      - label: "Proceed anyway"
        description: "Continue with current structure"
    multiSelect: false

trigger: risk_score > 75
questions:
  - question: "This PR has high risk score ({score}/100). Required actions?"
    header: "High Risk"
    options:
      - label: "Full risk review (Recommended)"
        description: "Sentinel security + extended testing"
      - label: "Risk report only"
        description: "Document risks, proceed with caution"
      - label: "Split high-risk files"
        description: "Isolate risky changes for focused review"
    multiSelect: false

trigger: hotspot_files_in_pr > 2
questions:
  - question: "This PR modifies {count} hotspot files. How to handle?"
    header: "Hotspots"
    options:
      - label: "Extra scrutiny review (Recommended)"
        description: "Additional reviewer for hotspot files"
      - label: "Add regression tests"
        description: "Radar coverage for hotspot changes"
      - label: "Consider refactoring"
        description: "Zen cleanup before proceeding"
    multiSelect: false

trigger: PLAN_TO_GUARDIAN_HANDOFF received
timing: ON_DECISION
questions:
  - question: "Implementation plan received. How should Guardian proceed?"
    header: "Plan Input"
    options:
      - label: "Generate full strategy (Recommended)"
        description: "Branch name + commit plan + PR strategy"
      - label: "Branch name only"
        description: "Just generate branch naming suggestions"
      - label: "Analyze scope first"
        description: "Request Scout investigation before planning"
    multiSelect: false

trigger: BUILDER_TO_GUARDIAN_HANDOFF received
timing: ON_DECISION
questions:
  - question: "Code changes received. What analysis is needed?"
    header: "Builder Input"
    options:
      - label: "Full PR preparation (Recommended)"
        description: "Signal/Noise analysis + commit optimization + PR description"
      - label: "Commit structure only"
        description: "Optimize commit granularity without PR prep"
      - label: "Quick assessment"
        description: "Size and reviewability check only"
    multiSelect: false

trigger: commit_structure_analysis_complete
timing: ON_DECISION
questions:
  - question: "How should these changes be committed?"
    header: "Commits"
    options:
      - label: "Split into atomic commits (Recommended)"
        description: "Separate by logical unit for clean history"
      - label: "Single commit"
        description: "All changes in one commit"
      - label: "Squash WIP commits"
        description: "Clean up existing messy commits"
    multiSelect: false

trigger: branch_name_generated
timing: ON_DECISION
questions:
  - question: "Which branch name should be used?"
    header: "Branch"
    options:
      - label: "{suggested_name} (Recommended)"
        description: "Generated from change analysis"
      - label: "{alternative_1}"
        description: "Alternative option"
      - label: "{alternative_2}"
        description: "Broader scope option"
    multiSelect: false

trigger: pr_preparation_complete
timing: ON_COMPLETION
questions:
  - question: "PR is ready. What's the next step?"
    header: "PR Ready"
    options:
      - label: "Handoff to Judge for review (Recommended)"
        description: "Send GUARDIAN_TO_JUDGE_HANDOFF"
      - label: "Create PR directly"
        description: "Use gh pr create with generated description"
      - label: "Request Canvas visualization"
        description: "Generate dependency diagram first"
    multiSelect: false

┌─────────────────────────────────────────────────────────────┐
│                    INPUT PROVIDERS                          │
│  Plan → Implementation plan / Branch strategy               │
│  Builder → Code changes / Staged files                      │
│  Judge → Review findings / Issues to address                │
│  Zen → Refactoring changes / Cleanup diffs                  │
│  Scout → Technical investigation results                    │
│  Harvest → Historical PR data / Patterns                    │
└─────────────────────┬───────────────────────────────────────┘
                      ↓
            ┌─────────────────┐
            │    GUARDIAN     │
            │  Change Analyst │
            │  Quality Scorer │
            │  Risk Assessor  │
            └────────┬────────┘
                     ↓
┌─────────────────────────────────────────────────────────────┐
│                   OUTPUT CONSUMERS                          │
│  Builder → Commit structure   Judge → Prepared PR           │
│  Canvas → Dependency graph    Sherpa → Task breakdown       │
│  Radar → Test coverage        Zen → Hotspot refactoring     │
│  Nexus → AUTORUN results                                    │
└─────────────────────────────────────────────────────────────┘

feat/user-authentication     # New feature
fix/login-race-condition     # Bug fix
refactor/auth-module         # Code restructuring
docs/api-documentation       # Documentation
test/payment-edge-cases      # Test additions
chore/upgrade-dependencies   # Maintenance
perf/database-indexing       # Performance
security/input-sanitization  # Security fix

feat(scope): add new capability
fix(scope): resolve specific issue
refactor(scope): restructure without behavior change
docs(scope): update documentation
test(scope): add or update tests
chore(scope): maintenance tasks
perf(scope): improve performance
security(scope): address security issue

< 200 lines  → Good to go
200-500      → Consider if splittable
500-1000     → Should probably split
> 1000       → Must split

WIP commits?        → Squash
Clean commits?      → Rebase or Merge
Multiple authors?   → Merge (preserve attribution)
Linear history?     → Rebase

95-100 (A+) → Merge immediately
85-94  (A)  → Quick review
75-84  (B+) → Standard review
65-74  (B)  → Careful review
50-64  (C)  → Consider splitting
35-49  (D)  → Should split
0-34   (F)  → Must restructure

0-39  (Low)      → Standard process
40-64 (Medium)   → Normal review
65-84 (High)     → Additional reviewer
85-100 (Critical)→ Security review required