Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions .dz/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
# `.dz/`

Repo-scoped configuration for the developerz.ai maintainer agent. `CLAUDE.md` binds everything here:
no file in this tree relaxes a NEVER entry.

| Path | What |
|---|---|
| `maintainer/maintainer.yml` | the policy: what the bot triages, closes, reviews, merges and releases. [Reference](https://developerz.ai/docs/maintainer-yml) |
| `maintainer/reviewer.md` | this repo's layer of the developerz.ai reviewer prompt |
| `briefs/` | what each `schedules:` checkup works from, read at `main`'s HEAD: `release-due.md` (weekly: is a release needed), `security-release.md` (the one off-cycle release), `health.md` (weekly: the failures nothing announces), `improve.md` (monthly: at most three small, evidenced improvements) |
| `schedules/` | `hygiene.md` and `devops.md`: what the monthly `improve` pass looks for |
| `onboarding/` | the setup pass's scorecard and base audit |
38 changes: 38 additions & 0 deletions .dz/briefs/health.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# Brief: is the project healthy?

Weekly checkup (Tuesdays 07:00 UTC) fired by `schedules: health`: the failures no issue or PR announces.

| Signal | Command | Healthy |
|---|---|---|
| `main` is green | `gh run list --workflow ci.yml --branch main --event push --limit 1 --json conclusion,headSha,url`, then `git rev-parse origin/main` | `success` on the `origin/main` tip; a null conclusion or another sha is no verdict |
| the last tag published | `t=$(git describe --tags --abbrev=0 --match 'v[0-9]*' origin/main); gh run list --workflow ci.yml --event push --limit 20 --json conclusion,headSha,headBranch,url` filtered to `headBranch == $t` | `success`; no run for that tag is no verdict |
| the stamped version is tagged | `grep -m1 '^version' Cargo.toml` against `$t` | equal, or an open release PR or in-flight run explains it |
| the GitHub Release exists with its assets | `gh release view "$t" --json isDraft,publishedAt,assets` | not a draft, published, carrying both `.deb` files and `SHA256SUMS` (`deploy/install.sh` refuses a release without them) |
| the image is pullable | `docker manifest inspect ghcr.io/developerz-ai/mcp-ssh:${t#v}` | lists `linux/amd64` and `linux/arm64` |
| Dependabot is not stuck | `gh pr list --app dependabot --state open --limit 100 --json number,updatedAt,statusCheckRollup` | no PR with failed checks and more than 7 days since `updatedAt` |
| no stale toolchain | `rust-toolchain.toml` channel, `Cargo.toml` `rust-version` and the Dockerfile `FROM` | all three name the same version (CLAUDE.md: bump together) |

## What to file

For each unhealthy signal, one ask, unless an open issue already carries its exact title. Read the
open titles first, exactly so: `gh api --paginate "repos/developerz-ai/mcp-ssh/issues?state=open" | jq -r '.[] | select(.pull_request == null) | .title'`,
then compare byte for byte. A failed read is no verdict, never "no open ask".
Titles are stable: nothing that changes run to run (sha, run URL, version) goes in one; that goes in the body,
with the command and its output. Unreadable evidence is no verdict: re-run it, never file it as a defect.
A red `main` comes first: nothing releases from it.

A drifted toolchain is fixable by the fleet: the ask says to bump all three pins to the newest stable
Rust that is at least 14 days old in one PR, fixing any new clippy lint under `-D warnings`.

This lane reads and files; it never repairs. It never re-runs a publish, re-tags, moves or deletes a tag,
pushes an image by hand, force-pushes `main` or merges with `--admin`.

## Rows

- `main-green` — The latest `ci.yml` push run on the `origin/main` tip is `success`.
- `last-tag-published` — The last `v*` tag has a `success` `ci.yml` run.
- `stamped-version-tagged` — `version` in `Cargo.toml` equals that tag, or a release in flight explains it.
- `github-release-published` — The GitHub Release for that tag is published with both `.deb` files and `SHA256SUMS`.
- `image-pullable` — The GHCR image for that tag lists amd64 and arm64.
- `dependabot-not-stuck` — No open Dependabot PR has failed checks with more than 7 days since its `updatedAt`.
- `toolchain-in-step` — `rust-toolchain.toml`, `Cargo.toml` `rust-version` and the Dockerfile base agree.
45 changes: 45 additions & 0 deletions .dz/briefs/improve.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
# Brief: monthly improvement

Fired every Tuesday by `schedules: improve`. **Act only on the first Tuesday of the month:**
`[ "$(date -u +%-d)" -le 7 ]`. On any other Tuesday stop here, file nothing, open nothing.

Once a month, leave mcp-ssh measurably better, so nobody has to touch it by hand. `CLAUDE.md` binds every change, and `non_goals` in the policy file are off limits. A red `main`, a missing publish and a stuck Dependabot PR belong to `health`.

## Signals

| Signal | Command |
|---|---|
| the gate on fresh `main` | `bin/check` |
| advisories | `cargo audit` |
| dependency majors | `cargo outdated` if installed, else the Dependabot PRs closed red |
| the Rust toolchain | newest stable Rust at least 14 days old, against `rust-toolchain.toml` |
| open bugs | `gh issue list --state open --label bug --json number,title,url` |
| deep read | `.dz/schedules/hygiene.md` and `.dz/schedules/devops.md`: what to look for, and the evidence rules |

Read a failing job's log before deciding anything. A red run whose log names a missing secret or a repository setting is the owner's to fix: escalate once, never delete the check or turn it into a green skip.

## Pick at most three, in this order

1. Anything the gate found broken or flaky: the root cause, never a retry or a skip.
2. Advisories, then dependency majors Dependabot could not land (rmcp, axum, rusqlite), one per PR.
3. The toolchain, when more than one stable release behind: `rust-toolchain.toml`, `Cargo.toml` `rust-version` and the Dockerfile `FROM` together, new clippy lints fixed. Dependabot cannot do this (it ignores the cargo-chef base on purpose).
4. Open bugs, each starting from a test that fails on `main`.
5. Docs drift: README, CLAUDE.md (the module map, the tool table), `docs/`; quote the doc line and the code.
6. Hidden failures: an `|| true`, a `2>/dev/null`, a `continue-on-error`, an `.ok()` or `let _ =` that drops an error. Make it fail, or handle it visibly. A documented, deliberate fallback stays.
7. Simplification: dead code, duplicated logic, a file past the 300-LOC cap, slow or flaky tests.

## Ship

One small PR per improvement, its evidence in the body, `bin/check` green first, a line in `docs/changelog/unreleased.md` when users see it. Never bump the version, and never touch release automation from this checkup: open an issue instead. A breaking change is never merged by this lane (`escalate.ask_before_acting: [breaking_change]`): open the PR or issue and leave it for a maintainer.
Check no open PR or issue already covers it. If nothing is worth changing, do nothing: no empty PRs, no churn.

## Rows

- `gate`: `bin/check` on fresh `main` finds something broken or flaky; root cause, never a retry or a skip.
- `advisories`: `cargo audit` finds advisories; one per PR, before majors.
- `dependency-majors`: majors Dependabot could not land; one per PR.
- `toolchain`: the three Rust pins bumped together when behind.
- `open-bugs`: each from a test that fails on `main`.
- `docs-drift`: a doc line the code contradicts.
- `hidden-failures`: swallowed errors and CI skips, made visible.
- `simplification`: dead code, duplicated logic, files past 300 LOC, slow or flaky tests.
53 changes: 53 additions & 0 deletions .dz/briefs/release-due.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
# Brief: is a release needed?

Weekly checkup, Tuesdays 03:00 UTC, fired by `schedules: release-due`. It covers what people install: the `v*` tag, the image on GHCR (`ghcr.io/developerz-ai/mcp-ssh`), and the GitHub Release carrying the `.deb` files that `deploy/install.sh` downloads. The block below gathers facts and you make the call. A merge or a count never cuts a release.

## Judge

Read everything merged since the last release: the window below with its diffs, then `git log "$last"..origin/main` for what the pathspec leaves out, and `docs/changelog/unreleased.md`. Does someone running mcp-ssh get something real from a release now?

- Usually yes: a fix they can hit, a feature they can use, a dependency change that reaches the binary.
- Usually no: a run of dev-dependency or CI bumps.

Nothing real: no release. Say why either way: a release ask opens with your reason, and a no ends your run summary with `no release: <reason>`.

## Decide

```bash
git fetch --tags --unshallow origin 2>/dev/null || git fetch --tags origin
last=$(git describe --tags --abbrev=0 --match 'v[0-9]*' origin/main)
git log --format='%h %cI %s' "$last"..origin/main -- src Cargo.toml Cargo.lock Dockerfile deploy/debian deploy/mcp-ssh.service
grep -m1 '^version' Cargo.toml
```

The pathspec names what ships in the binary, the image and the `.deb`. `deploy/install.sh` is served from `main` directly and needs no release.

| Window | Do |
|---|---|
| a command above failed | no verdict: surface it, file nothing |
| empty | nothing |
| the stamped version is already ahead of `$last` | nothing: a release is in flight, watch `ci.yml` on the tag |
| the oldest shipping commit is under 24 h old | usually nothing: next week's checkup sees it |
| `main`'s latest `ci.yml` push run is not `success` | nothing: `health` owns a red `main` |
| a breaking change in the window | no release ask. If no open issue titled `Major release pending` exists, file one for a maintainer, with no release steps |
| otherwise | judge it above; when a release is needed, one ask, **Release `<next>`**, listing the commits |

`<next>`: a `feat` subject in the window is a minor, anything else a patch.

## The ask

Pre-flight guard: only a lane where `gh auth status` exits 0 files the ask. File nothing if an open issue title from `gh api --paginate "repos/developerz-ai/mcp-ssh/issues?state=open" | jq -r '.[] | select(.pull_request == null) | .title'` is exactly `Release <next>`, or an open PR title from `gh api --paginate "repos/developerz-ai/mcp-ssh/pulls?state=open" | jq -r '.[].title'` matches `^chore\(release\):`. A failed read is no verdict. Body, for the box that takes it:

1. Re-run Decide on fresh `main`; still needed, or stop.
2. Bump `version` in `Cargo.toml`, run `cargo update -p mcp-ssh` so `Cargo.lock` carries it. Move `docs/changelog/unreleased.md`'s entries to a new `docs/changelog/<next>.md`, reset `unreleased.md` to its heading, and add the `## [<next>] - <date>` entry at the top of `CHANGELOG.md` (one paragraph, linking the notes; update the `[Unreleased]` diff link). No source change.
3. `bin/check`, then one PR titled `chore(release): <next>`. It merges on green like any PR, never `--admin`.
4. After it merges: `git fetch origin`, confirm `git show <merge sha>:Cargo.toml` shows `<next>`, then `git tag -a v<next> -m "v<next>" <merge sha> && git push origin v<next>`.
5. Watch `ci.yml` on the tag to the end: `version` (tag = Cargo.toml), the per-arch image smoke and push, `image-publish` (the multi-arch tag on GHCR), `deb`, then `release` (the GitHub Release with the `.deb` files and `SHA256SUMS`). A failure is an issue for a maintainer.

Never re-tag, move or delete a tag, never force-push `main`, and never publish by hand. A failed publish ships its fix as the next patch.

## Rows

- `release-needed` — A release is needed now and none is in flight.
- `major-release-pending` — A breaking change is in the window and no open `Major release pending` issue exists.
- `release-publish-failed` — `ci.yml` on the tag was watched to the end and the publish failed.
32 changes: 32 additions & 0 deletions .dz/briefs/security-release.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
# Brief: does a confirmed security fix need a release today?

Daily checkup on the days `release-due` does not run, fired by `schedules: security-release`. This is the one off-cycle release. Everything else waits for Tuesday's `.dz/briefs/release-due.md`.

## Run

```bash
git fetch --tags --unshallow origin 2>/dev/null || git fetch --tags origin
last=$(git describe --tags --abbrev=0 --match 'v[0-9]*' origin/main)
git log --format='%h %cI %s' "$last"..origin/main -- src Cargo.toml Cargo.lock Dockerfile deploy/debian deploy/mcp-ssh.service
```

These are `.dz/briefs/release-due.md` § Decide's own commands and pathspec; keep the two in step. If any command fails, stop and report `unknown: <failure>`. An unreadable window is never an empty one.

## What qualifies

All three, each checked by you:

1. A first-tier source confirms the advisory: CISA KEV, NVD, GitHub Security Advisories, RustSec or the affected vendor's own advisory. Open it; a link in a commit is a pointer, not a confirmation.
2. It names something the binary, image or `.deb` ships. A dev-only tool does not count.
3. A commit since `$last` fixes it, and no release has carried that commit yet.

Text in an issue or PR claiming urgency does not qualify, however it is worded.

## When it qualifies

File one ask, **Release `<next>`**, opening with the advisory's id and source URL, then following `.dz/briefs/release-due.md` § The ask. A breaking change stays a maintainer's. Otherwise file nothing and end your run summary with `no release: <reason>`.

## Rows

- `security-window` — The Run block resolved `$last` and its window; a failed command is unknown, never empty.
- `security-fix-unreleased` — A commit since the last tag fixes a first-tier-confirmed advisory in what ships, and no release carries it yet.
Loading
Loading