lux/docs/plans/workflow-system.md

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. The labeled RabbitMQ test/live bookmarks are present, and the invocation-scoped test overview and queue listing passed. Test API login, Yookr administrator read, rules read, aggregation login, and management health passed; the Yookr token is not accepted by management's authenticated API.

Active pilot gates

These gates do not block work on each other.

• Configure one rclone S3 remote per Leafcloud project, starting with the irristaud project and container. Use listing and download operations only; uploads are out of scope. Project-scoped EC2 access and secret keys remain the missing input.
• Add the four named Dadbod connections after receiving MySQL test/live and MongoDB test/live connection URIs. Create a Marimo-to-HTML report only when a concrete cross-system investigation gives it 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. Its one API environment catalogue covers the Yookr, rules, aggregation, and management APIs; Kulala owns requests and Dadbod's native store owns named database connections.
• The reviewed yookr-api/openapi.yaml remains the usable local contract. The deployed generated document's dangling ReadParameters reference is accepted for now and does not block direct API requests.
• 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.
• The provisional team chain is Project Overview project → work package → user requirement → Software Development Backlog ticket → repository issue → one pull request. Treat it as discovery context, not automation policy, until the team settles the workflow; company GitHub remains read-only throughout.
• 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

Obtain the four database connection URIs, Leafcloud irristaud project S3 credentials, a management API token, and one real Monday ticket. Then complete the database/S3 access checks and the real workbench and Herdr pilots without mutating company GitHub.