docs: archive workflow plans and introduce constellation

Preserve the accumulated phase-two record and introduce the constellation design and working agreement. Archived approvals and plans are historical, not current authority.
2026-09-09 17:31:03 +02:00
1 parent 85e4cbdc67
commit 4e3a3ac899
@@ -0,0 +1,220 @@
+# Workflow system blueprint
+
+Status: phase one implemented and active; explicitly deferred pilots remain.
+The operational handoff lives in
+[`plans/workflow-system.md`](plans/workflow-system.md).
+
+This document is the durable design for the workstation and surrounding Yookr
+workflow. Implementation history belongs in Git.
+
+## Governing intent
+
+Build a quiet, keyboard-first control plane over development, investigation,
+operations, agents, and personal knowledge. Keep the system small and give each
+intention one canonical owner.
+
+- Standardize vocabulary and entry points without forcing unlike workloads onto
+  one implementation.
+- Put frequent actions on direct keys and less frequent actions on their owning
+  discovery surface.
+- Keep stable packages, services, integration, and durable preferences in Nix.
+  Keep credentials, sessions, databases, caches, and other mutable state with
+  their owning application.
+- Prefer native file formats and supported application layers. Add wrappers only
+  for demonstrated gaps.
+- Repositories own reproducible development context, executable project
+  documentation, and code-specific artifacts.
+- Select `local`, `test`, or `live` per operation; do not depend on an ambient
+  production context.
+- Make production and destructive actions more deliberate than navigation and
+  read-only inspection.
+- Promote automation only after the manual workflow repeats and can be verified.
+- Optimize conceptual complexity and review burden, not package count or line
+  count in isolation.
+
+The main coordinates are scope (`work`, `own`, `ext`, or `forks`), Yookr domain,
+environment (`local`, `test`, or `live`), and intention (develop, inspect, query,
+review, operate, or deploy).
+
+## Ownership model
+
+<!-- markdownlint-disable MD013 -->
+
+| Intention | Canonical owner |
+| --- | --- |
+| Find applications, projects, or windows | Walker/Elephant and direct Niri bindings |
+| Search personal passwords | Walker with `rbw`; company Bitwarden stays in its browser extension |
+| Navigate browser state | Vivaldi Quick Commands |
+| Arrange windows and displays | Niri dynamic workspaces |
+| Work in a terminal | Kitty |
+| Edit related files and views | Neovim |
+| Enter a repository environment | `direnv` with `nix-direnv` |
+| Discover project actions | `just --list` |
+| Run edited first-party code | Native processes, optionally Process Compose |
+| Run a container-only project stack | Rootless Podman Compose |
+| Run a persistent containerized user service | Rootless Podman Quadlet |
+| Run a durable host service | NixOS modules and systemd |
+| Exercise APIs | Kulala and `xh`, with tracked `.http` files |
+| Query databases | Dadbod and native driver CLIs |
+| Investigate across Yookr systems | `yookr-workbench` |
+| Connect the Yookr VPN | NetworkManager/OpenVPN through Noctalia |
+| Inspect test Kubernetes | `just k8s test` using Gardenctl and read-only K9s |
+| Inspect RabbitMQ | Official management UI; `rabbitmqadmin` for exact terminal operations |
+| Browse S3-compatible storage | Native `rclone` commands |
+| Capture and find notes | `zk` through Neovim in one synchronized Markdown notebook |
+| Present work and personal PIM | Evolution pilot beside Thunderbird and Outlook |
+| Present personal PIM on Android | DAVx5, aCalendar+, Google Contacts, and Tasks.org |
+| Give agents durable project context | `AGENTS.md` and project commands |
+| Run top-level agents | Herdr on demand |
+| Maintain conversation state and subagents | Each native agent, primarily Codex |
+| Review local changes | LazyGit in the task checkout |
+| Review pull requests | `gh`, then a review worktree when local checks are useful |
+
+<!-- markdownlint-enable MD013 -->
+
+## Repository contract
+
+Active work repositories live under `~/dev/work`; inactive repositories live
+under `~/dev/work/.archive`, and worktrees under `~/dev/work/.worktrees`.
+Repositories and worktrees never live under `~/sync`.
+
+Participating repositories use the following small contract:
+
+- A tracked `.envrc` enters the default flake development shell without starting
+  services, fetching data, or mutating the checkout.
+- `flake.nix` owns reproducible dependencies, checks, packages, and formatting.
+- `just --list` indexes non-obvious tasks and delegates to native commands.
+- `AGENTS.md` contains concise project facts, invariants, architecture pointers,
+  and checks without duplicating global guidance.
+- Service-owned `.http` and schema-owned `.sql` files stay beside their owner;
+  generated views, caches, and scratch output do not become durable sources.
+- Secrets enter at runtime from an approved source or a user-only file outside
+  checkouts, initially `~/.config/yookr/<repository>.env`.
+- A new worktree behaves like a fresh clone and requires its own explicit
+  `direnv allow`.
+- Branch-derived ports, databases, and container names are added only after a
+  real collision.
+
+Use Process Compose only when multiple foreground processes benefit from one
+visible lifecycle. Use Podman Compose for wholly containerized project stacks,
+Quadlet for persistent user containers, and NixOS modules for durable host
+services. Do not nest lifecycle tools for another status screen.
+
+`yookr-workbench` owns cross-system API requests, operational queries, the
+Garden/Kubernetes entry point, and Marimo investigations. It does not collect
+service OpenAPI specifications, schema migrations, deployable model code, or
+copied application state.
+
+## Interaction and knowledge boundaries
+
+- Walker scans the four repository roots, excludes `.archive` and `.worktrees`,
+  and invokes one Nix-owned `open-project` command. The command opens Kitty at
+  the repository root, starts Neovim, and leaves a shell after Neovim exits.
+- Vivaldi remains the bookmark and web-app authority. Home Manager declares
+  stable launchers for Actual, WhatsApp, and Outlook without duplicating browser
+  state and reclaims their paths when a changed Home Manager generation is
+  deployed. Manual shortcut regeneration may replace one meanwhile and is an
+  accepted unused edge case. Its
+  `Operations` folder owns visibly labeled test/live RabbitMQ bookmarks; terminal
+  inspection uses the Nix-provided `rabbitmqadmin-ng` on demand.
+- Niri keeps dynamic general-purpose workspaces and a compact navigation and
+  movement vocabulary. The two-output active-workspace exchange remains a
+  bounded pilot.
+- Codex is primary; Claude Code and Pi are fallbacks. Herdr owns persistence and
+  attention for top-level sessions, while each agent owns its internal state.
+- Use one primary writer per checkout. Subagents may perform bounded independent
+  read-heavy work, but overlapping changes are sequenced.
+- Substantial multi-session work may keep one living
+  `docs/plans/<task-slug>.md`; lasting knowledge moves to normal documentation
+  and transient execution history is removed when finished.
+- `~/sync/notes` is the Markdown/zk authority. Daily intake uses
+  `daily/YYYY-MM-DD.md`; planned meetings and raw transcripts use `meetings/`
+  and `transcripts/` respectively.
+- Microsoft 365 remains authoritative for work/university PIM and Radicale for
+  personal CalDAV, VTODO, and CardDAV. Clients present those authorities without
+  bridging or copying them.
+- Fossify records on Android and Syncthing delivers completed recordings to
+  Orion. Orion owns event-driven CPU transcription, diarization fallback,
+  archival, and Markdown publication.
+
+## Safety boundaries
+
+GitHub and all other remotes are read-only. Local commits, clones, fetches, and
+worktrees are allowed; remote mutation requires a separate change to policy.
+Yookr production source is also read-only during these pilots. Development
+tooling may be changed, and `yookr-workbench` is the explicit source-code
+exception.
+
+Credentials and `.env` files normally stay outside Git, the Nix store, and broad
+synchronization. Machine-local Yookr credentials use the approved user-key SOPS
+authority at `~/.config/yookr/credentials.yaml`; callers expose only the fields
+they need. Original plaintext sources remain until their consumers are verified
+and removal is explicitly approved. The accepted `yookr-vpn.ovpn` is a narrow
+exception for Zenith and Polaris: keep it user-restricted and import it into
+NetworkManager without printing or committing its contents.
+
+`yookr-data-science/conf/local/credentials.yml` is a separate application-owned
+exception: Kedro resolves its named credential dataset through the conventional
+ignored `conf/local` hierarchy. Keep the file untracked and mode 0600; do not
+generalize the exception to other repositories.
+
+Only the user activates a NixOS or Home Manager generation. Agents may evaluate
+and build configurations, then provide an activation command.
+
+## Phase-one closure
+
+- The workbench environment, all four SOPS-derived Dadbod connections, read-only
+  example-query runs, and Kulala response chaining passed. The cross-system
+  investigation and Marimo report pilots move into phase two.
+- Add another ephemeral read-only rclone remote only when credentials for a new
+  Leafcloud project become available. Irristaud listing has passed; do not upload.
+- Use the reviewed local Yookr OpenAPI contract while the accepted malformed
+  generated test document remains deployed.
+- Herdr's bounded issue 197 pilot is complete. Documented named-session
+  detach/reattach persistence is accepted without a redundant live trial, and
+  notifications are intentionally disabled. Codex/Claude fallback, attention
+  states, local branches, parallel non-overlapping plans, and the dirty-removal
+  guard passed; the plans show that implementation belongs outside the dashboard
+  repository.
+- Keep Bruno and DBeaver; retiring old applications is outside phase one.
+
+## Deferred pilots
+
+Revisit these alongside related phase-two ideas rather than as isolated cleanup.
+
+- Capture Zenith's external display identity during a docked session and test the
+  two-output `Super+A` exchange, including name and focus restoration on failure.
+- Resume Evolution and Android PIM only when the user chooses to run those daily
+  use pilots.
+- Replicate the proven workstation workflow on Polaris only when the user resumes
+  its machine-local VPN and credential procedure.
+
+## Deferred work
+
+- Define the team release process and OpenAPI publication policy before encoding
+  deployment automation.
+- Adopt a company-wide infrastructure secret source only after Yookr selects one.
+- Publish `yookr-workbench` only when sharing becomes useful.
+- Pilot SharePoint browse/download through `rclone` after Microsoft consent.
+- Revisit Worktrunk, `codex agents`, Walker-to-agent launching, formal agent
+  evaluation, remote builders, CI runners, and agent offload only after a concrete
+  gap appears.
+- Add report servers, notebook hubs, groupware, terminal PIM, meeting summaries,
+  concurrency isolation, OCR, dictation, clipboard remapping, or additional
+  convenience surfaces only after repeated use establishes an owner.
+
+## Reference baseline
+
+Recheck fast-moving interfaces against their pinned versions before changing
+them.
+
+<!-- markdownlint-disable MD013 -->
+
+- Projects: [Nix flake templates](https://nix.dev/manual/nix/latest/command-ref/new-cli/nix3-flake-init), [nix-direnv](https://github.com/nix-community/nix-direnv), [just manual](https://just.systems/man/en/), [Podman Compose](https://docs.podman.io/en/latest/markdown/podman-compose.1.html), [Quadlet](https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html), [Marimo](https://docs.marimo.io/).
+- APIs/data: [Kulala](https://kulala.app/), [Dadbod](https://github.com/tpope/vim-dadbod), [RabbitMQ management](https://www.rabbitmq.com/docs/management), [rclone S3](https://rclone.org/s3/), [rclone OneDrive/SharePoint](https://rclone.org/onedrive/).
+- Desktop: [Walker](https://walkerlauncher.com/docs/providers), [Elephant menus](https://github.com/abenz1267/elephant/tree/master/internal/providers/menus), [Vivaldi web apps](https://help.vivaldi.com/desktop/miscellaneous/progressive-web-apps/), [Niri IPC](https://niri-wm.github.io/niri/IPC.html).
+- Agents: [Codex configuration](https://learn.chatgpt.com/docs/config-file/config-basic), [Codex long-running work](https://learn.chatgpt.com/docs/long-running-work), [Herdr](https://herdr.dev/docs/configuration/), [Git worktrees](https://git-scm.com/docs/git-worktree).
+- PIM/knowledge: [Evolution account types](https://help.gnome.org/evolution/intro-account-types.html), [Radicale](https://radicale.org/v3.html), [DAVx5](https://manual.davx5.com/introduction.html), [Tasks.org](https://tasks.org/docs/), [`zk` daily journal](https://github.com/zk-org/zk/blob/main/docs/tips/daily-journal.md).
+- Infrastructure: [Gardenctl](https://gardener.cloud/docs/gardenctl-v2/), [NetworkManager](https://networkmanager.pages.freedesktop.org/NetworkManager/NetworkManager/nmcli.html), [Syncthing](https://docs.syncthing.net/users/syncing).
+
+<!-- markdownlint-enable MD013 -->