lux/docs/plans/workflow-system.md

Workflow system execution

Source: ../workflow-discovery.md

Apply the global and repository-local AGENTS.md files and the ponytail skill at full intensity throughout. Preserve user work, prefer native capabilities, and add no abstraction without a demonstrated repeated need.

Current checkpoint

• Tranche: repository contracts and Yookr workbench
• State: active
• Branch: chore/workflow-system
• Baseline: nix flake check --no-build --quiet passed on 2026-09-05; only the existing dirty-tree and unknown modules output warnings were emitted.
• Next: activate the follow-up Garden shell fix, then remove the mutable Garden binaries that still shadow the verified Nix-owned tools. Defer database and Marimo artifacts until a concrete cross-system investigation supplies useful content; proceed with an independent pilot in the meantime.

Progress

Batch	State	Evidence or blocker
Bootstrap and repository ownership	Waiting for user	Repository and dashboard reconciliation complete; credential cleanup remains
Declarative workstation foundation	Complete	All-host builds pass with one Nixpkgs pin, just, and an explicit Podman Compose provider
Repository contracts and workbench	Active	Three contracts are checkpointed and the read-only test Kubernetes gate passed; API, database, and report evidence remain
Desktop, agents, notes, PIM, transcription	Pending	Independent pilots follow foundation changes
Conditional retirement and completion	Pending	Requires per-pilot evidence

Repository checkpoints

Repository	Branch	Commit	Purpose
NixOS configuration	chore/workflow-system	41bc61b	Discovery, paths, Git identity, and Codex defaults
NixOS configuration	chore/workflow-system	69552b7	Simplify flake inputs and declare workstation lifecycle tools
NixOS configuration	chore/workflow-system	0c121a6	Declare Garden tooling and the local workbench
yookr-dashboard-new	feat/gogv2	934605d	Remove obsolete dashboard converter
rules-service	chore/workflow-contract	555d9cd	Establish the first common repository contract
yookr-api	chore/workflow-contract	a76b2b7	Establish the HTTP and OpenAPI contract
traceability-data-model	chore/workflow-contract	33cb7ff	Establish the database and schema contract
yookr-workbench	main	733e7b7	Create the workbench and isolate its Garden session

Human actions

• Rotate the exposed Context7 key and provide CONTEXT7_API_KEY through a mode-0600 machine-local environment file on each workstation before removing the static user-config header.
• Relocate the mode-0644 /home/kiri/work/SECRETS file to an approved private owner and restrict it; its contents have not been inspected.
• Move the ignored rules-service/.env to ~/.config/yookr/rules-service.env with mode 0600; its contents have not been inspected or copied.
• Restore access to the locked yookrdev/constant-store commit or replace that retired dependency deliberately, then rerun just check in yookr-api.
• Deploy a GET image that exposes /full-api-docs/openapi.json, then rerun just openapi-refresh test; the current test deployment returns 404.
• Populate the ignored API HTTP credentials and perform the planned login plus harmless administrator read; no credential-bearing request has been made.
• Activate the follow-up Garden shell fix. The Nix-owned gardenctl, gardenlogin, and kubectl-gardenlogin are verified under ~/.nix-profile/bin; afterward remove the duplicate mutable binaries ~/.garden/gardenctl and ~/.local/bin/{gardenctl,gardenlogin,kubectl-gardenlogin}.
• Destructive cleanup, credentials, activation, and empirical pilot decisions will be surfaced here before use.

Decisions and discoveries

• Use /home/kiri/work/repos/yookr-dashboard-new as the reconciliation base; its feat/gogv2 head is 17 commits newer than the sync copy and matches its remote-tracking branch.
• The user confirmed the legacy BSON migration is no longer needed and the former work copy is authoritative. The sync copy was explicitly deleted; its removal may propagate through Syncthing.
• Active repositories now live under /home/kiri/dev/work; inactive material is preserved intact under .archive, and the registered dashboard sensor worktree is under .worktrees.
• Removed the obsolete dashboard converter app and Python dependency. The dashboard flake evaluates, while the pre-existing feature work remains uncommitted and unstaged.
• Pruned the absent feat/echarts-domain worktree metadata; its branch and commit remain. The registered sensor worktree is valid at its new path.
• Shared Codex defaults and MCP endpoints are generated at /etc/codex/config.toml; Context7 reads its header from the environment. The unused generic ~/.config/mcp/mcp.json owner is removed on next activation.
• Removed redundant legacy-path trust entries from the current Codex config; the existing trusted home scope covers the moved repositories.
• Bruno's transitional OpenAPI reference now follows the archived management repository until the HTTP pilot retires or retains Bruno.
• Post-move repository IDs, remotes, dirty counts, and the registered sensor worktree match the pre-move inventory. The Nix flake still evaluates.
• No-link system builds for Zenith, Polaris, and Orion pass with the migrated paths and declarative Codex defaults.
• Removed the unused stable Nixpkgs input and made Noctalia follow the root package-set pin. Added just to the workstation tools and selected the store-backed podman-compose provider through native containers.conf.
• The resulting flake check and no-link builds for all three hosts pass.
• rules-service now has a non-mutating direnv shell, minimal Nix toolchain and formatting check, native Cargo recipes, factual repository instructions, one .http request collection, explicit test/live deployment paths, and a corrected test-oriented environment example. The full locked Cargo check passes; Clippy reports 18 pre-existing advisory warnings.
• Private Cargo Git dependencies remain in the ordinary developer SSH boundary. They are not vendored or bridged into sandboxed Nix builds.
• yookr-api now owns its reviewed OpenAPI 3.1 contract, local/test/live HTTP metadata, curated login/health/admin-read requests, a non-mutating shell, and one explicit snapshot-and-diff recipe. oasdiff 1.31.0 is pinned with source and vendor hashes because Nixpkgs does not provide it.
• The API flake evaluation and built OpenAPI validation pass. Cargo stops before compilation because its locked constant-store repository is unavailable through both anonymous HTTPS and the working SSH identity. The test service is reachable, but its currently deployed GET image returns 404 for the full OpenAPI route already present in local source and ingress configuration.
• traceability-data-model preserves the existing domain/schema redesign while replacing automatic schema recreation with explicit just reset. Ordinary just dev retains its Compose volumes, and the flake check loads fixtures in text-ID mode plus a fresh schema in UUID-ID mode. Both the built check and the pinned podman-compose configuration validation pass.
• Gardenctl 2.14.0 and Gardenlogin 0.10.0 are pinned from their official release assets; the hashes match the existing binaries byte-for-byte. All three host builds pass, the OIDC kubectl plugin is declarative, and Zsh consumes the native gardenctl rc zsh output with its completion packaged declaratively.
• The local-only yookr-workbench has no remote and initially owns only just k8s test. Each invocation creates an isolated Garden session, rejects every environment except test, and opens K9s read-only. Its flake check and command catalog pass, and the live rejection path exits before Garden access.
• The user activated and rebooted into the Garden tooling, then confirmed that just k8s test opens the test shoot in read-only K9s. The initial shell error came from Garden writing completion into an absent Flatpak $fpath entry; the initial target warning came from the fresh session inheriting its parent's KUBECONFIG. Completion is now store-owned and the child recipe clears that variable before targeting.
• Named database connections and a Marimo-to-HTML report remain workbench evaluation evidence, not scaffolding requirements. Add them only for a real cross-system investigation that gives the queries and report durable value.
• Run independent pilots in parallel, but gate every retirement separately.