Workflow system execution

Source: ../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:
```
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.

Activate this NixOS configuration so networkmanager-openvpn is installed.
Restrict ~/sync/yookr-vpn.ovpn to mode 0600.
Import it with nmcli connection import type openvpn file ~/sync/yookr-vpn.ovpn.
Rename the connection to Yookr VPN, disable autoconnect, and add data-ciphers=AES-256-CBC.
Connect with nmcli connection up "Yookr VPN".
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.
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.

9.5 KiB Raw Blame History