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. Account login plus a raw-token management user read also passed. The approved user-key SOPS authority now contains active credentials and ten provenance-preserving archive namespaces. Its workbench exports passed a test API login, RabbitMQ overview, MySQL test/live SELECT 1, MongoDB test/live ping, and read-only Irristaud object-storage listing. Dadbod exposes all four names and the MongoDB connections work. Both MariaDB connections now use the native client with narrowly scoped certificate-verification exceptions; their exact example queries passed over TLS 1.3 in both environments. Direct test login and authenticated reads still return HTTP 200 for Yookr, rules, and management. Kulala login and response chaining are confirmed in Neovim.
• Herdr ran the issue 197 planning pilot in two predictable, non-overlapping dashboard worktrees. Codex produced frontend commit 20f9d0f; Claude produced backend commit bd965ea. Short, long, done, fallback-agent, and genuinely approval-blocked states behaved correctly, and dirty worktree removal was refused. Nothing reached company GitHub. Both plans found that password reset belongs to the separate account service rather than yookr-dashboard. Documented named-session detach/reattach persistence is accepted without a redundant live trial; notifications are intentionally disabled after their live pilot.

Active pilot gates

These gates do not block work on each other.

• Visually confirm the MariaDB examples in Dadbod. 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.
• Route issue 197 to the actual account repositories before implementation; leave the two local dashboard planning branches available as evidence.

Herdr's bounded pilot is complete. If later use exposes a problem, fall back independently to native agent sessions or native git worktree add/list/remove; do not add a wrapper or Worktrunk without a demonstrated gap.

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 receives the four named database connections from the workbench's SOPS-derived environment. The two MariaDB routers expose auto-generated private-CA certificates without a valid host identity, so only those URLs disable certificate verification while retaining TLS; restore verification when infrastructure provides usable CA and host certificates.
• 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.
• The credential audit and approved central SOPS authority are in credential-consolidation.md. The authority is active, while original plaintext sources remain pending consumer-specific verification and explicit removal approval.
• 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

Confirm the two MariaDB examples inside Dadbod, then run one real cross-system investigation without mutating company GitHub.