|
| 1 | +# M0 — Walking Skeleton: Retrospective |
| 2 | + |
| 3 | +**Closed:** 2026-04-27 (~1 day of agent-paced work vs. 1 week budget) |
| 4 | +**Exit commit:** to be tagged `m0-exit` from this branch's merge commit. |
| 5 | + |
| 6 | +## Scope delivered |
| 7 | + |
| 8 | +Plan §7.1 task list (#19–#28), with #29 (the `m0-exit` tag) attached to |
| 9 | +this retrospective's merge commit: |
| 10 | + |
| 11 | +- 13-crate Cargo workspace, compiling clean under MSRV 1.85 / edition 2024. |
| 12 | +- `pearlite-cli` clap stub: `pearlite --version`, `pearlite --help`. |
| 13 | +- `pearlite-audit` binary with SPDX-001 + 4 unit tests; subcommands |
| 14 | + `check` / `list` / `explain`. |
| 15 | +- Workspace lints per Plan §4.2, including `unsafe_code = "forbid"`. |
| 16 | +- `justfile` + `.rusty-hook.toml` + `scripts/ci/check-spdx.sh`. |
| 17 | +- `LICENSE` (canonical GPL-3.0-or-later), `README`, `AGENTS.md`, |
| 18 | + `CONTRIBUTING.md`, `CHANGELOG.md`. |
| 19 | +- Three AUR PKGBUILDs (`pearlite-bin`, `pearlite`, `pearlite-git`). |
| 20 | +- GitHub Actions: `ci.yml` (active), `vm.yml` (skeleton), `release.yml` |
| 21 | + (skeleton). |
| 22 | +- GitHub repo at `github.com/Steelbore/Pearlite`, branch protection per |
| 23 | + Plan §5.10, `CODEOWNERS` landed via PR #1 — workflow exercised |
| 24 | + end-to-end once. |
| 25 | + |
| 26 | +## What went well |
| 27 | + |
| 28 | +- **Walking-skeleton discipline held.** Every commit since first push |
| 29 | + has carried green CI tier 1+2+3; no broken-`main` intervals, no |
| 30 | + rebuild required. |
| 31 | +- **The Plan §4.2 lint set was strict but tractable.** Only |
| 32 | + `clippy::similar_names` and `clippy::single_match_else` snagged minor |
| 33 | + wording fixes during `pearlite-audit` work; nothing forced a |
| 34 | + structural rewrite. |
| 35 | +- **`pearlite-audit::check_spdx` caught its expected violation** during |
| 36 | + a hand-staged negative test against a malformed `bad_check.rs`, |
| 37 | + validating the pre-commit hook will do its job before contributor |
| 38 | + changes hit CI. |
| 39 | +- **Plan-as-spec held up under execution.** The §6.13 audit-crate brief |
| 40 | + translated to a working binary in one pass; the §4.2 / §4.3 / §4.5 |
| 41 | + workspace skeleton specifications were complete enough that no |
| 42 | + clarifying questions were needed. |
| 43 | + |
| 44 | +## What didn't |
| 45 | + |
| 46 | +- **`ghcr.io/cachyos/cachyos:latest` is not publicly available.** The |
| 47 | + Plan §5.6 `ci.yml` structure assumed this image existed. Discovered on |
| 48 | + the very first CI run (PR #1) — a pull-retry storm before the lint |
| 49 | + job even started. Fixed by dropping the container directive entirely; |
| 50 | + reinstating an Arch-family runner is M1 work. |
| 51 | +- **`cargo install cargo-machete` fails under our pinned 1.85 |
| 52 | + toolchain** because cargo-machete v0.9.2 transitively requires rustc |
| 53 | + 1.86 via `cargo-platform` 0.3.2. Fixed by switching all CI tooling |
| 54 | + installs to `taiki-e/install-action@v2` which fetches pre-built |
| 55 | + binaries — sidesteps build-time MSRV of the tooling without bumping |
| 56 | + the project's own MSRV. |
| 57 | +- **No system `cc` in the local dev environment.** Cargo invocations are |
| 58 | + wrapped in `nix-shell -p gcc --run` here. Documented in |
| 59 | + `CONTRIBUTING.md`; not an issue on a CachyOS dev box. |
| 60 | +- **Branch protection vs. solo dev.** `required_approving_review_count: 1` |
| 61 | + blocks self-merge; admin-bypass is the escape hatch and the runtime |
| 62 | + permission gate (correctly) treats each `--admin` merge as a separate |
| 63 | + authorisation boundary. Working as intended, but adds friction during |
| 64 | + solo work. Will revisit if a second contributor lands. |
| 65 | + |
| 66 | +## Open items rolled forward |
| 67 | + |
| 68 | +- **Phase 0:** AUR namespace reservation — deferred to M6 release prep |
| 69 | + per Plan §7.7. The names `pearlite-bin` / `pearlite` / `pearlite-git` |
| 70 | + remain claimable on the AUR until then. |
| 71 | +- **M1 Week 1:** pure crates — `pearlite-schema`, `pearlite-state`, |
| 72 | + `pearlite-fs` per Plan §6.1–§6.4. |
| 73 | + |
| 74 | +## Numbers |
| 75 | + |
| 76 | +| Metric | Value | |
| 77 | +|---|---| |
| 78 | +| Commits on `main` | 3 (walking skeleton, CODEOWNERS PR squash, this retrospective) | |
| 79 | +| PRs merged | 1 at exit | |
| 80 | +| Files tracked at exit | 53 | |
| 81 | +| Lines of code | ~3,200 (incl. `Cargo.lock` + GPL text) | |
| 82 | +| Crates compiling | 13 / 13 | |
| 83 | +| Tests passing | 4 / 4 (all in `pearlite-audit`) | |
| 84 | +| CI runtime, first green | ~105 s (T1 33 s + T2 34 s + T3 38 s) | |
| 85 | +| `cargo clippy --workspace --all-targets -- -D warnings` | zero warnings | |
| 86 | + |
| 87 | +## Actions for M1 |
| 88 | + |
| 89 | +1. **CachyOS CI runner.** Decide whether to publish a custom |
| 90 | + `ghcr.io/steelbore/cachyos` image or wait for an upstream one. Adapter |
| 91 | + tier-3 tests (paru/snapper/nickel) need the real toolchain; gating |
| 92 | + M2 apply work on that decision is risky. |
| 93 | +2. **Tooling MSRV drift.** Watch `cargo-machete` for a release that |
| 94 | + works with rustc 1.85, and decide whether MSRV bumps are tracked per |
| 95 | + ADR per Plan §13. If we end up needing an MSRV bump for tooling, |
| 96 | + ADR-008 is the place. |
| 97 | +3. **Begin Plan §6.1 — `pearlite-schema`.** Pure crate, ~600 LOC, |
| 98 | + ~6 PD. The two non-obvious parts are (a) property-test coverage of |
| 99 | + the contract validators, (b) a fixture-driven schemars-output check |
| 100 | + that the emitted JSON Schema is Draft 2020-12. |
0 commit comments