From c6b69bb1ec9423d842c2f6be8885357e9ce9e769 Mon Sep 17 00:00:00 2001 From: James Maes Date: Wed, 29 Jul 2026 11:34:06 -0500 Subject: [PATCH 1/2] fix(build): remove unfixable cargo verify alias, reword docs Cargo aliases are a single command argv and cannot chain subcommands, so `cargo verify = ["fmt --all -- --check", "check-all", "test-all"]` tried to run a literal subcommand named "fmt --all -- --check" and always errored. The pre-commit hook already runs the three checks as separate commands, so it was unaffected. Drop the broken alias, drop the matching RustRover run configuration, and reword every doc that told readers to run `cargo verify` to instead run fmt/check-all/test-all as three commands. --- .cargo/config.toml | 1 - .idea/runConfigurations/Cargo_Verify.xml | 16 --------------- CLAUDE.md | 15 ++++++++++++-- README.md | 5 ++++- docs/BACKLOG.md | 5 +++-- docs/DEVELOPING-IN-RUSTROVER.md | 26 +++++++++++++++++------- docs/HANDOFF.md | 8 ++++++-- docs/ROADMAP.md | 10 +++++---- docs/STORY-WORKFLOW.md | 11 ++++++---- 9 files changed, 58 insertions(+), 39 deletions(-) delete mode 100644 .idea/runConfigurations/Cargo_Verify.xml diff --git a/.cargo/config.toml b/.cargo/config.toml index 0d27fbe..3cd3665 100644 --- a/.cargo/config.toml +++ b/.cargo/config.toml @@ -3,7 +3,6 @@ check-all = "clippy --all-targets --workspace -- -D warnings" test-all = "test --workspace" cov = "llvm-cov --workspace --ignore-filename-regex main\\.rs --summary-only" -verify = ["fmt --all -- --check", "check-all", "test-all"] # Dogfooding: build the runnable daemon + reference CLI in release mode. build-release = ["build", "--release", "-p", "nunciod", "-p", "nuncio-cli"] # Remove the entire workspace target directory (all crates, all profiles). diff --git a/.idea/runConfigurations/Cargo_Verify.xml b/.idea/runConfigurations/Cargo_Verify.xml deleted file mode 100644 index c457f2c..0000000 --- a/.idea/runConfigurations/Cargo_Verify.xml +++ /dev/null @@ -1,16 +0,0 @@ - - - - diff --git a/CLAUDE.md b/CLAUDE.md index 235d070..7cd5f89 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -60,7 +60,16 @@ Cargo aliases (defined in `.cargo/config.toml`): cargo check-all # = clippy --all-targets --workspace -- -D warnings (the lint gate) cargo test-all # = test --workspace cargo cov # = llvm-cov --workspace --ignore-filename-regex main.rs --summary-only (informational; needs cargo-llvm-cov) -cargo verify # = fmt --all --check + check-all + test-all +``` + +There is no `cargo verify` alias — Cargo aliases are a single command's argv and +cannot chain subcommands. Run the full gate as three separate commands (this is +exactly what the pre-commit hook runs): + +```bash +cargo fmt --all -- --check +cargo check-all +cargo test-all ``` Common commands: @@ -92,7 +101,9 @@ A shared RustRover setup lives in `.idea/` (the useful parts are tracked; - *Run nunciod (daemon)* — start the daemon. - *Run nuncio-cli (system status)* — drive it (start the daemon first). - *Cargo Build Release (daemon + CLI)* — `cargo build-release`. - - *Cargo Check All* · *Cargo Test All* · *Cargo Verify (fmt + clippy + tests)* — the gates. + - *Cargo Check All* · *Cargo Test All* — the gates (run `cargo fmt --all -- --check` + separately; there is no combined run configuration, since Cargo aliases and + RustRover run configurations can't chain subcommands). - *Cargo Coverage* — informational `llvm-cov` (needs `cargo-llvm-cov` installed). - Tip: set Clippy as the external linter (Settings → Rust → External Linters) so the editor mirrors the `-D warnings` gate. diff --git a/README.md b/README.md index 6f51eac..a71f8f4 100644 --- a/README.md +++ b/README.md @@ -52,10 +52,13 @@ repositories (roadmap Phase 5). cargo build --workspace # build everything cargo check-all # clippy, all targets, warnings-as-errors (the gate) cargo test-all # run the whole test suite -cargo verify # fmt --check + check-all + test-all cargo test -p nuncio-store # test a single crate ``` +There is no `cargo verify` alias (Cargo aliases can't chain subcommands). Run the +full local gate as three separate commands — `cargo fmt --all -- --check`, +`cargo check-all`, `cargo test-all` — which is exactly what the pre-commit hook runs. + Cargo aliases are defined in [`.cargo/config.toml`](.cargo/config.toml). ## Documentation diff --git a/docs/BACKLOG.md b/docs/BACKLOG.md index adb250f..eeee56b 100644 --- a/docs/BACKLOG.md +++ b/docs/BACKLOG.md @@ -9,7 +9,8 @@ Ordered, executable stories for the first two phases of [`ROADMAP.md`](ROADMAP.m Each story has acceptance criteria (AC) and a rough size (S ≤1d, M ≈2–4d, L ≈1wk). Do them roughly top-to-bottom; within an epic, stories are mostly independent unless noted. **Definition of done for every story:** engine + (where applicable) -proto + CLI + offline test, and `cargo verify` green. +proto + CLI + offline test, and the local gate green (`cargo fmt --all -- --check`, +`cargo check-all`, `cargo test-all`). --- @@ -41,7 +42,7 @@ proto + CLI + offline test, and `cargo verify` green. `nuncio-core`). **AC:** `cargo check-all` exits 0 locally and in CI. - **0.C.2 Align CI to the local gate** (S). CI runs `cargo clippy --workspace` without `--all-targets`; make CI run `cargo check-all` so CI and local are - identical. **AC:** CI and `cargo verify` enforce the same lints. + identical. **AC:** CI and the local gate enforce the same lints. - **0.C.3 Replace the coverage gate** (M). Drop the gamed 100%-line gate (it excludes all `main.rs` and incentivized stub+matching-test theater) for a realistic threshold on engine crates plus a **required** mock-server E2E job. diff --git a/docs/DEVELOPING-IN-RUSTROVER.md b/docs/DEVELOPING-IN-RUSTROVER.md index 27669a7..aebf39b 100644 --- a/docs/DEVELOPING-IN-RUSTROVER.md +++ b/docs/DEVELOPING-IN-RUSTROVER.md @@ -110,9 +110,17 @@ RustRover's Cargo test integration is the fastest inner loop. ## 5. Quality gates (run before you commit/push) The Git pre-commit hook runs `fmt` + `clippy -D warnings` (all targets) + the full -test suite on every `git commit`, so make these green first: +test suite on every `git commit`, so make these green first. There is no combined +`cargo verify` alias — a Cargo alias is a single command's argv and can't chain +subcommands, so run the three checks separately (this is exactly what the +pre-commit hook does): + +```bash +cargo fmt --all -- --check +cargo check-all +cargo test-all +``` -- **Cargo Verify (fmt + clippy + tests)** — the whole gate in one click (= `cargo verify`). - **Cargo Check All** — just clippy, all targets, warnings-as-errors. - **Cargo Test All** — the suite. - **Cargo Coverage** — informational `llvm-cov` (needs `cargo-llvm-cov`; not a gate). @@ -120,8 +128,8 @@ test suite on every `git commit`, so make these green first: (= `cargo build-release`), i.e. what you ship for real dogfooding. Because the toolchain is pinned (1.97.1) and native, **green here == green in CI** — -so a clean *Cargo Verify* means a clean commit and (once CI minutes are back) a -clean pipeline. +so running `cargo fmt --all -- --check` plus *Cargo Check All* and *Cargo Test All* +clean means a clean commit and (once CI minutes are back) a clean pipeline. --- @@ -137,9 +145,11 @@ clean pipeline. | Cargo Build Release (daemon + CLI) | `build-release` | no | | Cargo Check All | `check-all` | no | | Cargo Test All | `test-all` | no | -| Cargo Verify (fmt + clippy + tests) | `verify` | no | | Cargo Coverage | `cov` (informational) | no | +There is no run configuration for the fmt check (`cargo fmt --all -- --check`) — +run it from the Terminal alongside *Cargo Check All* and *Cargo Test All*. + To make your own: **Run → Edit Configurations → + → Cargo Command**, set the command (e.g. `run -p nuncio-cli -- mail read --id abc`), and tick *Store as project file* to share it (it lands in `.idea/runConfigurations/`). @@ -151,7 +161,8 @@ project file* to share it (it lands in `.idea/runConfigurations/`). 1. Edit code; the editor lints (clippy) and formats-on-save as you go. 2. Run the nearest **test via its gutter icon** to check your change; **Debug** it if you need to step through. -3. When the feature/fix is done, run **Cargo Verify** — that's the commit gate. +3. When the feature/fix is done, run `cargo fmt --all -- --check`, **Cargo Check + All**, and **Cargo Test All** — that's the commit gate. 4. Commit (the hook re-runs the gate). Conventional Commits, feature branches off `dev` (see `CLAUDE.md`). 5. To see it end-to-end, run **nunciod** and drive it from the Terminal. @@ -170,7 +181,8 @@ project file* to share it (it lands in `.idea/runConfigurations/`). - **"Where's the TUI/GUI?"** Archived under `_reference/`; they'll be rebuilt as separate native client repos (roadmap Phase 5). They are not in the workspace. - **CI is currently paused** (GitHub Actions minutes). That's fine — the pinned - native toolchain makes your local *Cargo Verify* equivalent to CI. + native toolchain makes your local `fmt --check` + *Cargo Check All* + *Cargo Test + All* run equivalent to CI. --- diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md index 0e58da7..11d950b 100644 --- a/docs/HANDOFF.md +++ b/docs/HANDOFF.md @@ -6,7 +6,8 @@ machine (or a new LLM) picks up the work cold. ## TL;DR 1. `git checkout dev` — the canonical branch (Phases 0–2 done + the roadmap). It is - green under the pinned toolchain (1.97.1); `cargo verify` passes. + green under the pinned toolchain (1.97.1); `cargo fmt --all -- --check`, + `cargo check-all`, and `cargo test-all` all pass. 2. Read, in order: [`CLAUDE.md`](../CLAUDE.md), [`docs/ROADMAP.md`](ROADMAP.md), [`docs/STORY-WORKFLOW.md`](STORY-WORKFLOW.md), [`docs/ARCHITECTURE.md`](ARCHITECTURE.md). @@ -61,7 +62,10 @@ commit/push, review-before-close, honest-error over green-lie.** 1. Clone the repo; `git checkout dev`. The toolchain (1.97.1) installs automatically from `rust-toolchain.toml`. Native OS build (not WSL) — the daemon needs the OS keyring. -2. `cargo verify` (fmt + clippy `-D warnings` all-targets + test-all) — confirm green. +2. Confirm green: `cargo fmt --all -- --check`, then `cargo check-all` (clippy + `-D warnings` all-targets), then `cargo test-all`. (There is no combined + `cargo verify` alias — Cargo aliases can't chain subcommands — but this is + exactly what the pre-commit hook runs.) 3. Run it: `cargo run -p nunciod` (daemon), then drive with `cargo run -p nuncio-cli -- system status`. See `docs/RUNNING.md` / `docs/DEVELOPING-IN-RUSTROVER.md`. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 9ebd486..352dc0f 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -27,8 +27,9 @@ property of the **contract**, not of anyone's discipline. These are non-negotiable and apply to every item below: 1. **A capability is done only when engine + proto + CLI command + offline E2E - test all exist together**, and `cargo verify` (fmt + clippy `-D warnings` - all-targets + `test-all`) is green. + test all exist together**, and the local gate (`cargo fmt --all -- --check`, + `cargo check-all` (clippy `-D warnings` all-targets), `cargo test-all`) is + green. 2. **No fabricated success.** A path that cannot do the real thing returns an honest `Unimplemented`/error — never canned data, never a fake "sent". 3. **The `.proto` files are the contract.** The `nuncio-proto` contract-stability @@ -188,5 +189,6 @@ scheduled here or folded back into the engine as they earn their place. Each milestone maps to GitHub issues (numbers above). Every capability is built via one implementer + a spec/quality review gate + an offline E2E, committed only -when `cargo verify` is green and the proto golden is consistent. Issues close -only after the review step — never on a green build alone. +when the local gate (fmt + clippy `-D warnings` + tests) is green and the proto +golden is consistent. Issues close only after the review step — never on a green +build alone. diff --git a/docs/STORY-WORKFLOW.md b/docs/STORY-WORKFLOW.md index 5e57655..b9f8cc4 100644 --- a/docs/STORY-WORKFLOW.md +++ b/docs/STORY-WORKFLOW.md @@ -21,9 +21,11 @@ implement; the PO reviews and merges. Do not merge your own work. A story is done only when **all** of these hold: 1. **engine + proto (if the API surface changes) + CLI command + offline E2E test exist together** and prove the capability end to end. -2. `cargo verify` is green — that is `cargo fmt --all -- --check`, +2. The full local gate is green — that is `cargo fmt --all -- --check`, `cargo check-all` (clippy `--all-targets --workspace -D warnings`, **zero** - warnings), and `cargo test-all` (`cargo test --workspace`). **0 ignored tests.** + warnings), and `cargo test-all` (`cargo test --workspace`), run as three + separate commands (there is no combined `cargo verify` alias — Cargo aliases + can't chain subcommands). **0 ignored tests.** 3. **No fabricated success.** A path that cannot do the real thing returns an honest `Unimplemented`/error — never canned data, never a fake "sent"/"ok". (Anti-pattern to never imitate: a client that logs "fetching…" and returns a @@ -86,9 +88,10 @@ proto story is open. Non-proto stories (engine-only, CLI-only) can run in parall 2. TDD where practical. Keep commits Conventional (`feat(scope): …`, `fix(scope): …`), imperative, <72-char subject, **no AI attribution**, no issue refs in code (a `Refs #NNN` in the commit message is fine). -3. Before pushing, make `cargo verify` green. The pre-commit hook enforces it. +3. Before pushing, make sure `cargo fmt --all -- --check`, `cargo check-all`, and + `cargo test-all` are all green. The pre-commit hook enforces this. 4. Open a **PR to `dev`** (never to `main`). In the PR body: link the issue, - summarize what you built, **paste the gate output** (`cargo verify` result + + summarize what you built, **paste the gate output** (fmt/clippy/test results + test counts) as evidence, and list any decisions or follow-ups. If you found a real bug outside your scope, **file a new issue** — do not silently fix or ignore it. -- 2.54.0 From 71f3b715519ec0a57873ef8fbd7c01442b9b4254 Mon Sep 17 00:00:00 2001 From: James Maes Date: Wed, 29 Jul 2026 11:34:51 -0500 Subject: [PATCH 2/2] ci: run quality gates on the rc release branch The dev -> rc -> main flow left rc ungated: push/pull_request triggers only listed main and dev, so a release candidate branch could drift without CI ever running against it. Add rc to both branch lists. --- .github/workflows/ci.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 9316241..b3c72cd 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -2,9 +2,9 @@ name: CI Quality Gates & Build Pipeline on: push: - branches: [ main, dev ] + branches: [ main, dev, rc ] pull_request: - branches: [ main, dev ] + branches: [ main, dev, rc ] env: CARGO_TERM_COLOR: always -- 2.54.0