diff --git a/action.yml b/action.yml index 24701ca..4c534d1 100644 --- a/action.yml +++ b/action.yml @@ -1,5 +1,5 @@ name: "MergeWarden for AI PRs" -description: "Checkout-free policy gate for AI-generated pull requests" +description: "Reports when a pull request edits the files coding agents read as instructions (CLAUDE.md, AGENTS.md, .mcp.json). Closes nothing." author: "MergeWarden contributors" inputs: diff --git a/docs/roadmap.md b/docs/roadmap.md index 4818b38..cc4e438 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -2,14 +2,23 @@ The roadmap is ordered by evidence quality, not promised dates. -## Shipped in v0.3.1 - -- Ship v0.3.1 as a normal release with a public `npx` scan path. -- Fail closed on incomplete GitHub file/content collection. -- Make workflow findings differential and independently tunable. -- Add exact, expiring base-policy waivers. -- Detect a narrow, documented class of agentic workflow injection. -- Replace release-history-heavy onboarding with a concise product path. +## Shipped + +Through v0.10.2. The [changelog](../CHANGELOG.md) has every release; this is the +shape of what exists. + +- A public `npx` path, and a checkout-free Action that fails closed when it + cannot collect the files it needs. +- Workflow findings that compare against the base branch rather than restating + pre-existing conditions, each independently tunable, with exact and expiring + base-policy waivers. +- Reporting when a pull request changes the files coding agents read as + instructions, and a narrow documented class of agentic workflow injection. +- `mergewarden triage`, which reads a repository's open pull requests and + reports what each is missing without writing anything back. +- Identification of the co-author trailers coding tools write about themselves, + matched on exact address rather than domain or display name. +- A quiet default: the Action says nothing when there is nothing to say. ## Next diff --git a/packages/action/action.yml b/packages/action/action.yml index f2b1c13..bd3f7b3 100644 --- a/packages/action/action.yml +++ b/packages/action/action.yml @@ -1,5 +1,5 @@ name: "MergeWarden for AI PRs" -description: "Checkout-free policy gate for AI-generated pull requests" +description: "Reports when a pull request edits the files coding agents read as instructions (CLAUDE.md, AGENTS.md, .mcp.json). Closes nothing." author: "MergeWarden contributors" inputs: diff --git a/packages/cli/README.md b/packages/cli/README.md index f482f57..6c89066 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -1,23 +1,63 @@ # MergeWarden CLI -MergeWarden is a checkout-free policy gate for AI-generated GitHub pull requests. It reads pull request metadata and selected file contents through the GitHub API; it never clones the target repository or executes pull-request-controlled code. +Reads a GitHub pull request through the API and reports what a maintainer would +normally check by hand. It never clones the repository, never executes +pull-request-controlled code, and never calls a language model. -The npm package is `mergewarden`; the installed executable remains `mergewarden`. +The npm package is `mergewarden` and the installed executable is `mergewarden`. -## Try a public pull request +Most people run this as a [GitHub Action](https://github.com/sjh9714/mergewarden) +so it happens on every pull request. The CLI is for looking at one pull request, +or a whole queue, from your terminal. + +## Read a whole queue ```console -npx mergewarden@0.8.0 scan owner/repository#123 +npx mergewarden@0.10.2 triage owner/repository +``` + ``` +20 open pull request(s) read. 9 have something a maintainer checks by hand. + +#6941 update-unmanaged-certificates no description · template unused +#7227 add-tests no linked issue · oversized +#7790 feat/dedup-dynamic-upstreams no linked issue · template unused + +Nothing was closed, labelled, or commented on. +``` + +**This needs `GH_TOKEN` set, even on a public repository.** It makes one request +per pull request, and GitHub allows 60 an hour without one. A personal access +token with no scopes selected is enough, since nothing here writes. Without one +it reports what it could not read and exits non-zero rather than showing a queue +it only half saw. -Full GitHub pull request URLs are also accepted. Authentication is optional for public repositories. For private repositories or higher API limits, set `GH_TOKEN` (preferred) or `GITHUB_TOKEN` in the environment. +## Scan one pull request + +```console +npx mergewarden@0.10.2 scan owner/repository#123 +``` + +Full pull request URLs are accepted too. A single public pull request works +without a token. ```console mergewarden scan https://github.com/owner/repository/pull/123 --format markdown mergewarden scan owner/repository#123 --config policies/mergewarden.yml --mode warn ``` -Exit codes are stable: `0` for a complete pass or warning, `1` for a complete block decision, and `2` for usage, API, configuration, or incomplete-analysis failures. +Set `GH_TOKEN` (preferred) or `GITHUB_TOKEN` for private repositories and higher +rate limits. There is deliberately no command-line flag for the token, because +flags end up in shell history and CI logs. + +Exit codes are stable. `scan` and `replay` return `0` for a complete pass or +warning, `1` for a complete block decision, and `2` for usage, API, +configuration, or incomplete-analysis failures. + +`triage` differs, because a partly-read queue is still worth printing: `0` when +every pull request was read, `1` when some could not be and the answer is +therefore partial, and `2` when the arguments were wrong or the listing itself +failed. ## Replay a local fixture @@ -25,12 +65,18 @@ Exit codes are stable: `0` for a complete pass or warning, `1` for a complete bl mergewarden replay path/to/fixture ``` -A fixture directory contains `mergewarden.yml`, `fixture.json`, and optionally `pr-body.md`. Replay is fully local and deterministic — no network, no token. The repository's own fixtures live under [`fixtures/`](https://github.com/sjh9714/mergewarden/tree/main/fixtures) and are not bundled in this package. +A fixture directory contains `mergewarden.yml`, `fixture.json`, and optionally +`pr-body.md`. Replay is fully local and deterministic, with no network and no +token. The repository's own fixtures live under +[`fixtures/`](https://github.com/sjh9714/mergewarden/tree/main/fixtures) and are +not bundled in this package. Run `mergewarden --help` for the complete command reference. ## Security boundary -MergeWarden fetches the policy from the pull request base commit. It does not checkout either branch, evaluate workflow expressions, run package scripts, or call an LLM during analysis. +The policy comes from the pull request's base commit, never from the pull +request itself. It does not check out either branch, evaluate workflow +expressions, run package scripts, or call a model during analysis. License: MIT. See `THIRD_PARTY_NOTICES.md` for bundled dependency notices. diff --git a/packages/cli/package.json b/packages/cli/package.json index d82741d..cd3baf2 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -3,7 +3,7 @@ "version": "0.10.2", "private": false, "type": "module", - "description": "Checkout-free policy scanning for AI-generated GitHub pull requests", + "description": "Reports what a pull request changed that a maintainer normally checks by hand, starting with the files coding agents read as instructions", "license": "MIT", "repository": { "type": "git",