@cldmv/gh-broker 0.0.0-stage → 0.7.0

package/docs/changelog/v0/v0.3.0.md

@@ -0,0 +1,84 @@
+# gh-broker v0.3.0 Changelog
+
+**Release Date**: September 2026
+**Release Type**: Minor
+**Branch**: `release/0.3.0`
+
+---
+
+## Overview
+
+v0.3.0 replaces gh-broker's deploy tooling with a single idempotent **Node installer** that handles both first install and upgrade, makes credential storage a **backend the operator chooses at install** (host-bound `systemd-creds`, encrypted at rest, by default; or a portable plaintext file), and puts **platform-neutral path resolution** under the daemon.
+
+Nothing on the broker's runtime request path changed — owner/mode → PAT routing, the default-deny allowlist, the custom review-thread verbs, and the token-free config model all behave exactly as in v0.2.x. This release is entirely about how the daemon is **deployed, upgraded, and how its PATs are stored, migrated, and rotated**. It also carries a large batch of installer/secret-handling hardening and the deploy-model documentation.
+
+The immediately preceding release, **v0.2.5**, shipped the `npm_and_yarn` security group bump (#40) as a hotfix; v0.3.0 builds on top of it.
+
+---
+
+## ✨ Features
+
+### One Node installer — first install and upgrade in a single command (#45)
+
+`deploy/install.mjs` replaces the old shell scripts (`launch.sh`, `provision.sh`, `deploy-app.sh`). A single idempotent command does first install **and** upgrade: it regenerates the deployed config by **merging shipped defaults over the current config** (never a blind overwrite, so an operator's settings survive an upgrade while new defaults are picked up), deploys the built `dist/`, installs the hardened unit, and runs a post-deploy MCP smoke test. It is interactive by default and **fully non-interactive** via CLI flags (`--agent-user`, `--secrets-provider`, `--secrets-file`, `--create-agent-user`, `-y/--non-interactive`) or `GH_BROKER_SECRET_<NAME>` environment variables for unattended runs.
+
+### Operator-chosen secret backend, behind a provider seam (#45)
+
+At install the operator chooses how the PATs are stored at rest: **`systemd-creds`** (default — host-bound, encrypted, delivered into `$CREDENTIALS_DIRECTORY` via a `LoadCredentialEncrypted` unit drop-in) or a **portable plaintext `file`** (`0640 root:gh-broker`, platform-neutral). A `config.secrets.provider` seam and platform-neutral path resolution (`--config` / `GH_BROKER_CONFIG` / `GH_BROKER_SECRETS` → platform config dir → default) back both, and the daemon exposes `--print-paths` and `--check` so the installer resolves paths and validates the config through the daemon itself (one resolver, no drift).
+
+### In-place credential migration and rotation (#45)
+
+Existing `systemd-creds` tokens are **auto-migrated** on upgrade — the installer decrypts and re-uses them without re-prompting when they're detectable. A re-run **rotates** a credential when a new value is supplied (via `--secrets-file` or `GH_BROKER_SECRET_<NAME>`), while a plain re-run keeps the existing encrypted cred as-is.
+
+### The unit runs node via a maintained symlink (#43, #45)
+
+The systemd unit no longer hardcodes a versioned node path. #43 first resolved node from the system-wide nvm `default` alias; v0.3.0 finalizes this as the unit running **`/usr/local/bin/node`** (a maintained symlink), so bumping node needs no unit edit and the CLI and service share one indirection.
+
+---
+
+## 🐛 Bug Fixes
+
+### Secret, credential, and installer input handling hardened (#45)
+
+A batch of correctness and safety fixes across the installer and secret layer:
+
+- **Credential names** are constrained to a safe charset (`[A-Za-z0-9._-]`, rejecting `.`/`..`) on both the daemon and installer sides, so a `cred:` name can't traverse outside `$CREDENTIALS_DIRECTORY` / the secrets file or produce a malformed root-written systemd drop-in.
+- **File-provider tokens** strip a single trailing newline (matching `systemd-creds`), so a copy/pasted token isn't silently mismatched at auth time, and a newline-only value is rejected as empty.
+- **Config and `--secrets-file` validation** reject arrays (which `typeof === "object"` otherwise accepts) and empty values; `config.secrets.path` is rejected unless the provider is `file` (it would otherwise be silently ignored under `systemd-creds`).
+- **CLI flag parsing** rejects a missing/flag-shaped value (so `--agent-user --secrets-provider file` can't mis-parse the flag as the username), and `--config` without a path value fails fast rather than silently falling back to the default.
+- **Ownership operations fail fast** when a uid/gid can't be resolved, instead of silently leaving `/etc/gh-broker` / `/opt/gh-broker` mis-owned or running `chown NaN:NaN`.
+- **Switching to `systemd-creds`** now zero-overwrites and removes any leftover plaintext secrets file, so "encrypted at rest" isn't undermined by a stale file.
+- The interactive prompt **fails with guidance** (use `--secrets-file`/env) when asked for a multi-line App PEM, rather than capturing only its first line.
+- The post-deploy **smoke test waits for the socket** instead of failing on the first connect during the daemon's startup network I/O.
+
+---
+
+## 🔧 CI & tooling
+
+### esbuild install script approved (#43)
+
+`allowScripts` approves esbuild's install script so `npm ci` runs clean under npm 11's allow-scripts; lockfile integrity remains the gate.
+
+---
+
+## 📚 Documentation
+
+- **NEW:** deploy architecture (`docs/deploy-architecture.md`) — the installer/upgrade flow, config-merge semantics, the secret-store backends, and the node-symlink model (#45).
+- **NEW:** the **agent-as-separate-user isolation model** (`docs/agent-user-model.md`) — the users, bridge group, and permissions that make the boundary real, documented as a reproducible example setup (#43, #45).
+- `deploy/README.md` rewritten around the installer workflow and its non-interactive flags; README status updated to "deployed / in production" (#45).
+- The `link_issue` verb is **deferred** — its catalog advertising and router dispatch are commented out until the GitHub App path is wired; it is not advertised or callable (#45).
+- **NEW:** [docs/changelog/v0/v0.3.0.md](./v0.3.0.md) — this changelog, and the start of gh-broker's per-version changelog convention.
+
+---
+
+## 🔧 Dependencies
+
+_No dependency updates in this release._ The `npm_and_yarn` security group bump (#40) shipped separately as the **v0.2.5** hotfix.
+
+---
+
+## Upgrade notes
+
+- **No runtime or API change** — the broker's request routing, default-deny allowlist, custom verbs, and token-free config model are identical to v0.2.x. There is nothing to change in how an agent talks to the broker.
+- **The deploy process changed.** Install and upgrade with `sudo node deploy/install.mjs` (see `docs/deploy-architecture.md` and `deploy/README.md`); the old `launch.sh`, `provision.sh`, and `deploy-app.sh` are removed. Existing `systemd-creds` installs **auto-migrate** on upgrade — re-run the installer, no token re-entry needed.
+- The secret backend is chosen at install; `systemd-creds` (encrypted at rest) remains the default.

package/docs/changelog/v0/v0.3.1.md

@@ -0,0 +1,30 @@
+# gh-broker v0.3.1 Changelog
+
+**Release Date**: September 2026
+**Release Type**: Patch
+**Branch**: `release/0.3.1`
+
+---
+
+## Overview
+
+Toolchain-floor fix: `vitest` 5 requires Node `^20.19.0 || >=22.12.0`, which excludes plain `>=20.19.0`/`>=20`-style ranges that don't also cover the 22.x break point. Raises the real floor to match, in both the installer's own Node-version check and `package.json` `engines.node`.
+
+---
+
+## 🐛 Bug Fixes
+
+- Installer's Node-version prerequisite check raised to `>=22.12.0`, matching what `vitest` 5 actually requires — a lower floor there let the installer proceed on a Node version the test toolchain can't run on.
+- `engines.node` raised to `>=22.12.0` for the same reason.
+
+---
+
+## 🔧 Dependencies
+
+- `vitest`, `@vitest/coverage-v8`, `@octokit/auth-app`, `@types/node` bumped to their latest compatible versions (#52).
+
+---
+
+## Upgrade notes
+
+No breaking changes to the broker's runtime behavior — this only affects the Node version required to build/test/install it.

package/docs/changelog/v0/v0.3.2.md

@@ -0,0 +1,24 @@
+# gh-broker v0.3.2 Changelog
+
+**Release Date**: September 2026
+**Release Type**: Patch
+**Branch**: `release/0.3.2`
+
+---
+
+## Overview
+
+Follow-up to v0.3.1's Node-floor raise: brings the CI test matrix itself up to the same `>=22.12.0` floor so it actually exercises the versions the toolchain requires, and groups related Dependabot updates so they land as one PR instead of several.
+
+---
+
+## 🔧 CI & tooling
+
+- CI test matrix bumped to match the `>=22.12.0` engines floor raised in v0.3.1.
+- Dependabot config groups the `eslint`/`prettier` families and the `vitest`/`@vitest/*` family into one bump each, instead of a separate PR per package.
+
+---
+
+## Upgrade notes
+
+No breaking changes — CI/tooling only, no runtime code changed.

package/docs/changelog/v0/v0.3.3.md

@@ -0,0 +1,28 @@
+# gh-broker v0.3.3 Changelog
+
+**Release Date**: September 2026
+**Release Type**: Patch
+
+---
+
+## Overview
+
+v0.3.3 is a packaging-only release. The package's `publishConfig.access` changes from `restricted` to `public`, so the scoped `@cldmv/gh-broker` package is published as a public package. It shipped through the hotfixes lane ([#72](https://github.com/CLDMV/gh-broker/pull/72)). No runtime code changed.
+
+---
+
+## 🐛 Bug Fixes
+
+### Publish as a public scoped package ([#72](https://github.com/CLDMV/gh-broker/pull/72))
+
+`package.json` declared `"publishConfig": { "access": "restricted" }`, which is the setting for a private scoped package and makes the registry treat a publish of `@cldmv/gh-broker` as one. It is now `"public"`.
+
+## 📚 Documentation
+
+- **NEW:** [docs/changelog/v0/v0.3.3.md](./v0.3.3.md): this changelog.
+
+---
+
+## Upgrade notes
+
+- No breaking changes, and no runtime change: the broker behaves exactly as in [v0.3.2](./v0.3.2.md).

package/docs/changelog/v0/v0.4.0.md

@@ -0,0 +1,58 @@
+# gh-broker v0.4.0 Changelog
+
+**Release Date**: September 2026
+**Release Type**: Minor
+**Branch**: `release/0.4.0`
+
+---
+
+## Overview
+
+This release adds two report-style custom verbs — `report_unlabeled` and `report_ci_status` — plus a new way for the broker to enrich a proxied tool's response in place, and fixes three real bugs found while building and deploying them. Nothing about this release is breaking: every addition is a new verb or an opt-in parameter, and existing callers see no behavior change.
+
+The headline capability is CI visibility without per-call log fetches: `report_ci_status` (and the same logic layered onto a normal `pull_request_read`) answers "does this PR have failing checks" at whatever detail level the caller asks for — counts only by default, escalating to which job failed, which step failed, and finally a tail of the failing job's actual log — and only ever pays for that detail on runs that are genuinely failing. Verified against a real failing PR (`CLDMV/droidsock#35`): correct pass/fail classification across five jobs (including three cancelled matrix legs), correct per-step failure detail, and a real log tail that surfaced the actual root cause (an `npm ERESOLVE` peer-dependency conflict) with no further digging required.
+
+---
+
+## ✨ Features
+
+### `report_unlabeled` — issues/PRs missing labels, one repo or every repo an owner has (#57)
+
+Composes the already-allowlisted `list_issues`/`list_pull_requests` (plus an org-repo listing when `repo` is omitted) into a single report of unlabeled issues and/or PRs. Bounded by `maxRepos`/`perRepoLimit`/`maxApiCalls`, with a rate-limit floor read from the token's own `x-ratelimit-limit` header (not a hardcoded assumption about which token type is in use) so it backs off before GitHub does. Draft PRs are excluded by default (`includeDrafts` to override). Hitting a cap or the rate limit returns `truncated: true` with whatever was already found, rather than discarding partial results.
+
+### `report_ci_status` — tiered CI health for a PR, or every open PR in a repo (#61, #64)
+
+Reports pass/fail/pending counts by default (tier 0), escalating on request to which run/job failed (tier 1), which step inside that job failed (tier 2), and a tail of the failing job's log (tier 3). Detail beyond tier 0 is only ever fetched for jobs that are actually failing, so a healthy PR costs exactly one call regardless of the requested verbosity. Tier 3 calls the hosted MCP's own `get_job_logs` tool (`failed_only: true` fetches every failing job in a run in one call) rather than a hand-rolled REST fetch — one call per failing run, not per job (#64).
+
+### `pull_request_read` gets an inline `ciVerbosity` parameter (#61)
+
+A normal `pull_request_read` (`method: "get"`) can now carry CI status inline by passing `ciVerbosity` (0–3, same tiers as `report_ci_status`) and an optional `logLines`. This is the first tool the router's new **augment** dispatch mode powers: forward to the hosted MCP like a plain proxy, then post-process the result — gh-broker's own MCP contract for a proxied tool is not required to match the hosted MCP's shape verbatim. Opt-in only: omitting `ciVerbosity` is a byte-identical forward, so existing callers are unaffected.
+
+---
+
+## 🐛 Bug Fixes
+
+### `npm run dev` crashed outright (#63)
+
+`node --experimental-strip-types` — the project's own `dev` script — rejects TypeScript constructor-parameter-property syntax, which `Router` and `AppAuth` both used. Invisible to `typecheck`/`build`/`test` since `tsc` and `esbuild` transform the code rather than only stripping types. Fixed in both places it appeared; verified against the real `dev` command, which now reaches `listening` where it previously crashed before any application code ran.
+
+### Installer left root-owned `dist/`/`node_modules/` in the checkout (#63)
+
+The installer requires root, and its build-if-needed step ran `npm ci`/`npm run build` inside the repo checkout itself — not just the deploy target, which is chowned correctly elsewhere. That left build output owned by root in the operator's own working tree, breaking their next plain `npm run build` with `EACCES`. Fixed at the root cause: the build now runs via `sudo -u '#<uid>'`, with the uid read directly from the install script's own file ownership — no separate "agent user" concept needed, and no `chown` anywhere (not cross-platform, and unnecessary once nothing is ever created with the wrong owner to begin with). Detects and rebuilds a stale `dist/`/`node_modules/` left by an older version of this script, so re-running the installer is self-healing with no manual cleanup step.
+
+### Rate-limit floor was a hardcoded guess (#57)
+
+`report_unlabeled`'s proactive rate-limit backoff was a flat `100` with no derivation from GitHub's actual limit — wrong for any token whose real quota differs from a 5,000/hr PAT. Now reads `x-ratelimit-limit` off every response and floors at 2% of that, with an absolute minimum for low-limit tokens. `report_ci_status` shares the same rate-limit/call-budget module (`rest-client.ts`, extracted once a second verb needed the identical logic).
+
+---
+
+## 🔧 CI & tooling
+
+- Extracted the rate-limit-floor + call-budget machinery shared by `report_unlabeled` and `report_ci_status` into `src/verbs/rest-client.ts`.
+- `router.ts` gained a third dispatch mode, `augment`, alongside the existing `custom` (fully local) and plain-`forward` paths — logged in the audit trail the same way as the other two.
+
+---
+
+## Upgrade notes
+
+No breaking changes — every addition here is a new verb or an opt-in parameter on an existing one; nothing about an existing call's behavior changes unless the new parameters are used.

package/docs/changelog/v0/v0.4.1.md

@@ -0,0 +1,33 @@
+# gh-broker v0.4.1 Changelog
+
+**Release Date**: October 2026
+**Release Type**: Patch
+
+---
+
+## Overview
+
+v0.4.1 keeps the toolchain current and adopts the shared CLDMV file-header setup. Runtime dependencies move by one patch (`@modelcontextprotocol/sdk` 1.30.0 to 1.30.1), TypeScript goes back to 6, and every source, test and workflow file now carries a uniform header maintained by `@cldmv/fix-headers`. No broker behavior changed.
+
+---
+
+## 🔧 CI & tooling
+
+### Uniform file headers with `@cldmv/fix-headers` ([#84](https://github.com/CLDMV/gh-broker/pull/84))
+
+The repository adopts the shared CLDMV header configuration. `@cldmv/fix-headers` 2.1.1 and `@cldmv/configs` 1.2.0 are new dev dependencies, `.configs/fix-headers.json` holds the checked-in config, and a new `npm run fix:headers` script restamps headers. Every file under `src/`, `tests/`, `deploy/` and `.github/workflows/` was restamped in one pass, which is why the diff touches more than fifty files. The change is comments only.
+
+## 🔧 Dependencies
+
+- TypeScript is back on 6.0.3 ([#82](https://github.com/CLDMV/gh-broker/pull/82)). TypeScript 7 is not usable here until 7.1 ships a compiler API.
+- The patch group ([#80](https://github.com/CLDMV/gh-broker/pull/80)): `@modelcontextprotocol/sdk` 1.30.0 to 1.30.1, `@types/node` 26.6.2 to 26.6.3, and `vitest` and `@vitest/coverage-v8` 5.0.1 to 5.0.2 (both dev-only).
+
+## 📚 Documentation
+
+- **NEW:** [docs/changelog/v0/v0.4.1.md](./v0.4.1.md): this changelog.
+
+---
+
+## Upgrade notes
+
+- No breaking changes, and no change in how the broker behaves. Drop-in for [v0.4.0](./v0.4.0.md).

package/docs/changelog/v0/v0.4.2.md

@@ -0,0 +1,45 @@
+# gh-broker v0.4.2 Changelog
+
+**Release Date**: October 2026
+**Release Type**: Patch
+
+---
+
+## Overview
+
+v0.4.2 patches the three transitive dependencies behind four open Dependabot alerts, bumps the MCP SDK and the test runner, and fixes how the CI mirror job reports the required check. The broker's behavior is unchanged.
+
+---
+
+## 🔒 Security & supply chain
+
+### Patched transitive dependencies ([#90](https://github.com/CLDMV/gh-broker/pull/90))
+
+A lockfile-only update moves three packages that the MCP SDK pulls in to their patched releases:
+
+- `ip-address` 10.7.0 to 10.7.3, which fixes [alert 18](https://github.com/CLDMV/gh-broker/security/dependabot/18) (a long input could stall the process) and [alert 19](https://github.com/CLDMV/gh-broker/security/dependabot/19) (`isInSubnet` could admit an address from a different address family).
+- `fast-uri` 3.1.7 to 3.1.8, which fixes [alert 20](https://github.com/CLDMV/gh-broker/security/dependabot/20) (inconsistent host case normalization).
+- `hono` 4.13.5 to 4.13.12, which fixes [alert 21](https://github.com/CLDMV/gh-broker/security/dependabot/21) (the `hono/jsx` unescaped-string XSS).
+
+None of them is a direct dependency. The broker is a local stdio proxy, so exposure was low, but the alerts are now closed on the release branch.
+
+## 🔧 CI & tooling
+
+### The required-check mirror no longer skips ([#87](https://github.com/CLDMV/gh-broker/pull/87), [#89](https://github.com/CLDMV/gh-broker/pull/89))
+
+The `✅ Required PR Check` mirror job in `ci.yml` was skipped on in-repo feature PRs. GitHub treats a skipped required check as satisfied, and it never evaluates a skipped job's `name:`, so the PR showed the raw expression as a check name. The job now runs on every path with `if: always()`. On an in-repo PR it reports under a readable, non-required name (`⏭️ Required PR Check (reported by the push run)`) and passes as a no-op, while the push run still posts the required name. It still waits for the full test matrix through `needs: ci`.
+
+## 🔧 Dependencies
+
+- `@modelcontextprotocol/sdk` 1.30.1 to 1.31.0 ([#85](https://github.com/CLDMV/gh-broker/pull/85)).
+- `@cldmv/vitest-runner` 1.2.0 to 1.5.1, dev-only ([#85](https://github.com/CLDMV/gh-broker/pull/85)).
+
+## 📚 Documentation
+
+- **NEW:** [docs/changelog/v0/v0.4.2.md](./v0.4.2.md): this changelog.
+
+---
+
+## Upgrade notes
+
+- No breaking changes. Drop-in for [v0.4.1](./v0.4.1.md).

package/docs/changelog/v0/v0.5.0.md

@@ -0,0 +1,39 @@
+# gh-broker v0.5.0 Changelog
+
+**Release Date**: October 2026
+**Release Type**: Minor
+
+---
+
+## Overview
+
+v0.5.0 adds two report verbs that answer fleet-wide questions in one call instead of one call per repo: `report_security_alerts` for open Dependabot, CodeQL and secret-scanning alerts, and `report_release_prs` for open release PRs and whether each has its changelog. Existing verbs behave as before, with one fix in how rate limits are recognised.
+
+---
+
+## ✨ Features
+
+### `report_security_alerts` ([#91](https://github.com/CLDMV/gh-broker/pull/91))
+
+Lists every open Dependabot, code-scanning (CodeQL) and secret-scanning alert for one repo or a whole owner. It reads the org-level alert endpoints in a handful of calls and falls back to a per-repo sweep for any alert type the token cannot read org-wide. Each alert is normalized to one shape with type-specific fields (package, patched version and manifest for Dependabot; rule and location for CodeQL; secret type and validity for secrets), sorted worst first. Secret values are never returned. Results carry `scope` (org or per-repo for each type) and `disabled` (repos where a type is off), and the usual `truncated` / `truncatedReason` when a cap or the rate limit is hit. An alert's state tracks the default branch, so one already fixed on `next` still reads open until it ships.
+
+### `report_release_prs` ([#91](https://github.com/CLDMV/gh-broker/pull/91))
+
+Finds every open release PR (label `release`: the `next` and `hotfixes` lines into `master`) for an owner and reports whether each one's per-version changelog file (`docs/changelog[s]/v<major>/vX.Y.Z.md`) exists on the release branch, as `ready`, `needs-changelog` or `unknown-version`. It costs one search call plus a few calls per release PR, and `onlyMissing` narrows the list to the ones that still need a changelog.
+
+## 🐛 Bug Fixes
+
+### A permission 403 is no longer mistaken for a rate limit ([#91](https://github.com/CLDMV/gh-broker/pull/91))
+
+The shared REST client treated every `403` as throttling, so a "feature not enabled" answer (code scanning off on a repo) would have stopped a whole scan. A `403` now counts as a rate limit only when GitHub signals one: a `Retry-After` header, an exhausted `x-ratelimit-remaining`, or a rate-limit or abuse message. Everything else reaches the caller with its status. This also applies to `report_unlabeled` and `report_ci_status`. Dependabot's cursor pagination and the repo-listing helper moved into the shared client with it.
+
+## 📚 Documentation
+
+- **NEW:** [docs/changelog/v0/v0.5.0.md](./v0.5.0.md): this changelog.
+- The two verbs are documented in `docs/TOOLS.md` and the README.
+
+---
+
+## Upgrade notes
+
+- No breaking changes. The new verbs appear in the tool list after you redeploy and the client reconnects, and need no config change.

package/docs/changelog/v0/v0.5.1.md

@@ -0,0 +1,28 @@
+# gh-broker v0.5.1 Changelog
+
+**Release Date**: October 2026
+**Release Type**: Patch
+
+---
+
+## Overview
+
+v0.5.1 stops the installer from asking where credentials are stored when the install already has an answer. Upgrading no longer needs a keypress, and the broker itself is unchanged.
+
+---
+
+## 🐛 Bug Fixes
+
+### The installer keeps the existing secrets backend ([#95](https://github.com/CLDMV/gh-broker/pull/95))
+
+`deploy/install.mjs` asked "How should the PAT credentials be stored at rest?" on every interactive run, and only `--non-interactive` skipped it. It now works out the backend already in use: the provider recorded in the deployed config, otherwise encrypted `.cred` files (systemd-creds) or tokens in the secrets file. It logs `keeping existing backend: <name>` and carries on. A first install, or a state where both backends hold credentials and nothing is recorded, still prompts, and `--secrets-provider` still overrides. Six unit tests cover the detection.
+
+## 📚 Documentation
+
+- **NEW:** [docs/changelog/v0/v0.5.1.md](./v0.5.1.md): this changelog.
+
+---
+
+## Upgrade notes
+
+- No breaking changes. Re-run the installer as usual; it keeps your current credential backend.

package/docs/changelog/v0/v0.6.0.md

@@ -0,0 +1,52 @@
+# gh-broker v0.6.0 Changelog
+
+**Release Date**: October 2026
+**Release Type**: Minor
+**Branch**: `release/0.6.0`
+
+---
+
+## Overview
+
+v0.6.0 makes the two report verbs from v0.5.0 usable on a whole org. `report_security_alerts` can now return a compact per-repo roll-up instead of about 700 KB of alerts, filter by severity and repo, and tag each repo with its flow tier. `report_release_prs` can now judge whether each release is ready for its changelog, including whether an existing changelog is still up to date. All additions are opt-in parameters on verbs that already exist, so nothing changes for existing callers and no config change is needed.
+
+---
+
+## ✨ Features
+
+### Per-repo roll-up, filters and flow tier for `report_security_alerts` ([#99](https://github.com/CLDMV/gh-broker/pull/99))
+
+- **`byRepo` on every result.** One row per repo with at least one alert, worst first (criticals, then highs, then total), with per-type counts and critical / high / medium / low counts.
+- **`summaryOnly`.** Returns just the roll-up and the counts. An org run drops from about 700 KB to a few KB, and `alertsOmitted` says how many alerts were left out.
+- **`minSeverity` and `repos`.** Keep only alerts at or above a severity (secret-scanning alerts have no severity and are always kept), or only the named repos.
+- **`classify`.** Adds each repo's flow tier to its row: `v4` (carries the v4 release workflow), `dev-trunk` (a v4 repo whose real code lives on a persistent `dev` branch while `next` holds only the scaffold) or `non-v4` (no release workflow on the default branch, even if `next` and `hotfixes` branches exist). The raw facts behind the tier are returned as `tierSignals`, because the tier is a structural signal and not a verdict. It costs about three calls per repo that has alerts.
+
+### Release readiness for `report_release_prs` ([#99](https://github.com/CLDMV/gh-broker/pull/99))
+
+`analyze: true` adds an `analysis` block to each release PR and a `verdicts` tally:
+
+- **Open PRs against the release branch**, classified as doc, dependency, feature or draft.
+- **Changelog freshness.** The release PR's commits give the PRs that actually shipped; the changelog is checked for each one. The status is `current`, `minor-gap` (only CI, chore, style or test PRs missing), `stale` (a user-facing PR missing), `version-drift` (the heading names another version) or `thin` (a stub). The README What's New block is checked for the version too.
+- **A verdict:** `done`, `in-flight` (a doc PR is already open), `wait` (feature PRs still open), `gray` (only dependency PRs or drafts open), `write`, `update` or `inspect`.
+
+With `analyze`, `onlyMissing` lists every release PR whose verdict is not `done`, so a changelog that exists but is out of date is not hidden. It costs about five more calls per release PR, so raise `maxApiCalls` for a whole org.
+
+## 🔧 Dependencies
+
+All dev-only; no runtime dependency changed and the lockfile moves only these two packages.
+
+- `@cldmv/fix-headers` `^2.1.1` to `^2.2.0` (locked 2.1.1 to 2.2.0), in two steps: 2.1.4 ([#97](https://github.com/CLDMV/gh-broker/pull/97), no headers needed restamping) and then 2.2.0 ([#104](https://github.com/CLDMV/gh-broker/pull/104)). From 2.2.0 the `@Last modified by` tag follows content edits only, so a header-only rewrite keeps the recorded editor. Running it added the standard header block to `src/verbs/release-analysis.ts` and `src/verbs/repo-tier.ts`, the two files from the verb work above that had none; no existing header or code line changed.
+- `@cldmv/configs` `^1.2.0` to `^1.2.4` (locked 1.2.0 to 1.2.4) ([#104](https://github.com/CLDMV/gh-broker/pull/104)). Version 1.2.4 sets `forceAuthorUpdate` and `forceLastModifiedAuthorUpdate` to `false`, so `@Author` is never rewritten. Re-running `fix:headers` under the new config restamped no files.
+
+## 📚 Documentation
+
+- **NEW:** [docs/changelog/v0/v0.6.0.md](./v0.6.0.md): this changelog.
+- **NEW:** backfilled [v0.3.3](./v0.3.3.md), [v0.4.1](./v0.4.1.md), [v0.4.2](./v0.4.2.md), [v0.5.0](./v0.5.0.md) and [v0.5.1](./v0.5.1.md), which shipped without a changelog file.
+- The new parameters, the tier definitions and the verdict table are documented in `docs/TOOLS.md`.
+
+---
+
+## Upgrade notes
+
+- No breaking changes. The new parameters are optional, and the output of an existing call only gains a `byRepo` field.
+- Redeploy and reconnect your client to use them. A broker older than this version rejects the new parameters as unknown properties.

package/docs/changelog/v0/v0.6.1.md

@@ -0,0 +1,48 @@
+# gh-broker v0.6.1 Changelog
+
+**Release Date**: October 2026
+**Release Type**: Patch
+**Branch**: `release/0.6.1`
+
+---
+
+## Overview
+
+v0.6.1 updates the MCP SDK the broker is built on, `@modelcontextprotocol/sdk` from 1.31.0 to 1.32.0, and refreshes the development toolchain: vitest 5.0.3, `@cldmv/vitest-runner` 1.5.3 and `@types/node` 26.6.4.
+
+No broker source changed. The net diff against v0.6.0 is `package.json` and `package-lock.json` only, and the SDK is the single runtime package that moved: its own dependency ranges are identical between the two versions, so no new runtime package is installed. The SDK's 1.32.0 release does change how its HTTP client follows redirects (see Upgrade notes), and the broker uses that client to reach the upstream GitHub MCP endpoint, so the SDK bump is a runtime-affecting update even though no line of broker code differs.
+
+---
+
+## 🔧 Dependencies
+
+### Runtime
+
+- `@modelcontextprotocol/sdk` `^1.31.0` → `^1.32.0` (locked 1.31.0 → 1.32.0) ([#108](https://github.com/CLDMV/gh-broker/pull/108)). The 1.32.0 release notes list these changes:
+  - **Redirects (upgrade note).** The HTTP client transports now follow a redirect only when it stays on the same origin (same scheme, host and port; http to https on the same host is allowed). `redirectPolicy: 'follow'` on `StreamableHTTPClientTransport` restores the old behavior.
+  - **Two new options, off unless set:** `maxToolInputElements` on `McpServer` and `expectedResource` on `requireBearerAuth`. The broker uses neither: it builds its server on the SDK's low-level `Server` class (with a stdio transport bound to a local socket) and does not use the SDK's bearer-auth middleware.
+  - **Server fixes:** `tools/call` and `prompts/get` requests that omit `arguments` are accepted, and the in-memory task store keeps tasks within the session that created them. Neither was exercised by a broker code path that was changed.
+  - Documentation and example changes in the SDK repository (SECURITY.md, example session handling).
+
+### Development
+
+- `@cldmv/vitest-runner` `^1.5.1` → `^1.5.3` (locked 1.5.1 → 1.5.3) ([#109](https://github.com/CLDMV/gh-broker/pull/109)). Version 1.5.3 makes the runner's CommonJS entry fail with a clear error on a Node.js version without `require(esm)` and raises the runner's `engines.node` from `>=20.19.0` to `>=22.12.0`. The locked package's license field also changes from MIT to Apache-2.0. The runner's `chalk` dependency moves from 5.x to 6, so the locked `chalk` goes 5.6.2 → 6.0.1 and now requires Node.js 22 (`engines` `>=22`). The broker's own `engines.node` was already `>=22.12.0` and the CI matrix already starts at 22.12.0, so nothing about supported Node.js versions changes here.
+- `vitest` `^5.0.1` → `^5.0.3` (locked 5.0.2 → 5.0.3) ([#106](https://github.com/CLDMV/gh-broker/pull/106)), with `@vitest/coverage-v8`, `@vitest/mocker` and `@vitest/spy` following to 5.0.3 (the `@vitest/coverage-v8` range stays `^5.0.2`). Transitive, lockfile only: `vite` 8.3.1 → 8.3.2, `rolldown` and its platform bindings 1.2.11 → 1.2.12, `@oxc-project/types` 0.151.0 → 0.152.0, and `why-is-node-running` 3.2.2 → 3.2.1 (vitest 5.0.3 pins the older release).
+- `@types/node` `^26.6.3` → `^26.6.4` (locked 26.6.3 → 26.6.4) ([#109](https://github.com/CLDMV/gh-broker/pull/109)).
+
+`esbuild`, `typescript`, `@octokit/auth-app` and `@octokit/core` are unchanged.
+
+---
+
+## 📚 Documentation
+
+- **NEW:** [docs/changelog/v0/v0.6.1.md](./v0.6.1.md), this changelog.
+- README `✨ What's New` is promoted to v0.6.1.
+
+---
+
+## Upgrade notes
+
+- No breaking changes to the broker's verbs, configuration or installer; the source is identical to v0.6.0.
+- If the `upstream` URL in your config (the default is `https://api.githubcopilot.com/mcp/x/all`) ever answers with a redirect to a different origin, the SDK will no longer follow it. Point `upstream` at the final URL. It was not verified here whether the default endpoint redirects at all; if it does not, nothing changes for you.
+- Redeploy to pick up the new SDK; the development changes do not affect the installed broker.

package/docs/changelog/v0/v0.7.0.md

@@ -0,0 +1,71 @@
+# gh-broker v0.7.0 Changelog
+
+**Release Date**: October 2026
+**Release Type**: Minor
+**Branch**: `release/0.7.0`
+
+---
+
+## Overview
+
+v0.7.0 adds `issue_labels`, a write verb that edits an issue's or PR's labels one at a time. The hosted MCP's `issue_write` treats `labels` as a full replacement, so changing one status label through it silently drops every other label on the issue ([#117](https://github.com/CLDMV/gh-broker/issues/117)). `issue_labels` uses GitHub's per-label endpoints instead and only touches the labels it is given. The advertised `issue_write` description now carries a warning about the replacement behavior and points at the new verb.
+
+The rest of the release is dependency updates. The only runtime packages that changed are `@modelcontextprotocol/sdk` 1.32.0 → 1.32.1 (documentation-only upstream) and the transitive `proxy-addr` 2.0.7 → 2.0.8 (a security fix). Everything else is development tooling.
+
+Nothing is breaking: `issue_labels` is a new allowlist entry, and every existing tool behaves as before. A redeploy is needed to pick up the new verb, since the installer merges the new `config.example.json` entry into the live config.
+
+---
+
+## ✨ Features
+
+### `issue_labels`: add, remove, swap or set labels without touching the others ([#118](https://github.com/CLDMV/gh-broker/pull/118), closes [#117](https://github.com/CLDMV/gh-broker/issues/117))
+
+A custom verb (`mode: "write"`, `custom: true`) that runs on the write PAT (Issues: write) and works on issues and pull requests alike.
+
+- **`add` / `remove`** take one label or several and combine in one call. A label already present (`add`) or absent (`remove`) is a no-op, not an error.
+- **`swap: { prefix, to }`** removes every current label starting with `prefix` and adds `to`, e.g. `{ "prefix": "status: ", "to": "status: verified" }`. A `to` label that is already on the issue stays in place rather than being removed and re-added.
+- **`set`** replaces the whole set, only as an explicit choice. It cannot be combined with the other operations, and an empty `set` is refused so a call can never clear every label.
+- **Unknown labels are refused.** Every name on the add side is looked up first (case-insensitively, applying the repo's own spelling). A missing one fails the call with nothing written, unless `create_missing` is set, in which case the label is created (`color` defaults to `ededed`).
+- **Add before remove.** Writes run in a fixed order: create missing labels, one POST for the whole add side, then the DELETEs. A failure part-way never leaves an issue with fewer labels than it should have; a `swap` whose POST is rate-limited keeps its old status label.
+- **Partial failures are reported.** If any write fails, the error names what was applied and what was not, and keeps the HTTP status. A failure before the first write passes through unchanged, since nothing was written.
+- **Strict arguments.** The handler enforces its schema: an unknown key (a typo such as `remvoe`), a non-integer `issue_number`, a non-boolean `create_missing`, an empty list, a bad `color`, or more than 100 labels refuses the call before any request is made. Naming the same label on both the add and remove sides is refused too.
+- **Result.** The issue's resulting label set, plus what this call `added`, `removed` and `created`.
+
+Full parameter table and examples: [docs/TOOLS.md](https://github.com/CLDMV/gh-broker/blob/master/docs/TOOLS.md#issue_labels).
+
+### `issue_write` warns that `labels` replaces the whole set ([#118](https://github.com/CLDMV/gh-broker/pull/118))
+
+The broker appends a warning to the advertised description of the proxied `issue_write` tool: `labels` replaces the issue's whole label set. When `issue_labels` is allowlisted, the warning points at it; otherwise it says to read the current labels first and pass the full set back. The tool's schema and its forwarded behavior are unchanged.
+
+---
+
+## 📚 Documentation
+
+- **NEW:** [docs/changelog/v0/v0.7.0.md](./v0.7.0.md), this changelog.
+- `docs/TOOLS.md` gains an `issue_labels` section, and its tool-category table lists the new verb and the `issue_write` description warning.
+- README: a feature section for label edits, the new `src/verbs/issue_labels.ts` in the layout, and `✨ What's New` promoted to v0.7.0.
+
+---
+
+## 🔧 Dependencies
+
+### Runtime
+
+- `@modelcontextprotocol/sdk` `^1.32.0` → `^1.32.1` (locked 1.32.0 → 1.32.1) ([#114](https://github.com/CLDMV/gh-broker/pull/114)). The upstream release contains only documentation changes.
+- `proxy-addr` 2.0.7 → 2.0.8, transitive, lockfile only ([#113](https://github.com/CLDMV/gh-broker/pull/113)). Fixes CVE-2026-90711 (GHSA-jqcg-44mw-7w3h): IPv4 trust granted through IPv4-mapped IPv6 subnets with a short prefix. It arrives through the SDK's HTTP server dependencies; the broker serves MCP over a local Unix socket and does not use that server, but the patched version is now what gets installed.
+
+### Development
+
+- `@cldmv/configs` `^1.2.4` → `^1.3.0` ([#115](https://github.com/CLDMV/gh-broker/pull/115)). Version 1.3.0 adds shared Prettier, ESLint and Vitest configs and makes the ESLint plugins it configures regular dependencies of the package, which adds 147 dev-only packages to the lockfile (`eslint`, the `@eslint/*` language plugins, `@cldmv/eslint-plugin-jsonv` and their dependencies). The broker only uses the package's `fix-headers.json`, which is unchanged.
+- `@cldmv/fix-headers` `^2.2.0` → `^2.2.1`, `@cldmv/vitest-runner` `^1.5.3` → `^1.5.4` and `@types/node` `^26.6.4` → `^26.6.5` ([#114](https://github.com/CLDMV/gh-broker/pull/114)). The two CLDMV packages ship nothing new; both releases only update their own development setup.
+- `source-map-js` 1.2.1 → 1.2.2, transitive, dev-only ([#113](https://github.com/CLDMV/gh-broker/pull/113)). Fixes CVE-2026-93749, a denial of service from malicious indexed source maps.
+
+`@octokit/auth-app`, `@octokit/core`, `esbuild`, `typescript`, `vitest` and `@vitest/coverage-v8` are unchanged.
+
+---
+
+## Upgrade notes
+
+- No breaking changes. Every existing verb and proxied tool behaves as in v0.6.1; the only visible change to an existing tool is the extra warning in `issue_write`'s description.
+- Re-run the installer to deploy: it merges the new `issue_labels` allowlist entry into the live config, rebuilds and restarts the service. MCP clients need to reconnect afterwards to see the new tool.
+- `issue_labels` uses the existing write PAT and needs no new token permissions (Issues: write is already part of the write token's scope).