From 38332bf12594773cd020ec0d549cb648196b2724 Mon Sep 17 00:00:00 2001 From: sjh9714 <163989462+sjh9714@users.noreply.github.com> Date: Thu, 6 Aug 2026 18:41:19 +0900 Subject: [PATCH] docs: the surfaces people actually land on were still selling the old project The README was rewritten yesterday. Four public surfaces that nobody looks at while editing the README were not, and three of them are places people arrive rather than places they are sent. **GitHub Marketplace.** The listing is live at marketplace/actions/mergewarden-for-ai-prs and its description comes straight from action.yml, which still read "Checkout-free policy gate for AI-generated pull requests". The name is left alone on purpose: the Marketplace slug is derived from it, so renaming would orphan the existing URL for no gain. **The npm page for `mergewarden`.** packages/cli/README.md is what npmjs.com renders, and it was worse than stale: - it told people to run `npx mergewarden@0.8.0`, two releases back - it never mentioned `triage`, which is the reason 0.10.x exists - it said "Authentication is optional for public repositories", which is the exact claim corrected in the main README yesterday and which is false for triage: 60 unauthenticated requests an hour does not cover one queue Rewritten, and the exit codes are now stated per command because they differ. `scan` and `replay` return 2 on an incomplete analysis (replay.ts:478); `triage` returns 1, because a partly-read queue is still worth printing. The first draft of this file merged the two and would have shipped a wrong claim to npm. **The package description**, also rendered by npm, had the same old wording. **docs/roadmap.md** stopped at "Shipped in v0.3.1" while the project is on v0.10.2, so seven releases of work were invisible and the page read as a project that stalled in spring. The Shipped section now describes what exists. That file also already lists "A hosted SaaS, GitHub App, or built-in usage telemetry" under Explicit Non-Goals, which settles the question of whether to build a one-click App: it was decided and written down before today. Deliberately unchanged: the old version strings in docs/demo-prs.md, which record which build produced which verified external run, and would become false if updated. --- action.yml | 2 +- docs/roadmap.md | 25 ++++++++++----- packages/action/action.yml | 2 +- packages/cli/README.md | 62 +++++++++++++++++++++++++++++++++----- packages/cli/package.json | 2 +- 5 files changed, 74 insertions(+), 19 deletions(-) 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",