From f20c6edbf50d8e614ba5eca357f96099b47618cf Mon Sep 17 00:00:00 2001 From: Alex Wilkerson John Date: Fri, 10 Jul 2026 16:12:30 -0400 Subject: [PATCH 1/2] docs: add setup guide and restyle README as OSS tool Add docs/getting-started.md covering install paths, first scan, MCP, GitHub Action, and local control-plane setup. Rewrite README.md to match the devr-tools OSS style (badges, What it does, Install, Quickstart, SDK), moving operational detail into the setup guide. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 248 ++++++++++++++++++---------------------- docs/getting-started.md | 176 ++++++++++++++++++++++++++++ 2 files changed, 285 insertions(+), 139 deletions(-) create mode 100644 docs/getting-started.md diff --git a/README.md b/README.md index da18884..40e5e7d 100644 --- a/README.md +++ b/README.md @@ -1,67 +1,91 @@

- MergeR logo + merger logo

-# Merger +

+ CI status + CD status + + release version + + + Go Reference + + + Go Report Card + + Apache 2.0 license + + LinkedIn + +

-Merger is a mutation control plane for AI-native engineering organizations. It converts pull requests into structured Change Packets, classifies semantic mutations, estimates blast radius and rollout risk, applies policy, and assigns a merge lane that reflects how changes should safely propagate. +# merger -It is not a code review bot. The design center is operational coordination at a scale where autonomous agents can generate more software mutations than humans can inspect manually. +`merger` is a Go-native mutation control plane and CLI for AI-native engineering +organizations. It turns a pull request diff into a structured **Change Packet** — +classifying semantic mutations, estimating blast radius and rollout risk, applying +policy, and assigning a **merge lane** that reflects how a change should safely +propagate. -## Open-Source Shape +It is not a code review bot. The design center is operational coordination at a +scale where autonomous agents generate more software mutations than humans can +inspect by hand. -Merger is being built as an open-source platform core. The repository includes first-party implementations for GitHub, NATS, and PostgreSQL, but the extension seams are public so other organizations can plug in their own SCM systems, topology sources, event backbones, analyzers, and persistence adapters. +## What it does -See [docs/extending-merger.md](/Users/alex/Documents/GitHub/merger/docs/extending-merger.md:1) for the current extension surface. +- parses a PR diff into normalized changed files +- detects semantic mutations from path rules, patch signals, and structured analyzers +- resolves a runtime graph and estimates blast radius from topology hints and `CODEOWNERS` +- computes a weighted risk score and a policy decision from composable YAML rules +- assigns a merge lane — `GREEN`, `YELLOW`, `RED`, or `BLACK` +- runs the same pipeline three ways: offline CLI, embeddable SDK, and a full control plane -## Phase 1 Foundation +## Install -This repository scaffolds the first production-oriented control plane slice: +Recommended (Go): -- GitHub webhook ingest -- PR diff parsing -- Change Packet generation -- Rule-based semantic mutation detection -- Risk scoring -- Merge lane assignment -- YAML-backed policy evaluation -- GitHub Check Run publishing abstraction -- Internal event bus abstraction -- Structured logging and trace-ready instrumentation +```bash +go install github.com/devr-tools/merger/cmd/merger@latest +merger version +``` -## CLI +Other install paths: -The `merger` CLI is the local, installable face of the control plane. It runs -the same analysis pipeline offline — no services, database, or event bus -required — so you can classify a diff and preview its merge lane from a laptop -or a CI job. +- GitHub Releases: tagged archives for direct download +- Homebrew: `brew install devr-tools/tap/merger` +- GitHub Marketplace Action: `Devr Merger` +- Source build: `make build` -```bash -go install github.com/devr-tools/merger/cmd/merger@latest -# or: brew install devr-tools/tap/merger +Full setup — including the local control plane, toolchain bootstrap, and the +GitHub Action — lives in [docs/getting-started.md](docs/getting-started.md). + +## Quickstart + +The CLI runs the analysis pipeline offline — no services, database, or event bus +required — so you can classify a diff and preview its merge lane from a laptop or +a CI job: +```bash merger init # scaffold .merger/ config + policy merger validate # check config and policy resolve merger scan -base-ref origin/main # analyze the diff vs a base ref merger scan -diff change.diff -format json ``` -`merger scan` parses a unified diff (from `-diff ` or a -`-base-ref ` git range), runs mutation detection, runtime-graph, risk, -policy, and lane assignment, and prints a report (`-format text|json`). Pass -`-fail-on-lane RED` to exit non-zero when a change lands in a given lane or -higher — useful as a CI gate. - -Configuration is auto-discovered from `merger.yaml` or `.merger/merger.yaml` -(see [internal/cli](/Users/alex/Documents/GitHub/merger/internal/cli:1) and the -offline pipeline in [internal/scan](/Users/alex/Documents/GitHub/merger/internal/scan/scan.go:1)). +`merger scan` parses a unified diff (from `-diff ` or a `-base-ref ` +git range), runs mutation detection, runtime-graph, risk, policy, and lane +assignment, and prints a report (`-format text|json`). Pass `-fail-on-lane RED` +to exit non-zero when a change lands in a given lane or higher — a ready-made CI +gate. +Configuration is auto-discovered from `merger.yaml` or `.merger/merger.yaml`. `merger mcp` serves the same analysis as agent tools over the Model Context Protocol (stdio) — see [docs/mcp.md](docs/mcp.md). ## SDK -The same offline pipeline is available as a library from +The offline pipeline is available as a library from `github.com/devr-tools/merger/pkg/merger`: ```go @@ -89,37 +113,34 @@ func main() { Load a policy rule set with `merger.LoadPolicy(path)` and pass it as `ScanOptions.Policy`. See [docs/sdk.md](docs/sdk.md). -## Architecture - -The repository is organized around domain boundaries instead of a single service package: - -- `cmd/merger-ingest`: HTTP ingress for GitHub pull request webhooks. -- `cmd/merger-controlplane`: control-plane process for downstream orchestration and subscriptions. -- `internal/domain`: strongly typed core models such as `ChangePacket`, `Mutation`, `Risk`, and `PolicyDecision`. -- `internal/ingest`: request handling and Change Packet assembly. -- `internal/mutations`: semantic mutation engine and signal extractors. -- `internal/risk`: weighted risk scoring and risk summary generation. -- `internal/policy`: YAML-backed policy evaluation. -- `internal/lanes`: merge lane assignment. -- `internal/runtimegraph`: runtime graph contracts and pluggable topology sources. -- `internal/github`: GitHub App auth, webhook verification, PR/diff fetch, file content fetch, and check publishing. -- `internal/events`: async-friendly event bus abstraction with memory and NATS JetStream implementations. -- `internal/store`: PostgreSQL-backed persistence for Change Packets and emitted events. -- `internal/bootstrap`: provider construction for first-party adapters. -- `internal/telemetry`: structured logging, correlation IDs, and trace-ready interfaces. -- `pkg/diff`: unified diff parsing reusable across services. -- `pkg/merger`: public aliases for core MergeR types. -- `pkg/extensions`: public provider interfaces for open-source extension. -- `tests/`: black-box and package-level tests kept separate from source packages. - -## Merge Lane Model - -- `GREEN`: isolated, low-risk mutation with automated evidence and no mandatory human escalation. -- `YELLOW`: standard review path. -- `RED`: high-risk or owner/security-gated change. -- `BLACK`: blocked; decomposition, rework, or policy exception required. - -## Change Packet Flow +## Merge lane model + +- `GREEN` — isolated, low-risk mutation with automated evidence and no mandatory human escalation. +- `YELLOW` — standard review path. +- `RED` — high-risk or owner/security-gated change. +- `BLACK` — blocked; decomposition, rework, or policy exception required. + +Policies are YAML and intentionally composable: + +```yaml +policies: + - name: auth_requires_security_review + when: + mutations: + - auth_behavior_change + require: + reviewers: + - security + evidence: + - auth_integration_tests + deployment: + strategy: canary + requires_canary: true + action: + minimum_lane: RED +``` + +## Change Packet flow ```mermaid flowchart LR @@ -153,85 +174,34 @@ flowchart LR lane --> bus ``` -1. GitHub sends a `pull_request` webhook. -2. The ingest service creates a correlation-aware processing context. -3. Pull request metadata, diff, and file content are fetched through the GitHub App adapter. -4. The diff parser produces normalized changed files. -5. The mutation engine combines path rules, patch signals, and AST/structured analyzers. -6. Runtime graph sources ingest topology hints such as deploy manifests and `CODEOWNERS`. -7. The risk engine computes risks and an aggregate risk score. -8. The policy engine resolves reviewers, evidence, deployment constraints, and blockers. -9. The lane assigner selects `GREEN`, `YELLOW`, `RED`, or `BLACK`. -10. Change Packets and event envelopes are persisted in PostgreSQL. -11. A GitHub Check Run summary is published and internal events are emitted through NATS JetStream. +See [docs/flows/github-webhook-flow.md](docs/flows/github-webhook-flow.md) for +the detailed flow and [docs/examples/change-packet.json](docs/examples/change-packet.json) +for a sample Change Packet. -See [docs/flows/github-webhook-flow.md](/Users/alex/Documents/GitHub/merger/docs/flows/github-webhook-flow.md:1) for the detailed flow and [docs/examples/change-packet.json](/Users/alex/Documents/GitHub/merger/docs/examples/change-packet.json:1) for a sample Change Packet. +## Open-source shape -## Policy Example +merger is built as an open-source platform core. The repository ships first-party +implementations for GitHub, NATS, and PostgreSQL, but the extension seams are +public so other organizations can plug in their own SCM systems, topology sources, +event backbones, analyzers, and persistence adapters. See +[docs/extending-merger.md](docs/extending-merger.md) for the current extension +surface. -Policies are YAML and intentionally composable: +## Docs -```yaml -policies: - - name: auth_requires_security_review - when: - mutations: - - auth_behavior_change - require: - reviewers: - - security - evidence: - - auth_integration_tests - deployment: - strategy: canary - requires_canary: true - action: - minimum_lane: RED -``` - -## Local Development - -Merger now requires Go `1.25.10` for local development and CI. That upgrade is part of the security baseline, not an optional tooling preference. - -Bootstrap the expected toolchain into your shell before running repo commands: - -```bash -eval "$(./scripts/dev/use-go-1.25.10.sh)" -go version -``` - -That helper installs the `go1.25.10` launcher if needed, downloads the toolchain into `$HOME/sdk/go1.25.10`, and exports `GOROOT`, `PATH`, and `GO` for the current shell. - -After that one-time install, plain `make` targets will automatically prefer `$HOME/sdk/go1.25.10/bin/go` when it exists, so `make ci` does not depend on your shell defaulting to the right Go version. - -Use the provided compose stack for platform dependencies: - -```bash -make compose-up -make run-ingest -make run-controlplane -``` - -Default services: - -- Ingest HTTP: `:8080` -- Control-plane HTTP: `:8081` -- Control-plane gRPC: `:9091` -- PostgreSQL: `:5432` -- Redis: `:6379` -- NATS: `:4222` - -Suggested verification: - -```bash -make verify -``` +- [Getting started](docs/getting-started.md) +- [SDK guide](docs/sdk.md) +- [MCP server](docs/mcp.md) +- [Extending merger](docs/extending-merger.md) +- [GitHub webhook flow](docs/flows/github-webhook-flow.md) +- [Release automation](docs/release-automation.md) +- [Contributing](CONTRIBUTING.md) +- [Security](SECURITY.md) -## Near-Term TODOs +## Roadmap - Add Kafka and non-GitHub SCM providers to validate the public extension model. - Expand runtime graph ingestion from service catalogs, deployment systems, and ownership registries. - Add analyzer SDK examples for out-of-tree semantic detectors. - Introduce replay workers and outbox-based delivery guarantees. - Learn policy weights and lane thresholds from deploy outcomes and incident history. -- Upgrade generated protobuf plugins in lockstep with future gRPC releases. diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..5f1285a --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,176 @@ +# Getting Started + +This guide covers installing `merger`, running your first scan, and standing up +the full control plane locally. If you only want to classify a diff and preview +its merge lane, you can stop after [Install](#install) and [First scan](#first-scan) +— no services, database, or event bus required. + +## Prerequisites + +| Use case | Requirements | +| --- | --- | +| CLI / SDK | Go `1.25+` (only to build from source or `go install`; prebuilt binaries need nothing) | +| Local control plane | Docker + Docker Compose, Go `1.25.10` | +| GitHub Action | None — the action installs `merger` for you | + +## Install + +Recommended (Go): + +```bash +go install github.com/devr-tools/merger/cmd/merger@latest +merger version +``` + +Other install paths: + +- **GitHub Releases** — tagged archives for direct download +- **Homebrew** — `brew install devr-tools/tap/merger` +- **GitHub Marketplace Action** — `Devr Merger` (see [GitHub Action](#github-action)) +- **Source build** — `make build` produces `./bin/merger` + +## First scan + +`merger` runs the same analysis pipeline the control plane uses, entirely +offline. Scaffold a config, validate it, then scan a diff: + +```bash +merger init # scaffold .merger/ config + policy +merger validate # check config and policy resolve +merger scan -base-ref origin/main # analyze the diff vs a base ref +``` + +You can also feed a diff file (or stdin) directly and choose an output format: + +```bash +merger scan -diff change.diff -format json +git diff main...HEAD | merger scan -diff - -format text +``` + +Use `merger scan` as a CI gate by failing on a lane threshold: + +```bash +merger scan -base-ref origin/main -fail-on-lane RED +``` + +This exits non-zero when the assigned lane is at or above `RED`. + +### Configuration discovery + +`merger` auto-discovers configuration from, in order: + +1. `merger.yaml` in the repository root +2. `.merger/merger.yaml` + +Point `-config` at an explicit file or a directory (such as `.merger`) to +override discovery. Policies default to the config's policy path; override with +`-policy `. + +A minimal, composable policy looks like: + +```yaml +policies: + - name: auth_requires_security_review + when: + mutations: + - auth_behavior_change + require: + reviewers: + - security + evidence: + - auth_integration_tests + deployment: + strategy: canary + requires_canary: true + action: + minimum_lane: RED +``` + +## MCP server + +Serve the same offline analysis as agent tools over the Model Context Protocol +(stdio): + +```bash +merger mcp +``` + +Point an MCP client at the `merger mcp` command as a stdio server. See +[docs/mcp.md](mcp.md) for the tool contract. + +## GitHub Action + +Add the `Devr Merger` action to gate pull requests on their assigned lane: + +```yaml +- uses: devr-tools/merger@v1 + with: + base-ref: ${{ github.base_ref }} + fail-on-lane: RED +``` + +| Input | Default | Description | +| --- | --- | --- | +| `base-ref` | `main` | Base ref to diff against (`git diff ...HEAD`) | +| `config` | auto-discover | Path to a config file or directory | +| `repo-root` | `.` | Repository root for content lookups and relative paths | +| `format` | `text` | Output format (`text` or `json`) | +| `fail-on-lane` | report only | Fail when the assigned lane is at or above this lane | +| `version` | `latest` | `merger` version to install | + +## Run the control plane locally + +The full control plane (webhook ingest, persistence, event bus) needs the local +toolchain and the Compose stack for platform dependencies. + +### 1. Bootstrap the toolchain + +Merger requires Go `1.25.10` for local development and CI — this is part of the +security baseline, not an optional preference. Bootstrap it into your shell: + +```bash +eval "$(./scripts/dev/use-go-1.25.10.sh)" +go version +``` + +The helper installs the `go1.25.10` launcher if needed, downloads the toolchain +into `$HOME/sdk/go1.25.10`, and exports `GOROOT`, `PATH`, and `GO` for the +current shell. After that one-time install, plain `make` targets prefer +`$HOME/sdk/go1.25.10/bin/go` when it exists, so `make ci` does not depend on your +shell defaulting to the right Go version. + +### 2. Start dependencies and services + +```bash +make compose-up # Postgres, Redis, NATS via deployments/local/docker-compose.yml +make run-ingest # HTTP ingress for GitHub pull_request webhooks +make run-controlplane # downstream orchestration and subscriptions +``` + +Default ports: + +| Service | Port | +| --- | --- | +| Ingest HTTP | `:8080` | +| Control-plane HTTP | `:8081` | +| Control-plane gRPC | `:9091` | +| PostgreSQL | `:5432` | +| Redis | `:6379` | +| NATS | `:4222` | + +Tear the stack down with `make compose-down`. + +### 3. Verify + +```bash +make verify # test-all + build +make ci # full local CI (fmt, vet, tests, coverage, lint, security) +``` + +## Next steps + +- [SDK guide](sdk.md) — embed the offline pipeline as a Go library +- [MCP server](mcp.md) — agent tool contract +- [Extending merger](extending-merger.md) — plug in your own SCM, topology, event, and persistence adapters +- [GitHub webhook flow](flows/github-webhook-flow.md) — detailed end-to-end flow +- [Release automation](release-automation.md) — how releases are cut From 95787e0ce4eaff0abf8b335d8afd50da36240375 Mon Sep 17 00:00:00 2001 From: Alex Wilkerson John Date: Fri, 10 Jul 2026 18:13:02 -0400 Subject: [PATCH 2/2] docs: drop roadmap, add nav TOC and footer to README Remove the Roadmap section, add a compact Contents nav after the intro, and add an Apache 2.0 / devr-tools footer for a cleaner, easier-to-navigate landing page. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 40e5e7d..9a415fb 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,8 @@ It is not a code review bot. The design center is operational coordination at a scale where autonomous agents generate more software mutations than humans can inspect by hand. +**Contents:** [What it does](#what-it-does) · [Install](#install) · [Quickstart](#quickstart) · [SDK](#sdk) · [Merge lane model](#merge-lane-model) · [Change Packet flow](#change-packet-flow) · [Open-source shape](#open-source-shape) · [Docs](#docs) + ## What it does - parses a PR diff into normalized changed files @@ -198,10 +200,8 @@ surface. - [Contributing](CONTRIBUTING.md) - [Security](SECURITY.md) -## Roadmap +--- -- Add Kafka and non-GitHub SCM providers to validate the public extension model. -- Expand runtime graph ingestion from service catalogs, deployment systems, and ownership registries. -- Add analyzer SDK examples for out-of-tree semantic detectors. -- Introduce replay workers and outbox-based delivery guarantees. -- Learn policy weights and lane thresholds from deploy outcomes and incident history. +

+ Apache 2.0 · part of the devr-tools suite +