From 43a93d51328e34ce66a66b736fb062f445e0e59c Mon Sep 17 00:00:00 2001 From: UnbreakableMJ <34196588+UnbreakableMJ@users.noreply.github.com> Date: Mon, 27 Apr 2026 15:45:15 +0300 Subject: [PATCH] docs(retrospective): M0 walking skeleton closure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Plan §11.4 milestone-exit gate requires a retrospective in docs/retrospectives/M.md before the milestone tag is applied. Captures: scope delivered (Plan §7.1 #19-#28), what went well, what needed in-flight fixes (the cachyos GHCR container miss, cargo-machete MSRV gap), open items rolled forward to M1 (Phase 0 AUR namespaces, M1 Week 1 pure crates), and action items. Also updates TODO.md to mark Phase 0 / M0 items completed and re-classify the AUR namespace reservation as deferred to M6 per Plan §7.7. Co-Authored-By: Claude Opus 4.7 (1M context) --- TODO.md | 12 ++--- docs/retrospectives/M0.md | 100 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 106 insertions(+), 6 deletions(-) create mode 100644 docs/retrospectives/M0.md diff --git a/TODO.md b/TODO.md index 7b87f2e..a26315d 100644 --- a/TODO.md +++ b/TODO.md @@ -11,16 +11,16 @@ - [✓] Pearlite PRD v1.0 (55 pages, 18 sections) - [✓] Pearlite Implementation Plan v1.0 (67 pages, 15 sections) - [ ] Mawaqit-style brand assets adapted for Pearlite (logo, README banner) -- [ ] GitHub repository created at `github.com/Steelbore/Pearlite` -- [ ] Branch protection on `main` configured (per Plan §3.4) -- [ ] CODEOWNERS file authored -- [ ] AUR namespaces reserved (`pearlite-bin`, `pearlite`, `pearlite-git`) +- [✓] GitHub repository created at `github.com/Steelbore/Pearlite` +- [✓] Branch protection on `main` configured (per Plan §3.4) +- [✓] CODEOWNERS file authored +- [ ] AUR namespaces reserved (`pearlite-bin`, `pearlite`, `pearlite-git`) — deferred to M6 per Plan §7.7 --- ## M0 — Walking Skeleton (1 week) -- [~] Init git repo; configure branch protection (local `git init` done; GitHub branch protection deferred until repo is pushed) +- [✓] Init git repo; configure branch protection (Plan §3.4 + §5.10 active; `require_code_owner_reviews` true after CODEOWNERS landed via PR #1) - [✓] Workspace `Cargo.toml` (resolver "3", workspace metadata, lints, profiles) - [✓] `rust-toolchain.toml` pinning 1.85 - [✓] `deny.toml`, `clippy.toml`, `rustfmt.toml` @@ -32,7 +32,7 @@ - [✓] GitHub Actions: `ci.yml`, `vm.yml` (skeleton), `release.yml` (skeleton) - [✓] `pearlite-audit` binary with one trivial check (SPDX-001) wired into CI - [✓] Three AUR PKGBUILDs (pearlite-bin, pearlite, pearlite-git) for `0.1.0-alpha.0` -- [ ] Tag `m0-exit`; verify tarball + AUR build cleanly in CachyOS container +- [~] Tag `m0-exit` (signed tag from this commit); CachyOS-container PKGBUILD verification deferred to M6 since the container itself is M1 work --- diff --git a/docs/retrospectives/M0.md b/docs/retrospectives/M0.md new file mode 100644 index 0000000..f3075d6 --- /dev/null +++ b/docs/retrospectives/M0.md @@ -0,0 +1,100 @@ +# M0 — Walking Skeleton: Retrospective + +**Closed:** 2026-04-27 (~1 day of agent-paced work vs. 1 week budget) +**Exit commit:** to be tagged `m0-exit` from this branch's merge commit. + +## Scope delivered + +Plan §7.1 task list (#19–#28), with #29 (the `m0-exit` tag) attached to +this retrospective's merge commit: + +- 13-crate Cargo workspace, compiling clean under MSRV 1.85 / edition 2024. +- `pearlite-cli` clap stub: `pearlite --version`, `pearlite --help`. +- `pearlite-audit` binary with SPDX-001 + 4 unit tests; subcommands + `check` / `list` / `explain`. +- Workspace lints per Plan §4.2, including `unsafe_code = "forbid"`. +- `justfile` + `.rusty-hook.toml` + `scripts/ci/check-spdx.sh`. +- `LICENSE` (canonical GPL-3.0-or-later), `README`, `AGENTS.md`, + `CONTRIBUTING.md`, `CHANGELOG.md`. +- Three AUR PKGBUILDs (`pearlite-bin`, `pearlite`, `pearlite-git`). +- GitHub Actions: `ci.yml` (active), `vm.yml` (skeleton), `release.yml` + (skeleton). +- GitHub repo at `github.com/Steelbore/Pearlite`, branch protection per + Plan §5.10, `CODEOWNERS` landed via PR #1 — workflow exercised + end-to-end once. + +## What went well + +- **Walking-skeleton discipline held.** Every commit since first push + has carried green CI tier 1+2+3; no broken-`main` intervals, no + rebuild required. +- **The Plan §4.2 lint set was strict but tractable.** Only + `clippy::similar_names` and `clippy::single_match_else` snagged minor + wording fixes during `pearlite-audit` work; nothing forced a + structural rewrite. +- **`pearlite-audit::check_spdx` caught its expected violation** during + a hand-staged negative test against a malformed `bad_check.rs`, + validating the pre-commit hook will do its job before contributor + changes hit CI. +- **Plan-as-spec held up under execution.** The §6.13 audit-crate brief + translated to a working binary in one pass; the §4.2 / §4.3 / §4.5 + workspace skeleton specifications were complete enough that no + clarifying questions were needed. + +## What didn't + +- **`ghcr.io/cachyos/cachyos:latest` is not publicly available.** The + Plan §5.6 `ci.yml` structure assumed this image existed. Discovered on + the very first CI run (PR #1) — a pull-retry storm before the lint + job even started. Fixed by dropping the container directive entirely; + reinstating an Arch-family runner is M1 work. +- **`cargo install cargo-machete` fails under our pinned 1.85 + toolchain** because cargo-machete v0.9.2 transitively requires rustc + 1.86 via `cargo-platform` 0.3.2. Fixed by switching all CI tooling + installs to `taiki-e/install-action@v2` which fetches pre-built + binaries — sidesteps build-time MSRV of the tooling without bumping + the project's own MSRV. +- **No system `cc` in the local dev environment.** Cargo invocations are + wrapped in `nix-shell -p gcc --run` here. Documented in + `CONTRIBUTING.md`; not an issue on a CachyOS dev box. +- **Branch protection vs. solo dev.** `required_approving_review_count: 1` + blocks self-merge; admin-bypass is the escape hatch and the runtime + permission gate (correctly) treats each `--admin` merge as a separate + authorisation boundary. Working as intended, but adds friction during + solo work. Will revisit if a second contributor lands. + +## Open items rolled forward + +- **Phase 0:** AUR namespace reservation — deferred to M6 release prep + per Plan §7.7. The names `pearlite-bin` / `pearlite` / `pearlite-git` + remain claimable on the AUR until then. +- **M1 Week 1:** pure crates — `pearlite-schema`, `pearlite-state`, + `pearlite-fs` per Plan §6.1–§6.4. + +## Numbers + +| Metric | Value | +|---|---| +| Commits on `main` | 3 (walking skeleton, CODEOWNERS PR squash, this retrospective) | +| PRs merged | 1 at exit | +| Files tracked at exit | 53 | +| Lines of code | ~3,200 (incl. `Cargo.lock` + GPL text) | +| Crates compiling | 13 / 13 | +| Tests passing | 4 / 4 (all in `pearlite-audit`) | +| CI runtime, first green | ~105 s (T1 33 s + T2 34 s + T3 38 s) | +| `cargo clippy --workspace --all-targets -- -D warnings` | zero warnings | + +## Actions for M1 + +1. **CachyOS CI runner.** Decide whether to publish a custom + `ghcr.io/steelbore/cachyos` image or wait for an upstream one. Adapter + tier-3 tests (paru/snapper/nickel) need the real toolchain; gating + M2 apply work on that decision is risky. +2. **Tooling MSRV drift.** Watch `cargo-machete` for a release that + works with rustc 1.85, and decide whether MSRV bumps are tracked per + ADR per Plan §13. If we end up needing an MSRV bump for tooling, + ADR-008 is the place. +3. **Begin Plan §6.1 — `pearlite-schema`.** Pure crate, ~600 LOC, + ~6 PD. The two non-obvious parts are (a) property-test coverage of + the contract validators, (b) a fixture-driven schemars-output check + that the emitted JSON Schema is Draft 2020-12.