From 864de814cda2dec18b434d902ad7f4c55b1f0aeb Mon Sep 17 00:00:00 2001 From: LGUG2Z Date: Sat, 31 Oct 2026 14:59:52 -0700 Subject: [PATCH] docs: begin each plan document in docs/dev with a one-line status The documents in docs/dev were written at different points of the consolidation and some of their statements are history (for example unified-binaries.md still says "never write -p komorebi", true before step 8). Each now opens with a "Status (wip-cand4)" line saying whether it is design, evidence or a log, what has landed, what has not, and, for unified-binaries.md, which part is superseded. The statuses were taken from the revision list wip-main..wip-cand4 and the progress log, not from re-measuring. Only the line under the title was added; no existing text changed. Not built. --- docs/dev/backend-switch.md | 2 ++ docs/dev/bar-e2e.md | 2 ++ docs/dev/bar-unification.md | 2 ++ docs/dev/core-model.md | 2 ++ docs/dev/macos-handcheck.md | 2 ++ docs/dev/seam.md | 2 ++ docs/dev/settings.md | 2 ++ docs/dev/unified-binaries.md | 2 ++ 8 files changed, 16 insertions(+) diff --git a/docs/dev/backend-switch.md b/docs/dev/backend-switch.md index 2cc78001..dec2e4ae 100644 --- a/docs/dev/backend-switch.md +++ b/docs/dev/backend-switch.md @@ -1,5 +1,7 @@ # Windows: which call sites go through `backend()` +> **Status (wip-cand4):** in progress. The clusters in "Switched" are landed (each BEHAVIOUR, e2e-gated); the rest is deliberately left on `WindowsApi`, see the two "not switched" tables; nothing here is planned further until `WindowManager

` ([core-model.md](core-model.md) section 18). + Step 8 of the unified-binaries plan. `komorebi::windows_backend::backend()` returns the shared `komorebi_backend::Backend` (a stateless `WindowsBackend` over `WindowsApi` and `Window`). The daemon is switched one cluster at a time; each switch is its own revision marked BEHAVIOUR. diff --git a/docs/dev/bar-e2e.md b/docs/dev/bar-e2e.md index 19a0e4af..3b41647e 100644 --- a/docs/dev/bar-e2e.md +++ b/docs/dev/bar-e2e.md @@ -1,5 +1,7 @@ # Windows e2e for komorebi-bar +> **Status (wip-cand4):** current; the `bar` scenario exists and is the runtime gate for `komorebi-bar` and `komorebi-bar-core` on Windows. + The `bar` scenario (`e2e/platforms/qemu_windows/extras/bar.py`, registered as `EXTRAS["bar"]` in `run.py`) is the runtime gate for changes to `komorebi-bar` and `komorebi-bar-core`: the unit tests and the schema oracle cannot run the bar. Run it on the golden Windows guest: diff --git a/docs/dev/bar-unification.md b/docs/dev/bar-unification.md index cad5b74d..b9484b71 100644 --- a/docs/dev/bar-unification.md +++ b/docs/dev/bar-unification.md @@ -1,5 +1,7 @@ # One `komorebi-bar` for Windows and macOS +> **Status (wip-cand4):** B0-B3 done (one `komorebi-bar` package, a module per platform, schema views); B4 (merging the rendering code) not done and cannot be shown mechanical without a screen; macOS bar never rendered by these changes. + Status at the revision that adds this file. Everything below was measured on this tree with `diff` (counts are lines that differ, `<`/`>` lines of `diff`, hunks in parentheses). Nothing here was rendered: the bars cannot run on Linux. Gates that did run are named; the ones that diff --git a/docs/dev/core-model.md b/docs/dev/core-model.md index 4e150a99..0f8be2c8 100644 --- a/docs/dev/core-model.md +++ b/docs/dev/core-model.md @@ -1,5 +1,7 @@ # The core model: KDE and Windows compared, and the split into `komorebi-core` +> **Status (wip-cand4):** measurement plus a running log. `komorebi-core` has `Container`, `Monitor`, `Workspace` (incl. `update_shared`) over KDE, Windows and macOS; `WindowManager

