lux/docs/plans/workflow-system.md

# Workflow system execution

Source: [`../workflow-discovery.md`](../workflow-discovery.md)

The declarative workflow core is complete; pilots remain. This file is the
living handoff for operational constraints and external gates; implementation
history is available in Git.

## Activation boundary

Only the user may switch or activate configurations. Agents must not run
`nixos-rebuild switch`, Home Manager activation, or an equivalent command that
changes the active generation. Evaluation and builds are allowed; after a
successful build, provide the exact activation command and wait for the user.

This boundary includes changes described as user-level, harmless, temporary, or
necessary for live verification. A direct Home Manager activation previously
restarted Kitty and closed the user's terminal session.

## Execution discipline

- Advance all safe independent work before asking the user to act.
- Batch declarative changes behind user-controlled activation.
- Consolidate empirical, credential, hardware, and approval gates only after no
  autonomous work remains.
- Keep repositories and worktrees outside `~/sync`; synchronize authored
  artifacts instead.
- Keep GitHub and other repository remotes strictly read-only.
- Treat Yookr production source as read-only. Dev-tooling changes are allowed;
  `yookr-workbench` is the only repository whose own source may be changed for
  these pilots.

## Current checkpoint

- State: declarative core complete and active; pilots remain.
- Branch: `chore/workflow-system`.
- Validation: `nix flake check --no-build --quiet`, all three no-link system
  builds, generated Zenith and Polaris Niri validation, and all six companion
  flake evaluations passed on 2026-09-06. The updated data-science shell exposes
  Python 3.14.7 and its full project check passes. The expected dirty-tree and
  unknown `modules` warnings were emitted.
- Live state: Walker project and terminal actions, daily notes, stable web apps,
  Evolution D-Bus activation, the Zenith VPN, invocation-scoped GitHub and
  Context7 credentials, Pinta, and Orion transcription passed their completed
  pilots. The corrected Actual, WhatsApp, and Outlook launchers all started
  successfully, and the labeled RabbitMQ test/live bookmarks are present.

## Active pilot gates

These gates do not block work on each other.

- Supply approved test RabbitMQ management credentials at runtime, then verify
  the Nix-provided client without installing it permanently:

  ```console
  RABBITMQADMIN_BASE_URI=https://test.rabbitmq.yookr.org nix run --quiet nixpkgs#rabbitmqadmin-ng -- show overview
  RABBITMQADMIN_BASE_URI=https://test.rabbitmq.yookr.org nix run --quiet nixpkgs#rabbitmqadmin-ng -- queues list
  ```

  Export `RABBITMQADMIN_USERNAME` and `RABBITMQADMIN_PASSWORD` from the approved
  credential source first; do not place their values in documentation or shell
  history. Keep publishing, getting, and purge visibly interactive in the
  management UI.
- Supply one real Yookr S3 task, a least-privileged remote, and explicit permission
  for any upload. `rclone` is installed; no remote or wrapper is preconfigured.
- The test GET image exposes `/full-api-docs/openapi.json`. The 2026-09-06
  refresh reached it successfully but validation found a dangling
  `#/components/schemas/ReadParameters` reference. Have the application owner
  correct and deploy the generated document, then rerun the refresh; do not
  modify production source during this workflow.
- Provide current API user credentials before the planned login and harmless
  administrator read. The recovered legacy service credentials returned 401 and
  were not repurposed.
- Add workbench database connections and a Marimo-to-HTML report only when a real
  cross-system investigation gives them durable value.
- Keep Bruno, DBeaver, and PIM clients until their separate pilots decide them.
- Wait for a real Monday ticket before adding anything beyond native GitHub,
  Herdr, Git, and worktree workflows.

The Herdr pilot passes only when short, long, and approval-blocked sessions have
accurate attention state; detach and reattach preserve output; one Claude or Pi
fallback works; and each completed event produces exactly one notification.
Create two independently writing, non-overlapping task worktrees under
`~/dev/work/.worktrees/<repository>/<branch-slug>`, explicitly authorize each
`.envrc`, and confirm paths are predictable, dirty removal is refused, and the
branches remain for review. If a component fails, fall back independently to
native agent sessions and Codex TUI notifications or native
`git worktree add/list/remove`; do not add a wrapper or Worktrunk yet.

## Deferred pilots

- During a docked Zenith session, capture the external display's stable identity
  and test the two-output `Super+A` exchange. The current recorded session exposed
  only `eDP-1`.
