182 lines
10 KiB
Markdown
182 lines
10 KiB
Markdown
# 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. 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.
|
|
|
|
## Active pilot gates
|
|
|
|
These gates do not block work on each other.
|
|
|
|
- Activate the pending Neovim configuration, explicitly authorize the changed
|
|
workbench `.envrc`, and confirm Dadbod shows the four centralized test/live
|
|
connections. 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. Issue 197 is selected, but this Codex
|
|
session is outside Herdr and cannot safely control the pilot.
|
|
|
|
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 receives the four named database connections from the workbench's
|
|
SOPS-derived environment.
|
|
- 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`](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
|
|
|
|
Activate the pending Neovim change, authorize the changed workbench `.envrc`,
|
|
and confirm the four Dadbod names. Resume issue 197 from a Codex session launched
|
|
inside Herdr, then complete one real cross-system investigation and the Herdr
|
|
pilot without mutating company GitHub.
|