mergeguide 1.0.0

AI governance platform — policy enforcement for AI-assisted development. Four enforcement layers (IDE, MCP, Git hooks, PR Gate), 739 detection rules, 18+ compliance frameworks.

MergeGuide

Product: MergeGuide Status: Inception Origin: Pivot from BCP (Build Control Plane) Phase 30 postmortem Date: 2026-01-17

---

Executive Summary

MergeGuide is a developer-transparent governance layer that embeds policy enforcement into existing development workflows. Rather than requiring developers to adopt a new build system, MergeGuide meets developers where they already work—in their IDEs, AI assistants, Git workflows, and pull requests.

---

The Pivot: From BCP to MergeGuide

What is BCP?

BCP (Build Control Plane) is an artifact-first, AI-assisted software build system built on AWS. It uses:

• AI Consultant (Claude via Bedrock) to convert natural language into structured PRDs
• Step Functions to orchestrate a governance pipeline
• Bedrock for code generation
• CodeBuild for testing
• Contract checking for output validation
• GitHub integration for PR creation

BCP works. It successfully builds CLI tools and CRUD applications with JSON persistence through a fully automated pipeline.

The Challenge That Prompted the Pivot

During Phase 30 (Complexity Limit Discovery), we systematically tested BCP's capabilities and discovered:

1. Technical ceiling is manageable - BCP reliably handles Level 1-3 complexity (CLI tools, CRUD apps). Failures at Level 4+ (web UIs, complex parsing) have clear mitigation paths.

2. The real problem is workflow disconnection - BCP requires developers to:

   • Leave their IDE
   • Use a separate Consultant interface
   • Wait for batch pipeline execution
   • Review PRs generated by an external system

3. Modern AI-assisted development is conversational - Tools like Claude Code and GitHub Copilot enable iterative, in-context development. Developers don't want to context-switch to a separate system.

4. Governance is valuable, but the delivery mechanism matters - The contract checking, evidence artifacts, and audit trails BCP provides are genuinely useful for enterprises. But they need to be delivered transparently within existing workflows.

The Core Insight

"The governance is interesting to companies that develop software; however, BCP lives completely disconnected to how developers work."

The value of BCP is not the batch pipeline—it's the governance capabilities:

• Policy enforcement
• Contract validation
• Evidence artifacts
• Audit trails
• Complexity guardrails

These capabilities can be delivered without requiring workflow changes.

---

The MergeGuide Approach

Design Philosophy

1. Meet developers where they are - Integrate into IDEs, AI assistants, and Git workflows
2. Transparent enforcement - Governance happens automatically, not as a separate step
3. Defense in depth - Multiple layers catch issues at different points in the lifecycle
4. Shift left - Catch violations early to reduce rework and frustration
5. Fail closed at the gate - Server-side enforcement as the authoritative final check

The Four Solution Layers

Developer Intent → Code Generation → Local Commit → Push → PR → Merge
       ↓                ↓                ↓          ↓      ↓
   [IDE Plugin]    [MCP Server]     [Git Hooks]   [PR Gate]
       A                B                C            D

Option A: IDE Plugin (VS Code Extension)

• Real-time policy feedback during code authoring
• Inline warnings for violations
• Context-aware suggestions
• Advisory (developer can ignore)

Option B: MCP Server for Claude Code

• Governance tools exposed via Model Context Protocol
• AI assistant checks policies before suggesting code
• Seamless integration with Claude Code CLI
• Advisory (developer can ignore)

Option C: Git Hooks

• Pre-commit and pre-push validation
• Local enforcement before code leaves developer machine
• Bypassable with --no-verify (by design—emergencies happen)
• Distributed via package manager or org scripts

Option D: GitHub PR Gate (GitHub App)

• Server-side enforcement—cannot be bypassed
• Full PR diff analysis against org policies
• Evidence artifacts and audit trail
• Required status check for merge

Why Defense in Depth, Not Redundancy

Layer	When	What It Catches	Enforcement Level
A: IDE Plugin	During authoring	Real-time violations	Advisory
B: MCP Server	During AI generation	AI suggesting non-compliant patterns	Advisory
C: Git Hooks	Pre-commit/pre-push	Local violations	Local (bypassable)
D: PR Gate	Before merge	Everything that escaped earlier	Server (authoritative)

Each layer provides unique value:

• Different enforcement authority (advisory → local → server)
• Different feedback latency (immediate → seconds → minutes)
• Different context available (current file → staged changes → full PR)

---

Product Tiers

Tier 1: MergeGuide Essentials

• Components: PR Gate only (Option D)
• Value: Minimum viable governance with audit trail
• Target: Compliance-first organizations starting their governance journey
• Limitation: Issues caught late in cycle

Tier 2: MergeGuide Standard

• Components: PR Gate + MCP Server (D + B)
• Value: Real-time guidance during AI generation + server enforcement
• Target: Teams using Claude Code or similar AI assistants
• Benefit: Catch most issues early, guarantee enforcement

Tier 3: MergeGuide Enterprise

• Components: All four layers (A + B + C + D)
• Value: Complete shift-left + enforcement + audit
• Target: Enterprise with strict governance requirements
• Benefit: Maximum developer productivity with zero compliance escapes

---

Leveraging BCP Infrastructure

MergeGuide doesn't start from scratch. BCP provides battle-tested components:

Reusable from BCP

BCP Component	MergeGuide Use
Contract checking logic	Policy validation engine
Evidence artifact patterns	Audit trail generation
Profile system	Policy configuration
S3 artifact storage	Evidence storage
Step Functions patterns	Async processing (PR Gate)

What Changes

BCP Approach	MergeGuide Approach
Batch pipeline execution	Event-driven hooks
Separate Consultant UI	Embedded in existing tools
Full code generation	Policy validation only
PRD → Code workflow	Code → Validation workflow

