From 36f10f42b4e7ecf81377b9513f3c4cc28adeeebd Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 3 May 2026 00:33:45 +0000 Subject: [PATCH 1/3] Initial plan From 710ad5e6fe2bf9938e4f7e3d58caf1a4152b7b03 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 3 May 2026 00:35:52 +0000 Subject: [PATCH 2/3] docs(workstation): add world-class SourceOS and Mac-on-Linux gap plan Agent-Logs-Url: https://github.com/SociOS-Linux/source-os/sessions/68b7c5e1-6b1d-4278-8234-afd2ec955a0d Co-authored-by: mdheller <21163552+mdheller@users.noreply.github.com> --- .../world-class-sourceos-parity-plan.md | 387 ++++++++++++++++++ 1 file changed, 387 insertions(+) create mode 100644 docs/workstation/world-class-sourceos-parity-plan.md diff --git a/docs/workstation/world-class-sourceos-parity-plan.md b/docs/workstation/world-class-sourceos-parity-plan.md new file mode 100644 index 0000000..c4ad258 --- /dev/null +++ b/docs/workstation/world-class-sourceos-parity-plan.md @@ -0,0 +1,387 @@ +# World-Class SourceOS and Mac-on-Linux Gap Plan + +This document consolidates the current Mac-on-Linux / world-class SourceOS gap +analysis into a single actionable specification and plan. It is a docs-only +planning artifact. It does not claim full macOS parity or world-class OS +readiness. + +--- + +## Tier definitions + +Three tiers are distinguished throughout this document. Each has its own scope, +acceptance bar, and repo ownership. + +### Tier 1 — Mac-like GNOME workstation v0 + +**What it means:** A credible GNOME desktop that feels familiar to a macOS user +through bounded keyboard shortcuts, appearance defaults, touchpad gestures, +launcher behavior, and file navigation. No GNOME Shell fork. No proprietary +assets. No claim of feature-for-feature macOS parity. + +**Acceptance bar:** The features in `docs/workstation/mac-on-linux-acceptance.md` +reach `implemented` or `validation-backed` status and pass CI smoke checks. + +**Current status:** In progress. Several features are `implemented` or +`validation-backed`. Several items remain `planned`. See the acceptance matrix +for detail. + +### Tier 2 — macOS parity + +**What it means:** Matching a substantial portion of macOS UX, runtime, and +platform behaviors — including continuity features, iCloud-equivalent storage, +Handoff, AirDrop, signed/notarized application trust, accessibility parity, +full localization, and native-feel developer toolchains. + +**Current status:** Not attempted. Full macOS parity is a **non-goal** for +workstation-v0 and for the current SourceOS roadmap. This document does not +claim or target macOS parity. + +### Tier 3 — world-class OS + +**What it means:** An OS that competes on the following dimensions: runtime +integrity and verified boot, hardware lifecycle and firmware management, complete +backup and recovery, cryptographic identity and trust envelope, cross-device +continuity equivalents, accessible and fully localised UI, a stable and audited +contract canon for agents and host interfaces, evidence and reporting pipelines, +and a viable developer/user ecosystem. + +**Current status:** Not achieved. Design gaps are documented below. This +document does not claim world-class OS status. + +--- + +## What is already landed + +### `SociOS-Linux/source-os` + +| Area | Evidence | +|---|---| +| GNOME appearance defaults | `profiles/linux-dev/workstation-v0/gnome/appearance-apply.sh` | +| Mac-style keyboard shortcuts | `profiles/linux-dev/workstation-v0/gnome/mac-defaults.sh` | +| Screenshot bindings | `profiles/linux-dev/workstation-v0/bin/mac-screenshot.sh` | +| Launcher (SourceOS palette on `Super+Space`) | `profiles/linux-dev/workstation-v0/gnome/palette-hotkey.sh` | +| Finder-like sidebar bookmarks | `profiles/linux-dev/workstation-v0/gnome/files-sidebar.sh` | +| Touchpad gestures via Fusuma | `profiles/linux-dev/workstation-v0/gnome/fusuma-install.sh` | +| `input-remapper` keyboard backend | `profiles/linux-dev/workstation-v0/gnome/input-install.sh` | +| `xremap` compatibility lane | same as above | +| Lampstand-backed local file search | `profiles/linux-dev/workstation-v0/bin/sourceos-search.sh` | +| Aggregate polish validation | `profiles/linux-dev/workstation-v0/bin/check-workstation-polish.sh` | +| `sourceos status` / `sourceos doctor` CLI | `profiles/linux-dev/workstation-v0/bin/sourceos` | +| CI smoke workflows (keyboard, polish, Lampstand) | `.github/workflows/` | + +### `SourceOS-Linux/sourceos-spec` + +| Area | Notes | +|---|---| +| Contract canon drafts | Exists as the authoritative specification repository for SourceOS contracts. | +| Agent Machine interface drafts | Tracked in sourceos-spec; not fully ratified. | + +--- + +## What the design missed — gap catalogue + +The following areas have no or insufficient coverage in the current repositories. +Each gap is assigned a tier and a priority (P1 = blocking for next milestone, +P2 = important but not blocking, P3 = future). + +### Shell runtime and lifecycle (P1 — Tier 3) + +`SourceOS-Linux/sourceos-shell` **already exists** and is the designated repo +for the PDF-first / document-first runtime lane. The next required move is +**not** repo creation. It is: + +- Populating `sourceos-shell` with the PDF-first runtime primitives. +- Aligning `sourceos-shell` with the `source-os` workstation profile and the + `sourceos-spec` contract canon. +- Defining the handoff protocol between `sourceos-shell` and the `sourceos` + launcher in `source-os`. + +Gap: No content exists yet in `sourceos-shell` that demonstrates a working +runtime lane. No alignment document exists between the three repos. + +### Backup and recovery (P1 — Tier 3) + +Gap: No backup strategy, tooling, or runbook exists for the SourceOS workstation +profile. A world-class OS requires: + +- Automated, verifiable backup of user data and system state. +- Recovery runbook tested against at least one hardware target. +- Integration with `sourceos doctor` to report backup health. + +### Security and trust envelope (P1 — Tier 3) + +Gap: The current profile applies GNOME defaults and package installs without a +defined trust model. Required work: + +- Verified / measured boot integration plan (TPM, Secure Boot, image signing). +- Application signing and attestation policy. +- Audit of helper scripts for privilege escalation paths. +- Key/credential lifecycle — generation, rotation, revocation. + +### Continuity equivalents (P2 — Tier 2 / 3) + +Gap: macOS Continuity (Handoff, AirDrop, Universal Clipboard, iPhone Mirroring) +has no Linux-native equivalent in the profile. A world-class SourceOS could +define bounded equivalents: + +- Cross-device clipboard via a defined agent protocol. +- File transfer via an open, auditable channel. +- Notification bridging between workstation and mobile/tablet. + +### Contract canon and Agent Machine interface (P1 — Tier 3) + +Gap: `sourceos-spec` holds draft contracts but they are not ratified, versioned, +or enforced by `source-os` or `sourceos-shell`. Required work: + +- Publish a v0 contract schema for the Agent Machine / secure host interface. +- Require `source-os` and `sourceos-shell` to validate against the schema in CI. +- Define the lifecycle of a contract (proposal → draft → candidate → ratified). + +### PDF and document runtime (P1 — Tier 3, `sourceos-shell` lane) + +Gap: The PDF-first / document-first runtime is a stated SourceOS differentiator +but no implementation exists. `sourceos-shell` is the designated home. +Required work: + +- Define what "PDF-first runtime" means operationally (open format, viewer, + annotation, signing, archival). +- Implement a minimal working lane in `sourceos-shell`. +- Document the handoff to `source-os` workstation profile. + +### Application and runtime trust (P2 — Tier 3) + +Gap: No policy exists for what software may run on a SourceOS workstation, how +it is verified, or how sandboxing is applied. Required work: + +- Flatpak / OSTree / Nix trust policy document. +- Runtime integrity check integrated with `sourceos doctor`. +- Capability-based permission model sketch for agent-invoked processes. + +### Accessibility and localisation (P2 — Tier 2 / 3) + +Gap: No accessibility audit or localisation plan exists. The profile applies +GNOME defaults (which have reasonable a11y support) but does not test, document, +or extend it. Required work: + +- GNOME a11y settings applied by `appearance-apply.sh` or a dedicated helper. +- At least one locale other than `en_US` tested and documented. +- WCAG audit note on any custom UI surfaces (launcher, palette). + +### Evidence and reporting (P2 — Tier 3) + +Gap: `sourceos doctor --json` and `sourceos status` emit signals, but there is +no pipeline that aggregates evidence across all repos, surfaces a dashboard, or +feeds a release gate. Required work: + +- Define the evidence schema for a SourceOS release gate. +- Wire `source-os`, `sourceos-spec`, and `sourceos-shell` CI into a shared + evidence collection step. +- Produce a human-readable maturity report on each milestone boundary. + +--- + +## Parity scorecard — current state + +The following table uses the same status vocabulary as the acceptance matrix. + +| Domain | Tier 1 v0 | Tier 2 (parity) | Tier 3 (world-class) | +|---|---|---|---| +| GNOME appearance | validation-backed | not attempted | not attempted | +| Keyboard shortcuts | validation-backed | partial (Kinto planned) | not attempted | +| Touchpad gestures | implemented | partial | not attempted | +| Launcher / palette | implemented | not attempted | not attempted | +| Local file search | validation-backed | not attempted | not attempted | +| Screenshot | validation-backed | not attempted | not attempted | +| Status / doctor CLI | validation-backed | not attempted | not attempted | +| Shell runtime lane | not started | not started | gap (see above) | +| PDF / document runtime | not started | not started | gap (see above) | +| Backup / recovery | not started | not started | gap (see above) | +| Security / trust envelope | not started | not started | gap (see above) | +| Continuity equivalents | not attempted | not attempted | gap (see above) | +| Contract canon | draft only | draft only | gap (see above) | +| Agent Machine interface | draft only | draft only | gap (see above) | +| App / runtime trust | not started | not started | gap (see above) | +| Accessibility | GNOME defaults only | not audited | gap (see above) | +| Localisation | not started | not started | gap (see above) | +| Evidence / reporting | partial (CI only) | not started | gap (see above) | + +**Overall maturity rating: Tier 1 in progress. Tier 2 and Tier 3 not yet +attempted. This is not a world-class OS claim.** + +--- + +## Repo ownership boundaries + +| Repo | Owns | Does not own | +|---|---|---| +| `SociOS-Linux/source-os` | Workstation profile realization; GNOME helpers; `sourceos` CLI; CI smoke workflows; workstation docs | Contract canon; shell runtime primitives; spec ratification | +| `SourceOS-Linux/sourceos-spec` | Contract canon; schema definitions; Agent Machine interface spec; ratification lifecycle | Concrete realization scripts; CI for the workstation profile | +| `SourceOS-Linux/sourceos-shell` | PDF-first / document-first runtime lane; shell runtime primitives; alignment with sourceos-spec contracts | GNOME-specific helpers; workstation package manifests | +| SocioProphet agent / control-plane repos | Agent orchestration; secure host interface implementation; agent lifecycle | OS-level scripts; workstation profile; contract authorship | + +### Alignment requirement + +A gap exists today: the three primary repos (`source-os`, `sourceos-spec`, +`sourceos-shell`) have no shared alignment document and no cross-repo CI +enforcement of contracts. The next milestone must produce: + +1. A tri-repo alignment note (can live in `sourceos-spec`). +2. A contract validation step in `source-os` CI that imports a schema from + `sourceos-spec`. +3. A `sourceos-shell` README that references the alignment and defines its + runtime lane scope. + +--- + +## Execution plan — near-term work packets + +Work packets are listed in priority order. Each packet has an acceptance gate +that defines done. + +### WP-1: `sourceos-shell` bootstrap and alignment (P1) + +**Owner:** `SourceOS-Linux/sourceos-shell` primary + `SociOS-Linux/source-os` +alignment change. + +**Work:** +- Add a `README.md` to `sourceos-shell` that states the PDF-first runtime lane + scope and references `sourceos-spec` for the contract canon. +- Add an alignment section to `sourceos-spec` that names all three repos and + their boundaries (as above). +- Add a stub `docs/runtime-lane.md` to `sourceos-shell` with a minimal + definition of "PDF-first runtime" and the planned handoff to `source-os`. + +**Acceptance gate:** +```bash +test -s README.md # in sourceos-shell +test -s docs/runtime-lane.md # in sourceos-shell +grep -F "sourceos-shell" sourceos-spec/docs/alignment.md +``` + +### WP-2: Contract canon v0 (P1) + +**Owner:** `SourceOS-Linux/sourceos-spec`. + +**Work:** +- Publish a `contracts/v0/agent-machine.json` (or YAML) schema. +- Define the ratification lifecycle in `docs/contract-lifecycle.md`. +- Add a CI step that lints the schema against its own meta-schema. + +**Acceptance gate:** +```bash +test -s contracts/v0/agent-machine.json # in sourceos-spec +test -s docs/contract-lifecycle.md # in sourceos-spec +# CI lint step passes +``` + +### WP-3: Doctor integration for aggregate polish (P1) + +**Owner:** `SociOS-Linux/source-os` (tracked in issue #120). + +**Work:** +- Wire `check-workstation-polish.sh` output into `sourceos doctor --json`. +- Ensure `sourceos doctor` exits non-zero when a required polish check fails. + +**Acceptance gate:** `sourceos doctor --json` includes a `workstation_polish` +key and the CI workflow for doctor passes. + +### WP-4: Backup and recovery runbook (P1) + +**Owner:** `SociOS-Linux/source-os`. + +**Work:** +- Add `docs/workstation/backup-recovery.md` describing the backup strategy, + tooling choices, and recovery steps. +- Add a validation helper `profiles/linux-dev/workstation-v0/bin/check-backup.sh` + that emits a warning when no backup target is configured. + +**Acceptance gate:** +```bash +test -s docs/workstation/backup-recovery.md +bash -n profiles/linux-dev/workstation-v0/bin/check-backup.sh +``` + +### WP-5: Security and trust envelope plan (P1) + +**Owner:** `SociOS-Linux/source-os` (doc) + `SourceOS-Linux/sourceos-spec` +(trust model schema). + +**Work:** +- Add `docs/workstation/security-trust.md` covering verified boot, app signing, + and credential lifecycle at the plan level. +- Reference the trust model from `sourceos-spec`. + +**Acceptance gate:** +```bash +test -s docs/workstation/security-trust.md +grep -F "Secure Boot" docs/workstation/security-trust.md +``` + +### WP-6: Dock and extension validation helper (P2) + +**Owner:** `SociOS-Linux/source-os` (tracked in issue #130). + +**Work:** Implement `bin/check-dock-extensions.sh` and wire into the aggregate +polish workflow. + +**Acceptance gate:** Workflow passes; helper exits 0 on a correctly configured +GNOME session. + +### WP-7: Shortcut map contract (P2) + +**Owner:** `SociOS-Linux/source-os` (tracked in issue #126). + +**Work:** Publish `docs/workstation/shortcut-map-contract.md` and validate +against current `mac-defaults.sh` bindings. + +**Acceptance gate:** +```bash +test -s docs/workstation/shortcut-map-contract.md +``` + +### WP-8: Accessibility baseline (P2) + +**Owner:** `SociOS-Linux/source-os`. + +**Work:** Add an a11y settings block to `appearance-apply.sh` (high-contrast +toggle, screen reader note) and a `docs/workstation/accessibility.md` audit +note. + +**Acceptance gate:** +```bash +test -s docs/workstation/accessibility.md +``` + +### WP-9: Evidence and reporting schema (P2) + +**Owner:** `SourceOS-Linux/sourceos-spec` (schema) + `SociOS-Linux/source-os` +(CI wire-up). + +**Work:** Define an evidence schema and produce a milestone maturity report from +CI outputs. + +**Acceptance gate:** A `reports/milestone-N.json` artifact is produced by CI and +passes schema validation. + +--- + +## Non-goals preserved + +- No full macOS UI clone. +- No GNOME Shell fork or libadwaita replacement. +- No proprietary asset dependency. +- No production readiness claim from this document. +- No claim of full macOS parity. +- No world-class OS claim until Tier 3 gaps are closed and evidence exists. + +--- + +## Validation + +```bash +test -s docs/workstation/world-class-sourceos-parity-plan.md +grep -F "sourceos-shell already exists" docs/workstation/world-class-sourceos-parity-plan.md +grep -F "Mac-like GNOME workstation v0" docs/workstation/world-class-sourceos-parity-plan.md +grep -F "world-class OS" docs/workstation/world-class-sourceos-parity-plan.md +``` From 9075c54de48b430b51be5b24937ce808a9f7174f Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 3 May 2026 00:36:46 +0000 Subject: [PATCH 3/3] docs(workstation): fix British-English spelling in parity plan Agent-Logs-Url: https://github.com/SociOS-Linux/source-os/sessions/68b7c5e1-6b1d-4278-8234-afd2ec955a0d Co-authored-by: mdheller <21163552+mdheller@users.noreply.github.com> --- .../workstation/world-class-sourceos-parity-plan.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/docs/workstation/world-class-sourceos-parity-plan.md b/docs/workstation/world-class-sourceos-parity-plan.md index c4ad258..a392a20 100644 --- a/docs/workstation/world-class-sourceos-parity-plan.md +++ b/docs/workstation/world-class-sourceos-parity-plan.md @@ -42,7 +42,7 @@ claim or target macOS parity. **What it means:** An OS that competes on the following dimensions: runtime integrity and verified boot, hardware lifecycle and firmware management, complete backup and recovery, cryptographic identity and trust envelope, cross-device -continuity equivalents, accessible and fully localised UI, a stable and audited +continuity equivalents, accessible and fully localized UI, a stable and audited contract canon for agents and host interfaces, evidence and reporting pipelines, and a viable developer/user ecosystem. @@ -158,9 +158,9 @@ it is verified, or how sandboxing is applied. Required work: - Runtime integrity check integrated with `sourceos doctor`. - Capability-based permission model sketch for agent-invoked processes. -### Accessibility and localisation (P2 — Tier 2 / 3) +### Accessibility and localization (P2 — Tier 2 / 3) -Gap: No accessibility audit or localisation plan exists. The profile applies +Gap: No accessibility audit or localization plan exists. The profile applies GNOME defaults (which have reasonable a11y support) but does not test, document, or extend it. Required work: @@ -168,6 +168,11 @@ or extend it. Required work: - At least one locale other than `en_US` tested and documented. - WCAG audit note on any custom UI surfaces (launcher, palette). +**Acceptance gate:** +```bash +test -s docs/workstation/accessibility.md +``` + ### Evidence and reporting (P2 — Tier 3) Gap: `sourceos doctor --json` and `sourceos status` emit signals, but there is @@ -203,7 +208,7 @@ The following table uses the same status vocabulary as the acceptance matrix. | Agent Machine interface | draft only | draft only | gap (see above) | | App / runtime trust | not started | not started | gap (see above) | | Accessibility | GNOME defaults only | not audited | gap (see above) | -| Localisation | not started | not started | gap (see above) | +| Localization | not started | not started | gap (see above) | | Evidence / reporting | partial (CI only) | not started | gap (see above) | **Overall maturity rating: Tier 1 in progress. Tier 2 and Tier 3 not yet