Skip to content

docs(retrospective): M0 walking skeleton closure #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
UnbreakableMJ merged 1 commit into from
Apr 27, 2026
Merged

docs(retrospective): M0 walking skeleton closure #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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: 6 additions & 6 deletions TODO.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand All @@ -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

---

Expand Down
100 changes: 100 additions & 0 deletions docs/retrospectives/M0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Loading