---

Implementation Roadmap

Phase 1: PR Gate (Foundation)

Priority: Highest Rationale: Server-side enforcement is the authoritative layer. Start here.

1. Build GitHub App with webhook handlers
2. Implement policy engine (adapt BCP contract checking)
3. Create evidence artifact storage
4. Build admin dashboard for policy configuration
5. Deploy as SaaS or self-hosted option

Phase 2: MCP Server

Priority: High Rationale: Claude Code is the modern development experience. Integrate early.

1. Implement MCP protocol server
2. Expose governance tools (check_policy, list_violations, get_guidance)
3. Connect to same policy engine as PR Gate
4. Distribute via npm/pip package

Phase 3: Git Hooks

Priority: Medium Rationale: Covers developers not using AI assistants.

1. Create hook scripts (pre-commit, pre-push)
2. Package for easy installation (husky, pre-commit framework)
3. Connect to policy engine (local or remote)
4. Provide offline mode with cached policies

Phase 4: IDE Plugin

Priority: Lower Rationale: Highest development effort, most competitive market.

1. Build VS Code extension
2. Implement Language Server Protocol for diagnostics
3. Real-time policy checking as code changes
4. Integrate with existing linter infrastructure

---

Technical Architecture

Policy Engine (Core)

The heart of MergeGuide is a policy engine that:

• Accepts code diffs or full files
• Evaluates against configured policies
• Returns violations with remediation guidance
• Generates evidence artifacts

+---------------------------------------------------------+
|                      Policy Engine                       |
+---------------------------------------------------------+
|  Input: Code diff, file content, or PR metadata          |
|  Policies: Org-configured rules (security, style, deps)  |
|  Output: Violations[], Evidence artifact, Pass/Fail      |
+---------------------------------------------------------+
            ^                    ^                    ^
            |                    |                    |
     +------+------+      +-----+------+      +-----+------+
     |  PR Gate    |      | MCP Server  |      |  Git Hooks  |
     |  (GitHub)   |      | (Claude)    |      |  (Local)    |
     +-------------+      +------------+      +-------------+

Policy Configuration

Policies are defined per-organization and can include:

• Security: No hardcoded secrets, no vulnerable dependencies
• Dependencies: Allowed/blocked packages, version constraints
• Patterns: Required error handling, logging standards
• Complexity: Max file size, function length, cyclomatic complexity
• Custom: Organization-specific rules via plugin system

Evidence Artifacts

Every policy evaluation produces an evidence artifact:

{
  "artifact_type": "mergeguide_evaluation",
  "timestamp": "2026-01-17T15:30:00Z",
  "source": "pr_gate",
  "repository": "org/repo",
  "ref": "feature-branch",
  "commit_sha": "abc123",
  "policies_evaluated": ["security-v2", "deps-v1"],
  "result": "pass",
  "violations": [],
  "evidence_hash": "sha256:..."
}

---

Key Learnings from BCP Phase 30

What Works

1. Contract checking - Validating outputs against expected structure is reliable
2. Evidence artifacts - Immutable audit trail is valuable for compliance
3. Profile-based configuration - Different policies for different contexts
4. Fail-closed enforcement - Default deny with explicit allow is the right model

What to Avoid

1. Batch workflows - Developers want immediate feedback, not queued jobs
2. Separate UIs - Every context switch is adoption friction
3. AI code generation as core value - The market is commoditizing; governance is the differentiator
4. Complexity without escape hatches - Always provide bypass for emergencies (with audit)

Complexity Ceiling Insights

BCP's Phase 30 testing revealed that AI code generation has a complexity ceiling around Level 3 (CRUD CLI apps). This reinforces the pivot:

• Don't try to generate complex code
• Instead, validate code that developers (with AI assistance) write
• The governance layer doesn't have the same complexity constraints

---

Open Questions

1. Pricing model - Per-seat? Per-repo? Per-evaluation?
2. Self-hosted vs SaaS - Enterprise will want self-hosted; startups want SaaS
3. Policy marketplace - Should there be shareable/purchasable policy packs?
4. AI-assisted remediation - Should MergeGuide suggest fixes, or just identify violations?
5. Integration depth - How much BCP infrastructure to reuse vs. rebuild cleanly?

---

Next Steps

1. Validate PR Gate MVP - Build minimal GitHub App with basic policy checking
2. Define policy schema - How are policies defined, versioned, distributed?
3. Identify design partners - Find 2-3 organizations to pilot with
4. Competitive analysis - Map existing solutions (Snyk, SonarQube, etc.)
5. Decide build vs. buy - Which components to build, which to integrate?

---

File Index

development/
├── README.md                         # This document
├── docs/
│   ├── architecture.md               # Technical architecture details
│   ├── product_tiers.md              # Product packaging strategy
│   ├── implementation_roadmap.md     # Phased build plan
│   └── bcp_learnings.md              # Lessons from BCP Phase 30
├── reference/
│   ├── bcp_governance/               # Relevant BCP governance code
│   ├── infrastructure/               # IaC patterns from BCP
│   └── phase30_analysis/             # Phase 30 test results
├── solutions/
│   ├── pr_gate/                      # Option D specification
│   ├── mcp_server/                   # Option B specification
│   ├── ide_plugin/                   # Option A specification
│   └── git_hooks/                    # Option C specification
└── hydration/
    └── mergeguide_index.md           # Hydration index for Claude Code

---

References

• BCP Phase 30 Complexity Testing: reference/phase30_analysis/
• BCP Contract Check Implementation: reference/bcp_governance/contract_check/
• BCP Evidence Patterns: reference/bcp_governance/evidence_patterns/
• Model Context Protocol: https://modelcontextprotocol.io/