Metadata-Version: 2.4
Name: mergeguide
Version: 0.1.0
Summary: Developer-transparent governance layer for policy enforcement
Author: Chuck McWhirter
License: MIT
Project-URL: Homepage, https://mergeguide.ai
Project-URL: Documentation, https://mergeguide.ai/docs
Project-URL: Repository, https://github.com/MergeGuide/mergeguide
Project-URL: Issues, https://github.com/MergeGuide/mergeguide/issues
Keywords: governance,policy,security,code-review
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: jsonschema>=4.21.0
Requires-Dist: sarif-om>=1.0.4
Requires-Dist: httpx>=0.26.0
Requires-Dist: boto3>=1.34.0
Requires-Dist: click>=8.1.0
Requires-Dist: rich>=13.7.0
Requires-Dist: PyJWT>=2.8.0
Requires-Dist: cryptography>=41.0.0
Provides-Extra: cdk
Requires-Dist: aws-cdk-lib>=2.120.0; extra == "cdk"
Requires-Dist: constructs>=10.3.0; extra == "cdk"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: ruff>=0.2.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Requires-Dist: black>=24.1.0; extra == "dev"
Requires-Dist: types-PyYAML>=6.0.0; extra == "dev"
Requires-Dist: types-requests>=2.31.0; extra == "dev"
Requires-Dist: boto3-stubs[dynamodb,lambda,s3,secretsmanager]>=1.34.0; extra == "dev"
Requires-Dist: python-dotenv>=1.0.0; extra == "dev"
Requires-Dist: watchdog>=4.0.0; extra == "dev"

# Project Sentinel

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

---

## Executive Summary

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

---

## The Pivot: From BCP to Sentinel

### 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 Sentinel 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: Sentinel 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: Sentinel 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: Sentinel 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

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

### Reusable from BCP

| BCP Component | Sentinel 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 | Sentinel 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 Sentinel 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:
```json
{
  "artifact_type": "sentinel_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 Sentinel 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

```
sentinel/
├── 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/
    └── sentinel_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/
