From e845a6ee7264a2035e174347bddfaa7452bd8ef0 Mon Sep 17 00:00:00 2001 From: "claude@clouddev1" Date: Mon, 22 Jun 2026 21:43:51 +0000 Subject: [PATCH] docs: correct the stale fmt-gate note in CLAUDE.md; handoff-79 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CLAUDE.md said "fmt is intentionally not gated yet" — stale; the gate is now fmt + clippy + test (ADR-ci-002 Amendment 1 / issue #35), run via `nix develop -c`. Add CI-exact local-verification guidance and flag the exit-code-vs-piped-output trap that masked the fmt failure this session. handoff-79 records the blob removal + the CI/fmt lesson. --- CLAUDE.md | 16 +++++++--- docs/handoff/20260622-handoff-79.md | 46 ++++++++++++++++++++--------- 2 files changed, 44 insertions(+), 18 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 4be7430..e9bad8f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -115,15 +115,23 @@ Current decisions at a glance (each backed by an ADR): a self-hosted **Gitea Actions** pipeline built on a **nix flake** (pinned Rust `1.95.0` — one source of toolchain for dev *and* CI) plus a - prebuilt CI image. **Gate** (`ci.yaml`): `clippy -D warnings` + - `cargo test` on every branch push / PR. **Release** on a `v*` tag + prebuilt CI image. **Gate** (`ci.yaml`, every step run via `nix + develop -c` so dev and CI share the pinned toolchain): `cargo fmt + --check` + `clippy -D warnings` + `cargo test --no-fail-fast` on + every branch push / PR. **Verify locally the CI way before pushing** + — `nix develop -c cargo fmt --check`, `nix develop -c cargo clippy + --all-targets -- -D warnings`, `nix develop -c cargo test` — and read + the **exit code**, not piped output (a `cargo fmt --check | tail && + echo clean` masks the real result; a bare host `cargo` may also differ + from the pinned toolchain). **Release** on a `v*` tag (`release.yaml`): the four non-macOS **D1** targets cross-built with `cargo-zigbuild` (Linux musl static + standalone Windows `.exe`); the two macOS targets via the **dispatched** `release-macos.yaml` on a Tart Apple-Silicon runner (de-nix the `libiconv` load path + ad-hoc re-sign). All published to a Gitea - release with `.sha256`s. **`fmt` is intentionally not gated yet** - (the tree isn't stock-`rustfmt`-clean). Now that this is on `main`, + release with `.sha256`s. **`fmt` is gated** (`cargo fmt --check`, + stock defaults — enabled once the tree was reformatted on `main`, + ADR-ci-002 Amendment 1 / issue #35). Now that this is on `main`, `release-macos` is dispatchable (`workflow_dispatch` is Gitea-default-branch-only) — **dispatched and verified working**: the macOS build + de-nix/re-sign + upload runs end-to-end and the binaries diff --git a/docs/handoff/20260622-handoff-79.md b/docs/handoff/20260622-handoff-79.md index 5ab85c3..d6014ae 100644 --- a/docs/handoff/20260622-handoff-79.md +++ b/docs/handoff/20260622-handoff-79.md @@ -7,15 +7,15 @@ Amendment 2), which grew out of a one-line copy-rule fix. ## §1. State -**Branch `main`.** Commits this session so far (all on `main`, **not pushed**): -`07575da` (#39 gate) · `e88fa79` (handoff-77 + changelog rule) · `3ad4aff` -(#36 help) · `64818c0` (handoff-78) · `1a2002d` (**ADR-0005 Amendment 2** — -the blob-drop decision record). +**Branch `main`.** Commits this session (`1a2002d` ADR-0005 Am2 + `6b4c4dc` +blob removal, plus the earlier `07575da` #39 · `e88fa79` handoff-77 · `3ad4aff` +#36 · `64818c0` handoff-78) — **the user pushed these.** A follow-up +**`style:` rustfmt commit + this CLAUDE.md/handoff doc commit** land on top +(see §5) and are the only unpushed work at handoff time. -**Uncommitted: the blob-removal implementation** (39 files) — staged for review, -commit proposed at session end (see §4). **Full suite green: 2520 passed / 0 -failed / 1 ignored** (1810 lib + 7 e2e_pty + 503 it + 200 typing). -`clippy --all-targets -D warnings` + `fmt --check` clean. +**Suite green: 2521 passed / 0 failed / 1 ignored** (1810 lib + 8 e2e_pty + 503 +it + 200 typing), `fmt --check` + `clippy -D warnings` clean — **verified via +`nix develop -c`** (the CI-exact way; see §5's lesson). **Closed this session:** #36, #39. **Open:** #37 (clause hints), #38 (diagnostic route — needs a do/defer/close call), #40 (winget release notes). @@ -92,16 +92,34 @@ is deleted outright. ## §4. Process pins / next - Commits user-confirmed, no AI attribution, append-only, on `main`; **push is - the user's step** (everything this session is unpushed). + the user's step.** - **`/runda` was run on both the ADR (design) and the implementation.** The implementation pass found one real gap — the runtime's migrate-on-open glue was untested — closed with the new Tier-4 PTY test. It also verified the import path migrates (extract→migrate→rebuild) and the non-migration `parse_schema` callers fail-safe. -- Proposed commit split for the implementation: (1) `feat(types)!` — code + - tests + CHANGELOG; (2) `docs` — the CLAUDE.md/requirements/website/ADR-x-ref - sweep; (3) `docs(handoff-79)`. - Consider a `cargo sweep` at this milestone. - **Next open issues:** #37 (clause hints, on-mission), #38 (escalate - do/defer/close first), #40 (winget release notes). Plus: blob removal means a - `cargo sweep`-worthy build and a good moment to push. + do/defer/close first), #40 (winget release notes). + +## §5. CI/fmt lesson (cost a red CI run — don't repeat) + +The blob commit `6b4c4dc` **failed the CI `fmt` gate** (run 92, `ci.yaml`). +Two compounding causes, both fixed here: + +1. **`fmt` IS gated now** (`cargo fmt --check`, ADR-ci-002 Amendment 1 / issue + #35) — but `CLAUDE.md` still said "fmt is intentionally not gated yet." That + stale note bred complacency. **Corrected `CLAUDE.md`** (the gate is fmt + + clippy + test, run via `nix develop -c`). +2. **A broken local check masked the failure:** `cargo fmt --check 2>&1 | tail + -1 && echo "fmt clean"` tests `tail`'s exit code (always 0), **not** fmt's — + so "fmt clean" printed over real diffs. **Always read the exit code**, never + a piped `… | tail && echo clean`. + +**Going forward, verify the CI way:** `nix develop -c cargo fmt --check` / +`nix develop -c cargo clippy --all-targets -- -D warnings` / `nix develop -c +cargo test` — matching the pinned 1.95.0 toolchain *and* the devShell env, and +checking exit codes. (A bare host `cargo` happened to be 1.95.0 this time, so +the divergence was the masking pipe, not the toolchain — but `nix develop -c` +guards both.) The `style:` rustfmt fix + this doc update land on top of +`6b4c4dc`; CI re-runs green on the next push.