- Resume Evolution only when the user chooses to configure the personal,
  old-personal, university, work, and Radicale accounts. Keep Thunderbird and
  Outlook until the daily-use gate passes.
- On Android, complete the DAVx5/Radicale and Tasks.org pilots, including default
  accounts, recurrence, reminders, and Microsoft To Do within documented limits.
- Do not replicate the workstation workflow on Polaris until the user resumes
  the procedure below.

The Niri pilot is two-output-only. It passes when the active workspaces exchange
physical outputs, both arrivals are active, original names are preserved, and
focus returns to the original physical output. Any temporary names must be
collision-free and restored on success or failure; missing output or workspace
state must leave the session unchanged. Keep the helper only after repeated
reliable swaps with an acceptable visible transition.

## Deferred Polaris replication

Do not access or test Polaris unless the user resumes this deferred replication.
Zenith's result remains representative meanwhile.

1. Activate this NixOS configuration so `networkmanager-openvpn` is installed.
2. Restrict `~/sync/yookr-vpn.ovpn` to mode 0600.
3. Import it with `nmcli connection import type openvpn file ~/sync/yookr-vpn.ovpn`.
4. Rename the connection to `Yookr VPN`, disable autoconnect, and add
   `data-ciphers=AES-256-CBC`.
5. Connect with `nmcli connection up "Yookr VPN"`.
6. Create mode-0600 `~/.config/yookr/github-read-only.token` without a trailing
   newline, then verify a new shell can run
   `gh project list --owner yookrdev`.
7. Create mode-0600 `~/.config/context7/api-key` without a trailing newline,
   restart Codex after activation, and run one Context7 lookup.

Replication passes only when the VPN has the expected route and DNS behavior,
reaches a test service, reconnects after disconnect and suspend, and survives a
reboot without autoconnecting. The two credential files must remain mode 0600;
the fresh-shell GitHub read and restarted-Codex Context7 lookup must both work.

## Durable implementation decisions

- Active work repositories live under `~/dev/work`, archives under `.archive`,
  and worktrees under `.worktrees`. Repository trees never enter Syncthing.
- Participating repositories expose non-mutating direnv shells, minimal flake
  checks, native commands through `just`, concise `AGENTS.md`, and machine-local
  credential inputs.
- `yookr-data-science/conf/local/credentials.yml` is an approved narrow
  application-owned exception to the external credential-file default: Kedro's
  named credential dataset resolves it from the native ignored `conf/local`
  hierarchy. Keep it untracked and mode 0600.
- `yookr-data-science` follows ordinary `nixos-unstable`, like the other
  companion repositories; it needs no `devenv-nixpkgs` compatibility input.
- `yookr-workbench` starts with cross-system work only; isolation and additional
  tools wait for observed needs.
- Walker's native Elephant menu scans repository roots and calls one Nix-owned
  `open-project` command. Rare menu changes take effect at login.
- Home Manager declares the three stable Vivaldi launcher paths with forced
  ownership. Vivaldi's manual `Create shortcuts` action can replace one until a
  changed Home Manager generation reclaims it; repeating a no-op activation need
  not relink it. This accepted edge case does not justify filtering, immutable
  files, or a watcher because that action is not part of normal use.
- Kitty and Neovim are the sole declared terminal and editor. Retired duplicate
  applications and global language runtimes stay absent unless a concrete owner
  appears.
- The fine-grained GitHub token and Context7 key stay in mode-0600 machine-local
  files and are exposed only to their callers. Secrets do not enter Nix or broad
  process environments.
- `sync/notes` is the single notebook owner. Daily notes, meetings, and raw
  transcripts have separate paths, and agents do not create issues or ingest
  transcripts automatically.
- Orion is the sole transcription owner. It waits for file settlement, validates
  media, archives originals, and publishes an unlabeled transcript when
  diarization fails.
- Evolution remains a deferred presentation-layer pilot. Microsoft 365 and
  Radicale remain the data authorities; Thunderbird and Outlook remain available.
- GitHub and every other repository remote stay read-only. Local files, commits,
  fetches, clones, and worktrees remain available.
- Yookr production source stays read-only during workflow pilots. Changes to
  development tooling are allowed, and `yookr-workbench` remains the explicit
  source-code exception.

## Next step

Collect all inputs for the active pilots, then run them in the order RabbitMQ,
OpenAPI/API, workbench, S3, and Herdr.