`, the router and `process_event` are NOT shared yet (sections 17 and 18 give the blockers); sections 8 and 12 are the designs that were then implemented. + Status: measurement and proposal (plan step 9 preparation, KDE side). Measured at the tip of `wip-u-kfde` (based on `wip-main` 633e7453); the Windows tree is `komorebi/src`, KDE is `komorebi-for-kde/komorebi/src`, macOS (`komorebi-for-mac/komorebi/src`) is listed only where it diff --git a/docs/dev/macos-handcheck.md b/docs/dev/macos-handcheck.md index 40b156dd..4ae92298 100644 --- a/docs/dev/macos-handcheck.md +++ b/docs/dev/macos-handcheck.md @@ -1,5 +1,7 @@ # macOS hand-check list +> **Status (wip-cand4):** OPEN, for the user on a real Mac; only compile and unit tests have run on a Mac Mini, no macOS daemon behaviour has been observed; commands for the Mac are in [build-and-test.md](build-and-test.md). + Status: written by the `kfm` agent for the user, 2026-10-31. Nothing here has been run: macOS cannot be built, linked or tested on the Linux host, only type-checked through a fake C compiler (`tools/fast-check`). Every revision below is `type-checks, not run`. Revision ids are jj change ids (stable) with the commit id they had when this was written (commit ids change when a revision is rewritten; use `jj log -r `). How to use it: build the unified (or, until they exist, the per-tree) macOS `komorebi`, `komorebic` and `komorebi-bar`, run `cargo test --workspace` on the Mac first (the 399+ unit tests have never run against these changes), then walk the sections in order. For before/after capture use `komorebi-recorder` against a build of the baseline `wip-main` ancestor `ff3711dc` and the tip. A section is done when the "look for" column is true. diff --git a/docs/dev/seam.md b/docs/dev/seam.md index 138ad96c..a47edcd9 100644 --- a/docs/dev/seam.md +++ b/docs/dev/seam.md @@ -1,5 +1,7 @@ # The platform seam: evidence +> **Status (wip-cand4):** the evidence for `crates/komorebi-backend`, which has landed (trait, `FakeBackend`, contract tests); the Windows daemon goes through it for the clusters in [backend-switch.md](backend-switch.md); read section 8 as the list of what was never verified. + Status: evidence document (step 7a of the consolidation). No `Backend` trait is proposed here as code, and none may be written before this document has been reviewed. Every statement about the code carries a citation; where I could not confirm something it says "not verified" and the item is collected in section 8. ## 1. Purpose and how to read it diff --git a/docs/dev/settings.md b/docs/dev/settings.md index 3aea7225..da70d486 100644 --- a/docs/dev/settings.md +++ b/docs/dev/settings.md @@ -1,5 +1,7 @@ # Settings: replacing the process-wide statics +> **Status (wip-cand4):** design plus landing log. `crates/komorebi-settings` exists and the three daemons read the paddings, aspect ratio, layout defaults and display preferences through it; the remaining statics (see the section list) are still process-wide; macOS runtime is unverified. + Status: design (plan step 10, phase 1). Measured on `wip-main` 633e7453 (the Windows tree `komorebi/src`, KDE `komorebi-for-kde/komorebi/src`, macOS `komorebi-for-mac/komorebi/src`). Nothing here was run: counts come from `grep` and reading, and macOS cannot run on this host. The shared type diff --git a/docs/dev/unified-binaries.md b/docs/dev/unified-binaries.md index ca4d26a9..bdd20728 100644 --- a/docs/dev/unified-binaries.md +++ b/docs/dev/unified-binaries.md @@ -1,5 +1,7 @@ # One `komorebi`, one `komorebic`, one `komorebi-bar` +> **Status (wip-cand4):** steps 0-8 done: one `komorebi` (`komorebi-daemon/`), `komorebic`, `komorebi-client` and `komorebi-bar` package, platform by `cfg(target_os)`; the cutover (shim packages, one flake, final directories, one version) is open. The older sections below are history: in particular the note "never write `-p komorebi`" was true before step 8 and is wrong now; see [build-and-test.md](build-and-test.md) for current commands. + Goal: three packages and three binaries that build on Windows, KDE (Linux) and macOS, the platform chosen by `cfg(target_os)` (generics, `cfg_select!`, exhaustive `match`; no macros as a design tool). This file records a spike (throwaway revisions on bookmark `wip-u-pkg-spike`, titled `spike:`; nothing