From e20f5cfe7195fd054be6a2f608a5cfa69aa09936 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Sun, 26 Apr 2026 20:12:51 +0200
Subject: [PATCH 001/101] chore: firefly secret

---
 .secrets/sgx/firefly.yaml | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/.secrets/sgx/firefly.yaml b/.secrets/sgx/firefly.yaml
index 93bfc6b..da0c12d 100644
--- a/.secrets/sgx/firefly.yaml
+++ b/.secrets/sgx/firefly.yaml
@@ -1,6 +1,7 @@
 firefly:
     app_key: ENC[AES256_GCM,data:0BHC54xXb7EJcFBuGWFiDfIh7ZBgVs1R+1GGztOwte4CeD4Olz31umq1At1aRFESLkoC,iv:e3On3x9eSKTo9+SEp/ujFZA0a6o2slqT+atPhd1PDMM=,tag:k2pjyvgM8AcElBBOR95dwg==,type:str]
     sparda_pin: ENC[AES256_GCM,data:8jpahQBDQO4tFZUgCYGe,iv:Vi5WAyk+fTMdRsPvrJEKvR3QHJVgTaWt/mzubCtwpeM=,tag:LpHaKeW9ww2O9gfAyvtkcg==,type:str]
+    auto_import_secret: ENC[AES256_GCM,data:7JcxrIu4tRDgVhcUBoc/u2xN6NxRutKsTbvN8kr/u54BJ+fuZ94EVtDc9B1ZnTLuPb5LStbLnHFcLs17ocpk7g==,iv:DcilcMGEQgJ4hwuJJ2cF3Hdyy85QFpwHjlFwbFEwsAE=,tag:4+KPk7OJ61xngpBmAitlEA==,type:str]
 sops:
     age:
         - recipient: age149fqcw5jze00vd7jauylrp4j5xyv7amlu57jjfuzghkqtzlnxajs704uz3
@@ -30,7 +31,7 @@ sops:
             SGRyL01ISlltVG5YdWw4dWV0RGpPNEEK855vVFGwxgBrl0scAla980fd3XSiUjfP
             ULMGGQK06z1Oh6+bvPyfzbILjFkzlrel06yajpcvdSQgJZXpzQgJUA==
             -----END AGE ENCRYPTED FILE-----
-    lastmodified: "2026-04-26T14:28:13Z"
-    mac: ENC[AES256_GCM,data:TErSf6cfaqks/JyiMipIp/6kJKzuaTFr1ba0wbmDUxDPMc4R4c5Lok6cAC8fOcNlOYbeWurqkUwuqOt7owSKRK6J2XjGWdkGL36vAqFhoT72IUldDQEpeMuivoOUcxdAgY9jtIaGmRd/4LzlU1VO+EE1hr+K/XEXdyi1aLEJjbs=,iv:21KGjOOxpHkOxX4+f6CAXQ2ZmaB+g3Tasr4OOgzQnD8=,tag:RKFx1sp6G4queh3hk7YBLQ==,type:str]
+    lastmodified: "2026-04-26T18:12:24Z"
+    mac: ENC[AES256_GCM,data:e19xgZ0oZq3volq91zhM83ZLWVq9tDQopUJoMOmc4to25O3jxI+Cn0+ZMeSi6P9HwRQV97X6lDdODcRYv0hkgWAd8W1c876muH1bt0/nLYLBd2bwf/d/wdKvdobEkN/Xn8K9VK6lF3ojTsuASWTGJ+9ei4RQ2nQkQk8IBBn5Fzg=,iv:1C38ZXhQg+vS/ZSuLkW4vFgSgC0dtp25V9umTR5lC10=,tag:4+CBjsIry5RDXG1ct4UcXg==,type:str]
     unencrypted_suffix: _unencrypted
     version: 3.12.1

From 31df523787aeb3feb45ba68d491f732f759032a3 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@subzero.xyz>
Date: Mon, 27 Apr 2026 09:47:46 +0200
Subject: [PATCH 002/101] refactor(home): extract shared wezterm module

Add a `metacfg.tools.wezterm` home-manager module so wezterm.lua
configuration can be reused across hosts instead of being duplicated
inline. Migrate halo and amd to the new module and enable it on rialo
(font size 14, term = xterm-256color).
---
 homes/aarch64-darwin/harald@rialo/default.nix |  4 ++
 homes/x86_64-linux/harald@amd/default.nix     | 18 ++------
 homes/x86_64-linux/harald@halo/default.nix    | 18 ++------
 modules/home/tools/wezterm/default.nix        | 46 +++++++++++++++++++
 4 files changed, 58 insertions(+), 28 deletions(-)
 create mode 100644 modules/home/tools/wezterm/default.nix

diff --git a/homes/aarch64-darwin/harald@rialo/default.nix b/homes/aarch64-darwin/harald@rialo/default.nix
index 02f2130..793071b 100644
--- a/homes/aarch64-darwin/harald@rialo/default.nix
+++ b/homes/aarch64-darwin/harald@rialo/default.nix
@@ -32,6 +32,10 @@
         enable = true;
         userEmail = "harald@subzero.xyz";
       };
+      wezterm = {
+        enable = true;
+        term = "xterm-256color";
+      };
     };
   };
 
diff --git a/homes/x86_64-linux/harald@amd/default.nix b/homes/x86_64-linux/harald@amd/default.nix
index 9f5f8e1..088b662 100644
--- a/homes/x86_64-linux/harald@amd/default.nix
+++ b/homes/x86_64-linux/harald@amd/default.nix
@@ -20,6 +20,10 @@
     };
     tools = {
       git.enable = true;
+      wezterm = {
+        enable = true;
+        backgroundImage = ./terminal-background.png;
+      };
     };
     gui.kbd.ellipsis = true;
   };
@@ -71,18 +75,4 @@
 
   xdg.enable = true;
   xdg.mime.enable = true;
-
-  xdg.configFile."wezterm/wezterm.lua".text = ''
-    local wezterm = require("wezterm")
-    local config = wezterm.config_builder()
-    local act = wezterm.action
-
-    config.enable_kitty_keyboard = true
-    config.enable_scroll_bar = true
-    config.window_background_image = '${./terminal-background.png}'
-
-    config.term = 'wezterm'
-
-    return config
-  '';
 }
diff --git a/homes/x86_64-linux/harald@halo/default.nix b/homes/x86_64-linux/harald@halo/default.nix
index 9f5f8e1..088b662 100644
--- a/homes/x86_64-linux/harald@halo/default.nix
+++ b/homes/x86_64-linux/harald@halo/default.nix
@@ -20,6 +20,10 @@
     };
     tools = {
       git.enable = true;
+      wezterm = {
+        enable = true;
+        backgroundImage = ./terminal-background.png;
+      };
     };
     gui.kbd.ellipsis = true;
   };
@@ -71,18 +75,4 @@
 
   xdg.enable = true;
   xdg.mime.enable = true;
-
-  xdg.configFile."wezterm/wezterm.lua".text = ''
-    local wezterm = require("wezterm")
-    local config = wezterm.config_builder()
-    local act = wezterm.action
-
-    config.enable_kitty_keyboard = true
-    config.enable_scroll_bar = true
-    config.window_background_image = '${./terminal-background.png}'
-
-    config.term = 'wezterm'
-
-    return config
-  '';
 }
diff --git a/modules/home/tools/wezterm/default.nix b/modules/home/tools/wezterm/default.nix
new file mode 100644
index 0000000..56c66ef
--- /dev/null
+++ b/modules/home/tools/wezterm/default.nix
@@ -0,0 +1,46 @@
+{
+  lib,
+  config,
+  ...
+}:
+
+let
+  inherit (lib)
+    types
+    mkEnableOption
+    mkIf
+    optionalString
+    boolToString
+    ;
+  inherit (lib.metacfg) mkOpt mkBoolOpt;
+
+  cfg = config.metacfg.tools.wezterm;
+in
+{
+  options.metacfg.tools.wezterm = {
+    enable = mkEnableOption "wezterm config";
+    fontSize = mkOpt types.int 14 "Font size for wezterm.";
+    enableKittyKeyboard = mkBoolOpt true "Enable the kitty keyboard protocol.";
+    enableScrollBar = mkBoolOpt true "Enable the scroll bar.";
+    backgroundImage = mkOpt (types.nullOr types.path) null "Path to a window background image.";
+    term = mkOpt types.str "wezterm" "Value to set for `config.term`.";
+    extraConfig = mkOpt types.lines "" "Extra Lua appended before `return config`.";
+  };
+
+  config = mkIf cfg.enable {
+    xdg.configFile."wezterm/wezterm.lua".text = ''
+      local wezterm = require("wezterm")
+      local config = wezterm.config_builder()
+
+      config.enable_kitty_keyboard = ${boolToString cfg.enableKittyKeyboard}
+      config.enable_scroll_bar = ${boolToString cfg.enableScrollBar}
+      ${optionalString (
+        cfg.backgroundImage != null
+      ) "config.window_background_image = '${cfg.backgroundImage}'"}
+      config.font_size = ${toString cfg.fontSize}
+      config.term = '${cfg.term}'
+      ${cfg.extraConfig}
+      return config
+    '';
+  };
+}

From 9cc17db0d79329460c2ecfb576d7789bcf0544e9 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Mon, 27 Apr 2026 09:53:52 +0200
Subject: [PATCH 003/101] chore: flake.lock update

---
 flake.lock | 50 +++++++++++++++++++++++++-------------------------
 1 file changed, 25 insertions(+), 25 deletions(-)

diff --git a/flake.lock b/flake.lock
index f6f1245..186f8aa 100644
--- a/flake.lock
+++ b/flake.lock
@@ -19,16 +19,16 @@
     "brew-src": {
       "flake": false,
       "locked": {
-        "lastModified": 1774235677,
-        "narHash": "sha256-0ryNYmzDAeRlrzPTAgmzGH/Cgc8iv/LBN6jWGUANvIk=",
+        "lastModified": 1776478798,
+        "narHash": "sha256-ERStG27tf83VbCfYMxtDSs+sa8FUMJ/3jSu/QfX9rKE=",
         "owner": "Homebrew",
         "repo": "brew",
-        "rev": "894a3d23ac0c8aaf561b9874b528b9cb2e839201",
+        "rev": "3aae056b8d072624255bc8fd27febb7f327b2265",
         "type": "github"
       },
       "original": {
         "owner": "Homebrew",
-        "ref": "5.1.1",
+        "ref": "5.1.7",
         "repo": "brew",
         "type": "github"
       }
@@ -454,11 +454,11 @@
     "homebrew-cask": {
       "flake": false,
       "locked": {
-        "lastModified": 1777042368,
-        "narHash": "sha256-0k/7SBuYWs02t4Agz9dUIqpfo0d/IpM/mMgzYA8mhks=",
+        "lastModified": 1777275723,
+        "narHash": "sha256-7cKFYF/OeD+sVCAg2y78yUyG/8hPYQZ9m9ezybgiZvA=",
         "owner": "homebrew",
         "repo": "homebrew-cask",
-        "rev": "5d6c58496baf289e1dc4476c2a0d2b18da71758e",
+        "rev": "b277b47b93e11d93b04eb718acb7ae8c5af9d860",
         "type": "github"
       },
       "original": {
@@ -470,11 +470,11 @@
     "homebrew-core": {
       "flake": false,
       "locked": {
-        "lastModified": 1777046103,
-        "narHash": "sha256-1Bzd8tJSSW61qN5q4eD6F3xLtRvSLUi4HpJoD6f35Z4=",
+        "lastModified": 1777274771,
+        "narHash": "sha256-Uhqk0iqLZ8A6fatMGLCv4d7fU+so5tfAjpcJBOtTteE=",
         "owner": "homebrew",
         "repo": "homebrew-core",
-        "rev": "3bebf3fd70fb5ddb3664b5fb397e22d3087980bd",
+        "rev": "3fe25b3ce895a424b894c51b19cb8bb86680bc32",
         "type": "github"
       },
       "original": {
@@ -562,11 +562,11 @@
         "systems": "systems_2"
       },
       "locked": {
-        "lastModified": 1776987992,
-        "narHash": "sha256-hcAGb1ZH8AXFjy0UefPIgj0GCSKaaKXWU4kfPJtHutA=",
+        "lastModified": 1777150561,
+        "narHash": "sha256-YLVqyn6LpFa+h697TmZIk0qVIbe7MxMpL8UTF4K+efA=",
         "owner": "NotAShelf",
         "repo": "nvf",
-        "rev": "26b98908d9c1a3260724dc5fabd16f3da1e6ba6c",
+        "rev": "5b4f9c63205e5b0ef180a2b0e4cc844111f96fa6",
         "type": "github"
       },
       "original": {
@@ -580,11 +580,11 @@
         "brew-src": "brew-src"
       },
       "locked": {
-        "lastModified": 1774720267,
-        "narHash": "sha256-YYftFe8jyfpQI649yfr0E+dqEXE2jznZNcYvy/lKV1U=",
+        "lastModified": 1777250621,
+        "narHash": "sha256-WynkkG0hdZ5niYPJUbVg7oMfu8MVwGGzKZ6lKmfa+O8=",
         "owner": "zhaofengli-wip",
         "repo": "nix-homebrew",
-        "rev": "a7760a3a83f7609f742861afb5732210fdc437ed",
+        "rev": "aeb2069920742d0d6570089e8b3b8620050bacf2",
         "type": "github"
       },
       "original": {
@@ -642,11 +642,11 @@
     },
     "nixpkgs_2": {
       "locked": {
-        "lastModified": 1776734388,
-        "narHash": "sha256-vl3dkhlE5gzsItuHoEMVe+DlonsK+0836LIRDnm6MXQ=",
+        "lastModified": 1777077449,
+        "narHash": "sha256-AIiMJiqvGrN4HyLEbKAoCSRRYn0rnlW5VbKNIMIYqm4=",
         "owner": "nixos",
         "repo": "nixpkgs",
-        "rev": "10e7ad5bbcb421fe07e3a4ad53a634b0cd57ffac",
+        "rev": "a4bf06618f0b5ee50f14ed8f0da77d34ecc19160",
         "type": "github"
       },
       "original": {
@@ -749,11 +749,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1777000482,
-        "narHash": "sha256-CZ5FKUSA8FCJf0h9GWdPJXoVVDL9H5yC74GkVc5ubIM=",
+        "lastModified": 1777259803,
+        "narHash": "sha256-fIb/EoVu/1U0qVrE6qZCJ2WCfprRpywNIAVzKEACIQc=",
         "owner": "oxalica",
         "repo": "rust-overlay",
-        "rev": "403c09094a877e6c4816462d00b1a56ff8198e06",
+        "rev": "a6cb2224d975e16b5e67de688c6ad306f7203425",
         "type": "github"
       },
       "original": {
@@ -933,11 +933,11 @@
     },
     "unstable": {
       "locked": {
-        "lastModified": 1776548001,
-        "narHash": "sha256-ZSK0NL4a1BwVbbTBoSnWgbJy9HeZFXLYQizjb2DPF24=",
+        "lastModified": 1776877367,
+        "narHash": "sha256-EHq1/OX139R1RvBzOJ0aMRT3xnWyqtHBRUBuO1gFzjI=",
         "owner": "nixos",
         "repo": "nixpkgs",
-        "rev": "b12141ef619e0a9c1c84dc8c684040326f27cdcc",
+        "rev": "0726a0ecb6d4e08f6adced58726b95db924cef57",
         "type": "github"
       },
       "original": {

From a5472c567a81dd9edb8f5d278713bb71e76e4c93 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Mon, 27 Apr 2026 10:40:23 +0200
Subject: [PATCH 004/101] feat(amd): latest kernel ryzen kernel module

---
 systems/x86_64-linux/amd/hardware-configuration.nix | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/systems/x86_64-linux/amd/hardware-configuration.nix b/systems/x86_64-linux/amd/hardware-configuration.nix
index 0475e14..216eb61 100644
--- a/systems/x86_64-linux/amd/hardware-configuration.nix
+++ b/systems/x86_64-linux/amd/hardware-configuration.nix
@@ -4,6 +4,7 @@
 {
   config,
   lib,
+  pkgs,
   modulesPath,
   ...
 }:
@@ -13,6 +14,8 @@
     (modulesPath + "/installer/scan/not-detected.nix")
   ];
 
+  boot.kernelPackages = lib.mkOverride 0 pkgs.linuxPackages_latest;
+
   boot.initrd.availableKernelModules = [
     "nvme"
     "ahci"
@@ -23,8 +26,8 @@
     "sd_mod"
   ];
   boot.initrd.kernelModules = [ ];
-  boot.kernelModules = [ "kvm-amd" ];
-  boot.extraModulePackages = [ ];
+  boot.kernelModules = [ "kvm-amd" "ryzen_smu" ];
+  boot.extraModulePackages = [ config.boot.kernelPackages.ryzen-smu ];
 
   boot.kernelParams = [
     "lockdown=confidentiality"

From ed8b0eb473490752183e572728360b613ced94fc Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@subzero.xyz>
Date: Mon, 27 Apr 2026 14:08:32 +0200
Subject: [PATCH 005/101] chore: remove direnv from unstable

---
 overlays/unstable/default.nix | 1 -
 1 file changed, 1 deletion(-)

diff --git a/overlays/unstable/default.nix b/overlays/unstable/default.nix
index e80fe30..663f01f 100644
--- a/overlays/unstable/default.nix
+++ b/overlays/unstable/default.nix
@@ -7,7 +7,6 @@ final: prev: {
     # claude-code
     qwen-code
     llama-cpp-rocm
-    direnv
     # open-webui
     # vscode
     # nodejs_20

From 853a0642d7ae32e2fe4a1a53784c19328356f754 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@subzero.xyz>
Date: Mon, 27 Apr 2026 15:21:16 +0200
Subject: [PATCH 006/101] feat(overlays): bump geekbench_6 to 6.7.0

Override the unstable channel's geekbench_6 with version 6.7.0,
updating tarball URLs and hashes for x86_64-linux and aarch64-linux.
---
 overlays/unstable/default.nix | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/overlays/unstable/default.nix b/overlays/unstable/default.nix
index 663f01f..c212a6e 100644
--- a/overlays/unstable/default.nix
+++ b/overlays/unstable/default.nix
@@ -22,6 +22,24 @@ final: prev: {
 
   # goose-cli = channels.unstable.callPackage ./goose.nix { };
   claude-code = channels.unstable.callPackage ./claude-code/package.nix { };
+
+  geekbench_6 = channels.unstable.geekbench_6.overrideAttrs (prevAttrs: rec {
+    version = "6.7.0";
+    src = prev.fetchurl (
+      {
+        "x86_64-linux" = {
+          url = "https://cdn.geekbench.com/Geekbench-${version}-Linux.tar.gz";
+          hash = "sha256-Snt3179Re/zwxop1pvzWF39TXXi8ZUBlNWB+v7+YE38=";
+        };
+        "aarch64-linux" = {
+          url = "https://cdn.geekbench.com/Geekbench-${version}-LinuxARMPreview.tar.gz";
+          hash = "sha256-GCAOKYyijaQPVBgAixoZRPHIdiUfV8mPeeflE7aX8Ac=";
+        };
+      }
+      .${prev.stdenv.system}
+        or (throw "unsupported system ${prev.stdenv.hostPlatform.system}")
+    );
+  });
   # gemini-cli = channels.unstable.callPackage ./gemini-cli/package.nix { };
   # vscode-extensions = channels.unstable.vscode-extensions // {
   #  rooveterinaryinc = { roo-cline = channels.unstable.callPackage ./roo-code.nix { }; };

From b3e5a80936879535d7a398682d55018de6dd3547 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Mon, 27 Apr 2026 15:46:35 +0200
Subject: [PATCH 007/101] feat(packages): expose geekbench_6 as flake package

Allows running the overlay-pinned 6.7.0 build via `nix run .#geekbench_6`
without needing a host to install it.
---
 packages/geekbench_6/default.nix | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 packages/geekbench_6/default.nix

diff --git a/packages/geekbench_6/default.nix b/packages/geekbench_6/default.nix
new file mode 100644
index 0000000..c08fc1d
--- /dev/null
+++ b/packages/geekbench_6/default.nix
@@ -0,0 +1 @@
+{ geekbench_6 }: geekbench_6

From 054ed9637d4d08faff9b41b422615df4b6cf0e20 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Thu, 30 Apr 2026 10:39:03 +0200
Subject: [PATCH 008/101] chore: remove duplicates

---
 modules/nixos/services/gui/default.nix | 2 --
 1 file changed, 2 deletions(-)

diff --git a/modules/nixos/services/gui/default.nix b/modules/nixos/services/gui/default.nix
index 7a89b9c..391c8b7 100644
--- a/modules/nixos/services/gui/default.nix
+++ b/modules/nixos/services/gui/default.nix
@@ -131,7 +131,6 @@ in
         freerdp
         file
         firefox
-        freerdp
         gh
         gimp
         git
@@ -152,7 +151,6 @@ in
         kbfs
         libu2f-host
         mosh
-        mosh
         nixpkgs-fmt
         opensc
         pasystray

From ad7bd6b2a51f093184deaf42e0f6a05c2553cd48 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Fri, 1 May 2026 08:02:14 +0200
Subject: [PATCH 009/101] chore: claude-code update

---
 .../unstable/claude-code/package-lock.json    | 336 ++++--------------
 overlays/unstable/claude-code/package.nix     |  93 ++---
 overlays/unstable/claude-code/update.sh       |  14 +-
 3 files changed, 94 insertions(+), 349 deletions(-)

diff --git a/overlays/unstable/claude-code/package-lock.json b/overlays/unstable/claude-code/package-lock.json
index 96083b9..72eff49 100644
--- a/overlays/unstable/claude-code/package-lock.json
+++ b/overlays/unstable/claude-code/package-lock.json
@@ -1,334 +1,134 @@
 {
   "name": "@anthropic-ai/claude-code",
-  "version": "2.1.112",
+  "version": "2.1.126",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@anthropic-ai/claude-code",
-      "version": "2.1.112",
+      "version": "2.1.126",
+      "hasInstallScript": true,
       "license": "SEE LICENSE IN README.md",
       "bin": {
-        "claude": "cli.js"
+        "claude": "bin/claude.exe"
       },
       "engines": {
         "node": ">=18.0.0"
       },
       "optionalDependencies": {
-        "@img/sharp-darwin-arm64": "^0.34.2",
-        "@img/sharp-darwin-x64": "^0.34.2",
-        "@img/sharp-linux-arm": "^0.34.2",
-        "@img/sharp-linux-arm64": "^0.34.2",
-        "@img/sharp-linux-x64": "^0.34.2",
-        "@img/sharp-linuxmusl-arm64": "^0.34.2",
-        "@img/sharp-linuxmusl-x64": "^0.34.2",
-        "@img/sharp-win32-arm64": "^0.34.2",
-        "@img/sharp-win32-x64": "^0.34.2"
+        "@anthropic-ai/claude-code-darwin-arm64": "2.1.126",
+        "@anthropic-ai/claude-code-darwin-x64": "2.1.126",
+        "@anthropic-ai/claude-code-linux-arm64": "2.1.126",
+        "@anthropic-ai/claude-code-linux-arm64-musl": "2.1.126",
+        "@anthropic-ai/claude-code-linux-x64": "2.1.126",
+        "@anthropic-ai/claude-code-linux-x64-musl": "2.1.126",
+        "@anthropic-ai/claude-code-win32-arm64": "2.1.126",
+        "@anthropic-ai/claude-code-win32-x64": "2.1.126"
       }
     },
-    "node_modules/@img/sharp-darwin-arm64": {
-      "version": "0.34.5",
-      "resolved": "https://registry.npmjs.org/@img/sharp-darwin-arm64/-/sharp-darwin-arm64-0.34.5.tgz",
-      "integrity": "sha512-imtQ3WMJXbMY4fxb/Ndp6HBTNVtWCUI0WdobyheGf5+ad6xX8VIDO8u2xE4qc/fr08CKG/7dDseFtn6M6g/r3w==",
+    "node_modules/@anthropic-ai/claude-code-darwin-arm64": {
+      "version": "2.1.126",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code-darwin-arm64/-/claude-code-darwin-arm64-2.1.126.tgz",
+      "integrity": "sha512-e1p/d4ugb3a28+i1AfRcjFMDnFS9isxsJOy9sYlINmX98pDyCIY76MyJw1HDH0z0x/8jEK30nx/lrrNAvIMNwA==",
       "cpu": [
         "arm64"
       ],
-      "license": "Apache-2.0",
+      "license": "SEE LICENSE IN LICENSE.md",
       "optional": true,
       "os": [
         "darwin"
-      ],
-      "engines": {
-        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
-      },
-      "funding": {
-        "url": "https://opencollective.com/libvips"
-      },
-      "optionalDependencies": {
-        "@img/sharp-libvips-darwin-arm64": "1.2.4"
-      }
+      ]
     },
-    "node_modules/@img/sharp-darwin-x64": {
-      "version": "0.34.5",
-      "resolved": "https://registry.npmjs.org/@img/sharp-darwin-x64/-/sharp-darwin-x64-0.34.5.tgz",
-      "integrity": "sha512-YNEFAF/4KQ/PeW0N+r+aVVsoIY0/qxxikF2SWdp+NRkmMB7y9LBZAVqQ4yhGCm/H3H270OSykqmQMKLBhBJDEw==",
+    "node_modules/@anthropic-ai/claude-code-darwin-x64": {
+      "version": "2.1.126",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code-darwin-x64/-/claude-code-darwin-x64-2.1.126.tgz",
+      "integrity": "sha512-3fR0npNig7/ncwetfDAdtkFYo+hPN8vB6zRQpILVR/Atk0BjLuBFy0rA4/ALBOIftkVCenXMD5UIURPMnhh/sA==",
       "cpu": [
         "x64"
       ],
-      "license": "Apache-2.0",
+      "license": "SEE LICENSE IN LICENSE.md",
       "optional": true,
       "os": [
         "darwin"
-      ],
-      "engines": {
-        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
-      },
-      "funding": {
-        "url": "https://opencollective.com/libvips"
-      },
-      "optionalDependencies": {
-        "@img/sharp-libvips-darwin-x64": "1.2.4"
-      }
+      ]
     },
-    "node_modules/@img/sharp-libvips-darwin-arm64": {
-      "version": "1.2.4",
-      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-arm64/-/sharp-libvips-darwin-arm64-1.2.4.tgz",
-      "integrity": "sha512-zqjjo7RatFfFoP0MkQ51jfuFZBnVE2pRiaydKJ1G/rHZvnsrHAOcQALIi9sA5co5xenQdTugCvtb1cuf78Vf4g==",
+    "node_modules/@anthropic-ai/claude-code-linux-arm64": {
+      "version": "2.1.126",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code-linux-arm64/-/claude-code-linux-arm64-2.1.126.tgz",
+      "integrity": "sha512-iqdERAVEhU2BwEPlHy/S0O3ioKnlFUvlk5xS/G8DXnWok4Niin1HJ+7q4u6ayXWw7JFou3GW3pg34V31ddGhGg==",
       "cpu": [
         "arm64"
       ],
-      "license": "LGPL-3.0-or-later",
+      "license": "SEE LICENSE IN LICENSE.md",
       "optional": true,
       "os": [
-        "darwin"
-      ],
-      "funding": {
-        "url": "https://opencollective.com/libvips"
-      }
+        "linux"
+      ]
     },
-    "node_modules/@img/sharp-libvips-darwin-x64": {
-      "version": "1.2.4",
-      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-darwin-x64/-/sharp-libvips-darwin-x64-1.2.4.tgz",
-      "integrity": "sha512-1IOd5xfVhlGwX+zXv2N93k0yMONvUlANylbJw1eTah8K/Jtpi15KC+WSiaX/nBmbm2HxRM1gZ0nSdjSsrZbGKg==",
+    "node_modules/@anthropic-ai/claude-code-linux-arm64-musl": {
+      "version": "2.1.126",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code-linux-arm64-musl/-/claude-code-linux-arm64-musl-2.1.126.tgz",
+      "integrity": "sha512-soOkg7QjoQ1nMa78YmyhLeKDkFtRXgucsE9P84+J3HB3CDIcZI+MWQvwZT9lr5IuU8KbkNOijSzIRaUCLZAPuQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "license": "SEE LICENSE IN LICENSE.md",
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@anthropic-ai/claude-code-linux-x64": {
+      "version": "2.1.126",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code-linux-x64/-/claude-code-linux-x64-2.1.126.tgz",
+      "integrity": "sha512-D2A9TI62aoQcxxbZzsiOWlfqs+7X/K49qSthkPdCg4B24aQWv2rL0PWTvnvMTbQUTlg6bBL0PjauANdgHs+WjQ==",
       "cpu": [
         "x64"
       ],
-      "license": "LGPL-3.0-or-later",
-      "optional": true,
-      "os": [
-        "darwin"
-      ],
-      "funding": {
-        "url": "https://opencollective.com/libvips"
-      }
-    },
-    "node_modules/@img/sharp-libvips-linux-arm": {
-      "version": "1.2.4",
-      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm/-/sharp-libvips-linux-arm-1.2.4.tgz",
-      "integrity": "sha512-bFI7xcKFELdiNCVov8e44Ia4u2byA+l3XtsAj+Q8tfCwO6BQ8iDojYdvoPMqsKDkuoOo+X6HZA0s0q11ANMQ8A==",
-      "cpu": [
-        "arm"
-      ],
-      "license": "LGPL-3.0-or-later",
+      "license": "SEE LICENSE IN LICENSE.md",
       "optional": true,
       "os": [
         "linux"
-      ],
-      "funding": {
-        "url": "https://opencollective.com/libvips"
-      }
+      ]
     },
-    "node_modules/@img/sharp-libvips-linux-arm64": {
-      "version": "1.2.4",
-      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-arm64/-/sharp-libvips-linux-arm64-1.2.4.tgz",
-      "integrity": "sha512-excjX8DfsIcJ10x1Kzr4RcWe1edC9PquDRRPx3YVCvQv+U5p7Yin2s32ftzikXojb1PIFc/9Mt28/y+iRklkrw==",
-      "cpu": [
-        "arm64"
-      ],
-      "license": "LGPL-3.0-or-later",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "funding": {
-        "url": "https://opencollective.com/libvips"
-      }
-    },
-    "node_modules/@img/sharp-libvips-linux-x64": {
-      "version": "1.2.4",
-      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linux-x64/-/sharp-libvips-linux-x64-1.2.4.tgz",
-      "integrity": "sha512-tJxiiLsmHc9Ax1bz3oaOYBURTXGIRDODBqhveVHonrHJ9/+k89qbLl0bcJns+e4t4rvaNBxaEZsFtSfAdquPrw==",
+    "node_modules/@anthropic-ai/claude-code-linux-x64-musl": {
+      "version": "2.1.126",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code-linux-x64-musl/-/claude-code-linux-x64-musl-2.1.126.tgz",
+      "integrity": "sha512-y9NhIWnITVmKssq0XNoUFqLdfWiD9BmZI8SAVqcxUbFUpDmbsCKpNB2SrvMQmjYLZneDnmxdHLfciU0DS9S7HQ==",
       "cpu": [
         "x64"
       ],
-      "license": "LGPL-3.0-or-later",
+      "license": "SEE LICENSE IN LICENSE.md",
       "optional": true,
       "os": [
         "linux"
-      ],
-      "funding": {
-        "url": "https://opencollective.com/libvips"
-      }
+      ]
     },
-    "node_modules/@img/sharp-libvips-linuxmusl-arm64": {
-      "version": "1.2.4",
-      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-arm64/-/sharp-libvips-linuxmusl-arm64-1.2.4.tgz",
-      "integrity": "sha512-FVQHuwx1IIuNow9QAbYUzJ+En8KcVm9Lk5+uGUQJHaZmMECZmOlix9HnH7n1TRkXMS0pGxIJokIVB9SuqZGGXw==",
+    "node_modules/@anthropic-ai/claude-code-win32-arm64": {
+      "version": "2.1.126",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code-win32-arm64/-/claude-code-win32-arm64-2.1.126.tgz",
+      "integrity": "sha512-uKVVUKaAMq83IJSla9YMh/QUQJYhQP0Q95aYryXF/qNMUSqf0QUfi8dygkTkCzJqEbyLHTG0w+8q1gRCVydBVA==",
       "cpu": [
         "arm64"
       ],
-      "license": "LGPL-3.0-or-later",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "funding": {
-        "url": "https://opencollective.com/libvips"
-      }
-    },
-    "node_modules/@img/sharp-libvips-linuxmusl-x64": {
-      "version": "1.2.4",
-      "resolved": "https://registry.npmjs.org/@img/sharp-libvips-linuxmusl-x64/-/sharp-libvips-linuxmusl-x64-1.2.4.tgz",
-      "integrity": "sha512-+LpyBk7L44ZIXwz/VYfglaX/okxezESc6UxDSoyo2Ks6Jxc4Y7sGjpgU9s4PMgqgjj1gZCylTieNamqA1MF7Dg==",
-      "cpu": [
-        "x64"
-      ],
-      "license": "LGPL-3.0-or-later",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "funding": {
-        "url": "https://opencollective.com/libvips"
-      }
-    },
-    "node_modules/@img/sharp-linux-arm": {
-      "version": "0.34.5",
-      "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm/-/sharp-linux-arm-0.34.5.tgz",
-      "integrity": "sha512-9dLqsvwtg1uuXBGZKsxem9595+ujv0sJ6Vi8wcTANSFpwV/GONat5eCkzQo/1O6zRIkh0m/8+5BjrRr7jDUSZw==",
-      "cpu": [
-        "arm"
-      ],
-      "license": "Apache-2.0",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
-      },
-      "funding": {
-        "url": "https://opencollective.com/libvips"
-      },
-      "optionalDependencies": {
-        "@img/sharp-libvips-linux-arm": "1.2.4"
-      }
-    },
-    "node_modules/@img/sharp-linux-arm64": {
-      "version": "0.34.5",
-      "resolved": "https://registry.npmjs.org/@img/sharp-linux-arm64/-/sharp-linux-arm64-0.34.5.tgz",
-      "integrity": "sha512-bKQzaJRY/bkPOXyKx5EVup7qkaojECG6NLYswgktOZjaXecSAeCWiZwwiFf3/Y+O1HrauiE3FVsGxFg8c24rZg==",
-      "cpu": [
-        "arm64"
-      ],
-      "license": "Apache-2.0",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
-      },
-      "funding": {
-        "url": "https://opencollective.com/libvips"
-      },
-      "optionalDependencies": {
-        "@img/sharp-libvips-linux-arm64": "1.2.4"
-      }
-    },
-    "node_modules/@img/sharp-linux-x64": {
-      "version": "0.34.5",
-      "resolved": "https://registry.npmjs.org/@img/sharp-linux-x64/-/sharp-linux-x64-0.34.5.tgz",
-      "integrity": "sha512-MEzd8HPKxVxVenwAa+JRPwEC7QFjoPWuS5NZnBt6B3pu7EG2Ge0id1oLHZpPJdn3OQK+BQDiw9zStiHBTJQQQQ==",
-      "cpu": [
-        "x64"
-      ],
-      "license": "Apache-2.0",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
-      },
-      "funding": {
-        "url": "https://opencollective.com/libvips"
-      },
-      "optionalDependencies": {
-        "@img/sharp-libvips-linux-x64": "1.2.4"
-      }
-    },
-    "node_modules/@img/sharp-linuxmusl-arm64": {
-      "version": "0.34.5",
-      "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-arm64/-/sharp-linuxmusl-arm64-0.34.5.tgz",
-      "integrity": "sha512-fprJR6GtRsMt6Kyfq44IsChVZeGN97gTD331weR1ex1c1rypDEABN6Tm2xa1wE6lYb5DdEnk03NZPqA7Id21yg==",
-      "cpu": [
-        "arm64"
-      ],
-      "license": "Apache-2.0",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
-      },
-      "funding": {
-        "url": "https://opencollective.com/libvips"
-      },
-      "optionalDependencies": {
-        "@img/sharp-libvips-linuxmusl-arm64": "1.2.4"
-      }
-    },
-    "node_modules/@img/sharp-linuxmusl-x64": {
-      "version": "0.34.5",
-      "resolved": "https://registry.npmjs.org/@img/sharp-linuxmusl-x64/-/sharp-linuxmusl-x64-0.34.5.tgz",
-      "integrity": "sha512-Jg8wNT1MUzIvhBFxViqrEhWDGzqymo3sV7z7ZsaWbZNDLXRJZoRGrjulp60YYtV4wfY8VIKcWidjojlLcWrd8Q==",
-      "cpu": [
-        "x64"
-      ],
-      "license": "Apache-2.0",
-      "optional": true,
-      "os": [
-        "linux"
-      ],
-      "engines": {
-        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
-      },
-      "funding": {
-        "url": "https://opencollective.com/libvips"
-      },
-      "optionalDependencies": {
-        "@img/sharp-libvips-linuxmusl-x64": "1.2.4"
-      }
-    },
-    "node_modules/@img/sharp-win32-arm64": {
-      "version": "0.34.5",
-      "resolved": "https://registry.npmjs.org/@img/sharp-win32-arm64/-/sharp-win32-arm64-0.34.5.tgz",
-      "integrity": "sha512-WQ3AgWCWYSb2yt+IG8mnC6Jdk9Whs7O0gxphblsLvdhSpSTtmu69ZG1Gkb6NuvxsNACwiPV6cNSZNzt0KPsw7g==",
-      "cpu": [
-        "arm64"
-      ],
-      "license": "Apache-2.0 AND LGPL-3.0-or-later",
+      "license": "SEE LICENSE IN LICENSE.md",
       "optional": true,
       "os": [
         "win32"
-      ],
-      "engines": {
-        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
-      },
-      "funding": {
-        "url": "https://opencollective.com/libvips"
-      }
+      ]
     },
-    "node_modules/@img/sharp-win32-x64": {
-      "version": "0.34.5",
-      "resolved": "https://registry.npmjs.org/@img/sharp-win32-x64/-/sharp-win32-x64-0.34.5.tgz",
-      "integrity": "sha512-+29YMsqY2/9eFEiW93eqWnuLcWcufowXewwSNIT6UwZdUUCrM3oFjMWH/Z6/TMmb4hlFenmfAVbpWeup2jryCw==",
+    "node_modules/@anthropic-ai/claude-code-win32-x64": {
+      "version": "2.1.126",
+      "resolved": "https://registry.npmjs.org/@anthropic-ai/claude-code-win32-x64/-/claude-code-win32-x64-2.1.126.tgz",
+      "integrity": "sha512-heB2dj1f2rV2OshT2bKenPWCWoFJZV/gp2QSZmSVsYgDLS5mbv8kUBar69S+4ldLH9oeDERePnnoDHpch4BWew==",
       "cpu": [
         "x64"
       ],
-      "license": "Apache-2.0 AND LGPL-3.0-or-later",
+      "license": "SEE LICENSE IN LICENSE.md",
       "optional": true,
       "os": [
         "win32"
-      ],
-      "engines": {
-        "node": "^18.17.0 || ^20.3.0 || >=21.0.0"
-      },
-      "funding": {
-        "url": "https://opencollective.com/libvips"
-      }
+      ]
     }
   }
 }
diff --git a/overlays/unstable/claude-code/package.nix b/overlays/unstable/claude-code/package.nix
index ace4105..e25950b 100644
--- a/overlays/unstable/claude-code/package.nix
+++ b/overlays/unstable/claude-code/package.nix
@@ -1,78 +1,36 @@
-# NOTE: Use the following command to update the package
-# ```sh
-# nix-shell maintainers/scripts/update.nix --argstr commit true --arg predicate '(path: pkg: builtins.elem path [["claude-code"] ["vscode-extensions" "anthropic" "claude-code"]])'
-# ```
 {
   lib,
-  stdenvNoCC,
-  fetchurl,
-  installShellFiles,
-  makeBinaryWrapper,
-  autoPatchelfHook,
-  procps,
-  ripgrep,
-  bubblewrap,
-  socat,
-  versionCheckHook,
+  buildNpmPackage,
+  fetchzip,
   writableTmpDirAsHomeHook,
+  versionCheckHook,
 }:
-let
-  stdenv = stdenvNoCC;
-  baseUrl = "https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases";
-  manifest = lib.importJSON ./manifest.json;
-  platformKey = "${stdenv.hostPlatform.node.platform}-${stdenv.hostPlatform.node.arch}";
-  platformManifestEntry = manifest.platforms.${platformKey};
-in
-stdenv.mkDerivation (finalAttrs: {
+buildNpmPackage (finalAttrs: {
   pname = "claude-code";
-  inherit (manifest) version;
+  version = "2.1.126";
 
-  src = fetchurl {
-    url = "${baseUrl}/${finalAttrs.version}/${platformKey}/claude";
-    sha256 = platformManifestEntry.checksum;
+  src = fetchzip {
+    url = "https://registry.npmjs.org/@anthropic-ai/claude-code/-/claude-code-${finalAttrs.version}.tgz";
+    hash = "sha256-Il9MGrnnIV3i86cU3BjslGEdVodnV50VW3f2DEjSlMk=";
   };
 
-  dontUnpack = true;
-  dontBuild = true;
-  __noChroot = stdenv.hostPlatform.isDarwin;
-  # otherwise the bun runtime is executed instead of the binary
-  dontStrip = true;
+  npmDepsHash = "sha256-/5Qh99vAcTiFz6FrzJgm26RserqxVjLYqOOx5q5hkgc=";
 
-  nativeBuildInputs = [
-    installShellFiles
-    makeBinaryWrapper
-  ]
-  ++ lib.optionals stdenv.hostPlatform.isElf [ autoPatchelfHook ];
+  postPatch = ''
+    cp ${./package-lock.json} package-lock.json
+  '';
 
-  strictDeps = true;
+  dontNpmBuild = true;
 
-  installPhase = ''
-    runHook preInstall
-
-    installBin $src
+  env.AUTHORIZED = "1";
 
+  # `claude-code` tries to auto-update by default, this disables that functionality.
+  # https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview#environment-variables
+  # The DEV=true env var causes claude to crash with `TypeError: window.WebSocket is not a constructor`
+  postInstall = ''
     wrapProgram $out/bin/claude \
       --set DISABLE_AUTOUPDATER 1 \
-      --set-default FORCE_AUTOUPDATE_PLUGINS 1 \
-      --set DISABLE_INSTALLATION_CHECKS 1 \
-      --set USE_BUILTIN_RIPGREP 0 \
-      --prefix PATH : ${
-        lib.makeBinPath (
-          [
-            # claude-code uses [node-tree-kill](https://github.com/pkrumins/node-tree-kill) which requires procps's pgrep(darwin) or ps(linux)
-            procps
-            # https://code.claude.com/docs/en/troubleshooting#search-and-discovery-issues
-            ripgrep
-          ]
-          # the following packages are required for the sandbox to work (Linux only)
-          ++ lib.optionals stdenv.hostPlatform.isLinux [
-            bubblewrap
-            socat
-          ]
-        )
-      }
-
-    runHook postInstall
+      --unset DEV
   '';
 
   doInstallCheck = true;
@@ -88,23 +46,12 @@ stdenv.mkDerivation (finalAttrs: {
   meta = {
     description = "Agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster";
     homepage = "https://github.com/anthropics/claude-code";
-    downloadPage = "https://claude.com/product/claude-code";
-    changelog = "https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md";
+    downloadPage = "https://www.npmjs.com/package/@anthropic-ai/claude-code";
     license = lib.licenses.unfree;
-    sourceProvenance = with lib.sourceTypes; [ binaryNativeCode ];
-    platforms = [
-      "aarch64-darwin"
-      "x86_64-darwin"
-      "aarch64-linux"
-      "x86_64-linux"
-    ];
     maintainers = with lib.maintainers; [
-      adeci
       malo
       markus1189
-      mirkolenz
       omarjatoi
-      oskarwires
       xiaoxiangmoe
     ];
     mainProgram = "claude";
diff --git a/overlays/unstable/claude-code/update.sh b/overlays/unstable/claude-code/update.sh
index 1e2125a..a3fe5d8 100755
--- a/overlays/unstable/claude-code/update.sh
+++ b/overlays/unstable/claude-code/update.sh
@@ -1,12 +1,10 @@
-#!/usr/bin/env nix
-#!nix shell --ignore-environment .#cacert .#coreutils .#curl .#bash --command bash
+#!/usr/bin/env nix-shell
+#!nix-shell --pure --keep NIX_PATH -i bash --packages nodejs nix-update git cacert
 
 set -euo pipefail
 
-cd "$(dirname "${BASH_SOURCE[0]}")"
+version=$(npm view @anthropic-ai/claude-code version)
 
-BASE_URL="https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases"
-
-VERSION="${1:-$(curl -fsSL "$BASE_URL/latest")}"
-
-curl -fsSL "$BASE_URL/$VERSION/manifest.json" --output manifest.json
+# Update version and hashes
+AUTHORIZED=1 NIXPKGS_ALLOW_UNFREE=1 nix-update claude-code --version="$version" --generate-lockfile
+nix-update vscode-extensions.anthropic.claude-code --use-update-script --version "$version"

From 9deedfcb51ce41400b484673dc5368e36babc2b9 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Fri, 1 May 2026 08:09:42 +0200
Subject: [PATCH 010/101] chore: claude-code update

---
 overlays/unstable/claude-code/package.nix | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/overlays/unstable/claude-code/package.nix b/overlays/unstable/claude-code/package.nix
index e25950b..12d2d87 100644
--- a/overlays/unstable/claude-code/package.nix
+++ b/overlays/unstable/claude-code/package.nix
@@ -14,7 +14,7 @@ buildNpmPackage (finalAttrs: {
     hash = "sha256-Il9MGrnnIV3i86cU3BjslGEdVodnV50VW3f2DEjSlMk=";
   };
 
-  npmDepsHash = "sha256-/5Qh99vAcTiFz6FrzJgm26RserqxVjLYqOOx5q5hkgc=";
+  npmDepsHash = "sha256-tVQbjW2ZqzuH/MIpT8k5/OHBVLtuKPQt6P20TwBx3Cs=";
 
   postPatch = ''
     cp ${./package-lock.json} package-lock.json

From 14933e4e767a1c5ef64b8585d6de3402b2b2d096 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Fri, 1 May 2026 08:15:53 +0200
Subject: [PATCH 011/101] chore: claude-code update

---
 overlays/unstable/claude-code/manifest.json | 38 ++++-----
 overlays/unstable/claude-code/package.nix   | 93 ++++++++++++++++-----
 overlays/unstable/claude-code/update.sh     | 14 ++--
 3 files changed, 100 insertions(+), 45 deletions(-)

diff --git a/overlays/unstable/claude-code/manifest.json b/overlays/unstable/claude-code/manifest.json
index 774b348..6dbf791 100644
--- a/overlays/unstable/claude-code/manifest.json
+++ b/overlays/unstable/claude-code/manifest.json
@@ -1,47 +1,47 @@
 {
-  "version": "2.1.119",
-  "commit": "6f68554839756189e277b8285a18fe47acd9a5a1",
-  "buildDate": "2026-04-23T20:45:14Z",
+  "version": "2.1.126",
+  "commit": "e44c1d97bd39dbf2525164f3fd33be6edbf1661e",
+  "buildDate": "2026-04-30T16:08:06Z",
   "platforms": {
     "darwin-arm64": {
       "binary": "claude",
-      "checksum": "31db3444309d5d0f8b85e8782e2dcd86f31f7e48c1a1e83d69b09268c7b4f9a2",
-      "size": 213404000
+      "checksum": "87a1d05018ceadfc1fe616bfc10262b0503f51986f4af2dc42d1ed856ed3f7bb",
+      "size": 216260096
     },
     "darwin-x64": {
       "binary": "claude",
-      "checksum": "52b3b75cfe80c626982b2ffb3a6ce1c797824f257dc275cf0a3c32c202b6a3df",
-      "size": 214951760
+      "checksum": "49a90c474383a9eda11310bd71f7ea6bb91361ec99443b733cb5003f6e703ccb",
+      "size": 217824336
     },
     "linux-arm64": {
       "binary": "claude",
-      "checksum": "382aa73ea4b07fd8d698e3159b5ef9e1b8739fae7505ba8ddd28b8a6a62819ce",
-      "size": 245500480
+      "checksum": "88a6dca613a40559f3bac8a946a2ec6e60a870b91938d3df93dcac1dec4848cb",
+      "size": 248318528
     },
     "linux-x64": {
       "binary": "claude",
-      "checksum": "cca43053f062949495596b11b6fd1b59cf79102adb13bacbe66997e6fae41e4a",
-      "size": 245230208
+      "checksum": "fce96968d275161ff65a4c19fc6434efc6973d9f6d35dc3992a2ba0553cac18e",
+      "size": 248105600
     },
     "linux-arm64-musl": {
       "binary": "claude",
-      "checksum": "e09bfaedd8bfdeaebe5f1cf9bb81ebeb718312c68fffce379fb51786263143d0",
-      "size": 238225856
+      "checksum": "042bbc0c3610d005d371645e34c4b4055bb2499f7a4509ed667b2a8924ac5853",
+      "size": 241043840
     },
     "linux-x64-musl": {
       "binary": "claude",
-      "checksum": "ef41a11653b39c14db2d343f1f5e2a3af7eb9871c63e64deb6e65919670a4e0b",
-      "size": 239495616
+      "checksum": "b3f39b00069558e57c6d36ead6b2efe013afa57b603445c338374d0c873e95c0",
+      "size": 242370944
     },
     "win32-x64": {
       "binary": "claude.exe",
-      "checksum": "e18c7dcfad4a3f5d33d202ec2dde630b648cf5b41622154d6210e793c7cceadc",
-      "size": 254478496
+      "checksum": "1a6b4be4b45458ab1831bad138572bf2fec12cb1edea0685c5ff10ce6e97afb6",
+      "size": 254053024
     },
     "win32-arm64": {
       "binary": "claude.exe",
-      "checksum": "9e0deb10c45108612484ce558fad378206d5ac23feb203067450e6c38d001241",
-      "size": 251203232
+      "checksum": "7253defbc945f5461035240bc32d18970fb1acc5df63092c492ee8d7c7caf55f",
+      "size": 250115744
     }
   }
 }
diff --git a/overlays/unstable/claude-code/package.nix b/overlays/unstable/claude-code/package.nix
index 12d2d87..ace4105 100644
--- a/overlays/unstable/claude-code/package.nix
+++ b/overlays/unstable/claude-code/package.nix
@@ -1,36 +1,78 @@
+# NOTE: Use the following command to update the package
+# ```sh
+# nix-shell maintainers/scripts/update.nix --argstr commit true --arg predicate '(path: pkg: builtins.elem path [["claude-code"] ["vscode-extensions" "anthropic" "claude-code"]])'
+# ```
 {
   lib,
-  buildNpmPackage,
-  fetchzip,
-  writableTmpDirAsHomeHook,
+  stdenvNoCC,
+  fetchurl,
+  installShellFiles,
+  makeBinaryWrapper,
+  autoPatchelfHook,
+  procps,
+  ripgrep,
+  bubblewrap,
+  socat,
   versionCheckHook,
+  writableTmpDirAsHomeHook,
 }:
-buildNpmPackage (finalAttrs: {
+let
+  stdenv = stdenvNoCC;
+  baseUrl = "https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases";
+  manifest = lib.importJSON ./manifest.json;
+  platformKey = "${stdenv.hostPlatform.node.platform}-${stdenv.hostPlatform.node.arch}";
+  platformManifestEntry = manifest.platforms.${platformKey};
+in
+stdenv.mkDerivation (finalAttrs: {
   pname = "claude-code";
-  version = "2.1.126";
+  inherit (manifest) version;
 
-  src = fetchzip {
-    url = "https://registry.npmjs.org/@anthropic-ai/claude-code/-/claude-code-${finalAttrs.version}.tgz";
-    hash = "sha256-Il9MGrnnIV3i86cU3BjslGEdVodnV50VW3f2DEjSlMk=";
+  src = fetchurl {
+    url = "${baseUrl}/${finalAttrs.version}/${platformKey}/claude";
+    sha256 = platformManifestEntry.checksum;
   };
 
-  npmDepsHash = "sha256-tVQbjW2ZqzuH/MIpT8k5/OHBVLtuKPQt6P20TwBx3Cs=";
+  dontUnpack = true;
+  dontBuild = true;
+  __noChroot = stdenv.hostPlatform.isDarwin;
+  # otherwise the bun runtime is executed instead of the binary
+  dontStrip = true;
 
-  postPatch = ''
-    cp ${./package-lock.json} package-lock.json
-  '';
+  nativeBuildInputs = [
+    installShellFiles
+    makeBinaryWrapper
+  ]
+  ++ lib.optionals stdenv.hostPlatform.isElf [ autoPatchelfHook ];
 
-  dontNpmBuild = true;
+  strictDeps = true;
 
-  env.AUTHORIZED = "1";
+  installPhase = ''
+    runHook preInstall
+
+    installBin $src
 
-  # `claude-code` tries to auto-update by default, this disables that functionality.
-  # https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview#environment-variables
-  # The DEV=true env var causes claude to crash with `TypeError: window.WebSocket is not a constructor`
-  postInstall = ''
     wrapProgram $out/bin/claude \
       --set DISABLE_AUTOUPDATER 1 \
-      --unset DEV
+      --set-default FORCE_AUTOUPDATE_PLUGINS 1 \
+      --set DISABLE_INSTALLATION_CHECKS 1 \
+      --set USE_BUILTIN_RIPGREP 0 \
+      --prefix PATH : ${
+        lib.makeBinPath (
+          [
+            # claude-code uses [node-tree-kill](https://github.com/pkrumins/node-tree-kill) which requires procps's pgrep(darwin) or ps(linux)
+            procps
+            # https://code.claude.com/docs/en/troubleshooting#search-and-discovery-issues
+            ripgrep
+          ]
+          # the following packages are required for the sandbox to work (Linux only)
+          ++ lib.optionals stdenv.hostPlatform.isLinux [
+            bubblewrap
+            socat
+          ]
+        )
+      }
+
+    runHook postInstall
   '';
 
   doInstallCheck = true;
@@ -46,12 +88,23 @@ buildNpmPackage (finalAttrs: {
   meta = {
     description = "Agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster";
     homepage = "https://github.com/anthropics/claude-code";
-    downloadPage = "https://www.npmjs.com/package/@anthropic-ai/claude-code";
+    downloadPage = "https://claude.com/product/claude-code";
+    changelog = "https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md";
     license = lib.licenses.unfree;
+    sourceProvenance = with lib.sourceTypes; [ binaryNativeCode ];
+    platforms = [
+      "aarch64-darwin"
+      "x86_64-darwin"
+      "aarch64-linux"
+      "x86_64-linux"
+    ];
     maintainers = with lib.maintainers; [
+      adeci
       malo
       markus1189
+      mirkolenz
       omarjatoi
+      oskarwires
       xiaoxiangmoe
     ];
     mainProgram = "claude";
diff --git a/overlays/unstable/claude-code/update.sh b/overlays/unstable/claude-code/update.sh
index a3fe5d8..1e2125a 100755
--- a/overlays/unstable/claude-code/update.sh
+++ b/overlays/unstable/claude-code/update.sh
@@ -1,10 +1,12 @@
-#!/usr/bin/env nix-shell
-#!nix-shell --pure --keep NIX_PATH -i bash --packages nodejs nix-update git cacert
+#!/usr/bin/env nix
+#!nix shell --ignore-environment .#cacert .#coreutils .#curl .#bash --command bash
 
 set -euo pipefail
 
-version=$(npm view @anthropic-ai/claude-code version)
+cd "$(dirname "${BASH_SOURCE[0]}")"
 
-# Update version and hashes
-AUTHORIZED=1 NIXPKGS_ALLOW_UNFREE=1 nix-update claude-code --version="$version" --generate-lockfile
-nix-update vscode-extensions.anthropic.claude-code --use-update-script --version "$version"
+BASE_URL="https://storage.googleapis.com/claude-code-dist-86c565f3-f756-42ad-8dfa-d59b1c096819/claude-code-releases"
+
+VERSION="${1:-$(curl -fsSL "$BASE_URL/latest")}"
+
+curl -fsSL "$BASE_URL/$VERSION/manifest.json" --output manifest.json

From a4dd12481e6aae2d31257bfaf06b5b863eb48f99 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Fri, 1 May 2026 07:38:31 +0200
Subject: [PATCH 012/101] chore: update secret

---
 .secrets/sgx/firefly.yaml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/.secrets/sgx/firefly.yaml b/.secrets/sgx/firefly.yaml
index da0c12d..ca34275 100644
--- a/.secrets/sgx/firefly.yaml
+++ b/.secrets/sgx/firefly.yaml
@@ -1,6 +1,6 @@
 firefly:
     app_key: ENC[AES256_GCM,data:0BHC54xXb7EJcFBuGWFiDfIh7ZBgVs1R+1GGztOwte4CeD4Olz31umq1At1aRFESLkoC,iv:e3On3x9eSKTo9+SEp/ujFZA0a6o2slqT+atPhd1PDMM=,tag:k2pjyvgM8AcElBBOR95dwg==,type:str]
-    sparda_pin: ENC[AES256_GCM,data:8jpahQBDQO4tFZUgCYGe,iv:Vi5WAyk+fTMdRsPvrJEKvR3QHJVgTaWt/mzubCtwpeM=,tag:LpHaKeW9ww2O9gfAyvtkcg==,type:str]
+    sparda_pin: ENC[AES256_GCM,data:mEa7vQuXWWHfpITojTyxjEZOPck=,iv:gkMlAi27AACHWC0MaXeUeP8BBZF/0vshDJrg67GP0ho=,tag:CIo70Iu+R6KNj0eFu8XxAg==,type:str]
     auto_import_secret: ENC[AES256_GCM,data:7JcxrIu4tRDgVhcUBoc/u2xN6NxRutKsTbvN8kr/u54BJ+fuZ94EVtDc9B1ZnTLuPb5LStbLnHFcLs17ocpk7g==,iv:DcilcMGEQgJ4hwuJJ2cF3Hdyy85QFpwHjlFwbFEwsAE=,tag:4+KPk7OJ61xngpBmAitlEA==,type:str]
 sops:
     age:
@@ -31,7 +31,7 @@ sops:
             SGRyL01ISlltVG5YdWw4dWV0RGpPNEEK855vVFGwxgBrl0scAla980fd3XSiUjfP
             ULMGGQK06z1Oh6+bvPyfzbILjFkzlrel06yajpcvdSQgJZXpzQgJUA==
             -----END AGE ENCRYPTED FILE-----
-    lastmodified: "2026-04-26T18:12:24Z"
-    mac: ENC[AES256_GCM,data:e19xgZ0oZq3volq91zhM83ZLWVq9tDQopUJoMOmc4to25O3jxI+Cn0+ZMeSi6P9HwRQV97X6lDdODcRYv0hkgWAd8W1c876muH1bt0/nLYLBd2bwf/d/wdKvdobEkN/Xn8K9VK6lF3ojTsuASWTGJ+9ei4RQ2nQkQk8IBBn5Fzg=,iv:1C38ZXhQg+vS/ZSuLkW4vFgSgC0dtp25V9umTR5lC10=,tag:4+CBjsIry5RDXG1ct4UcXg==,type:str]
+    lastmodified: "2026-05-01T05:37:38Z"
+    mac: ENC[AES256_GCM,data:J5z5bZgQhkIkH4RaA5c74IsKiFgES7XDEqq0lmq/VaopOAhHAD6Lzi4v2jY2CtZkFLdtbEw/8nGGrEmFNonYNqSNOnWCkDfr5jQXk5uT+HGKUsKNOjqSZRs9xpF3LJKpSMZ9LlpzFbfEEv5JMJk74GXPodMTPWHYwTKsA7mHh4M=,iv:z7X7fJcZ2mXDaSNcb77VdjqeHihL0xzHrtbL7/ShIN4=,tag:7YlyBZ3Ro69qVVOG4OSnxw==,type:str]
     unencrypted_suffix: _unencrypted
     version: 3.12.1

From 55bef140765a71bc31d5acdbdab82cb0de984f54 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Fri, 1 May 2026 08:43:43 +0200
Subject: [PATCH 013/101] chore: secret update

---
 .secrets/sgx/firefly.yaml | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/.secrets/sgx/firefly.yaml b/.secrets/sgx/firefly.yaml
index ca34275..33a31a5 100644
--- a/.secrets/sgx/firefly.yaml
+++ b/.secrets/sgx/firefly.yaml
@@ -2,6 +2,7 @@ firefly:
     app_key: ENC[AES256_GCM,data:0BHC54xXb7EJcFBuGWFiDfIh7ZBgVs1R+1GGztOwte4CeD4Olz31umq1At1aRFESLkoC,iv:e3On3x9eSKTo9+SEp/ujFZA0a6o2slqT+atPhd1PDMM=,tag:k2pjyvgM8AcElBBOR95dwg==,type:str]
     sparda_pin: ENC[AES256_GCM,data:mEa7vQuXWWHfpITojTyxjEZOPck=,iv:gkMlAi27AACHWC0MaXeUeP8BBZF/0vshDJrg67GP0ho=,tag:CIo70Iu+R6KNj0eFu8XxAg==,type:str]
     auto_import_secret: ENC[AES256_GCM,data:7JcxrIu4tRDgVhcUBoc/u2xN6NxRutKsTbvN8kr/u54BJ+fuZ94EVtDc9B1ZnTLuPb5LStbLnHFcLs17ocpk7g==,iv:DcilcMGEQgJ4hwuJJ2cF3Hdyy85QFpwHjlFwbFEwsAE=,tag:4+KPk7OJ61xngpBmAitlEA==,type:str]
+    access_token: ENC[AES256_GCM,data:zxS95MlpwrqdhhQtVPgCknf0yVJHeLkswDegEYQPwUqpOMYDST/OVkUIzkKyNbEN8gS11i5WY7jPfTUi5yRYy4pPs9stz1XJ//c9LgAUMkP9W6XHL6ykcLpaG6EU3+UHFYlfZImFFGxNrqqIBspdCo9dGpQVLY2t46nSF+xhh29uUDXGkUZL5FeQFSMP09l9QkzBumUNuGhhfMtZNMOhXMvaS7s2ghaTqA2C1biqmeWX7leum6jjzUyoBMLGsFfVLYFhW2dfgPvvURIIIIxMM9tzvnCrNIczZkbzmuXpDn81KE7eYGYf4/0yvUhqzENcpplTiDTdVrQQK0tozJFO96D31iKf/kU29XRrxJJanwDBMychGYVtS2ba42mxwz+Zpca0yPxhYexb7OcjNkmuN1Kge0upd4+C/alshzEAWAAQCeX4C/Qbi5l6kQWHaGz9IRC+Rb5I2+F8+fOGIsFfFT4HFsohoQuzgtuOgpGwiX+uqNsH2CK5o11sh8AZNqyn4zb7lqTP3lM1et2V69ZXh8JZvkRY8oF3y/Cre4bY8gUXJ0A9czev6kh33aVexcXQvo4dUgA5t1HalgQwGVeEzvC9ukClq1G3Wzm9taWag3Ih7S6r64DAM1brbr3mzoDiEBB5CVT7YRu4CBVac8Hnxr6BwzQjLLFsNQKdczZ8ghnq/cPmbZ1oQlcGUfkBhct8e6VqLFDYToMQooRrN5kxtWiJXjrggGJuQi+N4A7hf3kQUV6CNo9RYRAUkpzNCMzRCf04jnK4rFuEiUXVsgr0v1m47oip+Q8yI422g/wby5FP2W6lvVvgujOL69AIW47EJ3XFO+0FeK6yS/UGf6fHbc+HsJSdJXlwZBYrjd/jf6hgOyGWfr5RQfj0xwQRGHJ5IXGWPXQc7p19QGA2mQI6U5wD6xYyHmMBAshmE/7Cx8sQzQ+FNi3QWfpn7huttp+j28s/5pDqy4aSEHvY7fpdiah940T22zLyB1A0nM0x9mVwOK7HPtyO4daG9O1bQPI7hPPdLv8sQkQcMdcoDqXRIeyATlgfE+dzDaLBQeMh/CWi0/WBzOdAZGaTwDlIE2YNc32vtPY/vwh8EMnnyFsHZfe6d8WsX5SuioPCEvR+p5k6Xr+8QfVvkeKK6gYqp92jDPCJoJM9PhBjL+dxiMyJ4r9m8Py3+39XnQQmgvxWFH5oNvyp22eWQnHfSP1rETF32ZAyb8hdArBCPyYyowkO0Ddv0hG8yHquiQJT0mOVr1tp9hBkZm4POE+44nyUnK4+1UXoXMAc26teN5KqR7zdxll3PGQ=,iv:EEqBs95xzcU49EzGCvc5/QLK1NK5bpudoxj1nE10rX4=,tag:XNVeFJ9EBs2tSWA8DSASmw==,type:str]
 sops:
     age:
         - recipient: age149fqcw5jze00vd7jauylrp4j5xyv7amlu57jjfuzghkqtzlnxajs704uz3
@@ -31,7 +32,7 @@ sops:
             SGRyL01ISlltVG5YdWw4dWV0RGpPNEEK855vVFGwxgBrl0scAla980fd3XSiUjfP
             ULMGGQK06z1Oh6+bvPyfzbILjFkzlrel06yajpcvdSQgJZXpzQgJUA==
             -----END AGE ENCRYPTED FILE-----
-    lastmodified: "2026-05-01T05:37:38Z"
-    mac: ENC[AES256_GCM,data:J5z5bZgQhkIkH4RaA5c74IsKiFgES7XDEqq0lmq/VaopOAhHAD6Lzi4v2jY2CtZkFLdtbEw/8nGGrEmFNonYNqSNOnWCkDfr5jQXk5uT+HGKUsKNOjqSZRs9xpF3LJKpSMZ9LlpzFbfEEv5JMJk74GXPodMTPWHYwTKsA7mHh4M=,iv:z7X7fJcZ2mXDaSNcb77VdjqeHihL0xzHrtbL7/ShIN4=,tag:7YlyBZ3Ro69qVVOG4OSnxw==,type:str]
+    lastmodified: "2026-05-01T06:43:39Z"
+    mac: ENC[AES256_GCM,data:crNd+yzqNJ8cpm//xeZtgRHgHjcWFQLetnDfMxQh26PZvx07daH6L3L9eVROr5pHZqfQQa0iNSA1wmp5LEIKyrVSW4AkV/btW1oXWBTBoEFLxeB7y76TgBiBZD0CvpkiQbZdAOclbNJ2LZAeIRauBurEWvgi0fv31dYB4zAHrm4=,iv:XmpzC58A7Mh42n3Gt2cJNC10NBWhT/c6WdLoKuEL1x0=,tag:l3Tl/Cw/Xg3zqBjInqHQmA==,type:str]
     unencrypted_suffix: _unencrypted
     version: 3.12.1

From 74af9fd5acd71a9c403a2a7293fb7f68aa6be6e8 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Sun, 26 Apr 2026 20:58:10 +0200
Subject: [PATCH 014/101] wip(sgx): firefly-sparda-fetch service + timer
 (DISABLED)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

End-to-end FinTS pipeline against Sparda Südwest is wired up but
disabled — aqbanking 6.8.2's `-P pinfile` flag does not consume the
file content correctly on this build (verified: pinfile bytes match
the manually-typed PIN exactly, yet the bank receives a wrong PIN).
Three rejected attempts locked the access at Sparda; do not re-arm
the timer until the auth path is replaced (likely python-fints).

What works:
- aqbanking config and FinTS dialog (manual PIN entry)
- getaccsepa workaround for HKCAZ "Mussfeld 9160" rejection
- custom CSV profile (decimal amounts + IBAN columns) wired in
- Firefly importer auto-upload settings + sops secret slot
- inbox + profile-symlink tmpfiles

What's broken:
- Headless PIN delivery via aqbanking-cli -P
- Timer left wantedBy=[] so it cannot fire post-deploy

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 systems/x86_64-linux/sgx/firefly.nix | 116 +++++++++++++++++++++++++--
 1 file changed, 110 insertions(+), 6 deletions(-)

diff --git a/systems/x86_64-linux/sgx/firefly.nix b/systems/x86_64-linux/sgx/firefly.nix
index 8a077b7..44c412f 100644
--- a/systems/x86_64-linux/sgx/firefly.nix
+++ b/systems/x86_64-linux/sgx/firefly.nix
@@ -2,8 +2,24 @@
 let
   domain = "firefly.hoyer.world";
   importDomain = "firefly-import.hoyer.world";
-  aqHome = "/var/lib/firefly-aqbanking";
-  inbox = "/var/lib/firefly-iii-data-importer/inbox";
+  importerHome = "/var/lib/firefly-iii-data-importer";
+  inbox = "${importerHome}/inbox";
+  configFile = "${importerHome}/sparda-config.json";
+
+  bankCode = "55090500";
+  userId = "5987838198";
+  giroAccountId = "3";
+
+  # aqbanking 6.8.2 ships only an "import" profile and a "full" export
+  # profile that renders amounts as fractions ("-499/100"). Firefly's CSV
+  # importer needs decimal amounts and benefits from localIban/remoteIban
+  # columns, so derive a profile that combines "full"'s columns with
+  # decimal value formatting.
+  fireflyCsvProfile = pkgs.runCommand "aqbanking-csv-firefly-profile" { } ''
+    sed 's/name="full"/name="firefly"/; s/valueFormat="rational"/valueFormat="float"/' \
+      ${pkgs.aqbanking}/share/aqbanking/imexporters/csv/profiles/full.conf > $out
+  '';
+
   vhostBase = {
     enableACME = false;
     useACMEHost = "internal.hoyer.world";
@@ -20,14 +36,97 @@ in
       sopsFile = ../../../.secrets/sgx/firefly.yaml;
       owner = "firefly-iii-data-importer";
     };
+    "firefly/auto_import_secret" = {
+      sopsFile = ../../../.secrets/sgx/firefly.yaml;
+      owner = "firefly-iii-data-importer";
+    };
   };
 
   environment.systemPackages = [ pkgs.aqbanking ];
 
-  systemd.tmpfiles.rules = [
-    "d ${aqHome} 0700 firefly-iii-data-importer firefly-iii-data-importer -"
-    "d ${inbox}  0700 firefly-iii-data-importer firefly-iii-data-importer -"
-  ];
+  systemd = {
+    tmpfiles.rules = [
+      "d ${inbox} 0700 firefly-iii-data-importer nginx -"
+      "d ${importerHome}/.aqbanking/imexporters/csv/profiles 0700 firefly-iii-data-importer nginx -"
+      "L+ ${importerHome}/.aqbanking/imexporters/csv/profiles/firefly.conf - - - - ${fireflyCsvProfile}"
+    ];
+
+    services.firefly-sparda-fetch = {
+      description = "Fetch Sparda transactions via FinTS and trigger Firefly auto-import";
+      after = [
+        "network-online.target"
+        "phpfpm-firefly-iii-data-importer.service"
+      ];
+      wants = [ "network-online.target" ];
+      path = with pkgs; [
+        aqbanking
+        curl
+        coreutils
+      ];
+
+      serviceConfig = {
+        Type = "oneshot";
+        User = "firefly-iii-data-importer";
+        Group = "nginx";
+        RuntimeDirectory = "firefly-sparda-fetch";
+        LoadCredential = [
+          "pin:${config.sops.secrets."firefly/sparda_pin".path}"
+          "secret:${config.sops.secrets."firefly/auto_import_secret".path}"
+        ];
+        ProtectSystem = "strict";
+        ReadWritePaths = [ importerHome ];
+        ProtectHome = true;
+        PrivateTmp = true;
+        NoNewPrivileges = true;
+        TimeoutStartSec = "3min";
+      };
+
+      script = ''
+        set -euo pipefail
+
+        pinfile=$RUNTIME_DIRECTORY/pinfile
+        umask 077
+        printf 'PIN_%s_%s = "%s"\n' "${bankCode}" "${userId}" \
+          "$(<"$CREDENTIALS_DIRECTORY/pin")" >"$pinfile"
+
+        ts=$(date +%Y%m%d-%H%M%S)
+        ctx=$RUNTIME_DIRECTORY/ctx-$ts.aqb
+        out=${inbox}/sparda-$ts.csv
+
+        # Refresh SEPA account list — Atruvia/Sparda rejects HKCAZ
+        # ("Mussfeld 9160") if this metadata isn't fresh in the dialog.
+        aqhbci-tool4 -n -A -P "$pinfile" getaccsepa -u ${giroAccountId}
+
+        fromdate=$(date --date='35 days ago' +%Y%m%d)
+        aqbanking-cli -n -A -P "$pinfile" request \
+          --transactions --fromdate="$fromdate" \
+          --aid=${giroAccountId} -c "$ctx"
+
+        aqbanking-cli export \
+          --exporter=csv --profile=firefly \
+          -c "$ctx" -o "$out"
+
+        secret=$(<"$CREDENTIALS_DIRECTORY/secret")
+        curl -fsS -X POST \
+          "https://${importDomain}/autoupload?secret=$secret" \
+          -F "json=@${configFile}" \
+          -F "importable=@$out"
+      '';
+    };
+
+    # Timer disabled while we work around aqbanking 6.8.2's broken
+    # `-P pinfile` handling. The fetch service authenticates with a wrong
+    # PIN against the bank — three runs locked the access at Sparda. Do
+    # not re-enable until the auth path is replaced (likely python-fints).
+    timers.firefly-sparda-fetch = {
+      wantedBy = [ ];
+      timerConfig = {
+        OnCalendar = "daily";
+        Persistent = true;
+        RandomizedDelaySec = "1h";
+      };
+    };
+  };
 
   services = {
     firefly-iii = {
@@ -54,6 +153,10 @@ in
         FIREFLY_III_URL = "https://${domain}";
         VANITY_URL = "https://${importDomain}";
         TZ = "Europe/Berlin";
+        CAN_POST_FILES = "true";
+        CAN_POST_AUTOIMPORT = "true";
+        IMPORT_DIR_ALLOWLIST = inbox;
+        AUTO_IMPORT_SECRET_FILE = config.sops.secrets."firefly/auto_import_secret".path;
       };
     };
 
@@ -62,4 +165,5 @@ in
       ${importDomain} = vhostBase;
     };
   };
+
 }

From e0d2a2f50da9391ee85354cd20342e7c997f5b23 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Fri, 1 May 2026 18:58:45 +0200
Subject: [PATCH 015/101] =?UTF-8?q?feat(sgx):=20finish=20firefly-sparda-fe?=
 =?UTF-8?q?tch=20=E2=80=94=20headless=20FinTS=20import?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

End-to-end verified: aqbanking-cli fetches Sparda Südwest transactions
via FinTS PIN/TAN + SecureGo+, exports CSV using a custom decimal-amount
profile, POSTs to firefly-iii-data-importer's autoupload endpoint, which
creates transactions in Firefly III via API.

Changes vs. previous WIP commit:
- firefly/access_token sops slot for the importer's Firefly III API auth
  (FIREFLY_III_ACCESS_TOKEN_FILE — was the missing piece causing 401s
  from the API after the autoupload secret authenticated)
- nginx fastcgi_read_timeout=600s on the importer vhost (prevents 504
  while PHP-FPM is still processing the batch)
- PHP-FPM max_execution_time=600s + memory_limit=512M on the importer
  pool (PHP's stock 30s aborts mid-import for batches > ~50 transactions)
- timer re-enabled, wantedBy=[timers.target]

Caveats baked into a code comment:
- Sparda online-banking PIN must be [A-Za-z0-9] only. aqbanking 6.8.2's
  -P pinfile mangles `:`, `+`, `'`, `?`, `@`, `%`, `*`; bank locks the
  access (3 soft / 9 hard strikes) on rejected attempts. Same applies
  whenever the sops secret is rotated.
- Bulk historical imports beyond the PSD2 90-day window need interactive
  SCA approval per ~30-day chunk and cannot run from the timer; the
  daily 35-day rolling window stays inside the no-SCA region.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 systems/x86_64-linux/sgx/firefly.nix | 32 ++++++++++++++++++++++------
 1 file changed, 26 insertions(+), 6 deletions(-)

diff --git a/systems/x86_64-linux/sgx/firefly.nix b/systems/x86_64-linux/sgx/firefly.nix
index 44c412f..9eb7000 100644
--- a/systems/x86_64-linux/sgx/firefly.nix
+++ b/systems/x86_64-linux/sgx/firefly.nix
@@ -40,6 +40,10 @@ in
       sopsFile = ../../../.secrets/sgx/firefly.yaml;
       owner = "firefly-iii-data-importer";
     };
+    "firefly/access_token" = {
+      sopsFile = ../../../.secrets/sgx/firefly.yaml;
+      owner = "firefly-iii-data-importer";
+    };
   };
 
   environment.systemPackages = [ pkgs.aqbanking ];
@@ -114,12 +118,13 @@ in
       '';
     };
 
-    # Timer disabled while we work around aqbanking 6.8.2's broken
-    # `-P pinfile` handling. The fetch service authenticates with a wrong
-    # PIN against the bank — three runs locked the access at Sparda. Do
-    # not re-enable until the auth path is replaced (likely python-fints).
+    # Sparda online-banking PIN must contain only [A-Za-z0-9] — special
+    # chars (`:`, `+`, `'`, `?`, `@`, `%`, `*`) get mangled by aqbanking
+    # 6.8.2's pinfile path and the bank locks the access after a few
+    # rejected attempts (3 soft / 9 hard). Same applies if the secret in
+    # sops is rotated.
     timers.firefly-sparda-fetch = {
-      wantedBy = [ ];
+      wantedBy = [ "timers.target" ];
       timerConfig = {
         OnCalendar = "daily";
         Persistent = true;
@@ -157,12 +162,27 @@ in
         CAN_POST_AUTOIMPORT = "true";
         IMPORT_DIR_ALLOWLIST = inbox;
         AUTO_IMPORT_SECRET_FILE = config.sops.secrets."firefly/auto_import_secret".path;
+        FIREFLY_III_ACCESS_TOKEN_FILE = config.sops.secrets."firefly/access_token".path;
       };
     };
 
     nginx.virtualHosts = {
       ${domain} = vhostBase;
-      ${importDomain} = vhostBase;
+      # Importer's autoupload endpoint blocks until the entire batch
+      # finishes — POSTing 100+ transactions takes minutes. Default 60s
+      # fastcgi timeout makes nginx 504 even though PHP-FPM keeps going.
+      ${importDomain} = vhostBase // {
+        extraConfig = ''
+          fastcgi_read_timeout 600s;
+        '';
+      };
+    };
+
+    # PHP's stock max_execution_time = 30s aborts large bulk imports
+    # mid-stream. Match the nginx fastcgi_read_timeout above.
+    phpfpm.pools.firefly-iii-data-importer.settings = {
+      "php_admin_value[max_execution_time]" = "600";
+      "php_admin_value[memory_limit]" = "512M";
     };
   };
 

From 81b9d2208c522c067bce3161a532cdd9d652b32d Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Fri, 1 May 2026 19:30:17 +0200
Subject: [PATCH 016/101] chore: secret update

---
 .secrets/sgx/firefly.yaml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/.secrets/sgx/firefly.yaml b/.secrets/sgx/firefly.yaml
index 33a31a5..aea372e 100644
--- a/.secrets/sgx/firefly.yaml
+++ b/.secrets/sgx/firefly.yaml
@@ -2,7 +2,7 @@ firefly:
     app_key: ENC[AES256_GCM,data:0BHC54xXb7EJcFBuGWFiDfIh7ZBgVs1R+1GGztOwte4CeD4Olz31umq1At1aRFESLkoC,iv:e3On3x9eSKTo9+SEp/ujFZA0a6o2slqT+atPhd1PDMM=,tag:k2pjyvgM8AcElBBOR95dwg==,type:str]
     sparda_pin: ENC[AES256_GCM,data:mEa7vQuXWWHfpITojTyxjEZOPck=,iv:gkMlAi27AACHWC0MaXeUeP8BBZF/0vshDJrg67GP0ho=,tag:CIo70Iu+R6KNj0eFu8XxAg==,type:str]
     auto_import_secret: ENC[AES256_GCM,data:7JcxrIu4tRDgVhcUBoc/u2xN6NxRutKsTbvN8kr/u54BJ+fuZ94EVtDc9B1ZnTLuPb5LStbLnHFcLs17ocpk7g==,iv:DcilcMGEQgJ4hwuJJ2cF3Hdyy85QFpwHjlFwbFEwsAE=,tag:4+KPk7OJ61xngpBmAitlEA==,type:str]
-    access_token: ENC[AES256_GCM,data:zxS95MlpwrqdhhQtVPgCknf0yVJHeLkswDegEYQPwUqpOMYDST/OVkUIzkKyNbEN8gS11i5WY7jPfTUi5yRYy4pPs9stz1XJ//c9LgAUMkP9W6XHL6ykcLpaG6EU3+UHFYlfZImFFGxNrqqIBspdCo9dGpQVLY2t46nSF+xhh29uUDXGkUZL5FeQFSMP09l9QkzBumUNuGhhfMtZNMOhXMvaS7s2ghaTqA2C1biqmeWX7leum6jjzUyoBMLGsFfVLYFhW2dfgPvvURIIIIxMM9tzvnCrNIczZkbzmuXpDn81KE7eYGYf4/0yvUhqzENcpplTiDTdVrQQK0tozJFO96D31iKf/kU29XRrxJJanwDBMychGYVtS2ba42mxwz+Zpca0yPxhYexb7OcjNkmuN1Kge0upd4+C/alshzEAWAAQCeX4C/Qbi5l6kQWHaGz9IRC+Rb5I2+F8+fOGIsFfFT4HFsohoQuzgtuOgpGwiX+uqNsH2CK5o11sh8AZNqyn4zb7lqTP3lM1et2V69ZXh8JZvkRY8oF3y/Cre4bY8gUXJ0A9czev6kh33aVexcXQvo4dUgA5t1HalgQwGVeEzvC9ukClq1G3Wzm9taWag3Ih7S6r64DAM1brbr3mzoDiEBB5CVT7YRu4CBVac8Hnxr6BwzQjLLFsNQKdczZ8ghnq/cPmbZ1oQlcGUfkBhct8e6VqLFDYToMQooRrN5kxtWiJXjrggGJuQi+N4A7hf3kQUV6CNo9RYRAUkpzNCMzRCf04jnK4rFuEiUXVsgr0v1m47oip+Q8yI422g/wby5FP2W6lvVvgujOL69AIW47EJ3XFO+0FeK6yS/UGf6fHbc+HsJSdJXlwZBYrjd/jf6hgOyGWfr5RQfj0xwQRGHJ5IXGWPXQc7p19QGA2mQI6U5wD6xYyHmMBAshmE/7Cx8sQzQ+FNi3QWfpn7huttp+j28s/5pDqy4aSEHvY7fpdiah940T22zLyB1A0nM0x9mVwOK7HPtyO4daG9O1bQPI7hPPdLv8sQkQcMdcoDqXRIeyATlgfE+dzDaLBQeMh/CWi0/WBzOdAZGaTwDlIE2YNc32vtPY/vwh8EMnnyFsHZfe6d8WsX5SuioPCEvR+p5k6Xr+8QfVvkeKK6gYqp92jDPCJoJM9PhBjL+dxiMyJ4r9m8Py3+39XnQQmgvxWFH5oNvyp22eWQnHfSP1rETF32ZAyb8hdArBCPyYyowkO0Ddv0hG8yHquiQJT0mOVr1tp9hBkZm4POE+44nyUnK4+1UXoXMAc26teN5KqR7zdxll3PGQ=,iv:EEqBs95xzcU49EzGCvc5/QLK1NK5bpudoxj1nE10rX4=,tag:XNVeFJ9EBs2tSWA8DSASmw==,type:str]
+    access_token: ENC[AES256_GCM,data:SOOPwYWw7ZxqLzt4Mg8/Acs37IF04EkeUukEwOyfgRpdD9uwpKEMM8MF+XzdT0WNYIR3rCn9jwuGAxISkzdSEGFSQsYLUb2zENOfWjT8I7WJXFVvoQnOr3r7Jq4yy+rqMatL98C6fkD6BpxPtMtiP3eO6e3vioKeBmkKgzNx+XusSXSFiARJdZgDZ6+G+F6YxMchzMueLagbHHFKY5SBNbxE5AdrDbgysXe9gzwcIz/FYi1V/agvYLUMNFFxzRz7vRzTyd23BqqR0eM3JK10/K9FMtLpYF7OPZZK/AGewv+p+1rOSbXkbTASXSIGhWovZz9hIwBU+TwW/1AnZK8Ju8j0pSI1HM60KA9PFfypeu2BgBKVZp8egoZdLyOviBOhJnYoPMK7jw3g9UyVNKZedblXcobOSg+Dn/3kWEV7w9zMoMPJ0dGNWKDRrx55v703gJKAGSSYMW9+a46rgV9as/WpaDKE7q+hJXRCf4gl6eyYoKH2pLmRjuhFSWMbfBrH+cEYiBp8HqlUkWWFvS41bA+6EoVuRaa6/Vh3lU/uBiz53iQ8+bSUN1EcA/bxZtIfA5TLNVi4RyhC7zRnEjYMg/2fNhAUZjsCd3o90etb8YJLbqBUFSxxknkZ3vhx+Lz/WjtYztkuA2GkECeUXzZAczHTao4dxQqQsaj8jbQh3Z6U429VZ1POIMrettWJ6hJCnTSMeC3EcPoCqpbe5Pz5tHe0SHALafKEYXEnWAMJ5ATLCnNBPDfHDrO0G/JjWLqreoXsdoF4EPBMku4U2ZSPtfj6UtGFhzi7qYs4pB9LPFccbNScnVvCWfCzdcFxEeDgsdtXgoQ9SsMa+3NI2wvTHdAbPBp7z7BK96dyDn6yAlY0DjaGIyBlTSsgC2wumuNn/QJ3MGI3ZJTorRZC+JDN6jCn6wMSNirRqf3Mmz+T2+zeLyrtiWMuyUB+d26/AvwYFiT1l9rf8KhFMG16hWDOxDxnXbpUBsVcu5L+pJEE3LWB4sm41/lWQ+WaRq3eII7KWxHhJPbIw7b5o37yqAoCLdC/2sCRK5sdPepBcuw2xVHSdPEIdg5ZHsXKlqAXmnRPWjsRlFXBytMyivr1Gbmay76UOskdEzW1022avvNMZforW79TSK3NJHCU2qBUz7+hEiWlsIbX16fYZrzy0zYUBtrfVOTzfs2zWG9rxAWuqw8mF1bo5K89zzDzQZk6YbYyk5fkWs3QefE23eOUqL16Ys0D9fuRjKU9ZFXglHNJYaxQU95xKwEpuN29OeL4dVfdz3w1WPv8NjsutR64MCu/6oii6Do=,iv:xEpiIvFt1OfViP79cJDJ5lugU6Dfs0u/EyjEMLmuom0=,tag:cHXRsj9xEiPPfrnhLpod2w==,type:str]
 sops:
     age:
         - recipient: age149fqcw5jze00vd7jauylrp4j5xyv7amlu57jjfuzghkqtzlnxajs704uz3
@@ -32,7 +32,7 @@ sops:
             SGRyL01ISlltVG5YdWw4dWV0RGpPNEEK855vVFGwxgBrl0scAla980fd3XSiUjfP
             ULMGGQK06z1Oh6+bvPyfzbILjFkzlrel06yajpcvdSQgJZXpzQgJUA==
             -----END AGE ENCRYPTED FILE-----
-    lastmodified: "2026-05-01T06:43:39Z"
-    mac: ENC[AES256_GCM,data:crNd+yzqNJ8cpm//xeZtgRHgHjcWFQLetnDfMxQh26PZvx07daH6L3L9eVROr5pHZqfQQa0iNSA1wmp5LEIKyrVSW4AkV/btW1oXWBTBoEFLxeB7y76TgBiBZD0CvpkiQbZdAOclbNJ2LZAeIRauBurEWvgi0fv31dYB4zAHrm4=,iv:XmpzC58A7Mh42n3Gt2cJNC10NBWhT/c6WdLoKuEL1x0=,tag:l3Tl/Cw/Xg3zqBjInqHQmA==,type:str]
+    lastmodified: "2026-05-01T17:30:13Z"
+    mac: ENC[AES256_GCM,data:LT1kOTEnjB9p5hUl5h3vLFuZ+K+hUaail3yeVnqtTZnkIeSsl6h/R2A1cuRaNTgpVdTRdlYzKlza2V6kdME1x3WXMBRJIrRVwnRhFbSzyckhYu4C5L2dDM+C2OxTJD7gsjhDYHzlCCtyD9u6eGgUN32gEnT0DVhL6C0MHH0vip0=,iv:4ZEwcLXu8dpCRwV8ZM6icUh30UxH35aHMO3ZrqMk9IU=,tag:2GjzhJZuHDwE3NPRLbv0QA==,type:str]
     unencrypted_suffix: _unencrypted
     version: 3.12.1

From c1503b56aa1e6e61ccb30e129a823fd2a03d614d Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Fri, 1 May 2026 19:31:07 +0200
Subject: [PATCH 017/101] sgx/firefly: disable btrfs CoW on Firefly III sqlite
 directory

Random-write SQLite traffic fragments CoW filesystems quickly. The `h`
tmpfiles directive sets +C on the database directory; new SQLite files
(WAL, SHM, recreated main DB) inherit no-CoW automatically. No-op on
non-btrfs filesystems.

Migration of existing files must be done manually with checkpoint-first:
  systemctl stop phpfpm-firefly-iii.service
  sqlite3 .../database.sqlite 'PRAGMA wal_checkpoint(TRUNCATE);'
  # then recreate main file inside the +C dir
  systemctl start phpfpm-firefly-iii.service

Skipping the wal_checkpoint and naively deleting .sqlite-wal will lose
all writes that haven't been checkpointed (PHP-FPM SIGTERM does not
trigger a checkpoint).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 systems/x86_64-linux/sgx/firefly.nix | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/systems/x86_64-linux/sgx/firefly.nix b/systems/x86_64-linux/sgx/firefly.nix
index 9eb7000..7b03607 100644
--- a/systems/x86_64-linux/sgx/firefly.nix
+++ b/systems/x86_64-linux/sgx/firefly.nix
@@ -53,6 +53,12 @@ in
       "d ${inbox} 0700 firefly-iii-data-importer nginx -"
       "d ${importerHome}/.aqbanking/imexporters/csv/profiles 0700 firefly-iii-data-importer nginx -"
       "L+ ${importerHome}/.aqbanking/imexporters/csv/profiles/firefly.conf - - - - ${fireflyCsvProfile}"
+      # Disable btrfs CoW on Firefly's SQLite directory — random-write
+      # SQLite traffic fragments CoW filesystems quickly. New files in
+      # this dir inherit the +C attribute. Existing database.sqlite,
+      # -wal, -shm need a one-time recreate to apply (use sqlite3 .backup
+      # into a fresh +C file). No-op on non-btrfs filesystems.
+      "h /var/lib/firefly-iii/storage/database - - - - +C"
     ];
 
     services.firefly-sparda-fetch = {

From 90324605b99f11952f397f8ce8d269a3d18af07b Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Fri, 1 May 2026 21:48:15 +0200
Subject: [PATCH 018/101] chore: update secret

---
 .secrets/sgx/firefly.yaml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/.secrets/sgx/firefly.yaml b/.secrets/sgx/firefly.yaml
index aea372e..aa7eb7f 100644
--- a/.secrets/sgx/firefly.yaml
+++ b/.secrets/sgx/firefly.yaml
@@ -2,7 +2,7 @@ firefly:
     app_key: ENC[AES256_GCM,data:0BHC54xXb7EJcFBuGWFiDfIh7ZBgVs1R+1GGztOwte4CeD4Olz31umq1At1aRFESLkoC,iv:e3On3x9eSKTo9+SEp/ujFZA0a6o2slqT+atPhd1PDMM=,tag:k2pjyvgM8AcElBBOR95dwg==,type:str]
     sparda_pin: ENC[AES256_GCM,data:mEa7vQuXWWHfpITojTyxjEZOPck=,iv:gkMlAi27AACHWC0MaXeUeP8BBZF/0vshDJrg67GP0ho=,tag:CIo70Iu+R6KNj0eFu8XxAg==,type:str]
     auto_import_secret: ENC[AES256_GCM,data:7JcxrIu4tRDgVhcUBoc/u2xN6NxRutKsTbvN8kr/u54BJ+fuZ94EVtDc9B1ZnTLuPb5LStbLnHFcLs17ocpk7g==,iv:DcilcMGEQgJ4hwuJJ2cF3Hdyy85QFpwHjlFwbFEwsAE=,tag:4+KPk7OJ61xngpBmAitlEA==,type:str]
-    access_token: ENC[AES256_GCM,data:SOOPwYWw7ZxqLzt4Mg8/Acs37IF04EkeUukEwOyfgRpdD9uwpKEMM8MF+XzdT0WNYIR3rCn9jwuGAxISkzdSEGFSQsYLUb2zENOfWjT8I7WJXFVvoQnOr3r7Jq4yy+rqMatL98C6fkD6BpxPtMtiP3eO6e3vioKeBmkKgzNx+XusSXSFiARJdZgDZ6+G+F6YxMchzMueLagbHHFKY5SBNbxE5AdrDbgysXe9gzwcIz/FYi1V/agvYLUMNFFxzRz7vRzTyd23BqqR0eM3JK10/K9FMtLpYF7OPZZK/AGewv+p+1rOSbXkbTASXSIGhWovZz9hIwBU+TwW/1AnZK8Ju8j0pSI1HM60KA9PFfypeu2BgBKVZp8egoZdLyOviBOhJnYoPMK7jw3g9UyVNKZedblXcobOSg+Dn/3kWEV7w9zMoMPJ0dGNWKDRrx55v703gJKAGSSYMW9+a46rgV9as/WpaDKE7q+hJXRCf4gl6eyYoKH2pLmRjuhFSWMbfBrH+cEYiBp8HqlUkWWFvS41bA+6EoVuRaa6/Vh3lU/uBiz53iQ8+bSUN1EcA/bxZtIfA5TLNVi4RyhC7zRnEjYMg/2fNhAUZjsCd3o90etb8YJLbqBUFSxxknkZ3vhx+Lz/WjtYztkuA2GkECeUXzZAczHTao4dxQqQsaj8jbQh3Z6U429VZ1POIMrettWJ6hJCnTSMeC3EcPoCqpbe5Pz5tHe0SHALafKEYXEnWAMJ5ATLCnNBPDfHDrO0G/JjWLqreoXsdoF4EPBMku4U2ZSPtfj6UtGFhzi7qYs4pB9LPFccbNScnVvCWfCzdcFxEeDgsdtXgoQ9SsMa+3NI2wvTHdAbPBp7z7BK96dyDn6yAlY0DjaGIyBlTSsgC2wumuNn/QJ3MGI3ZJTorRZC+JDN6jCn6wMSNirRqf3Mmz+T2+zeLyrtiWMuyUB+d26/AvwYFiT1l9rf8KhFMG16hWDOxDxnXbpUBsVcu5L+pJEE3LWB4sm41/lWQ+WaRq3eII7KWxHhJPbIw7b5o37yqAoCLdC/2sCRK5sdPepBcuw2xVHSdPEIdg5ZHsXKlqAXmnRPWjsRlFXBytMyivr1Gbmay76UOskdEzW1022avvNMZforW79TSK3NJHCU2qBUz7+hEiWlsIbX16fYZrzy0zYUBtrfVOTzfs2zWG9rxAWuqw8mF1bo5K89zzDzQZk6YbYyk5fkWs3QefE23eOUqL16Ys0D9fuRjKU9ZFXglHNJYaxQU95xKwEpuN29OeL4dVfdz3w1WPv8NjsutR64MCu/6oii6Do=,iv:xEpiIvFt1OfViP79cJDJ5lugU6Dfs0u/EyjEMLmuom0=,tag:cHXRsj9xEiPPfrnhLpod2w==,type:str]
+    access_token: ENC[AES256_GCM,data:+vvAxVJHuDxrGoLCnKVXCVZHZiyVgVC/6WZgHa/mx9AkRUR2i8inZZfzdGw2z/3Mkp4syPWh6eEDK8Yd3MYiKOqLI/Hr3wifXZJxXd9esd+ctQWI7dc3+b1fy/5rLHkf7aAI5nHdSkjfdyT+I4QTcWhavx5E4aTIosYehP/Ww0UUSWrgOYfCy9iQIeO28prMjK/qEqxkil0fk61YoHSopcvihZoJrvBuF92z1wWmtw63mmrLgTFZHGS5GMDSfsq/ixrSpd+5o4xOon3qUeCTNdAOKWaokKSn8YR3FZWLWaUAFdX0HqffU8kuPquzySlzC19lXsyY0YxhFQmZiRP1zIYAUzJcS6m9k9aAR1Z9aJoiHqyvJ23BvJnUAGDJVUAfqlHKELvYW1kWhjJzon6Aug4afbUtgu0EoIWVH/f7Wdtq9nflrtodr3giEYMxSiNsiH0s7pR2+fP2dkrXRoeGWKQv5ihpgR6QSU8CDg0a70RgRLB8ZIQw2yhDqzIoryMYvlThjQUT1ohGYu2bNZZsDvACMdLRefhWtQxvTbIhngvkFe3lTcOO0pjo3RlhUYFQc7FkqpIJ9lo36iiqAgtjBZCIboQq4lZ8ePjHCB2ix08YzFBolfIfwH3mmy0rWyqLYt0HCynnZ7viYayPfdZk9HrCTVlwBZOTR5A7KpdMlC9pBiMtjH9fVd+cF2Wxk8nobCc4GeyYd6QWHK1uyqvfzmINPdGadnJ5tUcOLM8S1PEzPJCEy0HY9V/QacU66rWW/8S1jcHTBHKxHauQDq+LwMctyjeMfIDIiPXj29PS1l53t65mkorBy7LRGuyikvXGPdUS8PzbhpTvasTPPafMR0VxkNf/QQ4TYpIVKxV6mMwUEerSkug+7kiVAZKrHkay8i0NwJUhy79NiYlCjzFJwwjrsf+EW7AZ2jI/NxM+E/Z9iJ5pgQyK7XqXXZktZz7/VR4ObUgKCsGIN/7DQTEmpsMRrWcHV3D+9SrZdxCTPwx5DvbPtAs/MObf9RVhyzLWLipE3x0baHR7spTV3z9IHpwWoeAdeCO52kVIGVVjxT2g1d+hJU8Rl/tfIYFywfSFDeApfbvbKuqebHyZO1x6PqmXmqsbRmghpnt3xbncAe5ofBwrZMgrAyqDDEXM5W6n1fbv+xV2tBTc7J424uM2OP4OO/juwloPLW3pFA653+s6gFAiLzSolAS1b/EFXNKbai7zCDwO+b/tf3uUQfkoC7kcSZf0onXNawfKZ5bQ/Hyx0VOW7uEPdWx6kmIQqiJEWSmVvh//NO6/3dFOiUI8S1Zk4fc=,iv:q9xkq2icsFwJTmqks4TXrBjXdDfAh+vUWlwsHzcdetA=,tag:zZH/KPF+gDrassu8DfoDOw==,type:str]
 sops:
     age:
         - recipient: age149fqcw5jze00vd7jauylrp4j5xyv7amlu57jjfuzghkqtzlnxajs704uz3
@@ -32,7 +32,7 @@ sops:
             SGRyL01ISlltVG5YdWw4dWV0RGpPNEEK855vVFGwxgBrl0scAla980fd3XSiUjfP
             ULMGGQK06z1Oh6+bvPyfzbILjFkzlrel06yajpcvdSQgJZXpzQgJUA==
             -----END AGE ENCRYPTED FILE-----
-    lastmodified: "2026-05-01T17:30:13Z"
-    mac: ENC[AES256_GCM,data:LT1kOTEnjB9p5hUl5h3vLFuZ+K+hUaail3yeVnqtTZnkIeSsl6h/R2A1cuRaNTgpVdTRdlYzKlza2V6kdME1x3WXMBRJIrRVwnRhFbSzyckhYu4C5L2dDM+C2OxTJD7gsjhDYHzlCCtyD9u6eGgUN32gEnT0DVhL6C0MHH0vip0=,iv:4ZEwcLXu8dpCRwV8ZM6icUh30UxH35aHMO3ZrqMk9IU=,tag:2GjzhJZuHDwE3NPRLbv0QA==,type:str]
+    lastmodified: "2026-05-01T19:48:10Z"
+    mac: ENC[AES256_GCM,data:9C+Jgm8b75EDCrQ9l9cpqNc8iEhNUgOvYlZKnOCpA+xKpOC7bEDovmFJ0WglmuO7DikSM/KXbUXTSmBvGS9tbYDv4zKV2NHtgwKONZmFfzwR6d928NPEnx24cqCa6CfQQP2CUUz7syQ6UMtH5yumvsAZXO8C+gVuS6qxpRpAojM=,iv:mt1cig96pGLDiExb8ohsNK7ihN4kYpXCfp03GMNkZfM=,tag:EPI2qHFzuaCisSA2Cg9TFg==,type:str]
     unencrypted_suffix: _unencrypted
     version: 3.12.1

From 491a7b38e4500108f77b03f4988ca5bcbf1ebd41 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Fri, 1 May 2026 21:44:12 +0200
Subject: [PATCH 019/101] sgx/firefly: switch Firefly III backend from sqlite
 to postgres
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

SQLite was slow under btrfs CoW, and the no-CoW migration path turned
out to be fragile (WAL deletion without checkpoint = data loss). Move
to PostgreSQL on Unix-socket peer auth — no password needed for the
local-host setup, NixOS provisions the database+user declaratively.

Drop the now-unused +C tmpfiles rule on the sqlite directory; the
leftover database.sqlite* files at /var/lib/firefly-iii/storage/database/
are harmless and can be removed manually after switch is verified.

Migration of existing Firefly III data is not preserved by this
commit — fresh-start path: re-register admin, re-issue PAT, re-POST
the bulk CSV through the importer.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 systems/x86_64-linux/sgx/firefly.nix | 22 ++++++++++++++++------
 1 file changed, 16 insertions(+), 6 deletions(-)

diff --git a/systems/x86_64-linux/sgx/firefly.nix b/systems/x86_64-linux/sgx/firefly.nix
index 7b03607..cef398a 100644
--- a/systems/x86_64-linux/sgx/firefly.nix
+++ b/systems/x86_64-linux/sgx/firefly.nix
@@ -53,12 +53,6 @@ in
       "d ${inbox} 0700 firefly-iii-data-importer nginx -"
       "d ${importerHome}/.aqbanking/imexporters/csv/profiles 0700 firefly-iii-data-importer nginx -"
       "L+ ${importerHome}/.aqbanking/imexporters/csv/profiles/firefly.conf - - - - ${fireflyCsvProfile}"
-      # Disable btrfs CoW on Firefly's SQLite directory — random-write
-      # SQLite traffic fragments CoW filesystems quickly. New files in
-      # this dir inherit the +C attribute. Existing database.sqlite,
-      # -wal, -shm need a one-time recreate to apply (use sqlite3 .backup
-      # into a fresh +C file). No-op on non-btrfs filesystems.
-      "h /var/lib/firefly-iii/storage/database - - - - +C"
     ];
 
     services.firefly-sparda-fetch = {
@@ -140,6 +134,17 @@ in
   };
 
   services = {
+    postgresql = {
+      enable = true;
+      ensureDatabases = [ "firefly-iii" ];
+      ensureUsers = [
+        {
+          name = "firefly-iii";
+          ensureDBOwnership = true;
+        }
+      ];
+    };
+
     firefly-iii = {
       enable = true;
       enableNginx = true;
@@ -153,6 +158,11 @@ in
         DEFAULT_LOCALE = "de_DE";
         TRUSTED_PROXIES = "**";
         LOG_CHANNEL = "stack";
+        # PostgreSQL via Unix socket peer auth — no password needed.
+        DB_CONNECTION = "pgsql";
+        DB_HOST = "/run/postgresql";
+        DB_DATABASE = "firefly-iii";
+        DB_USERNAME = "firefly-iii";
       };
     };
 

From 73bf52dbaf04e09e6082cf0b2f002fd852f38048 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Sat, 2 May 2026 16:44:20 +0200
Subject: [PATCH 020/101] sgx/firefly: bump fastcgi_read_timeout + PHP
 max_execution_time on both vhosts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Bulk imports of 100+ transactions per chunk hit the default 60s
fastcgi timeout on the main Firefly III vhost too — not just the
importer endpoint. The importer's per-transaction API call to Firefly's
/api/v1/transactions can take 20+s on a fresh DB without ANALYZE,
which compounds with the 30s PHP max_execution_time cap.

- nginx fastcgi_read_timeout=600s on both `firefly` and `firefly-import`
  vhosts
- php_admin_value[max_execution_time]=600 + memory_limit=512M on both
  PHP-FPM pools
- VANITY_URL on the importer now points to the main Firefly III URL
  (was wrongly pointing at the importer's own domain, breaking
  clickable transaction-show links in importer log messages)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 systems/x86_64-linux/sgx/firefly.nix | 23 +++++++++++++++++------
 1 file changed, 17 insertions(+), 6 deletions(-)

diff --git a/systems/x86_64-linux/sgx/firefly.nix b/systems/x86_64-linux/sgx/firefly.nix
index cef398a..94ad43b 100644
--- a/systems/x86_64-linux/sgx/firefly.nix
+++ b/systems/x86_64-linux/sgx/firefly.nix
@@ -172,7 +172,7 @@ in
       virtualHost = importDomain;
       settings = {
         FIREFLY_III_URL = "https://${domain}";
-        VANITY_URL = "https://${importDomain}";
+        VANITY_URL = "https://${domain}";
         TZ = "Europe/Berlin";
         CAN_POST_FILES = "true";
         CAN_POST_AUTOIMPORT = "true";
@@ -183,10 +183,16 @@ in
     };
 
     nginx.virtualHosts = {
-      ${domain} = vhostBase;
-      # Importer's autoupload endpoint blocks until the entire batch
-      # finishes — POSTing 100+ transactions takes minutes. Default 60s
-      # fastcgi timeout makes nginx 504 even though PHP-FPM keeps going.
+      # Both Firefly III and the importer can take minutes per request
+      # during bulk imports — importer's autoupload endpoint blocks until
+      # the whole batch finishes; main Firefly's API serves long
+      # individual transaction-create calls. Default 60s fastcgi timeout
+      # produces 504s while PHP-FPM keeps processing.
+      ${domain} = vhostBase // {
+        extraConfig = ''
+          fastcgi_read_timeout 600s;
+        '';
+      };
       ${importDomain} = vhostBase // {
         extraConfig = ''
           fastcgi_read_timeout 600s;
@@ -195,11 +201,16 @@ in
     };
 
     # PHP's stock max_execution_time = 30s aborts large bulk imports
-    # mid-stream. Match the nginx fastcgi_read_timeout above.
+    # mid-stream. Match the nginx fastcgi_read_timeout above on both
+    # the importer pool and the main Firefly pool.
     phpfpm.pools.firefly-iii-data-importer.settings = {
       "php_admin_value[max_execution_time]" = "600";
       "php_admin_value[memory_limit]" = "512M";
     };
+    phpfpm.pools.firefly-iii.settings = {
+      "php_admin_value[max_execution_time]" = "600";
+      "php_admin_value[memory_limit]" = "512M";
+    };
   };
 
 }

From e96bf83dfd84c9690864256f840dc8a42a1173eb Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Sun, 3 May 2026 09:00:13 +0200
Subject: [PATCH 021/101] feat(halo): add python313Packages.huggingface-hub

---
 systems/x86_64-linux/halo/default.nix | 1 +
 1 file changed, 1 insertion(+)

diff --git a/systems/x86_64-linux/halo/default.nix b/systems/x86_64-linux/halo/default.nix
index 927c743..9d1c0ce 100644
--- a/systems/x86_64-linux/halo/default.nix
+++ b/systems/x86_64-linux/halo/default.nix
@@ -120,6 +120,7 @@ with lib.metacfg;
     piper-tts
     uv
     llama-cpp-rocm
+    python313Packages.huggingface-hub
   ];
 
 

From b2027bd283c9d115ec50c65a8a0c8085c2decfbb Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Sun, 3 May 2026 13:44:09 +0200
Subject: [PATCH 022/101] sgx/network: open TCP 8000-8999 in firewall

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 systems/x86_64-linux/sgx/network.nix | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/systems/x86_64-linux/sgx/network.nix b/systems/x86_64-linux/sgx/network.nix
index acf37e1..58ab749 100644
--- a/systems/x86_64-linux/sgx/network.nix
+++ b/systems/x86_64-linux/sgx/network.nix
@@ -60,6 +60,12 @@
     22000
     config.services.netatalk.port
   ];
+  networking.firewall.allowedTCPPortRanges = [
+    {
+      from = 8000;
+      to = 8999;
+    }
+  ];
   networking.firewall.allowedUDPPorts = [
     5355
     22000

From c99ea665d4cd354d31b2d58c83e6c2b3b3871de9 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Sun, 3 May 2026 13:47:18 +0200
Subject: [PATCH 023/101] feat(sgx): add opencode

---
 systems/x86_64-linux/sgx/default.nix | 1 +
 1 file changed, 1 insertion(+)

diff --git a/systems/x86_64-linux/sgx/default.nix b/systems/x86_64-linux/sgx/default.nix
index cbc4ecb..5d20468 100644
--- a/systems/x86_64-linux/sgx/default.nix
+++ b/systems/x86_64-linux/sgx/default.nix
@@ -22,6 +22,7 @@
 
   environment.systemPackages = with pkgs; [
     claude-code
+    opencode
   ];
 
   services.tailscale.enable = true;

From c4e6599803c1f9fdf32c608511b921bbafddeb52 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Sun, 3 May 2026 13:49:14 +0200
Subject: [PATCH 024/101] chore: nix flake update

---
 flake.lock | 74 +++++++++++++++++++++++++++---------------------------
 1 file changed, 37 insertions(+), 37 deletions(-)

diff --git a/flake.lock b/flake.lock
index 186f8aa..42cc8f6 100644
--- a/flake.lock
+++ b/flake.lock
@@ -134,11 +134,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1776613567,
-        "narHash": "sha256-gC9Cp5ibBmGD5awCA9z7xy6MW6iJufhazTYJOiGlCUI=",
+        "lastModified": 1777713215,
+        "narHash": "sha256-8GzXDOXckDWwST8TY5DbwYFjdvQLlP7K9CLSVx6iTTo=",
         "owner": "nix-community",
         "repo": "disko",
-        "rev": "32f4236bfc141ae930b5ba2fb604f561fed5219d",
+        "rev": "63b4e7e6cf75307c1d26ac3762b886b5b0247267",
         "type": "github"
       },
       "original": {
@@ -421,11 +421,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1775425411,
-        "narHash": "sha256-KY6HsebJHEe5nHOWP7ur09mb0drGxYSzE3rQxy62rJo=",
+        "lastModified": 1777771528,
+        "narHash": "sha256-YycygK6n7KeW1YCobdFJcORWzkmrvNcp6xT+IovA0d4=",
         "owner": "nix-community",
         "repo": "home-manager",
-        "rev": "0d02ec1d0a05f88ef9e74b516842900c41f0f2fe",
+        "rev": "0585fbf645640973e3398863bbaf3bd1ddce4a51",
         "type": "github"
       },
       "original": {
@@ -454,11 +454,11 @@
     "homebrew-cask": {
       "flake": false,
       "locked": {
-        "lastModified": 1777275723,
-        "narHash": "sha256-7cKFYF/OeD+sVCAg2y78yUyG/8hPYQZ9m9ezybgiZvA=",
+        "lastModified": 1777796563,
+        "narHash": "sha256-AbO+MovPEWCLyKIj60qUWOSqSbJSVoGhF28QnCqxv3A=",
         "owner": "homebrew",
         "repo": "homebrew-cask",
-        "rev": "b277b47b93e11d93b04eb718acb7ae8c5af9d860",
+        "rev": "1e45d507af08e3f0926d93efe8f29f3d8c045f3b",
         "type": "github"
       },
       "original": {
@@ -470,11 +470,11 @@
     "homebrew-core": {
       "flake": false,
       "locked": {
-        "lastModified": 1777274771,
-        "narHash": "sha256-Uhqk0iqLZ8A6fatMGLCv4d7fU+so5tfAjpcJBOtTteE=",
+        "lastModified": 1777805875,
+        "narHash": "sha256-rq9WesmH4dJJl4xnQgBFqj4iGhoG7AOLR39dCdXRDwI=",
         "owner": "homebrew",
         "repo": "homebrew-core",
-        "rev": "3fe25b3ce895a424b894c51b19cb8bb86680bc32",
+        "rev": "a3c27b663b8d8aa257a90b5463a41a6071d7b913",
         "type": "github"
       },
       "original": {
@@ -562,11 +562,11 @@
         "systems": "systems_2"
       },
       "locked": {
-        "lastModified": 1777150561,
-        "narHash": "sha256-YLVqyn6LpFa+h697TmZIk0qVIbe7MxMpL8UTF4K+efA=",
+        "lastModified": 1777478067,
+        "narHash": "sha256-2vZnUuv8fg2sIE6pXgGxZQQ3ZhQW1XE7Sxieg8gK2p4=",
         "owner": "NotAShelf",
         "repo": "nvf",
-        "rev": "5b4f9c63205e5b0ef180a2b0e4cc844111f96fa6",
+        "rev": "13c4ad4b4bb926c22945e2fb8862769fe51f27f1",
         "type": "github"
       },
       "original": {
@@ -595,11 +595,11 @@
     },
     "nixos-hardware": {
       "locked": {
-        "lastModified": 1776983936,
-        "narHash": "sha256-ZOQyNqSvJ8UdrrqU1p7vaFcdL53idK+LOM8oRWEWh6o=",
+        "lastModified": 1777796046,
+        "narHash": "sha256-bEJp/zaQApzynGRaAO62BZSz9tFikKtIHCn2yIA/s7Q=",
         "owner": "NixOS",
         "repo": "nixos-hardware",
-        "rev": "2096f3f411ce46e88a79ae4eafcfc9df8ed41c61",
+        "rev": "eeb02f6e29fc8139c0b15af5ff0fdfdc6d0d3d90",
         "type": "github"
       },
       "original": {
@@ -642,11 +642,11 @@
     },
     "nixpkgs_2": {
       "locked": {
-        "lastModified": 1777077449,
-        "narHash": "sha256-AIiMJiqvGrN4HyLEbKAoCSRRYn0rnlW5VbKNIMIYqm4=",
+        "lastModified": 1777428379,
+        "narHash": "sha256-ypxFOeDz+CqADEQNL72haqGjvZQdBR5Vc7pyx2JDttI=",
         "owner": "nixos",
         "repo": "nixpkgs",
-        "rev": "a4bf06618f0b5ee50f14ed8f0da77d34ecc19160",
+        "rev": "755f5aa91337890c432639c60b6064bb7fe67769",
         "type": "github"
       },
       "original": {
@@ -749,11 +749,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1777259803,
-        "narHash": "sha256-fIb/EoVu/1U0qVrE6qZCJ2WCfprRpywNIAVzKEACIQc=",
+        "lastModified": 1777778183,
+        "narHash": "sha256-Lqv9MZO0XAGcMbXJU+ULBSMD41Pf391uJehylUQKe7Y=",
         "owner": "oxalica",
         "repo": "rust-overlay",
-        "rev": "a6cb2224d975e16b5e67de688c6ad306f7203425",
+        "rev": "dbba5f888c82ef3ce594c451c33ac2474eb80847",
         "type": "github"
       },
       "original": {
@@ -836,11 +836,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1776771786,
-        "narHash": "sha256-DRFGPfFV6hbrfO9a1PH1FkCi7qR5FgjSqsQGGvk1rdI=",
+        "lastModified": 1777338324,
+        "narHash": "sha256-bc+ZZCmOTNq86/svGnw0tVpH7vJaLYvGLLKFYP08Q8E=",
         "owner": "Mic92",
         "repo": "sops-nix",
-        "rev": "bef289e2248991f7afeb95965c82fbcd8ff72598",
+        "rev": "8eaee5c45428b28b8c47a83e4c09dccec5f279b5",
         "type": "github"
       },
       "original": {
@@ -933,11 +933,11 @@
     },
     "unstable": {
       "locked": {
-        "lastModified": 1776877367,
-        "narHash": "sha256-EHq1/OX139R1RvBzOJ0aMRT3xnWyqtHBRUBuO1gFzjI=",
+        "lastModified": 1777578337,
+        "narHash": "sha256-Ad49moKWeXtKBJNy2ebiTQUEgdLyvGmTeykAQ9xM+Z4=",
         "owner": "nixos",
         "repo": "nixpkgs",
-        "rev": "0726a0ecb6d4e08f6adced58726b95db924cef57",
+        "rev": "15f4ee454b1dce334612fa6843b3e05cf546efab",
         "type": "github"
       },
       "original": {
@@ -972,16 +972,16 @@
     "xremap": {
       "flake": false,
       "locked": {
-        "lastModified": 1776689543,
-        "narHash": "sha256-J07iDGltzJg/2r+bUlBaOpZxAhg020J1giqbTZNSDRY=",
+        "lastModified": 1777213346,
+        "narHash": "sha256-VhIdsBRJzPWhEMZCh9WaWQ3rOZxrKcT3ltpijtYiy0s=",
         "owner": "k0kubun",
         "repo": "xremap",
-        "rev": "7d23ea211451019c325c6f33c28ccd4e0d72fb00",
+        "rev": "37666ae7bff437e2c5fb5d77e7521c28ecbfbdcc",
         "type": "github"
       },
       "original": {
         "owner": "k0kubun",
-        "ref": "v0.15.2",
+        "ref": "v0.15.3",
         "repo": "xremap",
         "type": "github"
       }
@@ -994,11 +994,11 @@
         "xremap": "xremap"
       },
       "locked": {
-        "lastModified": 1776699398,
-        "narHash": "sha256-UzfoClPv+lH4/6qeBG2GUPawpa4FrrxAPKESvjqcIY0=",
+        "lastModified": 1777344123,
+        "narHash": "sha256-FORgBEkRc3LOQc23ZFJ8mDvjym9WkCgR97gUBT3tTp0=",
         "owner": "xremap",
         "repo": "nix-flake",
-        "rev": "2961d7191f78961028f999a81343ff0937b7df37",
+        "rev": "69bc1bcdf33da0350cd28b2824b82ccf065a1b4b",
         "type": "github"
       },
       "original": {

From a63abebda3a94c71e61f6335b254a50e8be7d0d9 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Sun, 3 May 2026 14:29:59 +0200
Subject: [PATCH 025/101] =?UTF-8?q?feat(home):=20opencode=20module=20?=
 =?UTF-8?q?=E2=80=94=20link=20config/opencode=20=E2=86=92=20~/.config/open?=
 =?UTF-8?q?code?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds metacfg.cli-apps.opencode (default enabled) which mounts the
in-repo opencode config (provider list, web-search skill) via
xdg.configFile, so all hosts pick it up automatically.
---
 config/opencode/config.json                | 39 ++++++++++
 config/opencode/skills/web-search/SKILL.md | 86 ++++++++++++++++++++++
 modules/home/cli-apps/opencode/default.nix | 23 ++++++
 3 files changed, 148 insertions(+)
 create mode 100644 config/opencode/config.json
 create mode 100644 config/opencode/skills/web-search/SKILL.md
 create mode 100644 modules/home/cli-apps/opencode/default.nix

diff --git a/config/opencode/config.json b/config/opencode/config.json
new file mode 100644
index 0000000..e3ad78e
--- /dev/null
+++ b/config/opencode/config.json
@@ -0,0 +1,39 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "halo-8001": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "Halo (8001)",
+      "options": {
+        "baseURL": "http://halo.fritz.box:8001/v1"
+      },
+      "models": {
+        "unsloth/Qwen3.6-35B-A3B-GGUF:UD-Q8_K_XL": { "name" : "halo 8001" }
+      }
+    },
+    "halo-8000": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "Halo (8000)",
+      "options": {
+        "baseURL": "http://halo.fritz.box:8000/v1"
+      },
+      "models": {
+        "unsloth/gemma-4-26B-A4B-it-GGUF:UD-Q8_K_XL": {
+          "name": "halo 8000"
+        }
+      }
+    },
+    "lmstudio-local": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "LM Studio (local)",
+      "options": {
+        "baseURL": "http://127.0.0.1:1234/v1"
+      },
+      "models": {
+        "qwen3-coder-30b-a3b-instruct-mlx@6bit": {
+          "name": "qwen3-coder-30b-a3b-instruct-mlx@6bit"
+        }
+      }
+    }
+  }
+}
diff --git a/config/opencode/skills/web-search/SKILL.md b/config/opencode/skills/web-search/SKILL.md
new file mode 100644
index 0000000..6a087db
--- /dev/null
+++ b/config/opencode/skills/web-search/SKILL.md
@@ -0,0 +1,86 @@
+---
+name: web-search
+description: Search the web and fetch page content via the user's private SearXNG instance at search.hoyer.world. Use this whenever current information is needed - library docs, error message lookups, recent releases, API references, or any general research that goes beyond training data. Trigger words include "search", "look up", "find docs for", "what's the current", "latest version of". Always prefer this over guessing from memory.
+---
+
+# Web Search via SearXNG
+
+The user runs a private SearXNG instance at `$SEARXNG_URL`
+(default: `https://search.hoyer.world`). Use it for all web research.
+
+Run searches via the `bash` tool. Do NOT attempt MCP or built-in web search.
+
+## Search
+
+```bash
+curl -sfG "${SEARXNG_URL:-https://search.hoyer.world}/search" \
+  --data-urlencode "q=QUERY HERE" \
+  --data-urlencode 'format=json' \
+  --data-urlencode 'language=en' \
+  --data-urlencode 'safesearch=0' \
+  | jq -r '.results[0:8][] | "## \(.title)\n<\(.url)>\n\(.content // "")\n"'
+```
+
+Keep queries short (3–6 words). For follow-ups, increment `pageno` instead of
+re-running the same query:
+
+```bash
+... --data-urlencode 'pageno=2' ...
+```
+
+## Categories
+
+Bias results to relevant engines via `categories`:
+
+| Category   | Use for                                       |
+|------------|-----------------------------------------------|
+| `general`  | default                                       |
+| `it`       | programming, dev tools (GitHub, SO, MDN, …)   |
+| `repos`    | source-code search                            |
+| `news`     | recent events                                 |
+| `science`  | papers, arXiv, PubMed                         |
+
+```bash
+... --data-urlencode 'categories=it' ...
+```
+
+## Time filtering
+
+For "current"/"latest" queries add `time_range=month` or `year` to drop
+stale results:
+
+```bash
+... --data-urlencode 'time_range=year' ...
+```
+
+## Fetching a page
+
+For full content of a result URL, use pandoc via `nix run` (no install needed):
+
+```bash
+curl -sfL --max-time 15 \
+  -H 'User-Agent: Mozilla/5.0' \
+  "$URL" \
+  | nix run nixpkgs#pandoc -- -f html -t gfm --wrap=none 2>/dev/null \
+  | sed -E 's/!\[[^]]*\]\([^)]*\)//g' \
+  | head -c 12000
+```
+
+The first `nix run` invocation may take a few seconds while pandoc is fetched
+into the Nix store; subsequent calls are instant.
+
+For very simple pages where you only want plain text:
+
+```bash
+curl -sfL --max-time 15 -H 'User-Agent: Mozilla/5.0' "$URL" \
+  | nix run nixpkgs#lynx -- -dump -nolist -stdin \
+  | head -c 12000
+```
+
+## Don'ts
+
+- Do not paginate by re-running identical queries — use `pageno`.
+- Do not fetch more than 3 URLs per task without checking with the user first.
+- Do not ignore `time_range` for version- or release-related questions.
+- Do not return raw JSON to the user — always render as the markdown shown above.
+
diff --git a/modules/home/cli-apps/opencode/default.nix b/modules/home/cli-apps/opencode/default.nix
new file mode 100644
index 0000000..8b6fd31
--- /dev/null
+++ b/modules/home/cli-apps/opencode/default.nix
@@ -0,0 +1,23 @@
+{
+  lib,
+  config,
+  ...
+}:
+let
+  inherit (lib) mkIf;
+  inherit (lib.metacfg) mkBoolOpt;
+
+  cfg = config.metacfg.cli-apps.opencode;
+in
+{
+  options.metacfg.cli-apps.opencode = {
+    enable = mkBoolOpt true "Enable opencode config.";
+  };
+
+  config = mkIf cfg.enable {
+    xdg.configFile."opencode" = {
+      source = ../../../../config/opencode;
+      recursive = true;
+    };
+  };
+}

From 38767905afe87a5bf6e4091f1bf69e6f8f1c4be5 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Sun, 3 May 2026 14:57:15 +0200
Subject: [PATCH 026/101] chore: opencode pw

---
 .secrets/sgx/opencode-web.yaml | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)
 create mode 100644 .secrets/sgx/opencode-web.yaml

diff --git a/.secrets/sgx/opencode-web.yaml b/.secrets/sgx/opencode-web.yaml
new file mode 100644
index 0000000..c998b3d
--- /dev/null
+++ b/.secrets/sgx/opencode-web.yaml
@@ -0,0 +1,34 @@
+opencode-web-password: ENC[AES256_GCM,data:5GRYJHf9TSqtKx9Dqg4kcUPLMKMc/q9UUWqXme3X7H16hQR47jyu7TwJucE=,iv:PVX46c+GJn0DIFmnxdbWlww587tK3DAEAktABRuUWPo=,tag:3JNEP48IJIxHRMJFEihK9w==,type:str]
+sops:
+    age:
+        - recipient: age149fqcw5jze00vd7jauylrp4j5xyv7amlu57jjfuzghkqtzlnxajs704uz3
+          enc: |
+            -----BEGIN AGE ENCRYPTED FILE-----
+            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSA1eW1XNDVEN2VtYjAyWWhL
+            RVNTZll3ejk4U0dDUXY0ZTg0dm0xLzI0SGtzCitnTnBqVWd0RlYwaGlnK2gyTk1r
+            cmhQQk9LWW5Eb1I4aVkvNjVoU0VBb2cKLS0tIFB1TURncHVqc29WSXZseThYeHdk
+            Q3I1ckd2T1FRS1h2Q1ZVOWhDWVYxZFUKfe8WEn3MIse7JLYFf6VYTzb6/h4sMtXO
+            mlTl6IohvP8nChQSGY1cJVYotC5smbNhyi5jF8DGuSwyCxUmse1kCg==
+            -----END AGE ENCRYPTED FILE-----
+        - recipient: age1dwcz3fmp29ju4svy0t0wz4ylhpwlqa8xpw4l7t4gmgqr0ev37qrsfn840l
+          enc: |
+            -----BEGIN AGE ENCRYPTED FILE-----
+            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSB5NG5HR3VHaktHNWpvWG0y
+            S0RkcFlnbUtUNEorTk9BVnlDeFdDbGxJTVhNCkw0ZTNkY2FXRjlJS3BzM2Z2M2wv
+            RlVNVkwzbzFBMmhLZDAzWG81bVpsUjgKLS0tIElvSzNvLy85dk1CQnozaDVZRnVD
+            bGp3R0tJNGhMdDJ5ZWdmVEFWUkdqYkkKUdxfHEKxgcpCdF9aV2R0WRNuxn9SAc5U
+            wnVgfFd29swuEAyFKYT3UbpN6/TF8IFYW7Vk4yLpQhuF9V5K662EgQ==
+            -----END AGE ENCRYPTED FILE-----
+        - recipient: age1cpm9xhgue7sjvq7zyeeaxwr96c93sfzxxxj76sxsq7s7kgnygvcq5jxren
+          enc: |
+            -----BEGIN AGE ENCRYPTED FILE-----
+            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBteUFWL2tGWmpIVjN6MUNY
+            YkNIQjhib3g4bWFxWkUzKzdCZXMyRVZySVdRCmZVcDFsSHdCWHhKVEsyREtDMHcy
+            aTJCdU41MFRyaWN6Y2FCRHpKS25GencKLS0tIHl2UzFoWmRiemFwOXhYWktZVXdY
+            S0hvUVBONXhtVWpMc01JRjRnRzhuYWcKFhe5yuQxmgFmZHWTcK/D3zYTAU44a27N
+            1T1bU3uYM6FGadCnMCJJe3vWlZZsED4Bj+/rCokiYtyTUFrIgvYbVQ==
+            -----END AGE ENCRYPTED FILE-----
+    lastmodified: "2026-05-03T12:57:02Z"
+    mac: ENC[AES256_GCM,data:6lW+KCgPEUnShW/nvYxA51Xp4MRekD+j11V5RUn7dsoZyhKWMu2CGeHHgbaAXKGS3gHackpacP2qNQqDGzShpdKTLZHGppftgmNwjgVMA4BDw/ZnDaUesLriIn+dfdohhxomBQZwZ1MypJB3VrO1zORuwm69o67Kfepa0Ud7Myo=,iv:wvehD4jvF5igrynI7zpR+MTY/Bpb+ur9boOawIDacuY=,tag:uPwzFCJvlb87XYkcgcnuYQ==,type:str]
+    unencrypted_suffix: _unencrypted
+    version: 3.12.1

From f74928ce5f3dae15ede6e0706caaff70fa361694 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Sun, 3 May 2026 14:48:41 +0200
Subject: [PATCH 027/101] chore: nix fmt

---
 modules/common.nix                            |  3 +-
 modules/darwin/services/base/default.nix      |  9 +++--
 modules/nixos/services/gui/default.nix        | 40 +++++++++----------
 overlays/inetutils-darwin-fix/default.nix     |  3 +-
 overlays/mods/default.nix                     |  3 +-
 overlays/unstable/default.nix                 |  3 +-
 systems/nixbuild.nix                          |  3 +-
 .../amd/hardware-configuration.nix            |  5 ++-
 systems/x86_64-linux/amd/sound.nix            |  3 +-
 systems/x86_64-linux/amd/xremap.nix           |  3 +-
 systems/x86_64-linux/attic/atticd.nix         | 10 +++--
 systems/x86_64-linux/attic/default.nix        |  7 +++-
 systems/x86_64-linux/halo/default.nix         | 15 +++----
 systems/x86_64-linux/halo/sound.nix           |  3 +-
 systems/x86_64-linux/halo/xremap.nix          |  3 +-
 systems/x86_64-linux/mx/nginx.nix             |  3 +-
 systems/x86_64-linux/sgx/fileserver.nix       |  3 +-
 systems/x86_64-linux/sgx/openwebui.nix        |  3 +-
 systems/x86_64-linux/sgx/uptime-kuma.nix      |  3 +-
 systems/x86_64-linux/sgx/wyoming.nix          |  3 +-
 systems/x86_64-linux/x1/xremap.nix            |  3 +-
 21 files changed, 60 insertions(+), 71 deletions(-)

diff --git a/modules/common.nix b/modules/common.nix
index 339ca3e..35dd320 100644
--- a/modules/common.nix
+++ b/modules/common.nix
@@ -1,5 +1,4 @@
-_:
-{
+_: {
   defaultSSHKeys = [
     "sk-ssh-ed25519@openssh.com AAAAGnNrLXNzaC1lZDI1NTE5QG9wZW5zc2guY29tAAAAIDsb/Tr69YN5MQLweWPuJaRGm+h2kOyxfD6sqKEDTIwoAAAABHNzaDo= harald@fedora.fritz.box"
     "sk-ecdsa-sha2-nistp256@openssh.com AAAAInNrLWVjZHNhLXNoYTItbmlzdHAyNTZAb3BlbnNzaC5jb20AAAAIbmlzdHAyNTYAAABBBACLgT81iB1iWWVuXq6PdQ5GAAGhaZhSKnveQCvcNnAOZ5WKH80bZShKHyAYzrzbp8IGwLWJcZQ7TqRK+qZdfagAAAAEc3NoOg== harald@hoyer.xyz"
diff --git a/modules/darwin/services/base/default.nix b/modules/darwin/services/base/default.nix
index edb4e01..84c8f08 100644
--- a/modules/darwin/services/base/default.nix
+++ b/modules/darwin/services/base/default.nix
@@ -1,7 +1,8 @@
-{ config
-, lib
-, pkgs
-, ...
+{
+  config,
+  lib,
+  pkgs,
+  ...
 }:
 with lib;
 with lib.metacfg;
diff --git a/modules/nixos/services/gui/default.nix b/modules/nixos/services/gui/default.nix
index 391c8b7..ac35c06 100644
--- a/modules/nixos/services/gui/default.nix
+++ b/modules/nixos/services/gui/default.nix
@@ -70,33 +70,31 @@ in
     hardware.graphics = {
       enable = true;
 
-      extraPackages =
-        lib.optionals pkgs.stdenv.targetPlatform.isx86_64 (
-          with pkgs;
-          [
-            vpl-gpu-rt
-            intel-compute-runtime
-            intel-media-driver # LIBVA_DRIVER_NAME=iHD
-            #intel-vaapi-driver # LIBVA_DRIVER_NAME=i965 (older but works better for Firefox/Chromium)
-            libvdpau-va-gl
-            rocmPackages.clr.icd
-          ]
-        );
+      extraPackages = lib.optionals pkgs.stdenv.targetPlatform.isx86_64 (
+        with pkgs;
+        [
+          vpl-gpu-rt
+          intel-compute-runtime
+          intel-media-driver # LIBVA_DRIVER_NAME=iHD
+          #intel-vaapi-driver # LIBVA_DRIVER_NAME=i965 (older but works better for Firefox/Chromium)
+          libvdpau-va-gl
+          rocmPackages.clr.icd
+        ]
+      );
     };
 
     systemd.tmpfiles.rules =
       let
         rocmEnv = pkgs.symlinkJoin {
           name = "rocm-combined";
-          paths =
-            lib.optionals pkgs.stdenv.targetPlatform.isx86_64 (
-              with pkgs.rocmPackages;
-              [
-                rocblas
-                hipblas
-                clr
-              ]
-            );
+          paths = lib.optionals pkgs.stdenv.targetPlatform.isx86_64 (
+            with pkgs.rocmPackages;
+            [
+              rocblas
+              hipblas
+              clr
+            ]
+          );
         };
       in
       [ "L+    /opt/rocm   -    -    -     -    ${rocmEnv}" ];
diff --git a/overlays/inetutils-darwin-fix/default.nix b/overlays/inetutils-darwin-fix/default.nix
index 9fc5644..38b1162 100644
--- a/overlays/inetutils-darwin-fix/default.nix
+++ b/overlays/inetutils-darwin-fix/default.nix
@@ -1,5 +1,4 @@
-_:
-final: prev: {
+_: final: prev: {
   inetutils = prev.inetutils.overrideAttrs (old: {
     # Fix gnulib variadic macro error on Darwin with newer Clang
     # The error.h macro __gl_error_call1 has issues with __VA_ARGS__
diff --git a/overlays/mods/default.nix b/overlays/mods/default.nix
index dfce3e3..d6a566b 100644
--- a/overlays/mods/default.nix
+++ b/overlays/mods/default.nix
@@ -1,5 +1,4 @@
-_:
-final: prev: {
+_: final: prev: {
   gnome-console = prev.gnome-console.overrideAttrs (prevAttrs: {
     patches = (prevAttrs.patches or [ ]) ++ [
       ./gnome-console-Add-image-and-file-path-pasting-support-for.patch
diff --git a/overlays/unstable/default.nix b/overlays/unstable/default.nix
index c212a6e..c3b2561 100644
--- a/overlays/unstable/default.nix
+++ b/overlays/unstable/default.nix
@@ -36,8 +36,7 @@ final: prev: {
           hash = "sha256-GCAOKYyijaQPVBgAixoZRPHIdiUfV8mPeeflE7aX8Ac=";
         };
       }
-      .${prev.stdenv.system}
-        or (throw "unsupported system ${prev.stdenv.hostPlatform.system}")
+      .${prev.stdenv.system} or (throw "unsupported system ${prev.stdenv.hostPlatform.system}")
     );
   });
   # gemini-cli = channels.unstable.callPackage ./gemini-cli/package.nix { };
diff --git a/systems/nixbuild.nix b/systems/nixbuild.nix
index fdb2a8c..94af67b 100644
--- a/systems/nixbuild.nix
+++ b/systems/nixbuild.nix
@@ -1,5 +1,4 @@
-_:
-{
+_: {
   nix.distributedBuilds = true;
 
   nix.buildMachines = [
diff --git a/systems/x86_64-linux/amd/hardware-configuration.nix b/systems/x86_64-linux/amd/hardware-configuration.nix
index 216eb61..26e992a 100644
--- a/systems/x86_64-linux/amd/hardware-configuration.nix
+++ b/systems/x86_64-linux/amd/hardware-configuration.nix
@@ -26,7 +26,10 @@
     "sd_mod"
   ];
   boot.initrd.kernelModules = [ ];
-  boot.kernelModules = [ "kvm-amd" "ryzen_smu" ];
+  boot.kernelModules = [
+    "kvm-amd"
+    "ryzen_smu"
+  ];
   boot.extraModulePackages = [ config.boot.kernelPackages.ryzen-smu ];
 
   boot.kernelParams = [
diff --git a/systems/x86_64-linux/amd/sound.nix b/systems/x86_64-linux/amd/sound.nix
index 99fa565..e0130d2 100644
--- a/systems/x86_64-linux/amd/sound.nix
+++ b/systems/x86_64-linux/amd/sound.nix
@@ -1,5 +1,4 @@
-_:
-{
+_: {
   services.pipewire.wireplumber.extraConfig."51-audio-priorities" = {
     "monitor.alsa.rules" = [
       {
diff --git a/systems/x86_64-linux/amd/xremap.nix b/systems/x86_64-linux/amd/xremap.nix
index a3090d4..2125205 100644
--- a/systems/x86_64-linux/amd/xremap.nix
+++ b/systems/x86_64-linux/amd/xremap.nix
@@ -1,5 +1,4 @@
-_:
-{
+_: {
   metacfg.services.xremap = {
     enable = true;
     deviceNames = [
diff --git a/systems/x86_64-linux/attic/atticd.nix b/systems/x86_64-linux/attic/atticd.nix
index 232c1ea..4bfee84 100644
--- a/systems/x86_64-linux/attic/atticd.nix
+++ b/systems/x86_64-linux/attic/atticd.nix
@@ -8,10 +8,12 @@
   services.postgresql = {
     enable = true;
     ensureDatabases = [ "atticd" ];
-    ensureUsers = [{
-      name = "atticd";
-      ensureDBOwnership = true;
-    }];
+    ensureUsers = [
+      {
+        name = "atticd";
+        ensureDBOwnership = true;
+      }
+    ];
   };
 
   environment.systemPackages = with pkgs; [ attic-client ];
diff --git a/systems/x86_64-linux/attic/default.nix b/systems/x86_64-linux/attic/default.nix
index 9b58f1e..b6ecf43 100644
--- a/systems/x86_64-linux/attic/default.nix
+++ b/systems/x86_64-linux/attic/default.nix
@@ -42,9 +42,12 @@
     matchConfig.Name = "enp1s0";
     networkConfig.DHCP = "ipv4";
     address = [ "2a01:4f9:c014:619::1/64" ];
-    routes = [{ Gateway = "fe80::1"; }];
+    routes = [ { Gateway = "fe80::1"; } ];
   };
-  networking.firewall.allowedTCPPorts = [ 80 443 ];
+  networking.firewall.allowedTCPPorts = [
+    80
+    443
+  ];
   networking.firewall.allowPing = true;
 
   security.acme = {
diff --git a/systems/x86_64-linux/halo/default.nix b/systems/x86_64-linux/halo/default.nix
index 9d1c0ce..eeb376c 100644
--- a/systems/x86_64-linux/halo/default.nix
+++ b/systems/x86_64-linux/halo/default.nix
@@ -26,13 +26,12 @@ with lib.metacfg;
   hardware.graphics = {
     enable = true;
 
-    extraPackages =
-      lib.optionals pkgs.stdenv.targetPlatform.isx86_64 (
-        with pkgs;
-        [
-          rocmPackages.clr.icd
-        ]
-      );
+    extraPackages = lib.optionals pkgs.stdenv.targetPlatform.isx86_64 (
+      with pkgs;
+      [
+        rocmPackages.clr.icd
+      ]
+    );
   };
 
   systemd.tmpfiles.rules =
@@ -123,13 +122,11 @@ with lib.metacfg;
     python313Packages.huggingface-hub
   ];
 
-
   virtualisation = {
     docker.enable = true;
     podman.dockerCompat = false;
   };
 
-
   # zram swap with zstd compression for better performance
   zramSwap = {
     algorithm = "zstd";
diff --git a/systems/x86_64-linux/halo/sound.nix b/systems/x86_64-linux/halo/sound.nix
index 99fa565..e0130d2 100644
--- a/systems/x86_64-linux/halo/sound.nix
+++ b/systems/x86_64-linux/halo/sound.nix
@@ -1,5 +1,4 @@
-_:
-{
+_: {
   services.pipewire.wireplumber.extraConfig."51-audio-priorities" = {
     "monitor.alsa.rules" = [
       {
diff --git a/systems/x86_64-linux/halo/xremap.nix b/systems/x86_64-linux/halo/xremap.nix
index a3090d4..2125205 100644
--- a/systems/x86_64-linux/halo/xremap.nix
+++ b/systems/x86_64-linux/halo/xremap.nix
@@ -1,5 +1,4 @@
-_:
-{
+_: {
   metacfg.services.xremap = {
     enable = true;
     deviceNames = [
diff --git a/systems/x86_64-linux/mx/nginx.nix b/systems/x86_64-linux/mx/nginx.nix
index 6e61be9..864d244 100644
--- a/systems/x86_64-linux/mx/nginx.nix
+++ b/systems/x86_64-linux/mx/nginx.nix
@@ -1,5 +1,4 @@
-_:
-{
+_: {
   services.nginx.virtualHosts = {
     "00000" = {
       useACMEHost = "hoyer.xyz";
diff --git a/systems/x86_64-linux/sgx/fileserver.nix b/systems/x86_64-linux/sgx/fileserver.nix
index 2dc8a07..699a7c7 100644
--- a/systems/x86_64-linux/sgx/fileserver.nix
+++ b/systems/x86_64-linux/sgx/fileserver.nix
@@ -1,5 +1,4 @@
-_:
-{
+_: {
   systemd.services.netatalk.requires = [
     "mnt-backup.mount"
     "mnt-raid.mount"
diff --git a/systems/x86_64-linux/sgx/openwebui.nix b/systems/x86_64-linux/sgx/openwebui.nix
index c072c47..589139e 100644
--- a/systems/x86_64-linux/sgx/openwebui.nix
+++ b/systems/x86_64-linux/sgx/openwebui.nix
@@ -1,5 +1,4 @@
-_:
-{
+_: {
   services.open-webui = {
     enable = true;
     port = 8080;
diff --git a/systems/x86_64-linux/sgx/uptime-kuma.nix b/systems/x86_64-linux/sgx/uptime-kuma.nix
index 0001220..6e9ae29 100644
--- a/systems/x86_64-linux/sgx/uptime-kuma.nix
+++ b/systems/x86_64-linux/sgx/uptime-kuma.nix
@@ -1,5 +1,4 @@
-_:
-{
+_: {
   services.uptime-kuma = {
     enable = true;
     settings = {
diff --git a/systems/x86_64-linux/sgx/wyoming.nix b/systems/x86_64-linux/sgx/wyoming.nix
index b8b2227..1b4f870 100644
--- a/systems/x86_64-linux/sgx/wyoming.nix
+++ b/systems/x86_64-linux/sgx/wyoming.nix
@@ -1,5 +1,4 @@
-_:
-{
+_: {
   services.wyoming = {
     faster-whisper.servers."main" = {
       enable = true;
diff --git a/systems/x86_64-linux/x1/xremap.nix b/systems/x86_64-linux/x1/xremap.nix
index a3090d4..2125205 100644
--- a/systems/x86_64-linux/x1/xremap.nix
+++ b/systems/x86_64-linux/x1/xremap.nix
@@ -1,5 +1,4 @@
-_:
-{
+_: {
   metacfg.services.xremap = {
     enable = true;
     deviceNames = [

From 0989b8ae4687fd915a258901f2db60a8ebb10c4f Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Sun, 3 May 2026 14:49:44 +0200
Subject: [PATCH 028/101] feat(sgx): add opencode web server

---
 systems/x86_64-linux/sgx/acme.nix     |  1 +
 systems/x86_64-linux/sgx/default.nix  |  1 +
 systems/x86_64-linux/sgx/nginx.nix    | 12 +++++++
 systems/x86_64-linux/sgx/opencode.nix | 46 +++++++++++++++++++++++++++
 4 files changed, 60 insertions(+)
 create mode 100644 systems/x86_64-linux/sgx/opencode.nix

diff --git a/systems/x86_64-linux/sgx/acme.nix b/systems/x86_64-linux/sgx/acme.nix
index da5d5cc..e82c9d2 100644
--- a/systems/x86_64-linux/sgx/acme.nix
+++ b/systems/x86_64-linux/sgx/acme.nix
@@ -18,6 +18,7 @@
         "status.hoyer.world"
         "firefly.hoyer.world"
         "firefly-import.hoyer.world"
+        "opencode.sgx.hoyer.world"
       ];
     };
   };
diff --git a/systems/x86_64-linux/sgx/default.nix b/systems/x86_64-linux/sgx/default.nix
index 5d20468..2e7e6e7 100644
--- a/systems/x86_64-linux/sgx/default.nix
+++ b/systems/x86_64-linux/sgx/default.nix
@@ -13,6 +13,7 @@
     ./searx.nix
     ./uptime-kuma.nix
     ./firefly.nix
+    ./opencode.nix
   ];
 
   boot.tmp.useTmpfs = false;
diff --git a/systems/x86_64-linux/sgx/nginx.nix b/systems/x86_64-linux/sgx/nginx.nix
index 26eeedf..64a38a7 100644
--- a/systems/x86_64-linux/sgx/nginx.nix
+++ b/systems/x86_64-linux/sgx/nginx.nix
@@ -41,5 +41,17 @@
         proxyWebsockets = true;
       };
     };
+    "opencode.sgx.hoyer.world" = {
+      enableACME = false;
+      useACMEHost = "internal.hoyer.world";
+      forceSSL = true;
+      locations."/" = {
+        proxyPass = "http://127.0.0.1:4196";
+        proxyWebsockets = true;
+        extraConfig = ''
+          proxy_buffering off;
+        '';
+      };
+    };
   };
 }
diff --git a/systems/x86_64-linux/sgx/opencode.nix b/systems/x86_64-linux/sgx/opencode.nix
new file mode 100644
index 0000000..10b2913
--- /dev/null
+++ b/systems/x86_64-linux/sgx/opencode.nix
@@ -0,0 +1,46 @@
+{
+  config,
+  pkgs,
+  lib,
+  ...
+}:
+
+let
+  port = 4196;
+  user = "harald";
+  homeDir = "/home/harald";
+in
+{
+  systemd.services.opencode-serve = {
+    description = "OpenCode Web Server";
+    after = [ "network.target" ];
+    wantedBy = [ "multi-user.target" ];
+
+    environment = {
+      HOME = homeDir;
+    };
+
+    serviceConfig = {
+      Type = "simple";
+      User = user;
+      Group = "users";
+      WorkingDirectory = homeDir;
+      ExecStart = "${pkgs.opencode}/bin/opencode serve --hostname 127.0.0.1 --port ${toString port}";
+      Restart = "always";
+      RestartSec = 5;
+      EnvironmentFile = config.sops.secrets.opencode-web-password.path;
+
+      # Security hardening
+      PrivateTmp = true;
+      ProtectSystem = "strict";
+      ProtectHome = false;
+      NoNewPrivileges = true;
+      ReadWritePaths = [ homeDir ];
+    };
+  };
+
+  sops.secrets.opencode-web-password = {
+    sopsFile = ../../../.secrets/sgx/opencode-web.yaml;
+    owner = user;
+  };
+}

From 3453f412fc8c321041ac17d614a271b711a8da50 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Sun, 3 May 2026 15:10:47 +0200
Subject: [PATCH 029/101] chore: opencode pw

---
 .secrets/sgx/opencode-web.yaml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/.secrets/sgx/opencode-web.yaml b/.secrets/sgx/opencode-web.yaml
index c998b3d..897d0b6 100644
--- a/.secrets/sgx/opencode-web.yaml
+++ b/.secrets/sgx/opencode-web.yaml
@@ -1,4 +1,4 @@
-opencode-web-password: ENC[AES256_GCM,data:5GRYJHf9TSqtKx9Dqg4kcUPLMKMc/q9UUWqXme3X7H16hQR47jyu7TwJucE=,iv:PVX46c+GJn0DIFmnxdbWlww587tK3DAEAktABRuUWPo=,tag:3JNEP48IJIxHRMJFEihK9w==,type:str]
+opencode-web-password: ENC[AES256_GCM,data:Tsu+RUkshfO3uURYO9+FbmKEjGH+8UdIEBzbRpH7AJoaS5MdbUGNzEgETV+q4kv2kklOaPbC3sT6IXnDuZwIF2ZBdp5U,iv:amen16H+nnDrrLUzudh4WIhkpo84EYnjrDZ8T1muTEs=,tag:Ar/hqJ9MO4hDiJMQ17gj6A==,type:str]
 sops:
     age:
         - recipient: age149fqcw5jze00vd7jauylrp4j5xyv7amlu57jjfuzghkqtzlnxajs704uz3
@@ -28,7 +28,7 @@ sops:
             S0hvUVBONXhtVWpMc01JRjRnRzhuYWcKFhe5yuQxmgFmZHWTcK/D3zYTAU44a27N
             1T1bU3uYM6FGadCnMCJJe3vWlZZsED4Bj+/rCokiYtyTUFrIgvYbVQ==
             -----END AGE ENCRYPTED FILE-----
-    lastmodified: "2026-05-03T12:57:02Z"
-    mac: ENC[AES256_GCM,data:6lW+KCgPEUnShW/nvYxA51Xp4MRekD+j11V5RUn7dsoZyhKWMu2CGeHHgbaAXKGS3gHackpacP2qNQqDGzShpdKTLZHGppftgmNwjgVMA4BDw/ZnDaUesLriIn+dfdohhxomBQZwZ1MypJB3VrO1zORuwm69o67Kfepa0Ud7Myo=,iv:wvehD4jvF5igrynI7zpR+MTY/Bpb+ur9boOawIDacuY=,tag:uPwzFCJvlb87XYkcgcnuYQ==,type:str]
+    lastmodified: "2026-05-03T13:10:39Z"
+    mac: ENC[AES256_GCM,data:Skvq6lM6xNCL3fCJTZrC+n/wlS4AuMz6FGIt5VW2Xo7WHyxEMPwHBKNUhu8tUnk2EhQea/jMWtQwaA6YUYGQXR4MWa4YyobbEY1Fp4Gks2brk34rBOXLzwdN8bYQZvsjbralcfvC5uyi8x7W65IJZje/vl/mjBFz+ZjCosvNo98=,iv:M2vvIZXno7Snqj6YXSg37MvilRDmVUodIs+Kc8KPqOo=,tag:h1oqbesC1QXEqf8BV1GMbA==,type:str]
     unencrypted_suffix: _unencrypted
     version: 3.12.1

From 59480cdc79bd118292e70e4a30cf1b1ae6ba4622 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Sun, 3 May 2026 15:14:54 +0200
Subject: [PATCH 030/101] chore: opencode pw

---
 .secrets/sgx/opencode-web.yaml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/.secrets/sgx/opencode-web.yaml b/.secrets/sgx/opencode-web.yaml
index 897d0b6..2fee410 100644
--- a/.secrets/sgx/opencode-web.yaml
+++ b/.secrets/sgx/opencode-web.yaml
@@ -1,4 +1,4 @@
-opencode-web-password: ENC[AES256_GCM,data:Tsu+RUkshfO3uURYO9+FbmKEjGH+8UdIEBzbRpH7AJoaS5MdbUGNzEgETV+q4kv2kklOaPbC3sT6IXnDuZwIF2ZBdp5U,iv:amen16H+nnDrrLUzudh4WIhkpo84EYnjrDZ8T1muTEs=,tag:Ar/hqJ9MO4hDiJMQ17gj6A==,type:str]
+opencode-web-password: ENC[AES256_GCM,data:u1Rw15snERc7+zkW2rZS91fadbuLk1msfEBIqe+bHVno6cdJabXoznsxtPyDnN/4G1+hHMZvBIWCSzNzoB78XMh4P/hmRr8=,iv:snqYkpsUQZL020wqitNneD3v2E3eM2VddzkrzaUEwBw=,tag:eAkktHW3bdYcwvWrjhppxw==,type:str]
 sops:
     age:
         - recipient: age149fqcw5jze00vd7jauylrp4j5xyv7amlu57jjfuzghkqtzlnxajs704uz3
@@ -28,7 +28,7 @@ sops:
             S0hvUVBONXhtVWpMc01JRjRnRzhuYWcKFhe5yuQxmgFmZHWTcK/D3zYTAU44a27N
             1T1bU3uYM6FGadCnMCJJe3vWlZZsED4Bj+/rCokiYtyTUFrIgvYbVQ==
             -----END AGE ENCRYPTED FILE-----
-    lastmodified: "2026-05-03T13:10:39Z"
-    mac: ENC[AES256_GCM,data:Skvq6lM6xNCL3fCJTZrC+n/wlS4AuMz6FGIt5VW2Xo7WHyxEMPwHBKNUhu8tUnk2EhQea/jMWtQwaA6YUYGQXR4MWa4YyobbEY1Fp4Gks2brk34rBOXLzwdN8bYQZvsjbralcfvC5uyi8x7W65IJZje/vl/mjBFz+ZjCosvNo98=,iv:M2vvIZXno7Snqj6YXSg37MvilRDmVUodIs+Kc8KPqOo=,tag:h1oqbesC1QXEqf8BV1GMbA==,type:str]
+    lastmodified: "2026-05-03T13:14:50Z"
+    mac: ENC[AES256_GCM,data:VQ9TMo0QtPpgmkbYOJEwPG/RDPbScHCsJhFO+bhRJ64dazMwIKxO1DAsHF1298YeTbY5/EXly+8FS1kE5dQY1cGSy64fcSusM14k0a9Js0GxCz1NuJNlwzJVCZv5zjP8koH2B7PdIUhgI45zGIAuNcfP6dmtgy2vfGXcFg2cZpU=,iv:6cR1mYKoIkpVYrLN9z1Dd5CBOuizlhjau1TNbRqg2zA=,tag:7eKKsi6gS7PdIMZ0UOt90g==,type:str]
     unencrypted_suffix: _unencrypted
     version: 3.12.1

From 01f42c085142b3a9c7de7303083e9ee8a962df9b Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Sun, 3 May 2026 15:23:40 +0200
Subject: [PATCH 031/101] feat(sops): trigger service restarts on secret
 rotation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Wire up restartUnits on secrets whose consumers cache them in memory
(daemons read at startup), so sops-nix restarts the affected unit on
activation when the decrypted content changes:

- firefly: app_key → phpfpm-firefly-iii;
  auto_import_secret + access_token → phpfpm-firefly-iii-data-importer
- searx: secret_key → uwsgi
- opencode: web password → opencode-serve
- mail: sasl_passwd → postfix
- forgejo: gitea_dbpass → forgejo; runner-token → gitea-runner-default

Secrets read on demand by oneshots/timers (firefly sparda_pin, ntfy
token, restic backup creds, acme dns creds, wg conf) are left as-is.
---
 systems/x86_64-linux/mx/forgejo.nix   | 2 ++
 systems/x86_64-linux/sgx/firefly.nix  | 3 +++
 systems/x86_64-linux/sgx/mail.nix     | 1 +
 systems/x86_64-linux/sgx/opencode.nix | 1 +
 systems/x86_64-linux/sgx/searx.nix    | 5 ++++-
 5 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/systems/x86_64-linux/mx/forgejo.nix b/systems/x86_64-linux/mx/forgejo.nix
index 4847b0a..6ae4644 100644
--- a/systems/x86_64-linux/mx/forgejo.nix
+++ b/systems/x86_64-linux/mx/forgejo.nix
@@ -7,6 +7,7 @@
   sops.secrets."postgres/gitea_dbpass" = {
     sopsFile = ../../../.secrets/hetzner/postgres.yaml; # bring your own password file
     owner = config.services.forgejo.user;
+    restartUnits = [ "forgejo.service" ];
   };
 
   services.forgejo = {
@@ -40,6 +41,7 @@
 
   sops.secrets."forgejo-runner-token" = {
     sopsFile = ../../../.secrets/hetzner/forgejo-runner-token.yaml; # bring your own password file
+    restartUnits = [ "gitea-runner-default.service" ];
   };
 
   services.gitea-actions-runner = {
diff --git a/systems/x86_64-linux/sgx/firefly.nix b/systems/x86_64-linux/sgx/firefly.nix
index 94ad43b..2aa9c76 100644
--- a/systems/x86_64-linux/sgx/firefly.nix
+++ b/systems/x86_64-linux/sgx/firefly.nix
@@ -31,6 +31,7 @@ in
     "firefly/app_key" = {
       sopsFile = ../../../.secrets/sgx/firefly.yaml;
       owner = "firefly-iii";
+      restartUnits = [ "phpfpm-firefly-iii.service" ];
     };
     "firefly/sparda_pin" = {
       sopsFile = ../../../.secrets/sgx/firefly.yaml;
@@ -39,10 +40,12 @@ in
     "firefly/auto_import_secret" = {
       sopsFile = ../../../.secrets/sgx/firefly.yaml;
       owner = "firefly-iii-data-importer";
+      restartUnits = [ "phpfpm-firefly-iii-data-importer.service" ];
     };
     "firefly/access_token" = {
       sopsFile = ../../../.secrets/sgx/firefly.yaml;
       owner = "firefly-iii-data-importer";
+      restartUnits = [ "phpfpm-firefly-iii-data-importer.service" ];
     };
   };
 
diff --git a/systems/x86_64-linux/sgx/mail.nix b/systems/x86_64-linux/sgx/mail.nix
index 289bac2..ff341a2 100644
--- a/systems/x86_64-linux/sgx/mail.nix
+++ b/systems/x86_64-linux/sgx/mail.nix
@@ -21,6 +21,7 @@
   sops.secrets.sasl_passwd = {
     sopsFile = ../../../.secrets/sgx/relay.yaml; # bring your own password file
     owner = config.services.postfix.user;
+    restartUnits = [ "postfix.service" ];
   };
 
 }
diff --git a/systems/x86_64-linux/sgx/opencode.nix b/systems/x86_64-linux/sgx/opencode.nix
index 10b2913..9ea0017 100644
--- a/systems/x86_64-linux/sgx/opencode.nix
+++ b/systems/x86_64-linux/sgx/opencode.nix
@@ -42,5 +42,6 @@ in
   sops.secrets.opencode-web-password = {
     sopsFile = ../../../.secrets/sgx/opencode-web.yaml;
     owner = user;
+    restartUnits = [ "opencode-serve.service" ];
   };
 }
diff --git a/systems/x86_64-linux/sgx/searx.nix b/systems/x86_64-linux/sgx/searx.nix
index 4f7f702..88690b5 100644
--- a/systems/x86_64-linux/sgx/searx.nix
+++ b/systems/x86_64-linux/sgx/searx.nix
@@ -1,6 +1,9 @@
 { pkgs, config, ... }:
 {
-  sops.secrets."searx/secret_key".sopsFile = ../../../.secrets/sgx/searx.yaml;
+  sops.secrets."searx/secret_key" = {
+    sopsFile = ../../../.secrets/sgx/searx.yaml;
+    restartUnits = [ "uwsgi.service" ];
+  };
 
   services.searx = {
     enable = true;

From 0e723e2da8bf6621a3a441c51e429649cab29d7a Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Sun, 3 May 2026 15:55:15 +0200
Subject: [PATCH 032/101] feat(amd): add opencode web server at
 opencode.amd.hoyer.world

Mirror of the sgx opencode setup: systemd service on port 4196 fronted
by nginx with a per-host ACME cert (DNS-01 via internetbs). Adds amd
key + path rule to .sops.yaml so secrets under .secrets/amd/ encrypt
for the host.
---
 .secrets/amd/internetbs.yaml          | 34 +++++++++++++++++++
 .secrets/amd/opencode-web.yaml        | 34 +++++++++++++++++++
 .sops.yaml                            |  7 ++++
 systems/x86_64-linux/amd/acme.nix     | 11 +++++++
 systems/x86_64-linux/amd/default.nix  |  7 ++++
 systems/x86_64-linux/amd/nginx.nix    | 18 ++++++++++
 systems/x86_64-linux/amd/opencode.nix | 47 +++++++++++++++++++++++++++
 7 files changed, 158 insertions(+)
 create mode 100644 .secrets/amd/internetbs.yaml
 create mode 100644 .secrets/amd/opencode-web.yaml
 create mode 100644 systems/x86_64-linux/amd/acme.nix
 create mode 100644 systems/x86_64-linux/amd/nginx.nix
 create mode 100644 systems/x86_64-linux/amd/opencode.nix

diff --git a/.secrets/amd/internetbs.yaml b/.secrets/amd/internetbs.yaml
new file mode 100644
index 0000000..f833693
--- /dev/null
+++ b/.secrets/amd/internetbs.yaml
@@ -0,0 +1,34 @@
+internetbs: ENC[AES256_GCM,data:HTTxPwcGWFo/WkWD6UZhE6qUaBmJSVFzDux3EFn2uH1mCPoW0vKykfUbbMCJo0tWMvQszetAuO5jnQJJBrIkM6vaXX06ZlDUWluh+sPavqKFeq9HDobgf9qhhaaSHgrD/hLgz+dJ+Lj87/huEMhWj8KrnPY1Hj5uDUFVaJOMgNzczSt6iLA/mdL/cEiBT5st8qk8,iv:Ug59B4G7p0zVEAuMQlEYk+GcOjy/QOxEvxbdLnRTgpA=,tag:Z/7ceoVgr3ciNFKSlncjpA==,type:str]
+sops:
+    age:
+        - recipient: age1u2glh4g65qjvlcan7u7qmhdlpvxqkc2h48m5zka8nafjrfnt5e3ss494vt
+          enc: |
+            -----BEGIN AGE ENCRYPTED FILE-----
+            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSAzV08vMTJrazQyRjNVaHRR
+            KzRJcFBlRWJjanhCRk16Q25DcExzUHl0Y2tNCjlzS2dnbWUwWERORWtZOFB3R0ZT
+            VEZvUjZpVVVOWkVSZHdUaWdaMHAxaW8KLS0tIFF5VThaU0lyWkh2MXVpTGtlOWwz
+            K2h0dXVFRWJ3NXkrNmw5TkpKZFJUbUUKxRBQN7jewc0knpSa4wKtcbfP3kUbWBoC
+            a0zUUXb+Ooa76Sg0tK+gz5BDUqcxcPNbwhUwWaMz4FlRHMtMkQGoaQ==
+            -----END AGE ENCRYPTED FILE-----
+        - recipient: age1dwcz3fmp29ju4svy0t0wz4ylhpwlqa8xpw4l7t4gmgqr0ev37qrsfn840l
+          enc: |
+            -----BEGIN AGE ENCRYPTED FILE-----
+            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSAwNnJaaUh4UDgxVzFIK1dD
+            RUFjKzVOTDU1TUhqZEN5SW9NcXFSTHlkNkNNCnprMXY5cDI3TC9PakZyNkY5NG00
+            SGhXbkJxQ2FUOUthcjNzMmQxVVg1WmcKLS0tIG16ZjFWSW5tQUw5SXV5WTgvVkt5
+            WFlyeTRBS3p4N0pVOW11NXh5M1RkZ3cKDR9dB36DavUmChJUriFOTCWN7+M9xwoK
+            2dRb1O4N0qouYpAxef8vwL7VQUXOF0pqb+F7KF87EqRtir+SmbqCfg==
+            -----END AGE ENCRYPTED FILE-----
+        - recipient: age1cpm9xhgue7sjvq7zyeeaxwr96c93sfzxxxj76sxsq7s7kgnygvcq5jxren
+          enc: |
+            -----BEGIN AGE ENCRYPTED FILE-----
+            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBYT1FYNEJmSFhOaEtRZ3ZH
+            TWtxeVd2cVVqeURLTEk2d2tOWUFCNnRMS3gwCis1QUIzOHpLQW5tUzI0Nzk4N0VQ
+            N3lIZkVYWDU5VlAvWXNFR2w4ZTNFTTAKLS0tIFNsdG5jcHNtWjYzVHgwcjBSOTYr
+            RGZ3aTdwUi83blNCbjQwR1phd2UzdVkKpxSOiGK1cyRKdzd+d7jiTxYGwkpgB6OO
+            6TyY896Eht2iL34w7jXyH+eKJ8fzQrftpyARHy54r7LDS3TBhEFVxA==
+            -----END AGE ENCRYPTED FILE-----
+    lastmodified: "2024-12-06T08:50:35Z"
+    mac: ENC[AES256_GCM,data:Tz1EutxDgl2DQgNWNJWap5cwSAgR/Y4EjLUva7qHtXIMWa5jKPKqimY2IQhcsbqYv1zZmm+OnbO+OCIdZRbpnDCk5waBhywQNxNxjGAbv9fo/hbRFg9cm/vwA2BrXk9BR1L+gMcejRyZnnlMwEK+NomBkqAkpDZDlKjE7ebHoz0=,iv:Lk9kE3opD9y4oheETzLOiPn6Z5dLx8JEAuyCaYbkpQ4=,tag:/KtGrq7sGUxfi7BaJObhOQ==,type:str]
+    unencrypted_suffix: _unencrypted
+    version: 3.9.1
diff --git a/.secrets/amd/opencode-web.yaml b/.secrets/amd/opencode-web.yaml
new file mode 100644
index 0000000..eaab057
--- /dev/null
+++ b/.secrets/amd/opencode-web.yaml
@@ -0,0 +1,34 @@
+opencode-web-password: ENC[AES256_GCM,data:u1Rw15snERc7+zkW2rZS91fadbuLk1msfEBIqe+bHVno6cdJabXoznsxtPyDnN/4G1+hHMZvBIWCSzNzoB78XMh4P/hmRr8=,iv:snqYkpsUQZL020wqitNneD3v2E3eM2VddzkrzaUEwBw=,tag:eAkktHW3bdYcwvWrjhppxw==,type:str]
+sops:
+    age:
+        - recipient: age1u2glh4g65qjvlcan7u7qmhdlpvxqkc2h48m5zka8nafjrfnt5e3ss494vt
+          enc: |
+            -----BEGIN AGE ENCRYPTED FILE-----
+            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBvRGkxeHdKUDZ3U3ZZM1Bu
+            cGxiTlNLMk5seWVrTW80WHgyVGhTRDVKWUFJCkROYkhnaVBONjVidHEwdUVSWVlk
+            dG53V0xkV3JlRjh0N01HbGxHbFdvUHMKLS0tIFVuQkZWRi8vTmJXbnc3Mjc1TlNy
+            YnFKRk5DbUZrNEVLWUZ0UWRQWE9ZZlkKCav6B/v1Gf1mPn8bgUVgFHqTACbIVzZX
+            8BODNMIbGYKRzLRWYr/UDMGnNONW+2i9o4Czei0yeb0sT9yZ9EozBQ==
+            -----END AGE ENCRYPTED FILE-----
+        - recipient: age1dwcz3fmp29ju4svy0t0wz4ylhpwlqa8xpw4l7t4gmgqr0ev37qrsfn840l
+          enc: |
+            -----BEGIN AGE ENCRYPTED FILE-----
+            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBhY1BCTUFJR2x2OEowcU5M
+            L0xCcUxZR2lzb3lBamJNR3hQMTZSRDlGeEY4Cm5Ea0hZQjI2SmRiTGw2bUZZT1Rn
+            SWhUTlJjNE1ZWmhDa05FSGRnV1A4L0kKLS0tIDRKK3l0VXE5aGkvNnNpbnVXUmNY
+            bmk0ekNuRzA2S2VFY0NhR0ZVRVhFWkUKyM/iL60iQ+qcxW4EtM6q7gkm+rqyMDqX
+            8rgh5sjjz03r7LujFkSyoXEEdylHsqW57Pp4sDyxpPcSeBbG1ubyNw==
+            -----END AGE ENCRYPTED FILE-----
+        - recipient: age1cpm9xhgue7sjvq7zyeeaxwr96c93sfzxxxj76sxsq7s7kgnygvcq5jxren
+          enc: |
+            -----BEGIN AGE ENCRYPTED FILE-----
+            YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IFgyNTUxOSBJYm1vS2dja3V4emtSTzh4
+            ZUlCckxQbi9vNkE3M1lvcjFTRVlDRGxaaVRJCjQrU1JnUDlmZVBYbkJ5TTJuTnd5
+            MXBTbFhLRlFGWTJjbDZQZHBzUmdGclkKLS0tIHRoSmZ0Sm9hd3M4MVpiSkh4VjJK
+            T094Q0pWdWozRnZJd0ZKSisvQmlDUXcKRIvz33dKoJuP4YEEcNEkMMMmQZ3/bp9y
+            eDoUR+35e4/Q60NeUJzlNYfW/wobggUbx0fijXkTSbp+7C7YGkSgyQ==
+            -----END AGE ENCRYPTED FILE-----
+    lastmodified: "2026-05-03T13:14:50Z"
+    mac: ENC[AES256_GCM,data:VQ9TMo0QtPpgmkbYOJEwPG/RDPbScHCsJhFO+bhRJ64dazMwIKxO1DAsHF1298YeTbY5/EXly+8FS1kE5dQY1cGSy64fcSusM14k0a9Js0GxCz1NuJNlwzJVCZv5zjP8koH2B7PdIUhgI45zGIAuNcfP6dmtgy2vfGXcFg2cZpU=,iv:6cR1mYKoIkpVYrLN9z1Dd5CBOuizlhjau1TNbRqg2zA=,tag:7eKKsi6gS7PdIMZ0UOt90g==,type:str]
+    unencrypted_suffix: _unencrypted
+    version: 3.12.1
diff --git a/.sops.yaml b/.sops.yaml
index cd9a64b..258f720 100644
--- a/.sops.yaml
+++ b/.sops.yaml
@@ -1,6 +1,7 @@
 keys:
   - &server_hetzner age1qur4kh3gay9ryk3jh2snvjp6x9eq94zdrmgkrfcv4fzsu7l6lumq4tr3uy
   - &server_sgx age149fqcw5jze00vd7jauylrp4j5xyv7amlu57jjfuzghkqtzlnxajs704uz3
+  - &server_amd age1u2glh4g65qjvlcan7u7qmhdlpvxqkc2h48m5zka8nafjrfnt5e3ss494vt
   - &server_t15 age1f2yu0cc826ej7hs4g865y29zy9uqfy0yp32f2m80typpk2pxqp7sfcffj4
   - &server_x1 age1z87u2na6vts0sqg6sc73p9ym6e5g9a0gf3hp9e7ha47e83zy4efqcjhk0y
   - &harald age1dwcz3fmp29ju4svy0t0wz4ylhpwlqa8xpw4l7t4gmgqr0ev37qrsfn840l
@@ -18,6 +19,12 @@ creation_rules:
           - *server_sgx
           - *harald
           - *harald_ssh
+  - path_regex: .secrets/amd/[^/]+\.(yaml|json|env|ini)$
+    key_groups:
+      - age:
+          - *server_amd
+          - *harald
+          - *harald_ssh
   - path_regex: .secrets/t15/[^/]+\.(yaml|json|env|ini)$
     key_groups:
       - age:
diff --git a/systems/x86_64-linux/amd/acme.nix b/systems/x86_64-linux/amd/acme.nix
new file mode 100644
index 0000000..fefc75d
--- /dev/null
+++ b/systems/x86_64-linux/amd/acme.nix
@@ -0,0 +1,11 @@
+{
+  config,
+  ...
+}:
+{
+  sops.secrets.internetbs = {
+    sopsFile = ../../../.secrets/amd/internetbs.yaml;
+  };
+
+  metacfg.services.acmeBase.credentialsFile = config.sops.secrets.internetbs.path;
+}
diff --git a/systems/x86_64-linux/amd/default.nix b/systems/x86_64-linux/amd/default.nix
index e1dc4b3..13f998d 100644
--- a/systems/x86_64-linux/amd/default.nix
+++ b/systems/x86_64-linux/amd/default.nix
@@ -10,12 +10,17 @@ with lib.metacfg;
     ./hardware-configuration.nix
     ./xremap.nix
     ./sound.nix
+    ./acme.nix
+    ./nginx.nix
+    ./opencode.nix
   ];
 
   powerManagement.cpuFreqGovernor = "performance";
 
   services.rustdesk-server.signal.enable = false;
   networking.firewall.allowedTCPPorts = [
+    80
+    443
     22000
   ];
 
@@ -29,6 +34,8 @@ with lib.metacfg;
   services.resolved.enable = true;
 
   metacfg = {
+    services.nginxBase.enable = true;
+    services.acmeBase.enable = true;
     hardware.wooting.enable = true;
     base.enable = true;
     gui.enable = true;
diff --git a/systems/x86_64-linux/amd/nginx.nix b/systems/x86_64-linux/amd/nginx.nix
new file mode 100644
index 0000000..1e0d0c5
--- /dev/null
+++ b/systems/x86_64-linux/amd/nginx.nix
@@ -0,0 +1,18 @@
+{
+  ...
+}:
+{
+  services.nginx.virtualHosts = {
+    "opencode.amd.hoyer.world" = {
+      enableACME = true;
+      forceSSL = true;
+      locations."/" = {
+        proxyPass = "http://127.0.0.1:4196";
+        proxyWebsockets = true;
+        extraConfig = ''
+          proxy_buffering off;
+        '';
+      };
+    };
+  };
+}
diff --git a/systems/x86_64-linux/amd/opencode.nix b/systems/x86_64-linux/amd/opencode.nix
new file mode 100644
index 0000000..68f62f4
--- /dev/null
+++ b/systems/x86_64-linux/amd/opencode.nix
@@ -0,0 +1,47 @@
+{
+  config,
+  pkgs,
+  lib,
+  ...
+}:
+
+let
+  port = 4196;
+  user = "harald";
+  homeDir = "/home/harald";
+in
+{
+  systemd.services.opencode-serve = {
+    description = "OpenCode Web Server";
+    after = [ "network.target" ];
+    wantedBy = [ "multi-user.target" ];
+
+    environment = {
+      HOME = homeDir;
+    };
+
+    serviceConfig = {
+      Type = "simple";
+      User = user;
+      Group = "users";
+      WorkingDirectory = homeDir;
+      ExecStart = "${pkgs.opencode}/bin/opencode serve --hostname 127.0.0.1 --port ${toString port}";
+      Restart = "always";
+      RestartSec = 5;
+      EnvironmentFile = config.sops.secrets.opencode-web-password.path;
+
+      # Security hardening
+      PrivateTmp = true;
+      ProtectSystem = "strict";
+      ProtectHome = false;
+      NoNewPrivileges = true;
+      ReadWritePaths = [ homeDir ];
+    };
+  };
+
+  sops.secrets.opencode-web-password = {
+    sopsFile = ../../../.secrets/amd/opencode-web.yaml;
+    owner = user;
+    restartUnits = [ "opencode-serve.service" ];
+  };
+}

From 441df05d8658f32918c35ed4b15cb5cf68c40702 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Sun, 3 May 2026 16:09:31 +0200
Subject: [PATCH 033/101] fix(opencode): add git and dev tools to service PATH

The opencode-serve unit ran with systemd's minimal default PATH, so
shell commands invoked by the agent (git, make, nix, node, rg, etc.)
were not found. Set systemd.services.opencode-serve.path on both sgx
and amd to a common dev toolset.
---
 systems/x86_64-linux/amd/opencode.nix | 17 +++++++++++++++++
 systems/x86_64-linux/sgx/opencode.nix | 17 +++++++++++++++++
 2 files changed, 34 insertions(+)

diff --git a/systems/x86_64-linux/amd/opencode.nix b/systems/x86_64-linux/amd/opencode.nix
index 68f62f4..4c7b91b 100644
--- a/systems/x86_64-linux/amd/opencode.nix
+++ b/systems/x86_64-linux/amd/opencode.nix
@@ -16,6 +16,23 @@ in
     after = [ "network.target" ];
     wantedBy = [ "multi-user.target" ];
 
+    path = with pkgs; [
+      git
+      bash
+      coreutils
+      findutils
+      gnused
+      gnugrep
+      gawk
+      gnumake
+      nix
+      nodejs
+      ripgrep
+      fd
+      curl
+      which
+    ];
+
     environment = {
       HOME = homeDir;
     };
diff --git a/systems/x86_64-linux/sgx/opencode.nix b/systems/x86_64-linux/sgx/opencode.nix
index 9ea0017..286df36 100644
--- a/systems/x86_64-linux/sgx/opencode.nix
+++ b/systems/x86_64-linux/sgx/opencode.nix
@@ -16,6 +16,23 @@ in
     after = [ "network.target" ];
     wantedBy = [ "multi-user.target" ];
 
+    path = with pkgs; [
+      git
+      bash
+      coreutils
+      findutils
+      gnused
+      gnugrep
+      gawk
+      gnumake
+      nix
+      nodejs
+      ripgrep
+      fd
+      curl
+      which
+    ];
+
     environment = {
       HOME = homeDir;
     };

From 569300948829fb107bc26be287caf1951b70958c Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Sun, 3 May 2026 16:29:24 +0200
Subject: [PATCH 034/101] fix(opencode): set LD_LIBRARY_PATH for prebuilt node
 bindings

The file watcher binding (and other node-precompiled .node modules
loaded via dlopen) failed with "libstdc++.so.6: cannot open shared
object file" because systemd services don't inherit the user shell's
LD path. Reuse the nix-ld library list so the service sees the same
common libraries unwrapped binaries get globally.
---
 systems/x86_64-linux/amd/opencode.nix | 1 +
 systems/x86_64-linux/sgx/opencode.nix | 1 +
 2 files changed, 2 insertions(+)

diff --git a/systems/x86_64-linux/amd/opencode.nix b/systems/x86_64-linux/amd/opencode.nix
index 4c7b91b..df23c73 100644
--- a/systems/x86_64-linux/amd/opencode.nix
+++ b/systems/x86_64-linux/amd/opencode.nix
@@ -35,6 +35,7 @@ in
 
     environment = {
       HOME = homeDir;
+      LD_LIBRARY_PATH = lib.makeLibraryPath config.programs.nix-ld.libraries;
     };
 
     serviceConfig = {
diff --git a/systems/x86_64-linux/sgx/opencode.nix b/systems/x86_64-linux/sgx/opencode.nix
index 286df36..1ec6438 100644
--- a/systems/x86_64-linux/sgx/opencode.nix
+++ b/systems/x86_64-linux/sgx/opencode.nix
@@ -35,6 +35,7 @@ in
 
     environment = {
       HOME = homeDir;
+      LD_LIBRARY_PATH = lib.makeLibraryPath config.programs.nix-ld.libraries;
     };
 
     serviceConfig = {

From 8b205ea9f18ff00fb7852599bb8eb1ca3b30375b Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Sun, 3 May 2026 16:12:47 +0200
Subject: [PATCH 035/101] chore(opencode): switch to Qwen3-Coder-Next model

---
 config/opencode/config.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/config/opencode/config.json b/config/opencode/config.json
index e3ad78e..5ccb2c1 100644
--- a/config/opencode/config.json
+++ b/config/opencode/config.json
@@ -18,7 +18,7 @@
         "baseURL": "http://halo.fritz.box:8000/v1"
       },
       "models": {
-        "unsloth/gemma-4-26B-A4B-it-GGUF:UD-Q8_K_XL": {
+        "unsloth/Qwen3-Coder-Next-GGUF:UD-Q8_K_XL": {
           "name": "halo 8000"
         }
       }

From 0d5fb7302215f9731fb221428a821a57a5ad0c8b Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Sun, 3 May 2026 16:03:57 +0200
Subject: [PATCH 036/101] fix(amd): opencode

---
 systems/x86_64-linux/amd/acme.nix  | 8 ++++++++
 systems/x86_64-linux/amd/nginx.nix | 3 ++-
 2 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/systems/x86_64-linux/amd/acme.nix b/systems/x86_64-linux/amd/acme.nix
index fefc75d..ccc8d2e 100644
--- a/systems/x86_64-linux/amd/acme.nix
+++ b/systems/x86_64-linux/amd/acme.nix
@@ -8,4 +8,12 @@
   };
 
   metacfg.services.acmeBase.credentialsFile = config.sops.secrets.internetbs.path;
+
+    security.acme.certs = {
+    "amd.hoyer.world" = {
+      extraDomainNames = [
+        "opencode.amd.hoyer.world"
+      ];
+    };
+  };
 }
diff --git a/systems/x86_64-linux/amd/nginx.nix b/systems/x86_64-linux/amd/nginx.nix
index 1e0d0c5..79c8269 100644
--- a/systems/x86_64-linux/amd/nginx.nix
+++ b/systems/x86_64-linux/amd/nginx.nix
@@ -4,7 +4,8 @@
 {
   services.nginx.virtualHosts = {
     "opencode.amd.hoyer.world" = {
-      enableACME = true;
+      enableACME = false;
+      useACMEHost = "amd.hoyer.world";
       forceSSL = true;
       locations."/" = {
         proxyPass = "http://127.0.0.1:4196";

From 9f937cb7896acb61dc75e9ef03fa981c1333e46f Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Sun, 3 May 2026 16:37:30 +0200
Subject: [PATCH 037/101] chore(opencode): add disabled_providers config

---
 config/opencode/config.json | 1 +
 1 file changed, 1 insertion(+)

diff --git a/config/opencode/config.json b/config/opencode/config.json
index 5ccb2c1..eb650ac 100644
--- a/config/opencode/config.json
+++ b/config/opencode/config.json
@@ -1,5 +1,6 @@
 {
   "$schema": "https://opencode.ai/config.json",
+  "disabled_providers": ["opencode"],
   "provider": {
     "halo-8001": {
       "npm": "@ai-sdk/openai-compatible",

From 75d8b5354d0e7d390a5e8026b1b835f11a482a55 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Mon, 4 May 2026 08:44:12 +0200
Subject: [PATCH 038/101] chore: flake update

---
 flake.lock | 42 +++++++++++++++++++++---------------------
 1 file changed, 21 insertions(+), 21 deletions(-)

diff --git a/flake.lock b/flake.lock
index 42cc8f6..6dc3415 100644
--- a/flake.lock
+++ b/flake.lock
@@ -421,11 +421,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1777771528,
-        "narHash": "sha256-YycygK6n7KeW1YCobdFJcORWzkmrvNcp6xT+IovA0d4=",
+        "lastModified": 1777851538,
+        "narHash": "sha256-Gp8qwTEYNoy2yvmErVGlvLOQvrtEECCAKbonW7VJef8=",
         "owner": "nix-community",
         "repo": "home-manager",
-        "rev": "0585fbf645640973e3398863bbaf3bd1ddce4a51",
+        "rev": "cc09c0f9b7eaa95c2d9827338a5eb03d32505ca5",
         "type": "github"
       },
       "original": {
@@ -454,11 +454,11 @@
     "homebrew-cask": {
       "flake": false,
       "locked": {
-        "lastModified": 1777796563,
-        "narHash": "sha256-AbO+MovPEWCLyKIj60qUWOSqSbJSVoGhF28QnCqxv3A=",
+        "lastModified": 1777875832,
+        "narHash": "sha256-2XTprI5buyV39fjZSTqC6fPdZQlcdLFIv3zsMNWeJL0=",
         "owner": "homebrew",
         "repo": "homebrew-cask",
-        "rev": "1e45d507af08e3f0926d93efe8f29f3d8c045f3b",
+        "rev": "ed9506cba175d395f660d3834832dafd1f0cf4f9",
         "type": "github"
       },
       "original": {
@@ -470,11 +470,11 @@
     "homebrew-core": {
       "flake": false,
       "locked": {
-        "lastModified": 1777805875,
-        "narHash": "sha256-rq9WesmH4dJJl4xnQgBFqj4iGhoG7AOLR39dCdXRDwI=",
+        "lastModified": 1777876393,
+        "narHash": "sha256-z3jrwRPuBEie7xgDSfAyl0aU+dPh1cqBAmInuiHb0jE=",
         "owner": "homebrew",
         "repo": "homebrew-core",
-        "rev": "a3c27b663b8d8aa257a90b5463a41a6071d7b913",
+        "rev": "3fac814f714e58e4d0f10e423c80563cd99671f1",
         "type": "github"
       },
       "original": {
@@ -515,11 +515,11 @@
     },
     "mnw": {
       "locked": {
-        "lastModified": 1770419553,
-        "narHash": "sha256-b1XqsH7AtVf2dXmq2iyRr2NC1yG7skY7Z6N2MpWHlK4=",
+        "lastModified": 1777828893,
+        "narHash": "sha256-gVWVnmyNr74BVKfhMMZDWkhx2699dhmZ2g0W8TTHtkk=",
         "owner": "Gerg-L",
         "repo": "mnw",
-        "rev": "2aaffa8030d0b262176146adbb6b0e6374ce2957",
+        "rev": "c1c0b544bfabe6669b5a6a0383ccb475fe60258b",
         "type": "github"
       },
       "original": {
@@ -562,11 +562,11 @@
         "systems": "systems_2"
       },
       "locked": {
-        "lastModified": 1777478067,
-        "narHash": "sha256-2vZnUuv8fg2sIE6pXgGxZQQ3ZhQW1XE7Sxieg8gK2p4=",
+        "lastModified": 1777837065,
+        "narHash": "sha256-uRD6a4uNno3SsAw0E0E6xqbiK7pX63Ad1F37q5fyz9g=",
         "owner": "NotAShelf",
         "repo": "nvf",
-        "rev": "13c4ad4b4bb926c22945e2fb8862769fe51f27f1",
+        "rev": "7ec206a5d9a7d5d27900d81a6bb382823902276d",
         "type": "github"
       },
       "original": {
@@ -642,11 +642,11 @@
     },
     "nixpkgs_2": {
       "locked": {
-        "lastModified": 1777428379,
-        "narHash": "sha256-ypxFOeDz+CqADEQNL72haqGjvZQdBR5Vc7pyx2JDttI=",
+        "lastModified": 1777673416,
+        "narHash": "sha256-5c2POKPOjU40Kh0MirOdScBLG0bu9TAuPYAtPRNZMBs=",
         "owner": "nixos",
         "repo": "nixpkgs",
-        "rev": "755f5aa91337890c432639c60b6064bb7fe67769",
+        "rev": "26ef669cffa904b6f6832ab57b77892a37c1a671",
         "type": "github"
       },
       "original": {
@@ -749,11 +749,11 @@
         ]
       },
       "locked": {
-        "lastModified": 1777778183,
-        "narHash": "sha256-Lqv9MZO0XAGcMbXJU+ULBSMD41Pf391uJehylUQKe7Y=",
+        "lastModified": 1777864665,
+        "narHash": "sha256-oE4lnjiBa3uE+dP9jM0jFzofP1xYIlK6IQBjLfWjH04=",
         "owner": "oxalica",
         "repo": "rust-overlay",
-        "rev": "dbba5f888c82ef3ce594c451c33ac2474eb80847",
+        "rev": "669151bbc7f2416b622af2f48e9136e2c9da5530",
         "type": "github"
       },
       "original": {

From 624a72737ca81f6e4c3fa59a49a4a66ec13e1b01 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Mon, 4 May 2026 08:58:21 +0200
Subject: [PATCH 039/101] fix(opencode): narrow LD_LIBRARY_PATH to libstdc++
 only

The full nix-ld library list shadowed nix's own curl, breaking
libnixstore.so with "CURL_OPENSSL_4 not found". The prebuilt node
watcher binding only needs libstdc++/libgcc_s, so use stdenv.cc.cc.lib
and let nix-built tools resolve their own deps via RUNPATH.
---
 systems/x86_64-linux/amd/opencode.nix | 2 +-
 systems/x86_64-linux/sgx/opencode.nix | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/systems/x86_64-linux/amd/opencode.nix b/systems/x86_64-linux/amd/opencode.nix
index df23c73..d862c8c 100644
--- a/systems/x86_64-linux/amd/opencode.nix
+++ b/systems/x86_64-linux/amd/opencode.nix
@@ -35,7 +35,7 @@ in
 
     environment = {
       HOME = homeDir;
-      LD_LIBRARY_PATH = lib.makeLibraryPath config.programs.nix-ld.libraries;
+      LD_LIBRARY_PATH = "${pkgs.stdenv.cc.cc.lib}/lib";
     };
 
     serviceConfig = {
diff --git a/systems/x86_64-linux/sgx/opencode.nix b/systems/x86_64-linux/sgx/opencode.nix
index 1ec6438..0060f25 100644
--- a/systems/x86_64-linux/sgx/opencode.nix
+++ b/systems/x86_64-linux/sgx/opencode.nix
@@ -35,7 +35,7 @@ in
 
     environment = {
       HOME = homeDir;
-      LD_LIBRARY_PATH = lib.makeLibraryPath config.programs.nix-ld.libraries;
+      LD_LIBRARY_PATH = "${pkgs.stdenv.cc.cc.lib}/lib";
     };
 
     serviceConfig = {

From 603e435db8c91a158bf0650d97bc72ac783fbc34 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@subzero.xyz>
Date: Tue, 5 May 2026 10:34:07 +0200
Subject: [PATCH 040/101] chore: fix opencode model config

---
 config/opencode/config.json | 18 ++----------------
 1 file changed, 2 insertions(+), 16 deletions(-)

diff --git a/config/opencode/config.json b/config/opencode/config.json
index eb650ac..8f337b2 100644
--- a/config/opencode/config.json
+++ b/config/opencode/config.json
@@ -9,7 +9,7 @@
         "baseURL": "http://halo.fritz.box:8001/v1"
       },
       "models": {
-        "unsloth/Qwen3.6-35B-A3B-GGUF:UD-Q8_K_XL": { "name" : "halo 8001" }
+        "placeholder": { "name" : "halo 8001" }
       }
     },
     "halo-8000": {
@@ -19,21 +19,7 @@
         "baseURL": "http://halo.fritz.box:8000/v1"
       },
       "models": {
-        "unsloth/Qwen3-Coder-Next-GGUF:UD-Q8_K_XL": {
-          "name": "halo 8000"
-        }
-      }
-    },
-    "lmstudio-local": {
-      "npm": "@ai-sdk/openai-compatible",
-      "name": "LM Studio (local)",
-      "options": {
-        "baseURL": "http://127.0.0.1:1234/v1"
-      },
-      "models": {
-        "qwen3-coder-30b-a3b-instruct-mlx@6bit": {
-          "name": "qwen3-coder-30b-a3b-instruct-mlx@6bit"
-        }
+        "unsloth/Qwen3.6-35B-A3B-GGUF:UD-Q8_K_XL": { "name" : "qwen3.6-35B-A3B" }
       }
     }
   }

From b11e5c8356e264cf8c6e36a810ddbe863ea15de5 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Tue, 5 May 2026 10:02:51 +0200
Subject: [PATCH 041/101] feat(halo): add llama-server systemd unit for
 Qwen3.6-35B-A3B

Runs llama.cpp's ROCm build under DynamicUser, with the HF model cache
in StateDirectory (survives systemctl clean) and KV slot saves in
CacheDirectory. Listens on :8000.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 systems/x86_64-linux/halo/default.nix      |  1 +
 systems/x86_64-linux/halo/llama-server.nix | 60 ++++++++++++++++++++++
 2 files changed, 61 insertions(+)
 create mode 100644 systems/x86_64-linux/halo/llama-server.nix

diff --git a/systems/x86_64-linux/halo/default.nix b/systems/x86_64-linux/halo/default.nix
index eeb376c..1934cd8 100644
--- a/systems/x86_64-linux/halo/default.nix
+++ b/systems/x86_64-linux/halo/default.nix
@@ -10,6 +10,7 @@ with lib.metacfg;
     ./hardware-configuration.nix
     #./xremap.nix
     ./wyoming.nix
+    ./llama-server.nix
   ];
 
   boot.lanzaboote.pkiBundle = "/var/lib/sbctl";
diff --git a/systems/x86_64-linux/halo/llama-server.nix b/systems/x86_64-linux/halo/llama-server.nix
new file mode 100644
index 0000000..e55e08c
--- /dev/null
+++ b/systems/x86_64-linux/halo/llama-server.nix
@@ -0,0 +1,60 @@
+{
+  pkgs,
+  lib,
+  ...
+}:
+{
+  systemd.services.llama-server = {
+    description = "llama.cpp server (Qwen3.6-35B-A3B, ROCm)";
+    after = [ "network-online.target" ];
+    wants = [ "network-online.target" ];
+    wantedBy = [ "multi-user.target" ];
+
+    environment = {
+      HOME = "%S/llama-server";
+      HF_HOME = "%S/llama-server";
+      HSA_OVERRIDE_GFX_VERSION = lib.mkDefault "11.0.0";
+    };
+
+    serviceConfig = {
+      Type = "simple";
+      DynamicUser = true;
+      SupplementaryGroups = [
+        "video"
+        "render"
+      ];
+      StateDirectory = "llama-server";
+      CacheDirectory = "llama-server";
+      WorkingDirectory = "%S/llama-server";
+      ExecStartPre = "${pkgs.coreutils}/bin/mkdir -p %C/llama-server/kv-slots";
+      ExecStart = lib.concatStringsSep " " [
+        "${pkgs.llama-cpp-rocm}/bin/llama-server"
+        "--flash-attn on"
+        "--parallel 2"
+        "--jinja"
+        "--host 0.0.0.0"
+        "--port 8000"
+        "--no-mmap"
+        "--n-gpu-layers 99"
+        "-hf unsloth/Qwen3.6-35B-A3B-GGUF:UD-Q8_K_XL"
+        "--alias qwen3.6-35b-a3b"
+        "--threads 8"
+        "--ubatch-size 256"
+        "-ctk q8_0 -ctv q8_0"
+        "--temp 0.6 --top-p 0.95 --top-k 20 --min-p 0.00"
+        "--no-context-shift"
+        ''--chat-template-kwargs '{"preserve_thinking": true}' ''
+        "-c 524288"
+        "--fit on"
+        "--slot-save-path %C/llama-server/kv-slots"
+      ];
+      Restart = "on-failure";
+      RestartSec = 10;
+
+      PrivateTmp = true;
+      ProtectSystem = "strict";
+      ProtectHome = true;
+      NoNewPrivileges = true;
+    };
+  };
+}

From da88a9b2d66498f9832518a6297f48d244f51005 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Tue, 5 May 2026 10:41:05 +0200
Subject: [PATCH 042/101] fix(halo): drop speculative HSA_OVERRIDE_GFX_VERSION
 from llama-server

Was set defensively without knowing the actual GPU arch; if ROCm
supports the card natively, the override is at best a no-op and at
worst masks the real arch. Add it back with the right value if the
service actually fails to detect the GPU.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 systems/x86_64-linux/halo/llama-server.nix | 1 -
 1 file changed, 1 deletion(-)

diff --git a/systems/x86_64-linux/halo/llama-server.nix b/systems/x86_64-linux/halo/llama-server.nix
index e55e08c..9e655f1 100644
--- a/systems/x86_64-linux/halo/llama-server.nix
+++ b/systems/x86_64-linux/halo/llama-server.nix
@@ -13,7 +13,6 @@
     environment = {
       HOME = "%S/llama-server";
       HF_HOME = "%S/llama-server";
-      HSA_OVERRIDE_GFX_VERSION = lib.mkDefault "11.0.0";
     };
 
     serviceConfig = {

From dbbb150bccea76d8413a74c38c971fc8bc4fc1c7 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Tue, 5 May 2026 13:20:52 +0200
Subject: [PATCH 043/101] chore: refactor opencode service

---
 config/opencode/skills/ask-claude/SKILL.md | 149 +++++++++++++++++++++
 1 file changed, 149 insertions(+)
 create mode 100644 config/opencode/skills/ask-claude/SKILL.md

diff --git a/config/opencode/skills/ask-claude/SKILL.md b/config/opencode/skills/ask-claude/SKILL.md
new file mode 100644
index 0000000..b667eee
--- /dev/null
+++ b/config/opencode/skills/ask-claude/SKILL.md
@@ -0,0 +1,149 @@
+---
+name: ask-claude
+description: Consult Claude (Anthropic's flagship model, Opus-class) as an oracle when you are uncertain, stuck, or facing a problem that needs deeper reasoning than your current model provides. Trigger when you would otherwise guess, when the user asks a hard architectural / design / debugging question, when you have produced two contradictory hypotheses, or when a code review needs a second opinion. Calling out to `claude` gives you results from a much more intelligent model — use it instead of guessing.
+---
+
+# Ask Claude
+
+Run `claude -p "<prompt>"` via the `bash` tool to get a one-shot answer from
+Claude. Claude is significantly more capable at reasoning, code review, and
+architectural judgment than smaller models — when you are not sure, ask.
+
+## When to use
+
+- You are uncertain between two approaches and want a second opinion.
+- The user asked a question whose answer you would otherwise guess.
+- You have a tricky bug, a subtle race condition, or a non-obvious design call.
+- You want a code review on a diff before reporting "done".
+- You need a careful read of a long document or a hairy stack trace.
+
+Do **not** use it for trivial lookups (use `web-search`), simple file edits, or
+anything you are already confident about — calls cost money and time.
+
+## Basic invocation
+
+```bash
+claude -p "Your question here, with all relevant context inline."
+```
+
+The prompt should be **self-contained** — Claude starts with no memory of this
+conversation. Include the file paths, code snippets, error messages, and
+what you have already tried.
+
+## Piping context via stdin
+
+For longer context (a file, a diff, log output), pipe it in:
+
+```bash
+cat path/to/file.rs | claude -p "Review this for race conditions; explain any you find."
+```
+
+```bash
+git diff main...HEAD | claude -p "Spot bugs or risky changes in this diff."
+```
+
+## Permissions
+
+In `-p` mode there is no human to approve prompts, so anything not explicitly
+permitted is **denied**. Default behaviour: Claude can reason about the text
+you give it but cannot touch the filesystem, run shell commands, or hit the
+network. That is usually exactly what you want for an oracle call.
+
+When Claude does need tool access, you control it with these flags:
+
+### `--allowedTools` / `--disallowedTools`
+
+Whitelist or blacklist tools. Names are space- or comma-separated, and each
+entry can carry a permission spec in parentheses to narrow the scope.
+
+```bash
+# Read-only project access — the most common upgrade
+claude -p --allowedTools "Read Grep Glob" "..."
+
+# Allow only specific bash subcommands
+claude -p --allowedTools "Read Grep Glob Bash(git diff:*) Bash(git log:*)" "..."
+
+# Allow web fetches, but only to one domain
+claude -p --allowedTools "WebFetch(domain:docs.python.org)" "..."
+
+# Block one tool, allow the rest of the defaults
+claude -p --disallowedTools "Bash" "..."
+```
+
+Spec syntax cheatsheet:
+- `Bash` — every shell command (broad; avoid).
+- `Bash(git *)` — any `git` invocation.
+- `Bash(git diff:*)` — `git diff` and its sub-args only.
+- `Read` / `Grep` / `Glob` — usually safe to allow whole.
+- `Edit(./src/**)` / `Write(./src/**)` — directory-scoped writes.
+- `WebFetch(domain:example.com)` — pin web access to one host.
+
+### `--tools`
+
+Coarser switch over the built-in toolset. Use `--tools ""` to disable
+**everything** built-in (only MCP tools and what `--allowedTools` adds), or
+`--tools "Read,Edit,Bash"` to pick a subset. `--allowedTools` then layers on
+top with finer-grained specs.
+
+### `--permission-mode <mode>`
+
+Sets the default behaviour for anything not covered by allow/disallow:
+
+| Mode                | Effect                                                       |
+|---------------------|--------------------------------------------------------------|
+| `default`           | prompt; in `-p` mode this means "deny" (no human present).   |
+| `dontAsk`           | silently deny anything not pre-allowed — clean for `-p`.     |
+| `plan`              | read-only planning; Claude proposes but cannot edit or run.  |
+| `acceptEdits`       | auto-accept file edits; still prompts for Bash etc.          |
+| `auto`              | model decides per-call; treat as semi-trusted.               |
+| `bypassPermissions` | skip all checks. Equivalent to `--dangerously-skip-permissions`. |
+
+```bash
+# Strict deny-by-default with an explicit allowlist (recommended for -p)
+claude -p --permission-mode dontAsk \
+  --allowedTools "Read Grep Glob" \
+  "Audit error handling in src/auth/."
+
+# Plan mode for a design review — Claude reads, thinks, won't touch anything
+claude -p --permission-mode plan "Propose a refactor for X."
+```
+
+### `--add-dir`
+
+Without it Claude only sees the current working directory. Add others when
+the question spans repos:
+
+```bash
+claude -p --allowedTools "Read Grep Glob" \
+  --add-dir ../other-repo --add-dir /etc/nixos \
+  "Compare how both projects handle config loading."
+```
+
+### `--dangerously-skip-permissions`
+
+Bypasses all checks. Only use inside a sandbox with no network and no secrets
+mounted. For oracle-style calls there is essentially no reason to set this —
+if Claude needs to do destructive things, you should be doing them, not it.
+
+### Cost and model controls
+
+These are not permissions but belong in the same risk-management box:
+
+- `--model opus` / `--model sonnet` — pick the tier. Opus for hard reasoning,
+  Sonnet when speed/cost matters.
+- `--output-format json` — stable structured output for piping into `jq`.
+
+## Output
+
+Default output is plain text on stdout, suitable for piping or for showing to
+the user. For machine-readable output use `--output-format json` and parse
+with `jq`.
+
+## Don'ts
+
+- Don't call `claude -p` in a loop or for trivial questions — it is expensive.
+- Don't pass the entire conversation history; distill the question first.
+- Don't ask Claude to "do" multi-step refactors with file writes — collect its
+  recommendations and apply them yourself, so you stay in control.
+- Don't forget that Claude has no memory between calls — every invocation
+  needs the full context.

From 3a1cb7487a9bff28bcaf106308e8a1d1a3eff685 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Tue, 5 May 2026 13:42:52 +0200
Subject: [PATCH 044/101] refactor(opencode): extract serve service into shared
 NixOS module

New `metacfg.services.opencode` module under modules/nixos/services/opencode/
with options for port, user, homeDir, sopsFile, and extraPackages. User and
homeDir default off `metacfg.user`. Host configs for amd and sgx reduce to
enabling the module and pointing at their respective sops file.

Service PATH gains jq, yq-go, python3, gh, gnutar, gzip, unzip, wget,
diffutils, patch, file, tree, bun, uv, ast-grep, claude-code, and tmux for
agent ergonomics.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 modules/nixos/services/opencode/default.nix | 115 ++++++++++++++++++++
 systems/x86_64-linux/amd/opencode.nix       |  60 +---------
 systems/x86_64-linux/sgx/opencode.nix       |  60 +---------
 3 files changed, 119 insertions(+), 116 deletions(-)
 create mode 100644 modules/nixos/services/opencode/default.nix

diff --git a/modules/nixos/services/opencode/default.nix b/modules/nixos/services/opencode/default.nix
new file mode 100644
index 0000000..d6473c6
--- /dev/null
+++ b/modules/nixos/services/opencode/default.nix
@@ -0,0 +1,115 @@
+{
+  config,
+  pkgs,
+  lib,
+  ...
+}:
+with lib;
+with lib.metacfg;
+let
+  cfg = config.metacfg.services.opencode;
+in
+{
+  options.metacfg.services.opencode = with types; {
+    enable = mkBoolOpt false "Whether or not to enable the OpenCode web server.";
+    port = mkOption {
+      type = types.port;
+      default = 4196;
+      description = "Port for the OpenCode web server to listen on.";
+    };
+    user = mkOption {
+      type = types.str;
+      default = config.metacfg.user.name;
+      defaultText = literalExpression "config.metacfg.user.name";
+      description = "User to run the OpenCode service as.";
+    };
+    homeDir = mkOption {
+      type = types.path;
+      default = config.users.users.${cfg.user}.home;
+      defaultText = literalExpression "config.users.users.\${cfg.user}.home";
+      description = "Home directory used as the working directory for the service.";
+    };
+    sopsFile = mkOption {
+      type = types.path;
+      description = "Path to the sops-encrypted yaml file containing opencode-web-password.";
+    };
+    extraPackages = mkOption {
+      type = types.listOf types.package;
+      default = [ ];
+      description = "Additional packages to add to the service PATH.";
+    };
+  };
+
+  config = mkIf cfg.enable {
+    systemd.services.opencode-serve = {
+      description = "OpenCode Web Server";
+      after = [ "network.target" ];
+      wantedBy = [ "multi-user.target" ];
+
+      path =
+        (with pkgs; [
+          git
+          bash
+          coreutils
+          findutils
+          gnused
+          gnugrep
+          gawk
+          gnumake
+          nix
+          nodejs
+          ripgrep
+          fd
+          curl
+          which
+          jq
+          yq-go
+          python3
+          gh
+          gnutar
+          gzip
+          unzip
+          wget
+          diffutils
+          patch
+          file
+          tree
+          bun
+          uv
+          ast-grep
+          claude-code
+          tmux
+        ])
+        ++ cfg.extraPackages;
+
+      environment = {
+        HOME = cfg.homeDir;
+        LD_LIBRARY_PATH = "${pkgs.stdenv.cc.cc.lib}/lib";
+      };
+
+      serviceConfig = {
+        Type = "simple";
+        User = cfg.user;
+        Group = "users";
+        WorkingDirectory = cfg.homeDir;
+        ExecStart = "${pkgs.opencode}/bin/opencode serve --hostname 127.0.0.1 --port ${toString cfg.port}";
+        Restart = "always";
+        RestartSec = 5;
+        EnvironmentFile = config.sops.secrets.opencode-web-password.path;
+
+        # Security hardening
+        PrivateTmp = true;
+        ProtectSystem = "strict";
+        ProtectHome = false;
+        NoNewPrivileges = true;
+        ReadWritePaths = [ cfg.homeDir ];
+      };
+    };
+
+    sops.secrets.opencode-web-password = {
+      inherit (cfg) sopsFile;
+      owner = cfg.user;
+      restartUnits = [ "opencode-serve.service" ];
+    };
+  };
+}
diff --git a/systems/x86_64-linux/amd/opencode.nix b/systems/x86_64-linux/amd/opencode.nix
index d862c8c..6e3242c 100644
--- a/systems/x86_64-linux/amd/opencode.nix
+++ b/systems/x86_64-linux/amd/opencode.nix
@@ -1,65 +1,9 @@
 {
-  config,
-  pkgs,
-  lib,
   ...
 }:
-
-let
-  port = 4196;
-  user = "harald";
-  homeDir = "/home/harald";
-in
 {
-  systemd.services.opencode-serve = {
-    description = "OpenCode Web Server";
-    after = [ "network.target" ];
-    wantedBy = [ "multi-user.target" ];
-
-    path = with pkgs; [
-      git
-      bash
-      coreutils
-      findutils
-      gnused
-      gnugrep
-      gawk
-      gnumake
-      nix
-      nodejs
-      ripgrep
-      fd
-      curl
-      which
-    ];
-
-    environment = {
-      HOME = homeDir;
-      LD_LIBRARY_PATH = "${pkgs.stdenv.cc.cc.lib}/lib";
-    };
-
-    serviceConfig = {
-      Type = "simple";
-      User = user;
-      Group = "users";
-      WorkingDirectory = homeDir;
-      ExecStart = "${pkgs.opencode}/bin/opencode serve --hostname 127.0.0.1 --port ${toString port}";
-      Restart = "always";
-      RestartSec = 5;
-      EnvironmentFile = config.sops.secrets.opencode-web-password.path;
-
-      # Security hardening
-      PrivateTmp = true;
-      ProtectSystem = "strict";
-      ProtectHome = false;
-      NoNewPrivileges = true;
-      ReadWritePaths = [ homeDir ];
-    };
-  };
-
-  sops.secrets.opencode-web-password = {
+  metacfg.services.opencode = {
+    enable = true;
     sopsFile = ../../../.secrets/amd/opencode-web.yaml;
-    owner = user;
-    restartUnits = [ "opencode-serve.service" ];
   };
 }
diff --git a/systems/x86_64-linux/sgx/opencode.nix b/systems/x86_64-linux/sgx/opencode.nix
index 0060f25..f04fd1b 100644
--- a/systems/x86_64-linux/sgx/opencode.nix
+++ b/systems/x86_64-linux/sgx/opencode.nix
@@ -1,65 +1,9 @@
 {
-  config,
-  pkgs,
-  lib,
   ...
 }:
-
-let
-  port = 4196;
-  user = "harald";
-  homeDir = "/home/harald";
-in
 {
-  systemd.services.opencode-serve = {
-    description = "OpenCode Web Server";
-    after = [ "network.target" ];
-    wantedBy = [ "multi-user.target" ];
-
-    path = with pkgs; [
-      git
-      bash
-      coreutils
-      findutils
-      gnused
-      gnugrep
-      gawk
-      gnumake
-      nix
-      nodejs
-      ripgrep
-      fd
-      curl
-      which
-    ];
-
-    environment = {
-      HOME = homeDir;
-      LD_LIBRARY_PATH = "${pkgs.stdenv.cc.cc.lib}/lib";
-    };
-
-    serviceConfig = {
-      Type = "simple";
-      User = user;
-      Group = "users";
-      WorkingDirectory = homeDir;
-      ExecStart = "${pkgs.opencode}/bin/opencode serve --hostname 127.0.0.1 --port ${toString port}";
-      Restart = "always";
-      RestartSec = 5;
-      EnvironmentFile = config.sops.secrets.opencode-web-password.path;
-
-      # Security hardening
-      PrivateTmp = true;
-      ProtectSystem = "strict";
-      ProtectHome = false;
-      NoNewPrivileges = true;
-      ReadWritePaths = [ homeDir ];
-    };
-  };
-
-  sops.secrets.opencode-web-password = {
+  metacfg.services.opencode = {
+    enable = true;
     sopsFile = ../../../.secrets/sgx/opencode-web.yaml;
-    owner = user;
-    restartUnits = [ "opencode-serve.service" ];
   };
 }

From 425ee187cf729d0421847496871bc47f18986a8b Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Tue, 5 May 2026 13:43:08 +0200
Subject: [PATCH 045/101] chore(opencode): re-order models

---
 config/opencode/config.json | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/config/opencode/config.json b/config/opencode/config.json
index 8f337b2..296d75a 100644
--- a/config/opencode/config.json
+++ b/config/opencode/config.json
@@ -2,16 +2,6 @@
   "$schema": "https://opencode.ai/config.json",
   "disabled_providers": ["opencode"],
   "provider": {
-    "halo-8001": {
-      "npm": "@ai-sdk/openai-compatible",
-      "name": "Halo (8001)",
-      "options": {
-        "baseURL": "http://halo.fritz.box:8001/v1"
-      },
-      "models": {
-        "placeholder": { "name" : "halo 8001" }
-      }
-    },
     "halo-8000": {
       "npm": "@ai-sdk/openai-compatible",
       "name": "Halo (8000)",
@@ -21,6 +11,16 @@
       "models": {
         "unsloth/Qwen3.6-35B-A3B-GGUF:UD-Q8_K_XL": { "name" : "qwen3.6-35B-A3B" }
       }
+    },
+    "halo-8001": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "Halo (8001)",
+      "options": {
+        "baseURL": "http://halo.fritz.box:8001/v1"
+      },
+      "models": {
+        "placeholder": { "name" : "halo 8001" }
+      }
     }
-  }
+ }
 }

From 5d0e1fcdd629a7d49c866220468207009e46c8bb Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Tue, 5 May 2026 13:56:40 +0200
Subject: [PATCH 046/101] docs(opencode): steer ask-claude skill toward repo
 access for reviews

Add a "Code review pattern" section that tells the opencode agent to give
claude read-only access to the repo (Read/Grep/Glob plus a narrow git
allowlist) instead of gathering a full `git diff` and piping it in. The
piped-diff form loses surrounding-file context, bloats the prompt, and
falls over on large branches. Also adds a matching entry to "Don'ts" and
caveats the existing pipe-stdin example.

Motivated by an opencode run that collected the entire branch diff as
stdin instead of pointing claude at the working tree.
---
 config/opencode/skills/ask-claude/SKILL.md | 37 ++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/config/opencode/skills/ask-claude/SKILL.md b/config/opencode/skills/ask-claude/SKILL.md
index b667eee..cf5d8a1 100644
--- a/config/opencode/skills/ask-claude/SKILL.md
+++ b/config/opencode/skills/ask-claude/SKILL.md
@@ -42,6 +42,40 @@ cat path/to/file.rs | claude -p "Review this for race conditions; explain any yo
 git diff main...HEAD | claude -p "Spot bugs or risky changes in this diff."
 ```
 
+Only pipe when the context is small and self-contained. For anything that
+spans multiple files, prefer giving Claude repo access (next section) so it
+can read surrounding code, not just the patch.
+
+## Code review pattern
+
+For a review of the current branch / working tree, **do not** gather diffs
+yourself and stuff them into the prompt. Point Claude at the directory and
+let it run `git` and read files on its own — it sees more context (full
+files, history, neighbouring code) than a piped diff alone can provide,
+and it will only fetch what it actually needs.
+
+Recommended invocation, run from the repo root:
+
+```bash
+claude -p --permission-mode dontAsk \
+  --allowedTools "Read Grep Glob Bash(git diff:*) Bash(git log:*) Bash(git status:*) Bash(git show:*)" \
+  "Review the changes on this branch vs main. Flag bugs, risky changes,
+   and anything that violates the project's conventions. Read whatever
+   files you need for context."
+```
+
+Why this is better than `git diff … | claude -p`:
+
+- Claude can open the *full* file around a hunk, not just the ±3 lines of
+  context in the patch.
+- Claude can follow references — call sites, tests, related modules.
+- The prompt stays small, so the model spends its tokens on reasoning
+  instead of re-reading a diff you already had on disk.
+- Works for large diffs that would otherwise blow the context window.
+
+Use the piped form only for a tiny, self-contained snippet where extra
+repo context genuinely adds nothing.
+
 ## Permissions
 
 In `-p` mode there is no human to approve prompts, so anything not explicitly
@@ -143,6 +177,9 @@ with `jq`.
 
 - Don't call `claude -p` in a loop or for trivial questions — it is expensive.
 - Don't pass the entire conversation history; distill the question first.
+- Don't gather a giant `git diff` and pipe it in for code review — give
+  Claude read-only repo access (see "Code review pattern") and let it pull
+  exactly the context it needs.
 - Don't ask Claude to "do" multi-step refactors with file writes — collect its
   recommendations and apply them yourself, so you stay in control.
 - Don't forget that Claude has no memory between calls — every invocation

From ba396eed1210021279cb370eef647cc134cb2de0 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Tue, 5 May 2026 14:03:44 +0200
Subject: [PATCH 047/101] feat(claude-code): manage commands and skills via
 home-manager

Add a home-manager module that symlinks config/claude/commands and
config/claude/skills into ~/.claude, mirroring the opencode module.
Seed the commands directory with a /commit slash command.
---
 config/claude/commands/commit.md              | 55 +++++++++++++++++++
 modules/home/cli-apps/claude-code/default.nix | 27 +++++++++
 2 files changed, 82 insertions(+)
 create mode 100644 config/claude/commands/commit.md
 create mode 100644 modules/home/cli-apps/claude-code/default.nix

diff --git a/config/claude/commands/commit.md b/config/claude/commands/commit.md
new file mode 100644
index 0000000..0c68b73
--- /dev/null
+++ b/config/claude/commands/commit.md
@@ -0,0 +1,55 @@
+Create a git commit following the project's conventional commit message conventions.
+
+## Instructions
+
+1. **Check git status and staged changes**:
+   - Run `git status` to see all untracked files
+   - Run `git diff --cached` to see staged changes 
+   - Run `git diff` to see unstaged changes
+
+2. **Stage relevant files**:
+   - Add any untracked files that should be committed
+   - Stage any unstaged changes that should be included
+
+3. **Analyze changes and create commit message**:
+   - Follow the conventional commit format from CLAUDE.md:
+     - `feat:` (new feature for the user)
+     - `fix:` (bug fix for the user)
+     - `docs:` (changes to the documentation)
+     - `style:` (formatting, missing semi colons, etc)
+     - `refactor:` (refactoring production code)
+     - `test:` (adding missing tests, refactoring tests)
+     - `chore:` (updating grunt tasks etc; no production code change)
+   - Write a clear, concise commit message that describes the "why" not just the "what"
+   - Focus on the purpose and impact of the changes
+
+4. **Create the commit**:
+   - Use the conventional commit format
+   - Do not add the Claude Code signature
+
+5. **Verify the commit**:
+   - Run `git status` to confirm the commit succeeded
+   - If pre-commit hooks modify files, amend the commit to include those changes
+
+## Message Format
+
+The commit message should be passed via HEREDOC for proper formatting:
+
+```bash
+git commit -m "$(cat <<'EOF'
+<type>: <description>
+
+<optional body>
+
+EOF
+)"
+```
+
+## Additional Context
+
+Optional commit message details: $ARGUMENTS
+
+**Important**: Never update git config, never use interactive flags like `-i`, and don't push unless explicitly requested.
+
+If the changes are complex, pass enough information for a reviewer in the message body. Reference relevant design documents
+or documentation files, which can help a reviewing AI agent to build enough context for a successful review.
diff --git a/modules/home/cli-apps/claude-code/default.nix b/modules/home/cli-apps/claude-code/default.nix
new file mode 100644
index 0000000..b7eafe5
--- /dev/null
+++ b/modules/home/cli-apps/claude-code/default.nix
@@ -0,0 +1,27 @@
+{
+  lib,
+  config,
+  ...
+}:
+let
+  inherit (lib) mkIf;
+  inherit (lib.metacfg) mkBoolOpt;
+
+  cfg = config.metacfg.cli-apps.claude-code;
+in
+{
+  options.metacfg.cli-apps.claude-code = {
+    enable = mkBoolOpt true "Enable claude-code config.";
+  };
+
+  config = mkIf cfg.enable {
+    home.file.".claude/commands" = {
+      source = ../../../../config/claude/commands;
+      recursive = true;
+    };
+    home.file.".claude/skills" = {
+      source = ../../../../config/claude/skills;
+      recursive = true;
+    };
+  };
+}

From 2a389a49b28d486af9848d7c2d27f355db669cf0 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Tue, 5 May 2026 14:08:23 +0200
Subject: [PATCH 048/101] fix(claude-code): track empty skills dir so flake
 source resolves

Git doesn't track empty directories, so config/claude/skills was missing
from the Nix store source path, breaking home.file.".claude/skills"
evaluation. Add a .gitkeep to keep the directory present until real
skills are added.
---
 config/claude/skills/.gitkeep | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 config/claude/skills/.gitkeep

diff --git a/config/claude/skills/.gitkeep b/config/claude/skills/.gitkeep
new file mode 100644
index 0000000..e69de29

From 77b7cd6259e11bc1de48fff8ed0545956b12c604 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@subzero.xyz>
Date: Tue, 5 May 2026 14:09:42 +0200
Subject: [PATCH 049/101] feat: add more claude skills

---
 config/claude/skills/grill-me/SKILL.md      |  10 ++
 config/claude/skills/write-a-skill/SKILL.md | 117 ++++++++++++++++++++
 2 files changed, 127 insertions(+)
 create mode 100644 config/claude/skills/grill-me/SKILL.md
 create mode 100644 config/claude/skills/write-a-skill/SKILL.md

diff --git a/config/claude/skills/grill-me/SKILL.md b/config/claude/skills/grill-me/SKILL.md
new file mode 100644
index 0000000..bd04394
--- /dev/null
+++ b/config/claude/skills/grill-me/SKILL.md
@@ -0,0 +1,10 @@
+---
+name: grill-me
+description: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".
+---
+
+Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions one at a time.
+
+If a question can be answered by exploring the codebase, explore the codebase instead.
diff --git a/config/claude/skills/write-a-skill/SKILL.md b/config/claude/skills/write-a-skill/SKILL.md
new file mode 100644
index 0000000..7339c8a
--- /dev/null
+++ b/config/claude/skills/write-a-skill/SKILL.md
@@ -0,0 +1,117 @@
+---
+name: write-a-skill
+description: Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill.
+---
+
+# Writing Skills
+
+## Process
+
+1. **Gather requirements** - ask user about:
+   - What task/domain does the skill cover?
+   - What specific use cases should it handle?
+   - Does it need executable scripts or just instructions?
+   - Any reference materials to include?
+
+2. **Draft the skill** - create:
+   - SKILL.md with concise instructions
+   - Additional reference files if content exceeds 500 lines
+   - Utility scripts if deterministic operations needed
+
+3. **Review with user** - present draft and ask:
+   - Does this cover your use cases?
+   - Anything missing or unclear?
+   - Should any section be more/less detailed?
+
+## Skill Structure
+
+```
+skill-name/
+├── SKILL.md           # Main instructions (required)
+├── REFERENCE.md       # Detailed docs (if needed)
+├── EXAMPLES.md        # Usage examples (if needed)
+└── scripts/           # Utility scripts (if needed)
+    └── helper.js
+```
+
+## SKILL.md Template
+
+```md
+---
+name: skill-name
+description: Brief description of capability. Use when [specific triggers].
+---
+
+# Skill Name
+
+## Quick start
+
+[Minimal working example]
+
+## Workflows
+
+[Step-by-step processes with checklists for complex tasks]
+
+## Advanced features
+
+[Link to separate files: See [REFERENCE.md](REFERENCE.md)]
+```
+
+## Description Requirements
+
+The description is **the only thing your agent sees** when deciding which skill to load. It's surfaced in the system prompt alongside all other installed skills. Your agent reads these descriptions and picks the relevant skill based on the user's request.
+
+**Goal**: Give your agent just enough info to know:
+
+1. What capability this skill provides
+2. When/why to trigger it (specific keywords, contexts, file types)
+
+**Format**:
+
+- Max 1024 chars
+- Write in third person
+- First sentence: what it does
+- Second sentence: "Use when [specific triggers]"
+
+**Good example**:
+
+```
+Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.
+```
+
+**Bad example**:
+
+```
+Helps with documents.
+```
+
+The bad example gives your agent no way to distinguish this from other document skills.
+
+## When to Add Scripts
+
+Add utility scripts when:
+
+- Operation is deterministic (validation, formatting)
+- Same code would be generated repeatedly
+- Errors need explicit handling
+
+Scripts save tokens and improve reliability vs generated code.
+
+## When to Split Files
+
+Split into separate files when:
+
+- SKILL.md exceeds 100 lines
+- Content has distinct domains (finance vs sales schemas)
+- Advanced features are rarely needed
+
+## Review Checklist
+
+After drafting, verify:
+
+- [ ] Description includes triggers ("Use when...")
+- [ ] SKILL.md under 100 lines
+- [ ] No time-sensitive info
+- [ ] Consistent terminology
+- [ ] Concrete examples included
+- [ ] References one level deep

From b4f1514df1fdb41064ce8523c568ecd2afb560b7 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@subzero.xyz>
Date: Tue, 5 May 2026 14:13:16 +0200
Subject: [PATCH 050/101] feat: opencode skills

---
 config/opencode/skills/grill-me/SKILL.md      |  10 ++
 config/opencode/skills/write-a-skill/SKILL.md | 117 ++++++++++++++++++
 2 files changed, 127 insertions(+)
 create mode 100644 config/opencode/skills/grill-me/SKILL.md
 create mode 100644 config/opencode/skills/write-a-skill/SKILL.md

diff --git a/config/opencode/skills/grill-me/SKILL.md b/config/opencode/skills/grill-me/SKILL.md
new file mode 100644
index 0000000..bd04394
--- /dev/null
+++ b/config/opencode/skills/grill-me/SKILL.md
@@ -0,0 +1,10 @@
+---
+name: grill-me
+description: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".
+---
+
+Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions one at a time.
+
+If a question can be answered by exploring the codebase, explore the codebase instead.
diff --git a/config/opencode/skills/write-a-skill/SKILL.md b/config/opencode/skills/write-a-skill/SKILL.md
new file mode 100644
index 0000000..7339c8a
--- /dev/null
+++ b/config/opencode/skills/write-a-skill/SKILL.md
@@ -0,0 +1,117 @@
+---
+name: write-a-skill
+description: Create new agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill.
+---
+
+# Writing Skills
+
+## Process
+
+1. **Gather requirements** - ask user about:
+   - What task/domain does the skill cover?
+   - What specific use cases should it handle?
+   - Does it need executable scripts or just instructions?
+   - Any reference materials to include?
+
+2. **Draft the skill** - create:
+   - SKILL.md with concise instructions
+   - Additional reference files if content exceeds 500 lines
+   - Utility scripts if deterministic operations needed
+
+3. **Review with user** - present draft and ask:
+   - Does this cover your use cases?
+   - Anything missing or unclear?
+   - Should any section be more/less detailed?
+
+## Skill Structure
+
+```
+skill-name/
+├── SKILL.md           # Main instructions (required)
+├── REFERENCE.md       # Detailed docs (if needed)
+├── EXAMPLES.md        # Usage examples (if needed)
+└── scripts/           # Utility scripts (if needed)
+    └── helper.js
+```
+
+## SKILL.md Template
+
+```md
+---
+name: skill-name
+description: Brief description of capability. Use when [specific triggers].
+---
+
+# Skill Name
+
+## Quick start
+
+[Minimal working example]
+
+## Workflows
+
+[Step-by-step processes with checklists for complex tasks]
+
+## Advanced features
+
+[Link to separate files: See [REFERENCE.md](REFERENCE.md)]
+```
+
+## Description Requirements
+
+The description is **the only thing your agent sees** when deciding which skill to load. It's surfaced in the system prompt alongside all other installed skills. Your agent reads these descriptions and picks the relevant skill based on the user's request.
+
+**Goal**: Give your agent just enough info to know:
+
+1. What capability this skill provides
+2. When/why to trigger it (specific keywords, contexts, file types)
+
+**Format**:
+
+- Max 1024 chars
+- Write in third person
+- First sentence: what it does
+- Second sentence: "Use when [specific triggers]"
+
+**Good example**:
+
+```
+Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.
+```
+
+**Bad example**:
+
+```
+Helps with documents.
+```
+
+The bad example gives your agent no way to distinguish this from other document skills.
+
+## When to Add Scripts
+
+Add utility scripts when:
+
+- Operation is deterministic (validation, formatting)
+- Same code would be generated repeatedly
+- Errors need explicit handling
+
+Scripts save tokens and improve reliability vs generated code.
+
+## When to Split Files
+
+Split into separate files when:
+
+- SKILL.md exceeds 100 lines
+- Content has distinct domains (finance vs sales schemas)
+- Advanced features are rarely needed
+
+## Review Checklist
+
+After drafting, verify:
+
+- [ ] Description includes triggers ("Use when...")
+- [ ] SKILL.md under 100 lines
+- [ ] No time-sensitive info
+- [ ] Consistent terminology
+- [ ] Concrete examples included
+- [ ] References one level deep

From 289920b726cc458eabe2e914a6a629eaba22bf06 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@subzero.xyz>
Date: Tue, 5 May 2026 14:14:25 +0200
Subject: [PATCH 051/101] feat: add opencode commands

---
 config/opencode/commands/commit.md | 55 ++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)
 create mode 100644 config/opencode/commands/commit.md

diff --git a/config/opencode/commands/commit.md b/config/opencode/commands/commit.md
new file mode 100644
index 0000000..0c68b73
--- /dev/null
+++ b/config/opencode/commands/commit.md
@@ -0,0 +1,55 @@
+Create a git commit following the project's conventional commit message conventions.
+
+## Instructions
+
+1. **Check git status and staged changes**:
+   - Run `git status` to see all untracked files
+   - Run `git diff --cached` to see staged changes 
+   - Run `git diff` to see unstaged changes
+
+2. **Stage relevant files**:
+   - Add any untracked files that should be committed
+   - Stage any unstaged changes that should be included
+
+3. **Analyze changes and create commit message**:
+   - Follow the conventional commit format from CLAUDE.md:
+     - `feat:` (new feature for the user)
+     - `fix:` (bug fix for the user)
+     - `docs:` (changes to the documentation)
+     - `style:` (formatting, missing semi colons, etc)
+     - `refactor:` (refactoring production code)
+     - `test:` (adding missing tests, refactoring tests)
+     - `chore:` (updating grunt tasks etc; no production code change)
+   - Write a clear, concise commit message that describes the "why" not just the "what"
+   - Focus on the purpose and impact of the changes
+
+4. **Create the commit**:
+   - Use the conventional commit format
+   - Do not add the Claude Code signature
+
+5. **Verify the commit**:
+   - Run `git status` to confirm the commit succeeded
+   - If pre-commit hooks modify files, amend the commit to include those changes
+
+## Message Format
+
+The commit message should be passed via HEREDOC for proper formatting:
+
+```bash
+git commit -m "$(cat <<'EOF'
+<type>: <description>
+
+<optional body>
+
+EOF
+)"
+```
+
+## Additional Context
+
+Optional commit message details: $ARGUMENTS
+
+**Important**: Never update git config, never use interactive flags like `-i`, and don't push unless explicitly requested.
+
+If the changes are complex, pass enough information for a reviewer in the message body. Reference relevant design documents
+or documentation files, which can help a reviewing AI agent to build enough context for a successful review.

From 471b5a4f117de79053a1354e00f89cce5e6ae48c Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@subzero.xyz>
Date: Tue, 5 May 2026 14:15:50 +0200
Subject: [PATCH 052/101] feat: map ./config/claude to ~/.claude

---
 modules/home/cli-apps/claude-code/default.nix | 8 ++------
 1 file changed, 2 insertions(+), 6 deletions(-)

diff --git a/modules/home/cli-apps/claude-code/default.nix b/modules/home/cli-apps/claude-code/default.nix
index b7eafe5..0d97eb5 100644
--- a/modules/home/cli-apps/claude-code/default.nix
+++ b/modules/home/cli-apps/claude-code/default.nix
@@ -15,12 +15,8 @@ in
   };
 
   config = mkIf cfg.enable {
-    home.file.".claude/commands" = {
-      source = ../../../../config/claude/commands;
-      recursive = true;
-    };
-    home.file.".claude/skills" = {
-      source = ../../../../config/claude/skills;
+    home.file.".claude" = {
+      source = ../../../../config/claude;
       recursive = true;
     };
   };

From 393ff652c74acb4a6457104baa7fe5262928aa93 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Tue, 5 May 2026 14:20:00 +0200
Subject: [PATCH 053/101] fix: add ssh key

---
 modules/common.nix | 1 +
 1 file changed, 1 insertion(+)

diff --git a/modules/common.nix b/modules/common.nix
index 35dd320..33051a5 100644
--- a/modules/common.nix
+++ b/modules/common.nix
@@ -5,5 +5,6 @@ _: {
     "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIMNsmP15vH8BVKo7bdvIiiEjiQboPGcRPqJK0+bH4jKD harald@lenovo.fritz.box"
     "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBEd2N6QSpuAXOXmSN5p2MPKyWe+oT5ayMBoRN3rCz/FS6ZI8PG2tntEte8+hkW7X0vA2dtB3aj2jWbqUJoQ8wKs= s22@termux"
     "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBAH8LCzJ6NmkiLAIcoiIcu0CCsH1BsctvbuK6pExVtDzRVkENqcaQn6gjUpJ3k7RRdljJJ91irgtu8yDdyqtaFs="
+    "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBE4bD16NjnQFtUbrwyiGqEXwzz0HAqmicc+0QVn1Dx2cOei6t17Bd5a90qZeAmWkOV9Egd/OqIdlJYvzfT7UZkM="
   ];
 }

From 927e575828bb608a2fdf5fbeee5c8943789c8549 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Tue, 5 May 2026 14:43:18 +0200
Subject: [PATCH 054/101] fix(opencode): require `--` before prompt in
 ask-claude skill

Variadic flags like --allowedTools and --add-dir were silently swallowing
the trailing prompt, causing `claude -p` to fail with "Input must be
provided through stdin or as a prompt argument". Mandate a uniform
`claude -p [flags] -- "<prompt>"` shape and document the gotcha.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 config/opencode/skills/ask-claude/SKILL.md | 61 ++++++++++++++++------
 1 file changed, 45 insertions(+), 16 deletions(-)

diff --git a/config/opencode/skills/ask-claude/SKILL.md b/config/opencode/skills/ask-claude/SKILL.md
index cf5d8a1..9b0afde 100644
--- a/config/opencode/skills/ask-claude/SKILL.md
+++ b/config/opencode/skills/ask-claude/SKILL.md
@@ -5,9 +5,9 @@ description: Consult Claude (Anthropic's flagship model, Opus-class) as an oracl
 
 # Ask Claude
 
-Run `claude -p "<prompt>"` via the `bash` tool to get a one-shot answer from
-Claude. Claude is significantly more capable at reasoning, code review, and
-architectural judgment than smaller models — when you are not sure, ask.
+Run `claude -p -- "<prompt>"` via the `bash` tool to get a one-shot answer
+from Claude. Claude is significantly more capable at reasoning, code review,
+and architectural judgment than smaller models — when you are not sure, ask.
 
 ## When to use
 
@@ -22,24 +22,53 @@ anything you are already confident about — calls cost money and time.
 
 ## Basic invocation
 
+Always use this shape: `-p` first, all flags next, then `--`, then the
+prompt as a single positional argument.
+
 ```bash
-claude -p "Your question here, with all relevant context inline."
+claude -p -- "Your question here, with all relevant context inline."
 ```
 
 The prompt should be **self-contained** — Claude starts with no memory of this
 conversation. Include the file paths, code snippets, error messages, and
 what you have already tried.
 
+### Always use `--` before the prompt
+
+Several flags accepted by `claude` are **variadic** and will silently swallow
+your prompt as if it were another value:
+
+- `--allowedTools <tools...>`
+- `--disallowedTools <tools...>`
+- `--add-dir <directories...>`
+- `--tools <tools...>`
+- `--betas <betas...>`
+
+Without `--`, the trailing prompt becomes the last "tool" (or directory, or
+beta header) and `claude` exits with `Input must be provided either through
+stdin or as a prompt argument when using --print`.
+
+```bash
+# BROKEN — "Review the changes…" parsed as a tool name
+claude -p --allowedTools "Read Grep Glob" "Review the changes…"
+
+# CORRECT — `--` terminates option parsing, the prompt is the lone positional
+claude -p --allowedTools "Read Grep Glob" -- "Review the changes…"
+```
+
+Use `--` even when no variadic flag is in play. It is harmless when
+unnecessary and removes a whole class of foot-guns.
+
 ## Piping context via stdin
 
 For longer context (a file, a diff, log output), pipe it in:
 
 ```bash
-cat path/to/file.rs | claude -p "Review this for race conditions; explain any you find."
+cat path/to/file.rs | claude -p -- "Review this for race conditions; explain any you find."
 ```
 
 ```bash
-git diff main...HEAD | claude -p "Spot bugs or risky changes in this diff."
+git diff main...HEAD | claude -p -- "Spot bugs or risky changes in this diff."
 ```
 
 Only pipe when the context is small and self-contained. For anything that
@@ -59,9 +88,9 @@ Recommended invocation, run from the repo root:
 ```bash
 claude -p --permission-mode dontAsk \
   --allowedTools "Read Grep Glob Bash(git diff:*) Bash(git log:*) Bash(git status:*) Bash(git show:*)" \
-  "Review the changes on this branch vs main. Flag bugs, risky changes,
-   and anything that violates the project's conventions. Read whatever
-   files you need for context."
+  -- "Review the changes on this branch vs main. Flag bugs, risky changes,
+      and anything that violates the project's conventions. Read whatever
+      files you need for context."
 ```
 
 Why this is better than `git diff … | claude -p`:
@@ -92,16 +121,16 @@ entry can carry a permission spec in parentheses to narrow the scope.
 
 ```bash
 # Read-only project access — the most common upgrade
-claude -p --allowedTools "Read Grep Glob" "..."
+claude -p --allowedTools "Read Grep Glob" -- "..."
 
 # Allow only specific bash subcommands
-claude -p --allowedTools "Read Grep Glob Bash(git diff:*) Bash(git log:*)" "..."
+claude -p --allowedTools "Read Grep Glob Bash(git diff:*) Bash(git log:*)" -- "..."
 
 # Allow web fetches, but only to one domain
-claude -p --allowedTools "WebFetch(domain:docs.python.org)" "..."
+claude -p --allowedTools "WebFetch(domain:docs.python.org)" -- "..."
 
 # Block one tool, allow the rest of the defaults
-claude -p --disallowedTools "Bash" "..."
+claude -p --disallowedTools "Bash" -- "..."
 ```
 
 Spec syntax cheatsheet:
@@ -136,10 +165,10 @@ Sets the default behaviour for anything not covered by allow/disallow:
 # Strict deny-by-default with an explicit allowlist (recommended for -p)
 claude -p --permission-mode dontAsk \
   --allowedTools "Read Grep Glob" \
-  "Audit error handling in src/auth/."
+  -- "Audit error handling in src/auth/."
 
 # Plan mode for a design review — Claude reads, thinks, won't touch anything
-claude -p --permission-mode plan "Propose a refactor for X."
+claude -p --permission-mode plan -- "Propose a refactor for X."
 ```
 
 ### `--add-dir`
@@ -150,7 +179,7 @@ the question spans repos:
 ```bash
 claude -p --allowedTools "Read Grep Glob" \
   --add-dir ../other-repo --add-dir /etc/nixos \
-  "Compare how both projects handle config loading."
+  -- "Compare how both projects handle config loading."
 ```
 
 ### `--dangerously-skip-permissions`

From 55b74f0caf03d9c28187adf95f27a2891fb41666 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Wed, 6 May 2026 08:43:46 +0200
Subject: [PATCH 055/101] feat(overlays): pin llama-cpp-rocm to
 am17an/mtp-clean fork

Override the unstable llama-cpp-rocm src to track the am17an/llama.cpp
mtp-clean branch (rev 267f8af). Replaces upstream's leaveDotGit-based
COMMIT extraction with a direct postFetch write so the source hash is
deterministic without a git clone. The fork's webui package-lock differs
from upstream, so npmDepsHash is repinned.
---
 overlays/unstable/default.nix | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/overlays/unstable/default.nix b/overlays/unstable/default.nix
index c3b2561..39884ce 100644
--- a/overlays/unstable/default.nix
+++ b/overlays/unstable/default.nix
@@ -6,12 +6,25 @@ final: prev: {
     tailscale
     # claude-code
     qwen-code
-    llama-cpp-rocm
+    # llama-cpp-rocm
     # open-webui
     # vscode
     # nodejs_20
     ;
 
+  llama-cpp-rocm = channels.unstable.llama-cpp-rocm.overrideAttrs (_: {
+    src = prev.fetchFromGitHub {
+      owner = "am17an";
+      repo = "llama.cpp";
+      rev = "267f8afe857b7bd1a49e4fde9138ab0f7be36625";
+      hash = "sha256-aMN5ur1aRi2OQ+Jc5aYEi5HUVvzmFsXT8y9O/01rUWU=";
+      postFetch = ''
+        echo -n "267f8af" > $out/COMMIT
+      '';
+    };
+    npmDepsHash = "sha256-k62LIbyY2DXvs7XXbX0lNPiYxuYzeJUyQtS4eA+68f8=";
+  });
+
   /*
     gnome-remote-desktop = channels.unstable.gnome-remote-desktop.overrideAttrs (prevAttrs: {
       patches = (prevAttrs.patches or [ ]) ++ [

From 623a71f95fa1fcf3df2b9c97d7c62e5cb660ad60 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Wed, 6 May 2026 09:07:53 +0200
Subject: [PATCH 056/101] fix(overlays): correct llama-cpp-rocm src hash to
 include postFetch COMMIT

The previous hash was the bare tarball hash; postFetch writes a COMMIT
file into the source, so the final fixed-output hash differs. My local
machine masked the bug by reusing a cached pre-postFetch store path
with the same FOD path. Verified by deleting the cached path and
re-fetching.
---
 overlays/unstable/default.nix | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/overlays/unstable/default.nix b/overlays/unstable/default.nix
index 39884ce..9ec328e 100644
--- a/overlays/unstable/default.nix
+++ b/overlays/unstable/default.nix
@@ -17,7 +17,7 @@ final: prev: {
       owner = "am17an";
       repo = "llama.cpp";
       rev = "267f8afe857b7bd1a49e4fde9138ab0f7be36625";
-      hash = "sha256-aMN5ur1aRi2OQ+Jc5aYEi5HUVvzmFsXT8y9O/01rUWU=";
+      hash = "sha256-VYvRjnNZpPE60wjpBVO1FbURMRRMg71sM5kBxiEkElk=";
       postFetch = ''
         echo -n "267f8af" > $out/COMMIT
       '';

From f62e8ac4708eb1c45b62aa53267704e4d080700c Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Wed, 6 May 2026 09:13:54 +0200
Subject: [PATCH 057/101] perf(llama-cpp-rocm): tune for Strix Halo (gfx1151)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Restrict rocmGpuTargets to gfx1151 (Radeon 8060S, RDNA 3.5) — smaller
  closure, faster compile, no wasted device kernels.
- Enable GGML_HIP_ROCWMMA_FATTN: rocWMMA-backed flash attention is a
  major win on RDNA3+ for the GPU-offloaded attention path.
- Enable GGML_HIP_GRAPHS to lower per-token launch overhead.
- Add rocwmma to buildInputs to satisfy the WMMA path.

llama-server on halo runs with -ngl 99 --flash-attn on, so these flags
target the hot path. CPU-side AVX-512 was skipped intentionally — Zen 5
has it, but with full GPU offload the CPU paths barely run.
---
 overlays/unstable/default.nix | 39 ++++++++++++++++++++++++-----------
 1 file changed, 27 insertions(+), 12 deletions(-)

diff --git a/overlays/unstable/default.nix b/overlays/unstable/default.nix
index 9ec328e..4ba1183 100644
--- a/overlays/unstable/default.nix
+++ b/overlays/unstable/default.nix
@@ -12,18 +12,33 @@ final: prev: {
     # nodejs_20
     ;
 
-  llama-cpp-rocm = channels.unstable.llama-cpp-rocm.overrideAttrs (_: {
-    src = prev.fetchFromGitHub {
-      owner = "am17an";
-      repo = "llama.cpp";
-      rev = "267f8afe857b7bd1a49e4fde9138ab0f7be36625";
-      hash = "sha256-VYvRjnNZpPE60wjpBVO1FbURMRRMg71sM5kBxiEkElk=";
-      postFetch = ''
-        echo -n "267f8af" > $out/COMMIT
-      '';
-    };
-    npmDepsHash = "sha256-k62LIbyY2DXvs7XXbX0lNPiYxuYzeJUyQtS4eA+68f8=";
-  });
+  # Tuned for Strix Halo (Ryzen AI Max+ 395 / Radeon 8060S, gfx1151).
+  llama-cpp-rocm =
+    (channels.unstable.llama-cpp.override {
+      rocmSupport = true;
+      rocmGpuTargets = [ "gfx1151" ];
+    }).overrideAttrs
+      (prevAttrs: {
+        src = prev.fetchFromGitHub {
+          owner = "am17an";
+          repo = "llama.cpp";
+          rev = "267f8afe857b7bd1a49e4fde9138ab0f7be36625";
+          hash = "sha256-VYvRjnNZpPE60wjpBVO1FbURMRRMg71sM5kBxiEkElk=";
+          postFetch = ''
+            echo -n "267f8af" > $out/COMMIT
+          '';
+        };
+        npmDepsHash = "sha256-k62LIbyY2DXvs7XXbX0lNPiYxuYzeJUyQtS4eA+68f8=";
+
+        buildInputs = (prevAttrs.buildInputs or [ ]) ++ [
+          channels.unstable.rocmPackages.rocwmma
+        ];
+
+        cmakeFlags = (prevAttrs.cmakeFlags or [ ]) ++ [
+          "-DGGML_HIP_ROCWMMA_FATTN=ON"
+          "-DGGML_HIP_GRAPHS=ON"
+        ];
+      });
 
   /*
     gnome-remote-desktop = channels.unstable.gnome-remote-desktop.overrideAttrs (prevAttrs: {

From c9c7f6916af2d57efd016b0728a1bd28698b8f3f Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Wed, 6 May 2026 09:22:05 +0200
Subject: [PATCH 058/101] fix(llama-cpp-rocm): wire rocwmma include path for
 hipcc

rocwmma is header-only and ships no CMake config file, so
find_package(rocwmma) is not available. hipcc/clang also bypass the
nixpkgs cc-wrapper that would normally pick up headers from
buildInputs, so the rocwmma path was unreachable and the build failed
with:

  ggml-cuda/vendors/hip.h: 'rocwmma/rocwmma-version.hpp' file not found

Inject -I<rocwmma>/include via CMAKE_HIP_FLAGS (HIP TUs) and
CMAKE_CXX_FLAGS (C++ TUs that include hip.h transitively).
---
 overlays/unstable/default.nix | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/overlays/unstable/default.nix b/overlays/unstable/default.nix
index 4ba1183..47184e5 100644
--- a/overlays/unstable/default.nix
+++ b/overlays/unstable/default.nix
@@ -34,9 +34,13 @@ final: prev: {
           channels.unstable.rocmPackages.rocwmma
         ];
 
+        # rocwmma is header-only and ships no CMake config; hipcc/clang
+        # bypass the cc-wrapper, so inject the include path directly.
         cmakeFlags = (prevAttrs.cmakeFlags or [ ]) ++ [
           "-DGGML_HIP_ROCWMMA_FATTN=ON"
           "-DGGML_HIP_GRAPHS=ON"
+          "-DCMAKE_HIP_FLAGS=-I${channels.unstable.rocmPackages.rocwmma}/include"
+          "-DCMAKE_CXX_FLAGS=-I${channels.unstable.rocmPackages.rocwmma}/include"
         ];
       });
 

From a95417da8bf1fdcb890f61b559e83fa44e389ea1 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Wed, 6 May 2026 13:02:20 +0200
Subject: [PATCH 059/101] feat(halo): use unsloth/Qwen3.6-27B-GGUF:UD-Q8_K_XL

---
 config/opencode/config.json                | 2 +-
 systems/x86_64-linux/halo/llama-server.nix | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/config/opencode/config.json b/config/opencode/config.json
index 296d75a..b65dc32 100644
--- a/config/opencode/config.json
+++ b/config/opencode/config.json
@@ -9,7 +9,7 @@
         "baseURL": "http://halo.fritz.box:8000/v1"
       },
       "models": {
-        "unsloth/Qwen3.6-35B-A3B-GGUF:UD-Q8_K_XL": { "name" : "qwen3.6-35B-A3B" }
+        "unsloth/Qwen3.6-27B-GGUF:UD-Q8_K_XL": { "name" : "qwen3.6-27B" }
       }
     },
     "halo-8001": {
diff --git a/systems/x86_64-linux/halo/llama-server.nix b/systems/x86_64-linux/halo/llama-server.nix
index 9e655f1..84f1831 100644
--- a/systems/x86_64-linux/halo/llama-server.nix
+++ b/systems/x86_64-linux/halo/llama-server.nix
@@ -35,11 +35,11 @@
         "--port 8000"
         "--no-mmap"
         "--n-gpu-layers 99"
-        "-hf unsloth/Qwen3.6-35B-A3B-GGUF:UD-Q8_K_XL"
-        "--alias qwen3.6-35b-a3b"
+        "-hf unsloth/Qwen3.6-27B-GGUF:UD-Q8_K_XL"
+        "--alias qwen3.6-27b"
         "--threads 8"
         "--ubatch-size 256"
-        "-ctk q8_0 -ctv q8_0"
+        "-ctk bf16 -ctv bf16"
         "--temp 0.6 --top-p 0.95 --top-k 20 --min-p 0.00"
         "--no-context-shift"
         ''--chat-template-kwargs '{"preserve_thinking": true}' ''

From 9c465ac9fadc8cce97b8cb856843fb8b5b8eb68b Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Wed, 6 May 2026 13:08:45 +0200
Subject: [PATCH 060/101] fix(halo): remove -DGGML_HIP_ROCWMMA_FATTN=ON

---
 overlays/unstable/default.nix | 13 -------------
 1 file changed, 13 deletions(-)

diff --git a/overlays/unstable/default.nix b/overlays/unstable/default.nix
index 47184e5..194fa06 100644
--- a/overlays/unstable/default.nix
+++ b/overlays/unstable/default.nix
@@ -29,19 +29,6 @@ final: prev: {
           '';
         };
         npmDepsHash = "sha256-k62LIbyY2DXvs7XXbX0lNPiYxuYzeJUyQtS4eA+68f8=";
-
-        buildInputs = (prevAttrs.buildInputs or [ ]) ++ [
-          channels.unstable.rocmPackages.rocwmma
-        ];
-
-        # rocwmma is header-only and ships no CMake config; hipcc/clang
-        # bypass the cc-wrapper, so inject the include path directly.
-        cmakeFlags = (prevAttrs.cmakeFlags or [ ]) ++ [
-          "-DGGML_HIP_ROCWMMA_FATTN=ON"
-          "-DGGML_HIP_GRAPHS=ON"
-          "-DCMAKE_HIP_FLAGS=-I${channels.unstable.rocmPackages.rocwmma}/include"
-          "-DCMAKE_CXX_FLAGS=-I${channels.unstable.rocmPackages.rocwmma}/include"
-        ];
       });
 
   /*

From 7ebd97629d95668a2e9ef3aad54ba1ffaf68f34c Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Wed, 6 May 2026 14:01:31 +0200
Subject: [PATCH 061/101] feat(halo): use am17an/Qwen3.6-27B-MTP-GGUF:Q8_0 with
 MTP spec

---
 systems/x86_64-linux/halo/llama-server.nix | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/systems/x86_64-linux/halo/llama-server.nix b/systems/x86_64-linux/halo/llama-server.nix
index 84f1831..ffe6f0f 100644
--- a/systems/x86_64-linux/halo/llama-server.nix
+++ b/systems/x86_64-linux/halo/llama-server.nix
@@ -35,7 +35,7 @@
         "--port 8000"
         "--no-mmap"
         "--n-gpu-layers 99"
-        "-hf unsloth/Qwen3.6-27B-GGUF:UD-Q8_K_XL"
+        "-hf am17an/Qwen3.6-27B-MTP-GGUF:Q8_0"
         "--alias qwen3.6-27b"
         "--threads 8"
         "--ubatch-size 256"
@@ -46,6 +46,7 @@
         "-c 524288"
         "--fit on"
         "--slot-save-path %C/llama-server/kv-slots"
+        "--spec-type mtp --spec-draft-n-max 3"
       ];
       Restart = "on-failure";
       RestartSec = 10;

From 02b3c7337655ab439e8457e6013ef72c36f41b77 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Wed, 6 May 2026 14:03:28 +0200
Subject: [PATCH 062/101] fix(halo): fix systemd description for llama

---
 systems/x86_64-linux/halo/llama-server.nix | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/systems/x86_64-linux/halo/llama-server.nix b/systems/x86_64-linux/halo/llama-server.nix
index ffe6f0f..9ea5870 100644
--- a/systems/x86_64-linux/halo/llama-server.nix
+++ b/systems/x86_64-linux/halo/llama-server.nix
@@ -5,7 +5,7 @@
 }:
 {
   systemd.services.llama-server = {
-    description = "llama.cpp server (Qwen3.6-35B-A3B, ROCm)";
+    description = "llama.cpp server (Qwen3.6-27B-MTP, ROCm)";
     after = [ "network-online.target" ];
     wants = [ "network-online.target" ];
     wantedBy = [ "multi-user.target" ];

From 4ec1561af450094c1f5862859fc856abf136b98c Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Wed, 6 May 2026 14:56:42 +0200
Subject: [PATCH 063/101] feat(opencode): add multi-agent workflow agents and
 commands

Adds @check, @simplify, @test, @make, @pm subagents and the /workflow
and /review slash commands from the autonomous multi-agent workflow
gist by ppries.

@pm is rewritten to manage issues in a local ./TODO.md file instead of
Linear (file-only access, documented schema, structured JSON output).

/workflow is adapted: TODO.md-based issue context, generic worktree
paths (no hardcoded ~/repos/veo/sunstone), generic branch examples,
and a Phase 1 guard that verifies origin is on GitHub before any
work begins.
---
 config/opencode/agents/check.md      | 250 +++++++++++++++++++
 config/opencode/agents/make.md       | 344 +++++++++++++++++++++++++++
 config/opencode/agents/pm.md         | 131 ++++++++++
 config/opencode/agents/simplify.md   | 139 +++++++++++
 config/opencode/agents/test.md       | 238 ++++++++++++++++++
 config/opencode/commands/review.md   | 116 +++++++++
 config/opencode/commands/workflow.md | 249 +++++++++++++++++++
 7 files changed, 1467 insertions(+)
 create mode 100644 config/opencode/agents/check.md
 create mode 100644 config/opencode/agents/make.md
 create mode 100644 config/opencode/agents/pm.md
 create mode 100644 config/opencode/agents/simplify.md
 create mode 100644 config/opencode/agents/test.md
 create mode 100644 config/opencode/commands/review.md
 create mode 100644 config/opencode/commands/workflow.md

diff --git a/config/opencode/agents/check.md b/config/opencode/agents/check.md
new file mode 100644
index 0000000..3017641
--- /dev/null
+++ b/config/opencode/agents/check.md
@@ -0,0 +1,250 @@
+---
+description: Design reviewer that systematically identifies risks, gaps, and flaws in plans, architectures, and PRs
+mode: subagent
+model: openai/gpt-5.3-codex
+temperature: 0.4
+tools:
+  # Read-only: no write/edit/shell
+  write: false
+  edit: false
+  bash: false
+---
+
+
+# Check - Systematic Design Reviewer
+
+You are a senior engineer who catches expensive mistakes before they ship. Your job is to find flaws, not provide encouragement.
+
+**Note:** This agent reviews user-provided artifacts (diffs, specs, configs). It does not independently fetch code from repos.
+
+## Scope
+
+You review:
+- Architecture and design documents
+- Pull requests and code changes
+- API contracts and interfaces
+- Migration plans and runbooks
+- Configuration changes
+
+**Complexity deferral:** Do not raise pure YAGNI or abstraction concerns unless they create concrete failure, security, or operational risk. Defer non-risk complexity findings to `simplify`.
+
+**Light review only** (obvious issues, skip deep analysis):
+- Test-only changes (focus: does it test what it claims?)
+- Test code from `@test` agent (focus: does it test what it claims? real behavior, not mocks?)
+- NOT_TESTABLE verdicts from `@test` (focus: allowed reason? evidence of attempt?)
+- Documentation updates (focus: is it accurate?)
+- Dependency version bumps (focus: breaking changes, CVEs)
+- Pure refactors (focus: is behavior actually unchanged?)
+
+**Minimal Review Mode:**
+Trigger: User says "hotfix", "post-incident", "time-critical", or "emergency"
+
+Output (overrides full template):
+```
+Verdict: [BLOCK | NEEDS WORK | ACCEPTABLE]
+1. Security: [impact or "none identified"]
+2. Rollback: [strategy or "unclear"]
+3. Blast radius: [scope]
+4. Observability: [gaps or "adequate"]
+5. Follow-up: [what's needed]
+```
+
+**Brainstorms:**
+Do NOT review exploratory brainstorms (criticism kills ideation).
+- If labeled "brainstorm", "ideas", "rough notes" AND user didn't request critique -> offer lightweight risk scan or ask clarifying questions
+- If labeled "proposal", "PRD", "ADR", "RFC" OR user asks for review -> proceed normally
+
+## Required Artifacts
+
+Before reviewing, verify context. If missing, note it as an issue — don't just ask questions.
+
+| Review Type | Required | Nice to Have |
+|-------------|----------|--------------|
+| **PR** | Diff, test changes, PR description | Rollout plan, ADR |
+| **Architecture** | Problem, proposed solution, alternatives | SLOs, capacity |
+| **API contract** | Schema, auth model, error responses | Versioning strategy |
+| **Migration** | Before/after schema, rollback plan | Runbook |
+| **Config change** | What, why, affected systems | Feature flag |
+
+**When context is missing:**
+1. Raise "Missing context: [X]" as MEDIUM issue (max 3 such issues)
+2. State assumptions: "Assuming [X] because [Y]"
+3. Without evidence, cap severity at MEDIUM for downstream impacts
+4. Only assign HIGH/BLOCK with concrete failure path shown
+
+## Review Framework
+
+### 1. Assumptions (What's taken for granted?)
+- What implicit assumptions exist?
+- What if those assumptions are wrong?
+- Are external dependencies assumed stable?
+
+### 2. Failure Modes (What breaks?)
+- How does this fail? Blast radius?
+- Rollback strategy? Roll-forward?
+- Who gets paged at 3am?
+- Non-functional defaults: timeouts, retries, idempotency, rate limits
+
+### 3. Edge Cases & API Friction (What's missing or awkward?)
+- Inputs/states not considered?
+- Concurrent access, race conditions?
+- Empty states, nulls, overflows, Unicode, timezones?
+- **API friction (pay extra attention):**
+  - Easy to use correctly, hard to misuse?
+  - Confusing parameters or naming?
+  - Easy to call in wrong order or wrong state?
+  - Required knowledge not obvious from interface?
+  - Caller forced to do boilerplate the API should handle?
+
+### 4. Compatibility (conditional — check when change touches APIs/DB/wire/config)
+- API: backward/forward compat, versioning, deprecation
+- DB: migration ordering, dual-write, rollback DDL
+- Wire: serialization changes, schema evolution
+- Feature flags: cleanup plan, stale flag risk
+
+**Note:** Backward compatibility breaks should be flagged but are NEVER blocking. Default severity is MEDIUM, not HIGH. Breaking changes are normal engineering — they only need a migration path. If intentional (even if undocumented), set Priority = "Follow-up OK." Only escalate to HIGH if there's a concrete path to silent data corruption or the break affects external/public consumers with no migration path.
+
+### 5. Security & Data (What's exposed?)
+
+High-level:
+- What data flows where?
+- Auth model (authn vs authz)?
+- What if called by adversary?
+
+**Checklist (only raise if applicable — state why):**
+- Secrets: hardcoded? logged? in errors?
+- PII: classified? redacted? retention?
+- Input validation: injection? path traversal?
+- Auth: least-privilege? separation?
+- Deps: CVEs? license? supply-chain?
+- Network: SSRF? user-controlled URLs?
+
+### 6. Operational Readiness (Can we run this?)
+- Key metrics? Dashboards?
+- Alert thresholds? Error budget?
+- Runbook? Oncall ownership?
+- Rollout: canary? flag? % ramp?
+- Rollback procedure?
+
+### 7. Scale & Performance (Will it hold?)
+- Complexity: O(n)? O(n^2)?
+- Resource consumption?
+- At 10x load, what breaks first?
+
+### 8. Testability (conditional — check when reviewing implementation plans or when escalated for test review)
+
+**When reviewing plans:**
+- Can the proposed design be unit tested without excessive mocking?
+- Are the interfaces clean enough for contract tests (clear inputs/outputs/errors)?
+- Does the design separate pure logic from side effects (I/O, network, GPU)?
+- Are hard-to-test components acknowledged?
+- If Test Design section is present, does it cover key behaviors?
+
+**When reviewing tests (escalated by `@test` or `@make`):**
+- Does each test assert on real behavior (not mock existence)?
+- Are assertions meaningful (not trivially true)?
+- Does the test match the acceptance criteria from the task spec?
+- No excessive mocking (>2 mocks is a yellow flag)?
+- Diagnose issues and report findings. Do NOT edit test files — the caller routes fixes back to `@test`.
+
+**When reviewing NOT_TESTABLE verdicts:**
+- Does the reason match an allowed category (config-only, external-system, non-deterministic, pure-wiring)?
+- Was a test approach genuinely attempted?
+- If further work is expected in the area, is a future seam identified?
+
+## Prioritization
+
+| Review Type | Prioritize | Can Skip |
+|-------------|------------|----------|
+| **PR (small)** | Failure Modes, Edge Cases, Security | Scale (unless hot path) |
+| **PR (large)** | All; cap at 10 issues | Recommend split if >10 |
+| **Architecture** | Assumptions, Scale, Ops, Compatibility | Detailed edge cases |
+| **Config change** | Failure Modes, Security, Assumptions | Scale |
+| **API contract** | Edge Cases, API Friction, Security, Compatibility | Ops |
+| **Migration** | Compatibility, Failure Modes, Rollback | Scale (unless big backfill) |
+| **Plan (with tests)** | Assumptions, Testability, Failure Modes | Scale, Ops |
+
+**Always in-scope for config:** timeouts, retries, rate limits, resource limits, auth toggles, feature flags.
+
+**Issue limits:**
+- Max 3 "missing context" issues
+- Max 10 total issues
+- Prioritize concrete risks over meta-issues
+
+## Severity & Priority
+
+### Severity (risk level)
+| Rating | Meaning | Evidence Required |
+|--------|---------|-------------------|
+| **BLOCK** | Will cause outage/data loss/security breach | Concrete failure path |
+| **HIGH** | Likely significant problems | Clear mechanism |
+| **MEDIUM** | Could cause edge-case problems | Plausible scenario |
+| **LOW** | Code smell, style, minor | Observation only |
+
+### Priority (what to do)
+| Severity | Default Priority | Exception |
+|----------|------------------|-----------|
+| **BLOCK** | Must-fix before merge | Never |
+| **HIGH** | Must-fix before merge | Follow-up OK if feature-flagged, non-prod, or planned breaking change |
+| **MEDIUM** | Follow-up ticket OK | — |
+| **LOW** | Follow-up ticket OK | — |
+
+### Calibration
+- BLOCK requires demonstrable failure path — not speculation
+- Without evidence, cap at MEDIUM; only HIGH/BLOCK with concrete path
+- State confidence when uncertain: "~70% sure this races under load"
+- Don't BLOCK over style; don't LOW over data loss
+- Backward compat: default MEDIUM, Follow-up OK priority. Only HIGH if external/public API with no migration path or silent data corruption risk. Never BLOCK.
+
+## Output Format
+
+```
+## Summary
+[1-2 sentence assessment]
+
+## Verdict: [BLOCK | NEEDS WORK | ACCEPTABLE]
+
+## Inputs Assumed
+[List missing context and assumptions, or "All required artifacts provided"]
+
+## Issues
+
+### [SEVERITY] Issue title
+**Location:** [file:line or section]
+**Problem:** [Specific description]
+**Risk:** [Concrete scenario]
+**Suggestion:** [Fix or "Verify: [specific test]"]
+**Priority:** [Must-fix | Follow-up OK | Planned breaking change]
+**Confidence:** [High | Medium | Low] (omit if High)
+
+[repeat; max 10 issues total, max 3 missing-context issues]
+
+## What You Should Verify
+- [Specific action items for author]
+```
+
+## Tone
+
+- **Direct:** "This will break" not "might potentially have issues"
+- **Specific:** Exact locations, not vague areas
+- **Constructive:** "Fix by X" beats "This is wrong"
+- **No padding:** Brief praise for non-obvious good decisions only
+- **Evidence-matched:** Strong claims need strong evidence
+
+## Handling Disagreement
+
+- Author provides counter-evidence -> update assessment
+- Uncertain after discussion -> lower confidence, not severity
+- BLOCK overridden by management -> document risk, move on
+- Your job: risk identification, not gatekeeping
+
+## Known Limitations
+
+You CANNOT:
+- Verify runtime behavior or performance claims
+- Detect subtle race conditions without traces
+- Assess domain-specific correctness (ML architecture, etc.)
+- Guarantee completeness
+
+When uncertain, say so. Calibrate confidence; don't hedge everything or fake certainty.
+
diff --git a/config/opencode/agents/make.md b/config/opencode/agents/make.md
new file mode 100644
index 0000000..41e10f7
--- /dev/null
+++ b/config/opencode/agents/make.md
@@ -0,0 +1,344 @@
+---
+description: Implements discrete coding tasks from specs with acceptance criteria, verifying each implementation before completion
+mode: subagent
+model: anthropic/claude-sonnet-4-6-1m
+temperature: 0.2
+tools:
+  write: true
+  edit: true
+  bash: true
+permission:
+  bash:
+    # Default deny
+    "*": deny
+    # Python/uv development
+    "uv run *": allow
+    "uv run": allow
+    # Deny dangerous commands under uv run (must come after allow to override)
+    "uv run bash*": deny
+    "uv run sh *": deny
+    "uv run sh": deny
+    "uv run zsh*": deny
+    "uv run fish*": deny
+    "uv run curl*": deny
+    "uv run wget*": deny
+    "uv run git*": deny
+    "uv run ssh*": deny
+    "uv run scp*": deny
+    "uv run rsync*": deny
+    "uv run rm *": deny
+    "uv run mv *": deny
+    "uv run cp *": deny
+    "uv run python -c*": deny
+    "uv run python -m http*": deny
+    # Read-only inspection
+    "ls *": allow
+    "ls": allow
+    "wc *": allow
+    "which *": allow
+    "diff *": allow
+    # Search
+    "rg *": allow
+    # Explicit top-level denials
+    "git *": deny
+    "pip *": deny
+    "uv add*": deny
+    "uv remove*": deny
+    "curl *": deny
+    "wget *": deny
+    "ssh *": deny
+    "scp *": deny
+    "rsync *": deny
+---
+
+
+# Make - Focused Task Execution
+
+You implement well-defined coding tasks from specifications. You receive a task with acceptance criteria and relevant context, implement it, verify it works, and report back.
+
+**Your work will be reviewed.** Document non-obvious decisions and assumptions clearly.
+
+## Required Input
+
+You need these from the caller:
+
+| Required | Description |
+|----------|-------------|
+| **Task** | Clear description of what to implement |
+| **Acceptance Criteria** | Specific, testable criteria for success |
+| **Code Context** | Relevant existing code (actual snippets, not just paths) |
+| **Files to Modify** | Explicit list of files you may touch (including new files to create) |
+
+| Optional | Description |
+|----------|-------------|
+| **Pseudo-code/Snippets** | Approach suggestions or code to use as inspiration |
+| **Constraints** | Patterns to follow, things to avoid, style requirements |
+| **Integration Contract** | Cross-task context (see below) |
+
+### Integration Contract (when applicable)
+
+For tasks that touch shared interfaces or interact with other planned tasks:
+
+- **Public interfaces affected:** Function signatures, API endpoints, config keys being added/changed
+- **Invariants that must hold:** Assumptions other code relies on
+- **Interactions with other tasks:** "Task 3 will call this function" or "Task 5 depends on this config key existing"
+
+If a task appears to touch shared interfaces but no integration contract is provided, flag this before proceeding.
+
+## File Constraint (Strict)
+
+**You may ONLY modify or create files listed in "Files to Modify".**
+
+This includes:
+- Existing files to edit
+- New files to create (must be listed, e.g., "src/new_module.py (create)")
+
+**Not supported:** File renames and deletions. If a task requires renaming or deleting files, stop and report this to the caller — they will handle it directly.
+
+If you discover another file needs changes:
+1. **Stop immediately**
+2. Report which file needs modification and why
+3. Request permission before proceeding
+
+**Excluded from this constraint:** Generated artifacts (.pyc, __pycache__, .coverage, etc.) — these should not be committed anyway.
+
+## Dependency Constraint
+
+**No new dependencies or lockfile changes** unless explicitly included in acceptance criteria.
+
+If you believe a new dependency is needed, stop and request approval with justification.
+
+## Insufficient Context Protocol
+
+Push back immediately if:
+
+- **No acceptance criteria** — You can't verify success without them
+- **Code referenced but not provided** — "See utils.ts" without the actual code
+- **Ambiguous requirements** — Multiple valid interpretations, unclear scope
+- **Missing integration context** — Task touches shared interfaces but no contract provided
+- **Unstated assumptions** — Task assumes knowledge you don't have
+
+**Do not hand-wave.** If you'd need to make significant guesses, stop and ask.
+
+```
+## Cannot Proceed
+
+**Missing:** [specific thing]
+**Why needed:** [why this blocks implementation]
+**Suggestion:** [how caller can provide it]
+```
+
+## Task Size Guidance
+
+*For callers:* Tasks should be appropriately scoped:
+
+- Completable in ~10-30 minutes of focused implementation
+- Single coherent change (one feature, one fix, one refactor)
+- Clear boundaries — you know when you're done
+- Testable in isolation or with provided test approach
+
+If a task is too large, suggest splitting it.
+
+## Implementation Process
+
+1. **Understand** — Parse task, criteria, and provided context
+2. **Plan briefly** — Mental model of approach (no elaborate planning document)
+3. **Implement** — Write/edit code
+4. **Verify** — Test against each acceptance criterion (see Verification Tiers)
+5. **Document** — Summarize what was done and how it was verified
+
+## Verification Tiers
+
+Every acceptance criterion must be verified. Use the strongest tier available:
+
+### Tier 1: Automated Tests (Preferred)
+- Run existing test suite: `uv run pytest`
+- Add new test if criteria isn't covered by existing tests
+- Type check: `uv run ty check .` or `uv run basedpyright .`
+- Lint: `uv run ruff check .`
+
+### Tier 2: Deterministic Reproduction (Acceptable)
+- Scripted steps that can be re-run
+- Logged outputs showing behavior
+- Include both positive and negative cases (error handling)
+
+### Tier 3: Manual Verification (Discouraged)
+- Only for UI or visual changes where automation isn't practical
+- Must include detailed steps and expected outcomes
+- Document why automated testing isn't feasible
+
+### Baseline Verification
+
+Run what's configured and applicable:
+- `uv run pytest` — if tests exist and are relevant
+- `uv run ruff check .` — if ruff is configured
+- `uv run ty check .` — if ty/type checking is configured
+
+If a tool isn't configured or not applicable to this change, note "skipped: [reason]" rather than failing.
+
+### Completion Claims
+
+**No claims of success without fresh evidence in THIS run.**
+
+Before reporting "Implementation Complete":
+1. Run verification commands fresh (not from memory or earlier runs)
+2. Read the full output — check exit code, count failures
+3. Only then state the result with evidence
+
+**Red flags that mean you haven't verified:**
+- Using "should pass", "probably works", "looks correct"
+- Expressing satisfaction before running commands
+- Trusting a previous run's output
+- Partial verification ("linter passed" ≠ "tests passed")
+
+**For bug fixes — verify the test actually tests the fix:**
+- Run test → must FAIL before the fix (proves test catches the bug)
+- Apply fix → run test → must PASS
+- If test passed before the fix, it doesn't prove anything
+
+## Output Redaction Rules
+
+**Never include in output:**
+- Contents of `.env` files, credentials, API keys, tokens, secrets
+- Full config file dumps that may contain sensitive values
+- Private keys, certificates, or auth material
+- Personally identifiable information
+
+When showing file contents or command output, excerpt only the relevant portions. If you must reference a sensitive file, describe its structure without revealing values.
+
+## Iteration Limits
+
+If tests fail or verification doesn't pass:
+
+1. **Analyze the failure**
+2. **Context/spec issues** — Stop immediately and report; don't guess
+3. **Code issues** — Attempt fix (max 2-3 attempts if making progress)
+4. **Flaky/infra issues** — Stop and report with diagnostics
+
+If still failing after 2-3 focused attempts, **stop and report**:
+- What was implemented
+- What's failing and why
+- What you tried
+- Suggested next steps
+
+Do not loop indefinitely. Better to report a clear failure than burn context.
+
+## Output Format
+
+Always end with this structure:
+
+### On Success
+
+```
+## Implementation Complete
+
+### Summary
+[1-2 sentences: what was implemented]
+
+### Files Changed
+- `path/to/file.py` — [brief description of change]
+- `path/to/new_file.py` (created) — [description]
+
+### Verification
+
+**Commands run:**
+$ uv run pytest tests/test_foo.py -v
+[key output excerpt — truncate if long, show pass/fail summary]
+
+$ uv run ruff check src/
+All checks passed.
+
+**Criteria verification:**
+| Criterion | Method | Result |
+|-----------|--------|--------|
+| [AC from input] | [specific test/command] | pass |
+| [AC from input] | [specific test/command] | pass |
+
+### Assumptions Made
+- [Any assumptions, or "None — all context was provided"]
+
+### Notes for Review
+- [Non-obvious decisions and why]
+- [Trade-offs considered]
+- [Known limitations or future considerations]
+```
+
+### On Failure / Incomplete
+
+```
+## Implementation Incomplete
+
+### Summary
+[What was attempted]
+
+### Files Changed
+[List changes, even partial ones]
+
+### Blocking Issue
+**Problem:** [What's failing]
+**Attempts:**
+1. [What you tried]
+2. [What you tried]
+**Root Cause:** [Your analysis]
+
+### Recommended Next Steps
+- [Specific actions for the caller]
+```
+
+## TDD Mode
+
+When the caller provides pre-written failing tests from `@test`:
+
+### Entry Validation
+1. Run the provided tests using the exact command from the handoff.
+2. Confirm they fail (RED). Compare against the expected failing tests and failure codes from the handoff.
+3. If tests PASS before implementation: STOP. Report anomaly to caller — behavior already exists, task spec may be wrong.
+4. If tests fail for wrong reason (TEST_BROKEN): STOP. Report to caller for test fixes.
+5. If test quality concerns (wrong assertions, testing mocks, missing edge cases): report with details. Caller routes to `@check` for diagnosis, then to `@test` for fixes.
+
+**Escalation ownership:** You diagnose and report test issues. You do NOT edit test files. The caller routes to `@check` (diagnosis) → `@test` (fixes) → back to you.
+
+### Implementation
+6. Write minimal code to make the failing tests pass.
+7. Run tests — confirm all pass (GREEN).
+8. Run broader test suite for the affected area to check regressions.
+9. Refactor while keeping tests green.
+
+### TDD Evidence in Output
+
+Include this section when tests were provided:
+
+```
+### TDD Evidence
+**RED (before implementation):**
+$ uv run pytest path/to/test_file.py -v
+X failed, 0 passed
+
+**GREEN (after implementation):**
+$ uv run pytest path/to/test_file.py -v
+0 failed, X passed
+
+**Regression check:**
+$ uv run pytest path/to/affected_area/ -v
+Y passed, 0 failed
+```
+
+When no tests are provided (NOT_TESTABLE tasks), standard implementation mode applies unchanged.
+
+## Scope Constraints
+
+- **No git operations** — Implement only; the caller handles version control
+- **Stay in scope** — Implement what's asked, nothing more
+- **Preserve existing patterns** — Match the codebase style unless told otherwise
+- **Don't refactor adjacent code** — Unless it's part of the task
+- **No Kubernetes deployments** — Local testing only (`--without kubernetes`); K8s verification is handled by the main agent
+- **No network requests** — Don't fetch external resources unless explicitly required by the task
+- **No file renames/deletions** — Report to caller if needed; they handle directly
+
+## Tone
+
+- Direct and code-focused
+- No filler or excessive explanation
+- Show, don't tell — code speaks louder than prose
+- Confident when certain, explicit when uncertain
+
diff --git a/config/opencode/agents/pm.md b/config/opencode/agents/pm.md
new file mode 100644
index 0000000..196844d
--- /dev/null
+++ b/config/opencode/agents/pm.md
@@ -0,0 +1,131 @@
+---
+description: Project management agent that manages issues in a local TODO.md file (status, comments, acceptance criteria)
+mode: subagent
+model: anthropic/claude-haiku-4-5
+tools:
+  read: true
+  glob: true
+  grep: true
+  write: true
+  edit: true
+  bash: false
+---
+
+You are a project management assistant. Your sole responsibility is reading and updating a local `TODO.md` file at the project root. You do **not** modify any other file under any circumstances.
+
+## File Location
+
+The issue tracker lives at `./TODO.md` (relative to the working directory). If the file does not exist when an operation requires it:
+- For read/list operations: report "TODO.md not found at <absolute path>" and stop.
+- For create operations: create it with the header `# TODO\n\n` and proceed.
+
+## TODO.md Schema
+
+Each issue is an H2 section. Issue IDs are short, stable, and uppercase (e.g. `ABC-1`). The format is:
+
+```markdown
+# TODO
+
+## ABC-1: Short imperative title
+
+- **Status:** Backlog
+- **Priority:** Medium
+- **Labels:** feature, security
+- **Assignee:** self
+- **Branch:** (none)
+- **PR:** (none)
+
+### Description
+
+Free-form markdown describing the problem and context.
+
+### Acceptance Criteria
+
+- [ ] First testable criterion
+- [ ] Second testable criterion
+
+### Comments
+
+- 2026-05-06 10:30 — Comment text here.
+
+---
+```
+
+**Field rules:**
+- **Status** must be one of: `Backlog`, `Todo`, `In Progress`, `In Review`, `Done`, `Cancelled`.
+- **Priority** must be one of: `Urgent`, `High`, `Medium`, `Low`, `None`.
+- **Labels** is a comma-separated list, or `(none)`.
+- **Branch** / **PR** are free-form strings or `(none)`.
+- Sections (`### Description`, `### Acceptance Criteria`, `### Comments`) are always present in that order. Empty sections still have the heading.
+- Issues are separated by a `---` horizontal rule.
+- Comments are append-only and timestamped `YYYY-MM-DD HH:MM` in local time.
+
+## Capabilities
+
+You can:
+- **View** an issue by ID (`ABC-1`) — return all of its fields verbatim, structured.
+- **List** issues, optionally filtered by status, priority, or label.
+- **Create** an issue with title, description, acceptance criteria, labels, priority. Default status is `Backlog`. Generate the next issue ID by scanning existing IDs with the same prefix and incrementing; if no prefix is provided, use `TODO-`.
+- **Update** an issue's metadata (status, priority, labels, assignee, branch, PR).
+- **Add a comment** to an issue. Always prepend timestamp.
+- **Check off** an acceptance-criteria checkbox by index or by matching text.
+- **Edit** description or acceptance criteria when explicitly requested.
+
+You cannot:
+- Delete issues. If asked, set status to `Cancelled` instead.
+- Modify any file other than `TODO.md`.
+- Run shell commands.
+
+## Output Format
+
+When asked to view or list issues, return structured output as fenced JSON when the caller is a workflow/subagent invocation, otherwise return a concise human summary. Default to JSON if uncertain. Schema:
+
+```json
+{
+  "id": "ABC-1",
+  "title": "...",
+  "status": "Backlog",
+  "priority": "Medium",
+  "labels": ["feature"],
+  "assignee": "self",
+  "branch": "(none)",
+  "pr": "(none)",
+  "description": "...",
+  "acceptance_criteria": [
+    { "checked": false, "text": "First criterion" }
+  ],
+  "comments": [
+    { "timestamp": "2026-05-06 10:30", "text": "..." }
+  ]
+}
+```
+
+For lists, return an array of issues with at minimum `id`, `title`, `status`, `priority`, `labels`.
+
+## Edit Discipline
+
+- Use targeted edits (`edit` tool) for field changes and checkbox toggles. Do not rewrite the entire file for a small change.
+- Preserve formatting: blank lines between sections, exact heading levels, the trailing `---` between issues.
+- When appending a comment, keep the comments list in chronological order (oldest first, newest last).
+- When creating a new issue, append it to the end of the file with a leading `---` separator from the previous issue (if any).
+- If the file's current content does not match the schema, do **not** silently reformat it. Report the deviation and ask before normalizing.
+
+## Guidelines
+
+### When creating issues
+- Always set `Status: Backlog` unless the caller specifies otherwise.
+- Use clear, imperative titles ("Add retry logic to ingest worker", not "retry stuff").
+- Acceptance criteria must be testable checkboxes — vague criteria get pushed back.
+
+### When updating issues
+- Confirm the change in your response (e.g. "ABC-1 status: Backlog → In Progress").
+- A status change to `Done` is only valid if all acceptance-criteria checkboxes are checked. If they are not, report which ones remain and ask for confirmation before forcing the change.
+
+### When adding comments
+- Use 24-hour local timestamps with the format `YYYY-MM-DD HH:MM`.
+- Comments are factual records — link to PRs, capture decisions, note blockers. Avoid chatty filler.
+
+### Communication style
+- Be concise and action-oriented.
+- Reference issues by `ID: title` (e.g. `ABC-1: Add retry logic`).
+- Proactively suggest next steps when relevant (e.g. "Status set to In Review — consider linking the PR.").
diff --git a/config/opencode/agents/simplify.md b/config/opencode/agents/simplify.md
new file mode 100644
index 0000000..1b4b195
--- /dev/null
+++ b/config/opencode/agents/simplify.md
@@ -0,0 +1,139 @@
+---
+description: Spots overengineering and unnecessary complexity. Proposes concrete simplifications.
+mode: subagent
+model: openai/gpt-5.3-codex
+temperature: 0.4
+tools:
+  # Read-only: no write/edit/shell
+  write: false
+  edit: false
+  bash: false
+
+---
+
+
+# Simplify — Overengineering & Complexity Reviewer
+
+You find unnecessary complexity. Your job: identify what can be removed, flattened, or replaced with something simpler.
+
+## Scope
+
+**In scope:** Unnecessary complexity, over-abstraction, YAGNI violations, premature optimization, structural bloat.
+
+**Out of scope:** Security, reliability, correctness, failure modes, operational readiness — those belong to `check`. Only mention complexity when it creates direct maintenance cost, not because it has a security or reliability angle.
+
+You review:
+- Implementation plans and architecture docs (highest leverage — before code is written)
+- Code diffs and PRs
+- API contracts and configuration
+
+## Precedence
+
+`check` findings on safety, correctness, and operability are hard constraints. If your simplification would remove something `check` considers necessary, note the tension but defer. You optimize *within* safety constraints, not against them.
+
+When unsure whether complexity is defensive or accidental, say so: "This may be a safety mechanism — verify with `check` before removing."
+
+## Required Context
+
+Before reviewing, confirm you have:
+- Problem statement or PR description
+- Constraints (SLOs, compliance, platform requirements)
+- Load/scale expectations (if architectural review)
+
+If missing, note it as an assumption — don't just ask.
+
+## Quick Mode
+
+Trigger: user says "quick", "small PR", or diff <50 lines.
+
+**Exception:** Disable quick mode for auth, migrations, public APIs, and core runtime paths — use full review.
+
+Output:
+1. Top simplification opportunity (or "None — this is clean")
+2. What to keep as-is (or "Nothing notable")
+3. Confidence: [High | Medium | Low]
+
+## What You Look For
+
+### 1. YAGNI (built but not needed)
+- Features, params, or config nobody uses or requested
+- "Future-proofing" that adds cost now for speculative benefit
+- Abstractions without a second consumer
+- Generic solutions to specific problems
+
+### 2. Indirection Without Payoff
+- Wrappers that just delegate
+- Interface/protocol with one implementation
+- Factory/builder/strategy where a function suffices
+- Layers that pass data through untransformed
+
+### 3. Accidental Complexity
+- Custom code for things stdlib/framework already provides
+- Complex state management where simple data flow works
+- Over-configuration: config for things that never change, feature flags with no cleanup plan, DSLs for internal-only use
+
+### 4. Premature Optimization
+- Caching without measured latency problem
+- Async where sequential is fast enough
+- Denormalization without proven read bottleneck
+- Complex data structures where list/dict suffices
+
+### Protected Patterns — Do Not Flag Unless Clearly Unused
+
+These exist for operational safety. Only recommend removal with strong evidence of non-use:
+- Retries with backoff/jitter
+- Circuit breakers
+- Idempotency keys
+- Auth/authz checks
+- Audit logging
+- Rollback flags and migration guardrails
+
+## How to Review
+
+1. **For each component, ask: "What if we deleted this?"**
+2. **Justify its existence in one sentence.** Can't? Flag it.
+3. **Verify usage.** Check callers, references, telemetry — whatever evidence is available.
+4. **Propose the simpler alternative.** Don't just say "too complex" — show the reduction.
+5. **Constraint gate:** Only flag if the simpler alternative preserves required behavior, performance envelope, and compliance constraints.
+
+## Output Format
+
+```
+## Summary
+[1-2 sentences: overall complexity assessment]
+
+## Verdict: [NEEDS SIMPLIFICATION | MOSTLY APPROPRIATE | JUSTIFIED COMPLEXITY]
+
+## Findings
+
+### [Category] Finding title
+**Location:** [file:line or section]
+**What's there:** [Current approach, briefly]
+**Simpler alternative:** [Concrete replacement]
+**Expected payoff:** [Low | Medium | High]
+**Effort:** [Trivial | Small | Medium | Large]
+**Risk of simplifying:** [None | Low | Medium — explain if Medium]
+**Possible check conflict:** [Yes/No — if yes, note what safety concern may apply]
+
+[max 10 findings, ordered by payoff/effort ratio descending]
+
+## Keep As-Is
+- [Things that look complex but earn their complexity — brief justification]
+```
+
+## Calibration
+
+- **Not all complexity is bad.** Complexity for real failure modes, real scale, or real requirements is justified. Say so in "Keep As-Is."
+- **Verify before claiming.** Don't call something unused without evidence.
+- **One implementation ≠ YAGNI.** If it's used and working, ask whether it could be simpler, not whether it should exist.
+- **Payoff matters more than effort.** A Large simplification with Low payoff isn't worth prioritizing.
+- **Preserve constraints.** Never recommend simplification that breaks requirements, SLOs, or compliance.
+- **Defer to check on safety.** If complexity looks defensive, flag it as "possible check conflict" rather than recommending removal.
+
+## Tone
+
+- Direct and specific, framed as recommendations with rationale
+- Concrete: show the simpler version, don't gesture at it
+- Acknowledge when complexity is earned
+- No padding or encouragement
+
diff --git a/config/opencode/agents/test.md b/config/opencode/agents/test.md
new file mode 100644
index 0000000..b3d6b25
--- /dev/null
+++ b/config/opencode/agents/test.md
@@ -0,0 +1,238 @@
+---
+description: Writes meaningful failing tests from task specs using TDD, verifying RED before handing off to @make
+mode: subagent
+model: anthropic/claude-sonnet-4-6-1m
+temperature: 0.2
+tools:
+  write: true
+  edit: true
+  bash: true
+permission:
+  bash:
+    # Default deny
+    "*": deny
+    # Test execution
+    "uv run pytest *": allow
+    "uv run pytest": allow
+    "uv run ruff check *": allow
+    "uv run ruff check": allow
+    # Read-only inspection
+    "ls *": allow
+    "ls": allow
+    "wc *": allow
+    "which *": allow
+    "diff *": allow
+    # Search
+    "rg *": allow
+    # Git inspection only (for file gate self-check)
+    "git diff --name-only*": allow
+    # Deny dangerous commands under uv run
+    "uv run bash*": deny
+    "uv run sh *": deny
+    "uv run sh": deny
+    "uv run zsh*": deny
+    "uv run fish*": deny
+    "uv run curl*": deny
+    "uv run wget*": deny
+    "uv run git*": deny
+    "uv run ssh*": deny
+    "uv run scp*": deny
+    "uv run rsync*": deny
+    "uv run rm *": deny
+    "uv run mv *": deny
+    "uv run cp *": deny
+    "uv run python -c*": deny
+    "uv run python -m http*": deny
+    # Explicit top-level denials
+    "git *": deny
+    "pip *": deny
+    "uv add*": deny
+    "uv remove*": deny
+    "curl *": deny
+    "wget *": deny
+    "ssh *": deny
+    "scp *": deny
+    "rsync *": deny
+---
+
+
+# Test - TDD Test Author
+
+You write meaningful, failing tests from task specifications. You verify they fail for the right reason (RED), then hand off to `@make` for implementation (GREEN).
+
+**Your tests will be reviewed.** Write tests that assert on real behavior, not mock existence.
+
+## Required Input
+
+You need these from the caller:
+
+| Required | Description |
+|----------|-------------|
+| **Task** | Clear description of what to implement |
+| **Acceptance Criteria** | Specific, testable criteria for success |
+| **Code Context** | Relevant existing code (actual snippets, not just paths) |
+| **Test File** | Path for the test file to create |
+
+| Optional | Description |
+|----------|-------------|
+| **Test Design** | Key behaviors to verify, edge cases, what NOT to test (from plan) |
+| **Constraints** | Patterns to follow, mocking boundaries, style requirements |
+
+When no Test Design is provided, derive test cases directly from the acceptance criteria.
+
+## File Constraint (Strict)
+
+**You may ONLY create or modify files matching these patterns:**
+- `**/test_*.py`
+- `**/*_test.py`
+- `**/conftest.py` (NEW files in new directories only — never modify existing conftest.py)
+- `**/test_data/**`
+- `**/test_fixtures/**`
+
+**You may NOT modify production/source code under any circumstances.**
+
+If you believe source code needs changes to be testable, report this to the caller — do not edit it yourself.
+
+This constraint is enforced by a post-step file gate. Violations cause your output to be discarded.
+
+## Test Philosophy
+
+**Contract tests + regression.** Write tests that verify:
+- Public API behavior: inputs, outputs, raised errors
+- Edge cases specified in acceptance criteria
+- For bug fixes: a test that reproduces the specific bug
+
+**Do NOT write:**
+- Tests for internal implementation details
+- Trivial tests (constructor creates object, getter returns value)
+- Tests that assert on mock behavior rather than real behavior
+- Tests requiring excessive mocking (>2 mocks suggests design problem — report it)
+
+**Follow existing codebase patterns:**
+- Use pytest (not unittest.TestCase)
+- Colocate tests with source code (match the project's existing pattern)
+- Use existing fixtures from conftest.py when available
+- Use `@pytest.mark.parametrize` for multiple cases of the same behavior
+- Use `unittest.mock` only for external services (W&B, Neptune, S3) or slow I/O
+- Organize related tests in plain classes (not TestCase subclasses)
+
+## Process
+
+1. **Read** existing code to understand the interface being tested
+2. **Write** test(s) asserting desired behavior from acceptance criteria
+3. **Run** tests — confirm they FAIL
+4. **Classify** the failure using structured failure codes (see below)
+5. **Report** with handoff for `@make`
+
+## Failure Classification
+
+After running tests, classify each failure:
+
+| Code | Meaning | Example | Valid RED? |
+|------|---------|---------|-----------|
+| `MISSING_BEHAVIOR` | Function/class/method doesn't exist yet | `ImportError`, `AttributeError`, `ModuleNotFoundError` on target module | Yes |
+| `ASSERTION_MISMATCH` | Code exists but behaves differently than expected | `AssertionError` with value diff | Yes (bug fixes) |
+| `TEST_BROKEN` | Test itself has errors | Collection error, fixture error, syntax error in test | No — fix before proceeding |
+| `ENV_BROKEN` | Environment issue | Missing dependency, CUDA unavailable | No — report as BLOCKED |
+
+**Mapping hints:**
+- `ImportError` / `ModuleNotFoundError` on the module being tested → `MISSING_BEHAVIOR`
+- `AttributeError: module 'X' has no attribute 'Y'` → `MISSING_BEHAVIOR`
+- `AssertionError` with actual vs expected values → `ASSERTION_MISMATCH`
+- `FixtureLookupError`, `SyntaxError` in test file, collection errors → `TEST_BROKEN`
+- `ModuleNotFoundError` on a third-party package → `ENV_BROKEN`
+
+Only `MISSING_BEHAVIOR` and `ASSERTION_MISMATCH` qualify as valid RED. Fix `TEST_BROKEN` before reporting. Report `ENV_BROKEN` as BLOCKED.
+
+## Escalation Flag
+
+Report `escalate_to_check: true` when ANY of these objective triggers apply:
+- Mixed failure codes across tests (some MISSING_BEHAVIOR, some ASSERTION_MISMATCH)
+- Test required new fixtures or test utilities
+- Tests involve nondeterministic behavior (timing, randomness, floating point)
+- You are uncertain whether the test asserts on the right behavior
+- Test required more than 2 mocks
+
+Otherwise report `escalate_to_check: false`.
+
+## NOT_TESTABLE Verdict
+
+You may return `NOT_TESTABLE` only for these allowed reasons:
+
+| Reason | Example |
+|--------|---------|
+| **Config-only** | .gitignore change, pyproject.toml metadata, env var |
+| **External system without harness** | Change only affects API call to service with no local mock possible |
+| **Non-deterministic** | GPU numerical results, timing-dependent behavior |
+| **Pure wiring** | Decorator swap, import reorganization, no logic change |
+
+Must provide:
+- Which allowed reason applies
+- What test approach was considered and why it's infeasible
+- Future seam (only when further work is expected in that area — skip for one-off dead-end changes)
+
+NOT_TESTABLE requires `@check` sign-off before proceeding.
+
+## Output Format
+
+```
+## Tests Written
+
+### Verdict: [TESTS_READY | NOT_TESTABLE | BLOCKED]
+
+### Test Files
+- `path/to/test_file.py` — [what it tests]
+
+### Handoff
+- **Pytest command:** `uv run pytest path/to/test_file.py -v`
+- **Expected failing tests:** test_name_1, test_name_2, ...
+- **Failure reasons:** MISSING_BEHAVIOR (all) | mixed (see detail)
+- **Escalate to @check:** true/false
+- **Escalation reason:** [only if true — which trigger]
+
+### RED Verification
+$ uv run pytest path/to/test_file.py -v
+[key failure output — truncated, not full dump]
+
+### Failure Detail (only for mixed/ambiguous failures)
+| Test | Failure Code | Status |
+|------|-------------|--------|
+| ... | MISSING_BEHAVIOR | VALID RED |
+| ... | ASSERTION_MISMATCH | VALID RED |
+
+### Notes for @make
+- [Setup instructions, fixture usage, import paths]
+- [Interface assumptions encoded in tests]
+```
+
+When verdict is `NOT_TESTABLE`:
+```
+### NOT_TESTABLE
+- **Allowed reason:** [config-only | external-system | non-deterministic | pure-wiring]
+- **Attempted:** [what test approach was considered]
+- **Future seam:** [what would make this testable — only if further work expected in area]
+```
+
+When verdict is `BLOCKED`:
+```
+### BLOCKED
+- **Problem:** [ENV_BROKEN details]
+- **Attempted:** [what was tried]
+- **Suggested fix:** [what the caller needs to resolve]
+```
+
+## Scope Constraints
+
+- **No production code edits** — Test files only; caller handles source
+- **No git operations** — Except `git diff --name-only` for self-inspection
+- **No new dependencies** — Use what's available in the environment
+- **No existing conftest.py modifications** — Create new conftest in new directories only
+- **Stay in scope** — Write tests for the task spec, nothing more
+
+## Tone
+
+- Direct and test-focused
+- Show the test code, don't describe it
+- Explicit about what each test verifies and why
+- Clear about failure classification
+
diff --git a/config/opencode/commands/review.md b/config/opencode/commands/review.md
new file mode 100644
index 0000000..245a75e
--- /dev/null
+++ b/config/opencode/commands/review.md
@@ -0,0 +1,116 @@
+---
+description: review changes [commit|branch|pr|@plan], defaults to uncommitted
+subtask: true
+---
+
+You are a code review orchestrator. Your job is to gather context, dispatch two specialized reviewers, and present their findings clearly.
+
+---
+
+## Step 1: Detect Input Type
+
+Input: $ARGUMENTS
+
+Classify the input into one of these modes:
+
+| Pattern | Mode |
+|---------|------|
+| Empty / no arguments | **code:uncommitted** |
+| Contains `github.com` or `pull` or is a bare number (e.g. `42`) | **code:pr** |
+| Hex string 7-40 chars (e.g. `a1b2c3d`) | **code:commit** |
+| File content provided via `@` reference (look for file contents in context) | **plan** |
+| Otherwise, treat as branch name | **code:branch** |
+
+Use best judgement when the input is ambiguous.
+
+---
+
+## Step 2: Gather Context
+
+### For code modes
+
+Run the appropriate git commands to get the diff:
+- **code:uncommitted**: `git diff` + `git diff --cached` + `git status --short` (read untracked files too)
+- **code:commit**: `git show $ARGUMENTS`
+- **code:branch**: `git diff $ARGUMENTS...HEAD`
+- **code:pr**: `gh pr view $ARGUMENTS` + `gh pr diff $ARGUMENTS`
+
+Then:
+1. Identify all changed files from the diff
+2. Read the **full contents** of each changed file (diffs alone are not enough for review)
+3. Check for project conventions: AGENTS.md, CONVENTIONS.md, .editorconfig
+
+### For plan mode
+
+1. The plan content is already available from the `@` file reference
+2. Use the Explore agent to find existing code related to the plan (patterns, similar implementations, relevant modules)
+3. Check for AGENTS.md, CONVENTIONS.md for project context
+
+---
+
+## Step 3: Dispatch Reviewers
+
+Dispatch BOTH reviewers using the Task tool. **Both are mandatory.**
+
+### @check
+
+Provide the full context gathered in Step 2.
+
+- **Code modes**: Tell it: "This is a code review. Here is the diff, the full file contents, and project conventions."
+- **Plan mode**: Tell it: "This is a plan/architecture review. Prioritize: Assumptions, Failure Modes, Testability, Compatibility. Here is the plan, related existing code, and project conventions."
+
+Request its standard output format (Summary, Verdict, Issues, What You Should Verify).
+
+### @simplify
+
+Provide the same context.
+
+- **Code modes**: Tell it: "Review this code change for unnecessary complexity."
+- **Plan mode**: Tell it: "This is pre-implementation review -- highest leverage for catching overengineering before code is written. Review this plan for unnecessary complexity."
+
+Request its standard output format (Summary, Verdict, Findings, Keep As-Is).
+
+### If either agent fails
+
+Note "Incomplete: [@agent] did not complete" in the output and present whatever results you have. Do not fabricate results for the missing agent.
+
+---
+
+## Step 4: Present Results
+
+Use this format exactly:
+
+```
+## Review Summary
+[1-2 sentences: what changed (or what the plan proposes) and overall assessment]
+
+## Gate Verdict (from @check): [BLOCK | NEEDS WORK | ACCEPTABLE]
+
+## Simplification Recommendation (from @simplify): [none | recommended | strong]
+
+## Risk & Correctness Issues
+[Present @check's issues verbatim, preserving its BLOCK/HIGH/MEDIUM/LOW
+severity and Must-fix/Follow-up OK priority labels.]
+
+## Simplification Opportunities
+[Present @simplify's findings verbatim, preserving its payoff/effort
+labels and category tags.]
+
+## Justified Complexity
+[@simplify's "Keep As-Is" items, if any]
+
+## What You Should Verify
+[@check's verification items]
+```
+
+---
+
+## Rules
+
+- Do NOT merge or normalize severity scales across agents. @check uses risk severity (BLOCK/HIGH/MEDIUM/LOW). @simplify uses payoff/effort. Show each in its native scale.
+- Do NOT invent your own issues. Only report what the agents found.
+- Do NOT add flattery, encouragement, or padding.
+- Do NOT deduplicate aggressively. If both agents flag the same location for different reasons, keep both -- the reader benefits from seeing both lenses.
+- The **Gate Verdict** (merge/no-merge decision) comes from @check only.
+- The **Simplification Recommendation** is advisory, not a merge gate.
+
diff --git a/config/opencode/commands/workflow.md b/config/opencode/commands/workflow.md
new file mode 100644
index 0000000..736758c
--- /dev/null
+++ b/config/opencode/commands/workflow.md
@@ -0,0 +1,249 @@
+---
+description: "Fire-and-forget multi-agent workflow: plan, test, implement, PR"
+agent: build
+---
+
+You are executing the autonomous multi-agent workflow. Run all phases without waiting for user input. The user has walked away.
+
+**Task reference:** $ARGUMENTS
+
+If `$ARGUMENTS` is empty, stop immediately: "Usage: `/workflow <ISSUE-ID>` (e.g. `/workflow ABC-1`). The ID must exist in `./TODO.md`."
+
+---
+
+## Phase 1: Repo Setup
+
+Verify you are at the bare repo root and the environment is ready.
+
+1. Confirm `.bare/` directory exists in the current working directory. If not, stop: "Not at bare repo root. Run from the directory containing `.bare/`."
+2. Verify the repo is hosted on GitHub: `git remote get-url origin 2>/dev/null | grep -qE '(github\.com|^git@github\.com:)'`. If the command fails (no `origin` remote, or origin is not on GitHub), stop: "Workflow requires a GitHub remote at `origin` (used by `gh pr create` in Phase 10)."
+3. Run `gh auth status`. If auth is expired or missing, stop: "GitHub CLI auth expired. Run `gh auth login` before retrying."
+4. Proceed to Phase 2 to get issue context before creating the worktree.
+
+---
+
+## Phase 2: Issue Context
+
+Use `@pm` to fetch the issue matching `$ARGUMENTS` from `./TODO.md`:
+- Issue title, description, acceptance criteria
+- Labels and priority
+- Any existing branch name / PR link
+
+If the issue does not exist or `@pm` fails, stop with error.
+
+Derive a branch name: `<issue-id-lowercase>-<slugified-title>` (e.g. `abc-1-add-retry-logic`). Validate: only `[A-Za-z0-9._/-]`, no leading `-`.
+
+---
+
+## Phase 3: Repo Setup (continued)
+
+From the bare repo root (the directory containing `.bare/`):
+
+1. `git fetch origin`
+2. Compute worktree directory: replace all `/` with `-` in the branch name (e.g. `feat/abc-1-foo` becomes `feat-abc-1-foo`)
+3. Check if worktree directory already exists. If yes, enter it and verify `git status --porcelain` is empty. If dirty, stop: "Worktree exists but has uncommitted changes. Clean it up first."
+4. If worktree does not exist: `git worktree add <dir-name> -b <branch-name> master`
+5. Change working directory to the new worktree.
+
+---
+
+## Phase 4: Plan
+
+Analyze the codebase in the worktree context. Create a detailed implementation plan addressing the issue's requirements and acceptance criteria.
+
+The plan should include:
+- Problem summary (from issue context)
+- Proposed approach with rationale
+- Files to modify (with brief description of changes)
+- New files to create
+- Risks and open questions
+- **Test Design (conditional — include for non-trivial tasks):**
+  - Key behaviors to verify (what tests should assert)
+  - Edge cases and error conditions worth testing
+  - What explicitly should NOT be tested (prevents bloat)
+  - Testability concerns (heavy external deps, GPU-only paths, etc.)
+
+  **Include Test Design for:** Public API changes, bug fixes with behavioral impact, new features with business logic, multi-module changes.
+  **Skip Test Design for:** Config-only changes, decorator swaps, import reorganization, documentation.
+  When skipped, `@test` derives test cases directly from acceptance criteria.
+
+---
+
+## Phase 5: Review Plan
+
+Dispatch `@check` and `@simplify` in parallel to review the plan.
+
+Reviewers should evaluate testability:
+- `@check`: Is the design testable? Are the right behaviors identified? (Review Framework §8)
+- `@simplify`: Is the test scope appropriate? Over-testing proposed?
+
+**Merge rules:**
+- `@check` safety/correctness findings are hard constraints
+- If `@simplify` recommends removing something `@check` flags as needed, `@check` wins
+- Note conflicts explicitly
+
+**Review loop (max 3 cycles):**
+1. Send plan to both reviewers
+2. Merge findings
+3. If verdict is ACCEPTABLE from both (or JUSTIFIED COMPLEXITY from `@simplify`): proceed to Phase 6
+4. If BLOCK or NEEDS WORK: revise the plan addressing findings, then re-review
+5. **Convergence detection:** if reviewers return the same findings as the previous cycle, stop the loop early
+6. If still unresolved after 3 cycles: note unresolved blockers and proceed anyway (they will be documented in the PR)
+
+---
+
+## Phase 6: Split into Tasks
+
+Break the approved plan into discrete tasks for `@make`. Each task needs:
+
+| Required | Description |
+|----------|-------------|
+| **Task** | Clear description of what to implement |
+| **Acceptance Criteria** | Specific, testable criteria (checkbox format) |
+| **Code Context** | Actual code snippets from the codebase, not just file paths |
+| **Files to Modify** | Explicit list, mark new files with "(create)" |
+| **Test File** | Path for test file (colocated pattern), e.g., `<module>/tests/test_<feature>.py (create)` |
+
+Include **Integration Contracts** when a task adds/changes function signatures, APIs, config keys, or has dependencies on other tasks.
+
+Include **Test Design** from Phase 4 when available, attached to the relevant task(s).
+
+**Task size:** ~10-30 minutes each, single coherent change, clear boundaries.
+
+---
+
+## Phase 7: Write Tests
+
+For each task from Phase 6, dispatch `@test` with:
+- The task spec (acceptance criteria, code context, files to modify)
+- The Test Design section from the plan (if provided)
+- The test file path to create (following colocated pattern)
+
+`@test` writes failing tests and verifies RED with structured failure codes.
+
+**Post-step file gate (MANDATORY):**
+Before dispatching `@test`, snapshot the current changed files:
+```bash
+git diff --name-only > /tmp/pre_test_baseline.txt
+```
+After `@test` completes, validate only NEW changes:
+```bash
+git diff --name-only | comm -23 - /tmp/pre_test_baseline.txt > /tmp/test_new_files.txt
+```
+All new files must match: `**/test_*.py`, `**/*_test.py`, `**/conftest.py` (new only), `**/test_data/**`, `**/test_fixtures/**`.
+If any non-matching file appears: discard `@test` output, report violation.
+
+**Decision table — handling `@test` results:**
+
+| Condition | Action |
+|-----------|--------|
+| `TESTS_READY` + `escalate_to_check: false` | Proceed to Phase 8 |
+| `TESTS_READY` + `escalate_to_check: true` | Route tests to `@check` for light review. `@check` diagnoses, caller routes fixes to `@test`. Then proceed. |
+| `NOT_TESTABLE` | Route to `@check` for sign-off on justification. If approved, task goes to `@make` without tests. |
+| `BLOCKED` | Investigate. May need to revise task spec or plan. |
+| Test passes immediately | Investigate — behavior may already exist. Task spec may be wrong. |
+
+**Parallelism:** Independent tasks can have tests written in parallel.
+**Constraint:** `@test` must not modify existing conftest.py files (prevents collision during parallel execution).
+
+---
+
+## Phase 8: Implement
+
+Execute each task by dispatching `@make` with:
+- The task spec (from Phase 6)
+- Relevant code context (actual snippets)
+- **Pre-written failing tests and handoff from `@test` (if TESTS_READY)**
+
+`@make` runs in TDD mode when tests are provided:
+1. Entry validation: run tests, verify RED, check failure codes match handoff
+2. Implement minimal code to make tests pass (GREEN)
+3. Regression check on broader area
+4. Refactor while keeping green
+5. Report RED→GREEN evidence
+
+**Escalation:** If `@make` flags test quality concerns during entry validation:
+1. `@make` reports the issue to caller
+2. Caller routes to `@check` for diagnosis
+3. `@check` reports findings
+4. Caller routes to `@test` for fixes
+5. Fixed tests return to `@make`
+
+For NOT_TESTABLE tasks, `@make` runs in standard mode.
+
+After all tasks complete, verify overall integration:
+- Run the project's test suite if available
+- Run linting/type checking if configured
+- Fix any integration issues between tasks
+
+---
+
+## Phase 9: Final Review
+
+Dispatch `@check` and `@simplify` in parallel to review the full implementation (all changes across all files).
+
+Provide reviewers with:
+- The original plan
+- The full diff (`git diff master...HEAD`)
+- Any decisions or deviations from the plan
+
+**Review loop (max 3 cycles):**
+1. Send implementation to both reviewers
+2. Merge findings (same precedence rules as Phase 5)
+3. If ACCEPTABLE: proceed to Phase 10
+4. If issues found: fix them directly (no need to re-dispatch `@make` for small fixes), then re-review
+5. **Convergence detection:** same findings twice = stop loop early
+6. If unresolved after 3 cycles: document blockers, proceed to PR anyway
+
+---
+
+## Phase 10: Commit, PR, and Wrap Up
+
+### Commit
+- Stage all changes
+- Write a conventional commit message summarizing the implementation
+- If changes are large/varied, use multiple atomic commits (one per logical unit)
+
+### Draft PR
+- `gh pr create --draft --title "<conventional title>" --body "<execution report>"`
+- PR body should include:
+  - Summary of what was implemented
+  - Reference to TODO.md issue ID
+  - Acceptance criteria checklist (from issue)
+  - Files changed with brief descriptions
+  - TDD summary: X tasks with tests (RED→GREEN), Y tasks NOT_TESTABLE with justifications
+  - Any test quality escalations and their resolution
+  - Unresolved blockers (if any from review loops)
+  - Review cycle outcomes
+
+### TODO Update
+- Use `@pm` to update the issue in `./TODO.md`:
+  - Set the **PR** field to the draft PR URL
+  - Set **Branch** to the worktree branch name
+  - Set **Status** to `In Review`
+  - Add a comment with the PR link and a one-line summary
+- If acceptance-criteria checkboxes were addressed by the implementation, ask `@pm` to check them off
+
+### Local Summary
+- Write `.opencode/workflow-summary.md` in the worktree with:
+  - Run timestamp
+  - Issue reference and title
+  - Branch and PR link
+  - Summary of implementation
+  - TDD evidence (RED→GREEN per task, NOT_TESTABLE justifications)
+  - Review outcomes (plan review + final review verdicts)
+  - Unresolved items (if any)
+  - Files changed
+
+---
+
+## Failure Handling
+
+At any phase, if an unrecoverable error occurs:
+1. Write `.opencode/workflow-summary.md` with what was completed and what failed
+2. If any code was written, commit it with message `wip: incomplete workflow run for <issue-id>`
+3. If a branch exists with commits, create the draft PR noting it is incomplete
+4. Stop execution
+
+**Never hang on interactive prompts.** If any command appears to require input, treat it as a failure and follow the above procedure.
+

From 2941faa8222dbbcf496bb0ae15e4915281181ea8 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Wed, 6 May 2026 15:28:08 +0200
Subject: [PATCH 064/101] refactor(opencode): make workflow forge-agnostic and
 read TODO.md from bare repo

Drops all GitHub-specific tooling (gh CLI, draft PR creation) so the
workflow stops at git commit and leaves push/PR/MR to the user.

TODO.md is now expected to be a tracked file on the default branch.
Phase 1 verifies the repo is bare via `git rev-parse --is-bare-repository`,
resolves the default branch from HEAD / init.defaultBranch, and snapshots
TODO.md via `git show "$DEFAULT_BRANCH:TODO.md"` to a tempfile that @pm
reads in Phase 2. Phase 10 updates the live TODO.md inside the worktree
and commits the change separately. The /review command drops its PR
mode for the same reason; @pm documents the read-only-snapshot vs.
live-worktree path distinction.
---
 config/opencode/agents/pm.md         | 17 ++++--
 config/opencode/commands/review.md   |  6 +-
 config/opencode/commands/workflow.md | 84 +++++++++++++++-------------
 3 files changed, 61 insertions(+), 46 deletions(-)

diff --git a/config/opencode/agents/pm.md b/config/opencode/agents/pm.md
index 196844d..fa95269 100644
--- a/config/opencode/agents/pm.md
+++ b/config/opencode/agents/pm.md
@@ -11,13 +11,22 @@ tools:
   bash: false
 ---
 
-You are a project management assistant. Your sole responsibility is reading and updating a local `TODO.md` file at the project root. You do **not** modify any other file under any circumstances.
+You are a project management assistant. Your sole responsibility is reading and updating a `TODO.md` file. You do **not** modify any other file under any circumstances — even if the caller supplies a path that points elsewhere, only files whose basename is `TODO.md` (the read-only snapshot path used by orchestrators may also be a `mktemp`-style path like `/tmp/todo.XXXXXX.md`) are acceptable.
 
 ## File Location
 
-The issue tracker lives at `./TODO.md` (relative to the working directory). If the file does not exist when an operation requires it:
-- For read/list operations: report "TODO.md not found at <absolute path>" and stop.
-- For create operations: create it with the header `# TODO\n\n` and proceed.
+The caller supplies the TODO.md path in the prompt as an absolute path. There are two patterns:
+
+1. **Read-only snapshot** — the caller has extracted TODO.md from a git ref (e.g. `git show main:TODO.md`) into a temp file like `/tmp/todo.abc123.md`. Read it but do **not** write to it. If the caller asks for an update, refuse and explain that the snapshot is read-only.
+2. **Live worktree path** — the caller passes a path like `/path/to/worktree/TODO.md`. Both reads and writes are allowed.
+
+The caller indicates the mode in the prompt (e.g. "read-only snapshot at ..." vs. "live file at ..."). When the mode is unclear, default to read-only and ask.
+
+If no path is provided, fall back to `./TODO.md` relative to the current working directory. This fallback is for ad-hoc invocations only.
+
+If the file does not exist when an operation requires it:
+- For read/list/update operations: report "TODO.md not found at <absolute path>" and stop.
+- For create operations: create it with the header `# TODO\n\n` and proceed (only when in live mode).
 
 ## TODO.md Schema
 
diff --git a/config/opencode/commands/review.md b/config/opencode/commands/review.md
index 245a75e..77522e0 100644
--- a/config/opencode/commands/review.md
+++ b/config/opencode/commands/review.md
@@ -1,5 +1,5 @@
 ---
-description: review changes [commit|branch|pr|@plan], defaults to uncommitted
+description: review changes [commit|branch|@plan], defaults to uncommitted
 subtask: true
 ---
 
@@ -16,12 +16,11 @@ Classify the input into one of these modes:
 | Pattern | Mode |
 |---------|------|
 | Empty / no arguments | **code:uncommitted** |
-| Contains `github.com` or `pull` or is a bare number (e.g. `42`) | **code:pr** |
 | Hex string 7-40 chars (e.g. `a1b2c3d`) | **code:commit** |
 | File content provided via `@` reference (look for file contents in context) | **plan** |
 | Otherwise, treat as branch name | **code:branch** |
 
-Use best judgement when the input is ambiguous.
+Use best judgement when the input is ambiguous. The command is forge-agnostic — review remote pull/merge requests by checking out the branch locally and passing the branch name (or by passing the merge-base commit).
 
 ---
 
@@ -33,7 +32,6 @@ Run the appropriate git commands to get the diff:
 - **code:uncommitted**: `git diff` + `git diff --cached` + `git status --short` (read untracked files too)
 - **code:commit**: `git show $ARGUMENTS`
 - **code:branch**: `git diff $ARGUMENTS...HEAD`
-- **code:pr**: `gh pr view $ARGUMENTS` + `gh pr diff $ARGUMENTS`
 
 Then:
 1. Identify all changed files from the diff
diff --git a/config/opencode/commands/workflow.md b/config/opencode/commands/workflow.md
index 736758c..3a5997b 100644
--- a/config/opencode/commands/workflow.md
+++ b/config/opencode/commands/workflow.md
@@ -1,5 +1,5 @@
 ---
-description: "Fire-and-forget multi-agent workflow: plan, test, implement, PR"
+description: "Fire-and-forget multi-agent workflow: plan, test, implement, commit"
 agent: build
 ---
 
@@ -13,21 +13,33 @@ If `$ARGUMENTS` is empty, stop immediately: "Usage: `/workflow <ISSUE-ID>` (e.g.
 
 ## Phase 1: Repo Setup
 
-Verify you are at the bare repo root and the environment is ready.
+Verify you are in a bare git repo and that the issue tracker exists.
 
-1. Confirm `.bare/` directory exists in the current working directory. If not, stop: "Not at bare repo root. Run from the directory containing `.bare/`."
-2. Verify the repo is hosted on GitHub: `git remote get-url origin 2>/dev/null | grep -qE '(github\.com|^git@github\.com:)'`. If the command fails (no `origin` remote, or origin is not on GitHub), stop: "Workflow requires a GitHub remote at `origin` (used by `gh pr create` in Phase 10)."
-3. Run `gh auth status`. If auth is expired or missing, stop: "GitHub CLI auth expired. Run `gh auth login` before retrying."
-4. Proceed to Phase 2 to get issue context before creating the worktree.
+1. Verify the current repository is bare: `git rev-parse --is-bare-repository 2>/dev/null` must output `true`. If not, stop: "Workflow requires a bare git repository (set up with `git clone --bare` or the `.bare/` + `.git` file pattern)."
+2. Capture the bare repo root for later worktree creation: `BARE_REPO_ROOT="$(pwd)"`.
+3. Determine the default branch (source of TODO.md and base for new worktrees). Resolve in order:
+   a. `git symbolic-ref --short HEAD` — the bare repo's HEAD
+   b. `git config init.defaultBranch` — the configured default
+   c. fall back to `main`
+
+   Store as `DEFAULT_BRANCH`.
+4. Verify TODO.md exists on the default branch: `git show "$DEFAULT_BRANCH:TODO.md" > /dev/null 2>&1`. If not, stop: "TODO.md not found on `$DEFAULT_BRANCH`. Commit a TODO.md there first — the workflow expects it to be a tracked file."
+5. Snapshot TODO.md to a temp file so `@pm` can read it before any worktree exists:
+   ```bash
+   TODO_READ_PATH="$(mktemp -t todo.XXXXXX.md)"
+   git show "$DEFAULT_BRANCH:TODO.md" > "$TODO_READ_PATH"
+   ```
+   Pass `$TODO_READ_PATH` to `@pm` in Phase 2 (read-only context).
+6. Proceed to Phase 2.
 
 ---
 
 ## Phase 2: Issue Context
 
-Use `@pm` to fetch the issue matching `$ARGUMENTS` from `./TODO.md`:
+Use `@pm` to fetch the issue matching `$ARGUMENTS` from the snapshot at `$TODO_READ_PATH`:
 - Issue title, description, acceptance criteria
 - Labels and priority
-- Any existing branch name / PR link
+- Any existing branch name
 
 If the issue does not exist or `@pm` fails, stop with error.
 
@@ -37,13 +49,13 @@ Derive a branch name: `<issue-id-lowercase>-<slugified-title>` (e.g. `abc-1-add-
 
 ## Phase 3: Repo Setup (continued)
 
-From the bare repo root (the directory containing `.bare/`):
+From `$BARE_REPO_ROOT`:
 
-1. `git fetch origin`
+1. If an `origin` remote is configured, run `git fetch origin` (best-effort; ignore failure if there is no remote).
 2. Compute worktree directory: replace all `/` with `-` in the branch name (e.g. `feat/abc-1-foo` becomes `feat-abc-1-foo`)
 3. Check if worktree directory already exists. If yes, enter it and verify `git status --porcelain` is empty. If dirty, stop: "Worktree exists but has uncommitted changes. Clean it up first."
-4. If worktree does not exist: `git worktree add <dir-name> -b <branch-name> master`
-5. Change working directory to the new worktree.
+4. If worktree does not exist: `git worktree add <dir-name> -b <branch-name> "$DEFAULT_BRANCH"`
+5. Change working directory to the new worktree. From here on, `./TODO.md` in the worktree is the **live, writable** copy that Phase 10 will update.
 
 ---
 
@@ -88,7 +100,7 @@ Reviewers should evaluate testability:
 3. If verdict is ACCEPTABLE from both (or JUSTIFIED COMPLEXITY from `@simplify`): proceed to Phase 6
 4. If BLOCK or NEEDS WORK: revise the plan addressing findings, then re-review
 5. **Convergence detection:** if reviewers return the same findings as the previous cycle, stop the loop early
-6. If still unresolved after 3 cycles: note unresolved blockers and proceed anyway (they will be documented in the PR)
+6. If still unresolved after 3 cycles: note unresolved blockers and proceed anyway (they will be documented in the workflow summary and commit message)
 
 ---
 
@@ -184,7 +196,7 @@ Dispatch `@check` and `@simplify` in parallel to review the full implementation
 
 Provide reviewers with:
 - The original plan
-- The full diff (`git diff master...HEAD`)
+- The full diff (`git diff "$DEFAULT_BRANCH"...HEAD`)
 - Any decisions or deviations from the plan
 
 **Review loop (max 3 cycles):**
@@ -193,57 +205,53 @@ Provide reviewers with:
 3. If ACCEPTABLE: proceed to Phase 10
 4. If issues found: fix them directly (no need to re-dispatch `@make` for small fixes), then re-review
 5. **Convergence detection:** same findings twice = stop loop early
-6. If unresolved after 3 cycles: document blockers, proceed to PR anyway
+6. If unresolved after 3 cycles: document blockers, proceed to commit anyway
 
 ---
 
-## Phase 10: Commit, PR, and Wrap Up
+## Phase 10: Commit and Wrap Up
 
-### Commit
-- Stage all changes
-- Write a conventional commit message summarizing the implementation
+The workflow is forge-agnostic. It commits locally and stops. **Do not push, and do not open a pull/merge request** — the user chooses their forge and review workflow manually.
+
+### Commit Code Changes
+- Stage code changes (everything except `TODO.md` and `.opencode/workflow-summary.md`, which are committed separately below)
+- Write a conventional commit message summarizing the implementation. Reference the TODO.md issue ID in the body (e.g. `Refs: ABC-1`).
 - If changes are large/varied, use multiple atomic commits (one per logical unit)
 
-### Draft PR
-- `gh pr create --draft --title "<conventional title>" --body "<execution report>"`
-- PR body should include:
-  - Summary of what was implemented
-  - Reference to TODO.md issue ID
-  - Acceptance criteria checklist (from issue)
-  - Files changed with brief descriptions
-  - TDD summary: X tasks with tests (RED→GREEN), Y tasks NOT_TESTABLE with justifications
-  - Any test quality escalations and their resolution
-  - Unresolved blockers (if any from review loops)
-  - Review cycle outcomes
-
 ### TODO Update
-- Use `@pm` to update the issue in `./TODO.md`:
-  - Set the **PR** field to the draft PR URL
+- Use `@pm` to update the issue in `./TODO.md` (worktree-local; this is the live, writable copy):
   - Set **Branch** to the worktree branch name
   - Set **Status** to `In Review`
-  - Add a comment with the PR link and a one-line summary
+  - Add a comment with the branch name, latest commit SHA, and a one-line summary
 - If acceptance-criteria checkboxes were addressed by the implementation, ask `@pm` to check them off
+- Commit the TODO.md change as a separate atomic commit: `chore(todo): update <issue-id> status and progress`
 
 ### Local Summary
 - Write `.opencode/workflow-summary.md` in the worktree with:
   - Run timestamp
   - Issue reference and title
-  - Branch and PR link
+  - Branch name and final commit SHA(s)
   - Summary of implementation
   - TDD evidence (RED→GREEN per task, NOT_TESTABLE justifications)
   - Review outcomes (plan review + final review verdicts)
   - Unresolved items (if any)
   - Files changed
+- Commit the summary: `chore(workflow): summary for <issue-id>`
+
+### Cleanup
+- Remove the temp snapshot from Phase 1: `rm -f "$TODO_READ_PATH"`
 
 ---
 
 ## Failure Handling
 
 At any phase, if an unrecoverable error occurs:
-1. Write `.opencode/workflow-summary.md` with what was completed and what failed
+1. Write `.opencode/workflow-summary.md` (in the worktree, if one exists) with what was completed and what failed
 2. If any code was written, commit it with message `wip: incomplete workflow run for <issue-id>`
-3. If a branch exists with commits, create the draft PR noting it is incomplete
-4. Stop execution
+3. Leave the branch and worktree intact for the user to inspect — do not push, do not delete
+4. If a worktree exists, use `@pm` to add a comment on the issue in `./TODO.md` summarising what failed
+5. Remove the temp snapshot if it was created: `rm -f "$TODO_READ_PATH"`
+6. Stop execution
 
 **Never hang on interactive prompts.** If any command appears to require input, treat it as a failure and follow the above procedure.
 

From 37be2d9505c101fff970803eda4672efe19c6331 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Wed, 6 May 2026 15:33:11 +0200
Subject: [PATCH 065/101] fix(opencode): remove agent models and temperature

---
 config/opencode/agents/check.md    | 1 -
 config/opencode/agents/make.md     | 2 --
 config/opencode/agents/pm.md       | 1 -
 config/opencode/agents/simplify.md | 2 --
 config/opencode/agents/test.md     | 2 --
 5 files changed, 8 deletions(-)

diff --git a/config/opencode/agents/check.md b/config/opencode/agents/check.md
index 3017641..eb8bd67 100644
--- a/config/opencode/agents/check.md
+++ b/config/opencode/agents/check.md
@@ -1,7 +1,6 @@
 ---
 description: Design reviewer that systematically identifies risks, gaps, and flaws in plans, architectures, and PRs
 mode: subagent
-model: openai/gpt-5.3-codex
 temperature: 0.4
 tools:
   # Read-only: no write/edit/shell
diff --git a/config/opencode/agents/make.md b/config/opencode/agents/make.md
index 41e10f7..6780ffa 100644
--- a/config/opencode/agents/make.md
+++ b/config/opencode/agents/make.md
@@ -1,8 +1,6 @@
 ---
 description: Implements discrete coding tasks from specs with acceptance criteria, verifying each implementation before completion
 mode: subagent
-model: anthropic/claude-sonnet-4-6-1m
-temperature: 0.2
 tools:
   write: true
   edit: true
diff --git a/config/opencode/agents/pm.md b/config/opencode/agents/pm.md
index fa95269..a0124be 100644
--- a/config/opencode/agents/pm.md
+++ b/config/opencode/agents/pm.md
@@ -1,7 +1,6 @@
 ---
 description: Project management agent that manages issues in a local TODO.md file (status, comments, acceptance criteria)
 mode: subagent
-model: anthropic/claude-haiku-4-5
 tools:
   read: true
   glob: true
diff --git a/config/opencode/agents/simplify.md b/config/opencode/agents/simplify.md
index 1b4b195..04d0977 100644
--- a/config/opencode/agents/simplify.md
+++ b/config/opencode/agents/simplify.md
@@ -1,8 +1,6 @@
 ---
 description: Spots overengineering and unnecessary complexity. Proposes concrete simplifications.
 mode: subagent
-model: openai/gpt-5.3-codex
-temperature: 0.4
 tools:
   # Read-only: no write/edit/shell
   write: false
diff --git a/config/opencode/agents/test.md b/config/opencode/agents/test.md
index b3d6b25..af8fad1 100644
--- a/config/opencode/agents/test.md
+++ b/config/opencode/agents/test.md
@@ -1,8 +1,6 @@
 ---
 description: Writes meaningful failing tests from task specs using TDD, verifying RED before handing off to @make
 mode: subagent
-model: anthropic/claude-sonnet-4-6-1m
-temperature: 0.2
 tools:
   write: true
   edit: true

From d22acf690634883490b2117b6668e328e1804374 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Wed, 6 May 2026 15:42:17 +0200
Subject: [PATCH 066/101] refactor(opencode): let @pm read TODO.md via git
 show, drop tempfile

Gives @pm narrowly-scoped bash access (git show *, git rev-parse *) so
it can read TODO.md directly from any git ref. The workflow no longer
needs to mktemp + redirect the file before invoking the agent; Phase 2
just tells @pm the bare repo path and default branch and lets it run
git show "$DEFAULT_BRANCH:TODO.md" itself. Cleanup steps for the temp
snapshot are removed from Phase 10 and the failure handler.
---
 config/opencode/agents/pm.md         | 31 ++++++++++++++++++----------
 config/opencode/commands/workflow.md | 15 +++-----------
 2 files changed, 23 insertions(+), 23 deletions(-)

diff --git a/config/opencode/agents/pm.md b/config/opencode/agents/pm.md
index a0124be..e32342c 100644
--- a/config/opencode/agents/pm.md
+++ b/config/opencode/agents/pm.md
@@ -7,25 +7,34 @@ tools:
   grep: true
   write: true
   edit: true
-  bash: false
+  bash: true
+permission:
+  bash:
+    "*": deny
+    "git show *": allow
+    "git rev-parse *": allow
 ---
 
-You are a project management assistant. Your sole responsibility is reading and updating a `TODO.md` file. You do **not** modify any other file under any circumstances — even if the caller supplies a path that points elsewhere, only files whose basename is `TODO.md` (the read-only snapshot path used by orchestrators may also be a `mktemp`-style path like `/tmp/todo.XXXXXX.md`) are acceptable.
+You are a project management assistant. Your sole responsibility is reading and updating a `TODO.md` file. You do **not** modify any other file under any circumstances.
 
-## File Location
+## How to Read TODO.md
 
-The caller supplies the TODO.md path in the prompt as an absolute path. There are two patterns:
+There are two ways to read TODO.md, depending on what the caller tells you:
 
-1. **Read-only snapshot** — the caller has extracted TODO.md from a git ref (e.g. `git show main:TODO.md`) into a temp file like `/tmp/todo.abc123.md`. Read it but do **not** write to it. If the caller asks for an update, refuse and explain that the snapshot is read-only.
-2. **Live worktree path** — the caller passes a path like `/path/to/worktree/TODO.md`. Both reads and writes are allowed.
+1. **From a git ref** (used when there is no working tree, e.g. inside a bare repo) — run `git show <ref>:TODO.md` and parse stdout. Example: caller says "read TODO.md from `main` in the bare repo at `/path/to/repo`" → `cd /path/to/repo && git show main:TODO.md`. This is **read-only**: never attempt to update TODO.md when invoked in this mode. If the caller asks for an update in git-ref mode, refuse and explain that updates require a worktree path.
+2. **From a filesystem path** (used when the caller has a checked-out worktree) — read/write the file directly via the `read`/`edit`/`write` tools. The caller supplies an absolute path like `/path/to/worktree/TODO.md`.
 
-The caller indicates the mode in the prompt (e.g. "read-only snapshot at ..." vs. "live file at ..."). When the mode is unclear, default to read-only and ask.
+The caller indicates the mode in the prompt. When the mode is ambiguous, default to read-only git-ref mode and ask.
 
-If no path is provided, fall back to `./TODO.md` relative to the current working directory. This fallback is for ad-hoc invocations only.
+If no path or ref is provided, fall back to `./TODO.md` relative to the current working directory (ad-hoc invocations only).
 
-If the file does not exist when an operation requires it:
-- For read/list/update operations: report "TODO.md not found at <absolute path>" and stop.
-- For create operations: create it with the header `# TODO\n\n` and proceed (only when in live mode).
+## Bash Discipline
+
+The only bash commands you may run are `git show <ref>:TODO.md` and `git rev-parse <args>` (for verifying refs/repo state). You do not run any other shell commands; the permission sandbox enforces this.
+
+If TODO.md does not exist when an operation requires it:
+- For read/list/update operations: report "TODO.md not found at <absolute path or ref>" and stop.
+- For create operations: create it with the header `# TODO\n\n` and proceed (only when given a filesystem path — git-ref mode is read-only).
 
 ## TODO.md Schema
 
diff --git a/config/opencode/commands/workflow.md b/config/opencode/commands/workflow.md
index 3a5997b..9bcd0af 100644
--- a/config/opencode/commands/workflow.md
+++ b/config/opencode/commands/workflow.md
@@ -24,19 +24,13 @@ Verify you are in a bare git repo and that the issue tracker exists.
 
    Store as `DEFAULT_BRANCH`.
 4. Verify TODO.md exists on the default branch: `git show "$DEFAULT_BRANCH:TODO.md" > /dev/null 2>&1`. If not, stop: "TODO.md not found on `$DEFAULT_BRANCH`. Commit a TODO.md there first — the workflow expects it to be a tracked file."
-5. Snapshot TODO.md to a temp file so `@pm` can read it before any worktree exists:
-   ```bash
-   TODO_READ_PATH="$(mktemp -t todo.XXXXXX.md)"
-   git show "$DEFAULT_BRANCH:TODO.md" > "$TODO_READ_PATH"
-   ```
-   Pass `$TODO_READ_PATH` to `@pm` in Phase 2 (read-only context).
-6. Proceed to Phase 2.
+5. Proceed to Phase 2.
 
 ---
 
 ## Phase 2: Issue Context
 
-Use `@pm` to fetch the issue matching `$ARGUMENTS` from the snapshot at `$TODO_READ_PATH`:
+Dispatch `@pm` in **read-only git-ref mode**: tell it the bare repo path is `$BARE_REPO_ROOT` and to read TODO.md via `git show "$DEFAULT_BRANCH:TODO.md"`. Ask for the issue matching `$ARGUMENTS`:
 - Issue title, description, acceptance criteria
 - Labels and priority
 - Any existing branch name
@@ -238,8 +232,6 @@ The workflow is forge-agnostic. It commits locally and stops. **Do not push, and
   - Files changed
 - Commit the summary: `chore(workflow): summary for <issue-id>`
 
-### Cleanup
-- Remove the temp snapshot from Phase 1: `rm -f "$TODO_READ_PATH"`
 
 ---
 
@@ -250,8 +242,7 @@ At any phase, if an unrecoverable error occurs:
 2. If any code was written, commit it with message `wip: incomplete workflow run for <issue-id>`
 3. Leave the branch and worktree intact for the user to inspect — do not push, do not delete
 4. If a worktree exists, use `@pm` to add a comment on the issue in `./TODO.md` summarising what failed
-5. Remove the temp snapshot if it was created: `rm -f "$TODO_READ_PATH"`
-6. Stop execution
+5. Stop execution
 
 **Never hang on interactive prompts.** If any command appears to require input, treat it as a failure and follow the above procedure.
 

From 28c7785816e228da5fbd2d5c765a0e69f53f4f48 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Wed, 6 May 2026 15:56:45 +0200
Subject: [PATCH 067/101] fix(opencode): pass absolute worktree path to every
 subagent dispatch

Subagents do not inherit the orchestrator's `cd`, so dispatched prompts
that referred to files relative to the worktree were resolved against
the bare repo root and failed with "file not found" (observed when
@check tried to read src/main.rs after Phase 3).

Phase 3 now captures `WORKTREE_PATH="$(pwd)"` after entering the
worktree. A new "Subagent Dispatch Convention" section requires every
dispatch in phases 5, 7, 8, 9, and 10 to open with `Worktree: <path>`
and pass file references as absolute paths under `$WORKTREE_PATH/`.
Phase 9's diff command uses `git -C "$WORKTREE_PATH"` rather than
relying on shell CWD, and @pm updates receive the explicit absolute
path to `$WORKTREE_PATH/TODO.md`.
---
 config/opencode/commands/workflow.md | 34 ++++++++++++++++++++--------
 1 file changed, 24 insertions(+), 10 deletions(-)

diff --git a/config/opencode/commands/workflow.md b/config/opencode/commands/workflow.md
index 9bcd0af..0009a63 100644
--- a/config/opencode/commands/workflow.md
+++ b/config/opencode/commands/workflow.md
@@ -49,7 +49,21 @@ From `$BARE_REPO_ROOT`:
 2. Compute worktree directory: replace all `/` with `-` in the branch name (e.g. `feat/abc-1-foo` becomes `feat-abc-1-foo`)
 3. Check if worktree directory already exists. If yes, enter it and verify `git status --porcelain` is empty. If dirty, stop: "Worktree exists but has uncommitted changes. Clean it up first."
 4. If worktree does not exist: `git worktree add <dir-name> -b <branch-name> "$DEFAULT_BRANCH"`
-5. Change working directory to the new worktree. From here on, `./TODO.md` in the worktree is the **live, writable** copy that Phase 10 will update.
+5. Change working directory to the new worktree and capture its absolute path: `WORKTREE_PATH="$(pwd)"`. From here on, `$WORKTREE_PATH/TODO.md` is the **live, writable** copy that Phase 10 will update.
+
+---
+
+## Subagent Dispatch Convention
+
+**Subagents do not inherit the orchestrator's `cd`.** When opencode dispatches `@check`, `@simplify`, `@test`, `@make`, or `@pm`, each starts with a fresh shell in an unspecified working directory and may resolve relative paths against the bare repo root rather than the worktree. This produces silent "file not found" failures for paths like `src/main.rs`.
+
+**Every dispatch prompt in Phases 5, 7, 8, 9, and 10 must:**
+
+1. Open with the header `Worktree: <absolute path>` using the captured `$WORKTREE_PATH`.
+2. State explicitly: "All file paths in this prompt are relative to that worktree. Read files via their absolute path (`<worktree>/<rel>`); do not rely on the current working directory."
+3. Pass any file reference (in code context, diff snippets, file lists) as an absolute path under `$WORKTREE_PATH/`.
+
+`@pm` invocations that update TODO.md must receive `$WORKTREE_PATH/TODO.md` as the live path. `@pm` invocations that only read from a git ref (Phase 2) instead receive `$BARE_REPO_ROOT` and the ref name.
 
 ---
 
@@ -77,7 +91,7 @@ The plan should include:
 
 ## Phase 5: Review Plan
 
-Dispatch `@check` and `@simplify` in parallel to review the plan.
+Dispatch `@check` and `@simplify` in parallel to review the plan. Each dispatch prompt must follow the **Subagent Dispatch Convention** (header `Worktree: $WORKTREE_PATH`, absolute paths only).
 
 Reviewers should evaluate testability:
 - `@check`: Is the design testable? Are the right behaviors identified? (Review Framework §8)
@@ -120,10 +134,10 @@ Include **Test Design** from Phase 4 when available, attached to the relevant ta
 
 ## Phase 7: Write Tests
 
-For each task from Phase 6, dispatch `@test` with:
+For each task from Phase 6, dispatch `@test` with (per the **Subagent Dispatch Convention** — `Worktree: $WORKTREE_PATH`, absolute paths):
 - The task spec (acceptance criteria, code context, files to modify)
 - The Test Design section from the plan (if provided)
-- The test file path to create (following colocated pattern)
+- The test file path to create as an absolute path under `$WORKTREE_PATH/` (following colocated pattern)
 
 `@test` writes failing tests and verifies RED with structured failure codes.
 
@@ -156,9 +170,9 @@ If any non-matching file appears: discard `@test` output, report violation.
 
 ## Phase 8: Implement
 
-Execute each task by dispatching `@make` with:
+Execute each task by dispatching `@make` with (per the **Subagent Dispatch Convention** — `Worktree: $WORKTREE_PATH`, absolute paths):
 - The task spec (from Phase 6)
-- Relevant code context (actual snippets)
+- Relevant code context (actual snippets, with absolute file paths under `$WORKTREE_PATH/`)
 - **Pre-written failing tests and handoff from `@test` (if TESTS_READY)**
 
 `@make` runs in TDD mode when tests are provided:
@@ -186,11 +200,11 @@ After all tasks complete, verify overall integration:
 
 ## Phase 9: Final Review
 
-Dispatch `@check` and `@simplify` in parallel to review the full implementation (all changes across all files).
+Dispatch `@check` and `@simplify` in parallel to review the full implementation (all changes across all files). Each dispatch prompt must follow the **Subagent Dispatch Convention** (header `Worktree: $WORKTREE_PATH`, absolute paths only).
 
 Provide reviewers with:
 - The original plan
-- The full diff (`git diff "$DEFAULT_BRANCH"...HEAD`)
+- The full diff (`git -C "$WORKTREE_PATH" diff "$DEFAULT_BRANCH"...HEAD`)
 - Any decisions or deviations from the plan
 
 **Review loop (max 3 cycles):**
@@ -213,7 +227,7 @@ The workflow is forge-agnostic. It commits locally and stops. **Do not push, and
 - If changes are large/varied, use multiple atomic commits (one per logical unit)
 
 ### TODO Update
-- Use `@pm` to update the issue in `./TODO.md` (worktree-local; this is the live, writable copy):
+- Dispatch `@pm` (per the **Subagent Dispatch Convention**) and pass the live path `$WORKTREE_PATH/TODO.md` so it edits the worktree's writable copy. Ask it to:
   - Set **Branch** to the worktree branch name
   - Set **Status** to `In Review`
   - Add a comment with the branch name, latest commit SHA, and a one-line summary
@@ -241,7 +255,7 @@ At any phase, if an unrecoverable error occurs:
 1. Write `.opencode/workflow-summary.md` (in the worktree, if one exists) with what was completed and what failed
 2. If any code was written, commit it with message `wip: incomplete workflow run for <issue-id>`
 3. Leave the branch and worktree intact for the user to inspect — do not push, do not delete
-4. If a worktree exists, use `@pm` to add a comment on the issue in `./TODO.md` summarising what failed
+4. If a worktree exists, dispatch `@pm` (with header `Worktree: $WORKTREE_PATH` and the absolute path `$WORKTREE_PATH/TODO.md`) to add a comment on the issue summarising what failed
 5. Stop execution
 
 **Never hang on interactive prompts.** If any command appears to require input, treat it as a failure and follow the above procedure.

From c879870ccfa9fe1e12b066db213a80067693e501 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Wed, 6 May 2026 16:43:35 +0200
Subject: [PATCH 068/101] fix(opencode): remove temperature

---
 config/opencode/agents/check.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/config/opencode/agents/check.md b/config/opencode/agents/check.md
index eb8bd67..2329978 100644
--- a/config/opencode/agents/check.md
+++ b/config/opencode/agents/check.md
@@ -1,7 +1,6 @@
 ---
 description: Design reviewer that systematically identifies risks, gaps, and flaws in plans, architectures, and PRs
 mode: subagent
-temperature: 0.4
 tools:
   # Read-only: no write/edit/shell
   write: false

From f750c76877a5e4652e3a7dae5030af26fc03a968 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Wed, 6 May 2026 16:51:19 +0200
Subject: [PATCH 069/101] fix(opencode): keep workflow-summary.md local, never
 commit it

A per-branch artifact written by every run causes merge conflicts when
multiple workflow branches are merged together. The summary is now
documented as an intentionally untracked local file: not staged in the
main commit, not committed in its own commit, and not staged in the
failure-path WIP commit. Recommends the user add `.opencode/` to
`.gitignore`.
---
 config/opencode/commands/workflow.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/config/opencode/commands/workflow.md b/config/opencode/commands/workflow.md
index 0009a63..0051053 100644
--- a/config/opencode/commands/workflow.md
+++ b/config/opencode/commands/workflow.md
@@ -222,7 +222,7 @@ Provide reviewers with:
 The workflow is forge-agnostic. It commits locally and stops. **Do not push, and do not open a pull/merge request** — the user chooses their forge and review workflow manually.
 
 ### Commit Code Changes
-- Stage code changes (everything except `TODO.md` and `.opencode/workflow-summary.md`, which are committed separately below)
+- Stage code changes only. **Do not stage `TODO.md`** (committed separately below) and **do not stage `.opencode/workflow-summary.md`** (intentionally never committed — see Local Summary).
 - Write a conventional commit message summarizing the implementation. Reference the TODO.md issue ID in the body (e.g. `Refs: ABC-1`).
 - If changes are large/varied, use multiple atomic commits (one per logical unit)
 
@@ -244,7 +244,7 @@ The workflow is forge-agnostic. It commits locally and stops. **Do not push, and
   - Review outcomes (plan review + final review verdicts)
   - Unresolved items (if any)
   - Files changed
-- Commit the summary: `chore(workflow): summary for <issue-id>`
+- **Do not commit this file.** It is a per-run, per-branch artifact; committing it would create merge conflicts whenever multiple workflow branches are merged. Leave it untracked. Recommend the user add `.opencode/` to `.gitignore` if not already.
 
 
 ---
@@ -252,8 +252,8 @@ The workflow is forge-agnostic. It commits locally and stops. **Do not push, and
 ## Failure Handling
 
 At any phase, if an unrecoverable error occurs:
-1. Write `.opencode/workflow-summary.md` (in the worktree, if one exists) with what was completed and what failed
-2. If any code was written, commit it with message `wip: incomplete workflow run for <issue-id>`
+1. Write `.opencode/workflow-summary.md` (in the worktree, if one exists) with what was completed and what failed. Do **not** stage or commit this file.
+2. If any code was written, commit it with message `wip: incomplete workflow run for <issue-id>`. Stage code only — exclude `.opencode/workflow-summary.md`.
 3. Leave the branch and worktree intact for the user to inspect — do not push, do not delete
 4. If a worktree exists, dispatch `@pm` (with header `Worktree: $WORKTREE_PATH` and the absolute path `$WORKTREE_PATH/TODO.md`) to add a comment on the issue summarising what failed
 5. Stop execution

From 8fcf7e5d34a07cb6e9c10c0ba86ab8676bae5e02 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Wed, 6 May 2026 17:09:34 +0200
Subject: [PATCH 070/101] feat(opencode): make @make and @test polyglot
 (Python, Rust, nix devshell)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Both agents previously hardcoded the Python/uv toolchain. They now
detect the language from marker files (pyproject.toml, Cargo.toml,
flake.nix) and run the appropriate test/lint/format/type-check commands
for Python, Rust, or both. When a flake.nix devshell is present, every
toolchain command is wrapped in `nix develop -c …`.

@make's permission allowlist gains `cargo *` and `nix develop -c *`,
plus matching denies for cargo add/remove/install/publish. The
Verification Tiers and Baseline Verification sections are rewritten as
per-language bullets, and output/TDD-evidence examples are now
language-neutral. Generalised the "no Kubernetes deployments"
constraint to cover any deploy/publish.

@test gains the same devshell + cargo allows (scoped to test, check,
clippy, fmt only — no build/run/install). Its file constraint adds
`tests/**/*.rs` for Rust integration tests, with an explicit note that
Rust unit tests stay with @make because they live inside production
source files. Failure-classification hints add Rust compiler-error
mappings, and the NOT_TESTABLE table gets a "Rust unit-only" row.
---
 config/opencode/agents/make.md | 145 ++++++++++++++++++++++++---------
 config/opencode/agents/test.md | 110 +++++++++++++++++++------
 2 files changed, 192 insertions(+), 63 deletions(-)

diff --git a/config/opencode/agents/make.md b/config/opencode/agents/make.md
index 6780ffa..67802fb 100644
--- a/config/opencode/agents/make.md
+++ b/config/opencode/agents/make.md
@@ -9,10 +9,48 @@ permission:
   bash:
     # Default deny
     "*": deny
-    # Python/uv development
+
+    # ── Nix devshell entry ──
+    # All toolchain commands may be wrapped in `nix develop -c <cmd>` to run
+    # them inside the project's devshell with the correct versions.
+    "nix develop -c *": allow
+    "nix develop --command *": allow
+
+    # ── Python (uv) ──
     "uv run *": allow
     "uv run": allow
-    # Deny dangerous commands under uv run (must come after allow to override)
+
+    # ── Rust (cargo) ──
+    "cargo *": allow
+    "cargo": allow
+
+    # ── Read-only inspection ──
+    "ls *": allow
+    "ls": allow
+    "wc *": allow
+    "which *": allow
+    "diff *": allow
+    "rg *": allow
+
+    # ── Explicit top-level denials ──
+    "git *": deny
+    "pip *": deny
+    "uv add*": deny
+    "uv remove*": deny
+    "cargo add*": deny
+    "cargo remove*": deny
+    "cargo install*": deny
+    "cargo publish*": deny
+    "curl *": deny
+    "wget *": deny
+    "ssh *": deny
+    "scp *": deny
+    "rsync *": deny
+    "rm *": deny
+    "mv *": deny
+    "cp *": deny
+
+    # ── Deny dangerous commands under `uv run` ──
     "uv run bash*": deny
     "uv run sh *": deny
     "uv run sh": deny
@@ -29,24 +67,6 @@ permission:
     "uv run cp *": deny
     "uv run python -c*": deny
     "uv run python -m http*": deny
-    # Read-only inspection
-    "ls *": allow
-    "ls": allow
-    "wc *": allow
-    "which *": allow
-    "diff *": allow
-    # Search
-    "rg *": allow
-    # Explicit top-level denials
-    "git *": deny
-    "pip *": deny
-    "uv add*": deny
-    "uv remove*": deny
-    "curl *": deny
-    "wget *": deny
-    "ssh *": deny
-    "scp *": deny
-    "rsync *": deny
 ---
 
 
@@ -89,7 +109,7 @@ If a task appears to touch shared interfaces but no integration contract is prov
 
 This includes:
 - Existing files to edit
-- New files to create (must be listed, e.g., "src/new_module.py (create)")
+- New files to create (must be listed, e.g. `src/new_module.py (create)` or `crates/foo/src/lib.rs (create)`)
 
 **Not supported:** File renames and deletions. If a task requires renaming or deleting files, stop and report this to the caller — they will handle it directly.
 
@@ -98,7 +118,33 @@ If you discover another file needs changes:
 2. Report which file needs modification and why
 3. Request permission before proceeding
 
-**Excluded from this constraint:** Generated artifacts (.pyc, __pycache__, .coverage, etc.) — these should not be committed anyway.
+**Excluded from this constraint:** Generated artifacts (`.pyc`, `__pycache__`, `.coverage`, `target/`, `Cargo.lock` only when allowed by acceptance criteria, etc.) — these should not be committed anyway.
+
+## Language and Toolchain
+
+You may be invoked on Python, Rust, or polyglot Nix-flake projects. Detect the toolchain at the start of the task and use the appropriate commands:
+
+| Marker file | Toolchain | Test | Lint / Format | Type-check |
+|---|---|---|---|---|
+| `pyproject.toml`, `uv.lock` | Python (`uv`) | `uv run pytest` | `uv run ruff check .` / `uv run ruff format --check .` | `uv run ty check .` or `uv run basedpyright .` |
+| `Cargo.toml` | Rust (`cargo`) | `cargo test` | `cargo clippy --all-targets -- -D warnings`, `cargo fmt -- --check` | `cargo check` (compiler-driven) |
+| `flake.nix` | Nix flake | `nix flake check` | `nix fmt -- --check` (if configured) | (n/a) |
+
+### Devshell wrapping
+
+If the project has a `flake.nix` with a `devShells.default` (or per-system equivalent), **run all toolchain commands inside the devshell** by prefixing them with `nix develop -c`:
+
+```
+nix develop -c cargo test
+nix develop -c uv run pytest
+nix develop -c cargo clippy --all-targets -- -D warnings
+```
+
+The devshell guarantees the right toolchain versions are available. Detect once at task start, decide whether to wrap, then be consistent for the whole task. **Never drop into an interactive `nix develop` (with no command).** If a non-trivial task touches multiple commands and the devshell entry overhead matters, you may still wrap each command individually — that is the supported pattern.
+
+### Polyglot tasks
+
+A task may legitimately span multiple languages (e.g. a Rust binary plus its Python test harness). Run the appropriate verification per file area; document each in the verification block.
 
 ## Dependency Constraint
 
@@ -150,10 +196,23 @@ If a task is too large, suggest splitting it.
 Every acceptance criterion must be verified. Use the strongest tier available:
 
 ### Tier 1: Automated Tests (Preferred)
-- Run existing test suite: `uv run pytest`
-- Add new test if criteria isn't covered by existing tests
-- Type check: `uv run ty check .` or `uv run basedpyright .`
-- Lint: `uv run ruff check .`
+- Run the language-appropriate test runner (see **Language and Toolchain**):
+  - Python: `uv run pytest`
+  - Rust: `cargo test`
+  - Polyglot Nix: `nix flake check`
+- Add new tests if a criterion isn't covered by existing ones.
+- Lint:
+  - Python: `uv run ruff check .`
+  - Rust: `cargo clippy --all-targets -- -D warnings`
+- Format check:
+  - Python: `uv run ruff format --check .`
+  - Rust: `cargo fmt -- --check`
+  - Nix: `nix fmt -- --check` (if configured)
+- Type check:
+  - Python: `uv run ty check .` or `uv run basedpyright .`
+  - Rust: `cargo check` (the compiler covers it)
+
+Wrap every command in `nix develop -c …` when the project has a devshell.
 
 ### Tier 2: Deterministic Reproduction (Acceptable)
 - Scripted steps that can be re-run
@@ -167,10 +226,11 @@ Every acceptance criterion must be verified. Use the strongest tier available:
 
 ### Baseline Verification
 
-Run what's configured and applicable:
-- `uv run pytest` — if tests exist and are relevant
-- `uv run ruff check .` — if ruff is configured
-- `uv run ty check .` — if ty/type checking is configured
+Run what's configured and applicable to the project's toolchain. Prefix with `nix develop -c` when a devshell exists.
+
+- **Python:** `uv run pytest`, `uv run ruff check .`, `uv run ruff format --check .`, `uv run ty check .`
+- **Rust:** `cargo test`, `cargo clippy --all-targets -- -D warnings`, `cargo fmt -- --check`
+- **Nix flake:** `nix flake check`, `nix fmt -- --check` (if configured)
 
 If a tool isn't configured or not applicable to this change, note "skipped: [reason]" rather than failing.
 
@@ -234,17 +294,22 @@ Always end with this structure:
 [1-2 sentences: what was implemented]
 
 ### Files Changed
-- `path/to/file.py` — [brief description of change]
-- `path/to/new_file.py` (created) — [description]
+- `path/to/file.{py,rs,nix,…}` — [brief description of change]
+- `path/to/new_file.{py,rs,nix,…}` (created) — [description]
 
 ### Verification
 
-**Commands run:**
-$ uv run pytest tests/test_foo.py -v
+**Commands run:** (use whichever apply to this language; wrap with `nix develop -c` if a devshell exists)
+
+$ cargo test --package my_crate
 [key output excerpt — truncate if long, show pass/fail summary]
 
+$ cargo clippy --all-targets -- -D warnings
+[summary]
+
+(or, for Python:)
+$ uv run pytest tests/test_foo.py -v
 $ uv run ruff check src/
-All checks passed.
 
 **Criteria verification:**
 | Criterion | Method | Result |
@@ -309,18 +374,20 @@ Include this section when tests were provided:
 ```
 ### TDD Evidence
 **RED (before implementation):**
-$ uv run pytest path/to/test_file.py -v
+$ <test command>     # e.g. `uv run pytest path/to/test_file.py -v`, `cargo test --test integration`
 X failed, 0 passed
 
 **GREEN (after implementation):**
-$ uv run pytest path/to/test_file.py -v
+$ <same test command>
 0 failed, X passed
 
 **Regression check:**
-$ uv run pytest path/to/affected_area/ -v
+$ <broader test command>     # e.g. `uv run pytest path/to/affected_area/ -v`, `cargo test`
 Y passed, 0 failed
 ```
 
+Use the project's actual command (Python/Rust/Nix), wrapped in `nix develop -c` if applicable.
+
 When no tests are provided (NOT_TESTABLE tasks), standard implementation mode applies unchanged.
 
 ## Scope Constraints
@@ -329,7 +396,7 @@ When no tests are provided (NOT_TESTABLE tasks), standard implementation mode ap
 - **Stay in scope** — Implement what's asked, nothing more
 - **Preserve existing patterns** — Match the codebase style unless told otherwise
 - **Don't refactor adjacent code** — Unless it's part of the task
-- **No Kubernetes deployments** — Local testing only (`--without kubernetes`); K8s verification is handled by the main agent
+- **No deployments or releases** — Local testing only. No `cargo publish`, no `uv publish`, no Kubernetes apply. Release/deploy verification is handled by the main agent.
 - **No network requests** — Don't fetch external resources unless explicitly required by the task
 - **No file renames/deletions** — Report to caller if needed; they handle directly
 
diff --git a/config/opencode/agents/test.md b/config/opencode/agents/test.md
index af8fad1..aec7615 100644
--- a/config/opencode/agents/test.md
+++ b/config/opencode/agents/test.md
@@ -9,22 +9,56 @@ permission:
   bash:
     # Default deny
     "*": deny
-    # Test execution
+
+    # ── Nix devshell entry ──
+    "nix develop -c *": allow
+    "nix develop --command *": allow
+
+    # ── Python (uv) — pytest + ruff only ──
     "uv run pytest *": allow
     "uv run pytest": allow
     "uv run ruff check *": allow
     "uv run ruff check": allow
-    # Read-only inspection
+
+    # ── Rust (cargo) — test/check/clippy/fmt only ──
+    "cargo test*": allow
+    "cargo nextest *": allow
+    "cargo check*": allow
+    "cargo clippy*": allow
+    "cargo fmt*": allow
+
+    # ── Read-only inspection ──
     "ls *": allow
     "ls": allow
     "wc *": allow
     "which *": allow
     "diff *": allow
-    # Search
     "rg *": allow
-    # Git inspection only (for file gate self-check)
+
+    # ── Git inspection only (for file-gate self-check) ──
     "git diff --name-only*": allow
-    # Deny dangerous commands under uv run
+
+    # ── Explicit top-level denials ──
+    "git *": deny
+    "pip *": deny
+    "uv add*": deny
+    "uv remove*": deny
+    "cargo add*": deny
+    "cargo remove*": deny
+    "cargo install*": deny
+    "cargo publish*": deny
+    "cargo build*": deny
+    "cargo run*": deny
+    "curl *": deny
+    "wget *": deny
+    "ssh *": deny
+    "scp *": deny
+    "rsync *": deny
+    "rm *": deny
+    "mv *": deny
+    "cp *": deny
+
+    # ── Deny dangerous commands under `uv run` ──
     "uv run bash*": deny
     "uv run sh *": deny
     "uv run sh": deny
@@ -41,16 +75,6 @@ permission:
     "uv run cp *": deny
     "uv run python -c*": deny
     "uv run python -m http*": deny
-    # Explicit top-level denials
-    "git *": deny
-    "pip *": deny
-    "uv add*": deny
-    "uv remove*": deny
-    "curl *": deny
-    "wget *": deny
-    "ssh *": deny
-    "scp *": deny
-    "rsync *": deny
 ---
 
 
@@ -81,14 +105,31 @@ When no Test Design is provided, derive test cases directly from the acceptance
 ## File Constraint (Strict)
 
 **You may ONLY create or modify files matching these patterns:**
+
+Python:
 - `**/test_*.py`
 - `**/*_test.py`
 - `**/conftest.py` (NEW files in new directories only — never modify existing conftest.py)
 - `**/test_data/**`
 - `**/test_fixtures/**`
 
+Rust (integration tests only — see "Rust unit tests" below):
+- `tests/**/*.rs` (crate-level integration tests directory)
+- `**/tests/**/*.rs` (per-crate integration tests in workspace layouts)
+- `**/test_data/**`
+- `**/test_fixtures/**`
+
 **You may NOT modify production/source code under any circumstances.**
 
+### Rust unit tests
+
+Rust unit tests live inside production source files (inside `#[cfg(test)] mod tests { ... }` blocks in `src/**/*.rs`). Because that would require modifying production code, **you do not write Rust unit tests.** Options when the task spec requests unit-level coverage in Rust:
+
+1. Convert to an integration test under `tests/` if the unit is part of the public API.
+2. Return `NOT_TESTABLE` with reason `pure-wiring` or `external-system` if no integration-level seam exists, and let `@make` write the in-source tests.
+
+Report this constraint to the caller rather than silently degrading coverage.
+
 If you believe source code needs changes to be testable, report this to the caller — do not edit it yourself.
 
 This constraint is enforced by a post-step file gate. Violations cause your output to be discarded.
@@ -106,14 +147,27 @@ This constraint is enforced by a post-step file gate. Violations cause your outp
 - Tests that assert on mock behavior rather than real behavior
 - Tests requiring excessive mocking (>2 mocks suggests design problem — report it)
 
-**Follow existing codebase patterns:**
+**Follow existing codebase patterns** (per language):
+
+Python:
 - Use pytest (not unittest.TestCase)
 - Colocate tests with source code (match the project's existing pattern)
-- Use existing fixtures from conftest.py when available
+- Use existing fixtures from `conftest.py` when available
 - Use `@pytest.mark.parametrize` for multiple cases of the same behavior
-- Use `unittest.mock` only for external services (W&B, Neptune, S3) or slow I/O
+- Use `unittest.mock` only for external services or slow I/O
 - Organize related tests in plain classes (not TestCase subclasses)
 
+Rust:
+- Integration tests only (see File Constraint). Place under `tests/<feature>.rs` or `tests/<feature>/main.rs`.
+- Use the standard `#[test]` attribute. For async tests, match what the crate already uses (`#[tokio::test]`, `#[async_std::test]`, etc.).
+- For parameterised cases, prefer `rstest` if the crate already uses it; otherwise simple loops or per-case `#[test]` functions.
+- Use `assert_eq!`, `assert_ne!`, `assert!` with informative messages.
+- Use existing test helpers from the crate's `tests/common/` module when present.
+
+### Devshell wrapping
+
+If the project has a `flake.nix` with a `devShells.default`, wrap every test/lint command with `nix develop -c …` (e.g. `nix develop -c cargo test`, `nix develop -c uv run pytest`). The devshell guarantees the right toolchain is on PATH.
+
 ## Process
 
 1. **Read** existing code to understand the interface being tested
@@ -133,13 +187,20 @@ After running tests, classify each failure:
 | `TEST_BROKEN` | Test itself has errors | Collection error, fixture error, syntax error in test | No — fix before proceeding |
 | `ENV_BROKEN` | Environment issue | Missing dependency, CUDA unavailable | No — report as BLOCKED |
 
-**Mapping hints:**
+**Mapping hints (Python):**
 - `ImportError` / `ModuleNotFoundError` on the module being tested → `MISSING_BEHAVIOR`
 - `AttributeError: module 'X' has no attribute 'Y'` → `MISSING_BEHAVIOR`
 - `AssertionError` with actual vs expected values → `ASSERTION_MISMATCH`
 - `FixtureLookupError`, `SyntaxError` in test file, collection errors → `TEST_BROKEN`
 - `ModuleNotFoundError` on a third-party package → `ENV_BROKEN`
 
+**Mapping hints (Rust):**
+- `error[E0432]: unresolved import` / `error[E0425]: cannot find function/value` for the symbol under test → `MISSING_BEHAVIOR`
+- `error[E0599]: no method named ...` on a real but incomplete type → `MISSING_BEHAVIOR`
+- Test panics with `assertion failed: ... left: ..., right: ...` → `ASSERTION_MISMATCH`
+- Test file fails to compile due to its own bug (typo, wrong type, unused-import-as-error) → `TEST_BROKEN`
+- `linker not found`, missing system library, missing feature flag → `ENV_BROKEN`
+
 Only `MISSING_BEHAVIOR` and `ASSERTION_MISMATCH` qualify as valid RED. Fix `TEST_BROKEN` before reporting. Report `ENV_BROKEN` as BLOCKED.
 
 ## Escalation Flag
@@ -159,10 +220,11 @@ You may return `NOT_TESTABLE` only for these allowed reasons:
 
 | Reason | Example |
 |--------|---------|
-| **Config-only** | .gitignore change, pyproject.toml metadata, env var |
+| **Config-only** | `.gitignore` change, `pyproject.toml` / `Cargo.toml` metadata, env var, `flake.nix` input bump |
 | **External system without harness** | Change only affects API call to service with no local mock possible |
 | **Non-deterministic** | GPU numerical results, timing-dependent behavior |
-| **Pure wiring** | Decorator swap, import reorganization, no logic change |
+| **Pure wiring** | Decorator swap, import / `use` reorganization, no logic change |
+| **Rust unit-only** | Coverage requires `#[cfg(test)]` mod tests in production source; @test cannot write those — let @make handle it |
 
 Must provide:
 - Which allowed reason applies
@@ -179,17 +241,17 @@ NOT_TESTABLE requires `@check` sign-off before proceeding.
 ### Verdict: [TESTS_READY | NOT_TESTABLE | BLOCKED]
 
 ### Test Files
-- `path/to/test_file.py` — [what it tests]
+- `path/to/test_file.{py,rs}` — [what it tests]
 
 ### Handoff
-- **Pytest command:** `uv run pytest path/to/test_file.py -v`
+- **Test command:** the exact command (e.g. `uv run pytest path/to/test_file.py -v`, `cargo test --test integration_foo`, wrapped in `nix develop -c …` if applicable)
 - **Expected failing tests:** test_name_1, test_name_2, ...
 - **Failure reasons:** MISSING_BEHAVIOR (all) | mixed (see detail)
 - **Escalate to @check:** true/false
 - **Escalation reason:** [only if true — which trigger]
 
 ### RED Verification
-$ uv run pytest path/to/test_file.py -v
+$ <test command>
 [key failure output — truncated, not full dump]
 
 ### Failure Detail (only for mixed/ambiguous failures)

From e2e35acdae8545ececb7dbe933ea7bc3cf5aad2b Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Wed, 6 May 2026 17:31:56 +0200
Subject: [PATCH 071/101] refactor(opencode): assume opencode runs in the
 worktree, drop bare-repo plumbing

The workflow previously created a worktree itself (Phase 3) and worked
around opencode's lack of per-subagent CWD by capturing absolute paths
and threading them through every dispatch (the "Subagent Dispatch
Convention"). That ceremony exists only because the orchestrator's CWD
differed from where subagents were rooted.

Now the workflow assumes the user has already created the worktree and
launched opencode inside it. Subagents inherit that as their project
root, so all the absolute-path plumbing goes away. Phase 3 is removed,
phases renumber to 1-9, and the Subagent Dispatch Convention section
is dropped.

Phase 1 is a sanity check (non-bare worktree, TODO.md present, HEAD
not detached, current branch != base branch) that resolves the base
branch from an optional second argument or by trying main then master.
@pm now uses live filesystem mode against ./TODO.md throughout (the
git-ref read mode stays available for ad-hoc use). Phase 8's diff
uses git diff "$BASE_BRANCH"...HEAD without git -C wrapping.
---
 config/opencode/commands/workflow.md | 130 ++++++++++++---------------
 1 file changed, 55 insertions(+), 75 deletions(-)

diff --git a/config/opencode/commands/workflow.md b/config/opencode/commands/workflow.md
index 0051053..08105b1 100644
--- a/config/opencode/commands/workflow.md
+++ b/config/opencode/commands/workflow.md
@@ -1,75 +1,54 @@
 ---
-description: "Fire-and-forget multi-agent workflow: plan, test, implement, commit"
+description: "Multi-agent workflow for the current worktree: plan, test, implement, commit"
 agent: build
 ---
 
-You are executing the autonomous multi-agent workflow. Run all phases without waiting for user input. The user has walked away.
+You are executing the multi-agent workflow inside the worktree this opencode session was started from. Run all phases without waiting for user input. The user has walked away.
+
+**Prerequisites (the user handles before launching opencode):**
+- A git worktree is checked out for the issue's feature branch
+- `opencode` was launched from the root of that worktree
+- `TODO.md` is committed to the repo and present at `./TODO.md`
 
 **Task reference:** $ARGUMENTS
 
-If `$ARGUMENTS` is empty, stop immediately: "Usage: `/workflow <ISSUE-ID>` (e.g. `/workflow ABC-1`). The ID must exist in `./TODO.md`."
+If `$ARGUMENTS` is empty, stop immediately: "Usage: `/workflow <ISSUE-ID> [base-branch]` (e.g. `/workflow ABC-1`). The ID must exist in `./TODO.md`. Base branch defaults to `main` (then `master`)."
+
+Parse `$ARGUMENTS`: the first whitespace-separated token is the issue ID, an optional second token overrides the base branch.
 
 ---
 
-## Phase 1: Repo Setup
+## Phase 1: Sanity Check
 
-Verify you are in a bare git repo and that the issue tracker exists.
-
-1. Verify the current repository is bare: `git rev-parse --is-bare-repository 2>/dev/null` must output `true`. If not, stop: "Workflow requires a bare git repository (set up with `git clone --bare` or the `.bare/` + `.git` file pattern)."
-2. Capture the bare repo root for later worktree creation: `BARE_REPO_ROOT="$(pwd)"`.
-3. Determine the default branch (source of TODO.md and base for new worktrees). Resolve in order:
-   a. `git symbolic-ref --short HEAD` — the bare repo's HEAD
-   b. `git config init.defaultBranch` — the configured default
-   c. fall back to `main`
-
-   Store as `DEFAULT_BRANCH`.
-4. Verify TODO.md exists on the default branch: `git show "$DEFAULT_BRANCH:TODO.md" > /dev/null 2>&1`. If not, stop: "TODO.md not found on `$DEFAULT_BRANCH`. Commit a TODO.md there first — the workflow expects it to be a tracked file."
-5. Proceed to Phase 2.
+1. Verify CWD is a non-bare git worktree: `git rev-parse --is-bare-repository 2>/dev/null` must output `false`. If not, stop: "Workflow must be run from a non-bare worktree (the directory opencode was launched in)."
+2. Verify `./TODO.md` exists. If not, stop: "TODO.md not found in the current worktree. Commit a TODO.md to the repo first."
+3. Verify HEAD is not detached: `git symbolic-ref --short HEAD` must succeed. If it fails, stop: "Cannot run on a detached HEAD. Check out a feature branch first."
+4. Capture the current branch: `BRANCH_NAME="$(git symbolic-ref --short HEAD)"`.
+5. Resolve the base branch (`BASE_BRANCH`):
+   - If `$ARGUMENTS` provided a second token, use it.
+   - Else if `git rev-parse --verify --quiet main` succeeds, use `main`.
+   - Else if `git rev-parse --verify --quiet master` succeeds, use `master`.
+   - Else stop: "Could not determine base branch (no `main` or `master`). Pass it as the second argument: `/workflow <ISSUE-ID> <base-branch>`."
+6. Verify the current branch is not the base branch: if `BRANCH_NAME == BASE_BRANCH`, stop: "Cannot run workflow on the base branch (`$BASE_BRANCH`). Switch to a feature branch first."
 
 ---
 
 ## Phase 2: Issue Context
 
-Dispatch `@pm` in **read-only git-ref mode**: tell it the bare repo path is `$BARE_REPO_ROOT` and to read TODO.md via `git show "$DEFAULT_BRANCH:TODO.md"`. Ask for the issue matching `$ARGUMENTS`:
+Dispatch `@pm` to read `./TODO.md` (live filesystem mode) and fetch the issue matching the parsed ID:
 - Issue title, description, acceptance criteria
 - Labels and priority
-- Any existing branch name
+- Existing status
 
 If the issue does not exist or `@pm` fails, stop with error.
 
-Derive a branch name: `<issue-id-lowercase>-<slugified-title>` (e.g. `abc-1-add-retry-logic`). Validate: only `[A-Za-z0-9._/-]`, no leading `-`.
+If the issue's status is `Backlog` or `Todo`, ask `@pm` to set it to `In Progress` (this edit will be staged in Phase 9 alongside other TODO.md updates).
 
 ---
 
-## Phase 3: Repo Setup (continued)
+## Phase 3: Plan
 
-From `$BARE_REPO_ROOT`:
-
-1. If an `origin` remote is configured, run `git fetch origin` (best-effort; ignore failure if there is no remote).
-2. Compute worktree directory: replace all `/` with `-` in the branch name (e.g. `feat/abc-1-foo` becomes `feat-abc-1-foo`)
-3. Check if worktree directory already exists. If yes, enter it and verify `git status --porcelain` is empty. If dirty, stop: "Worktree exists but has uncommitted changes. Clean it up first."
-4. If worktree does not exist: `git worktree add <dir-name> -b <branch-name> "$DEFAULT_BRANCH"`
-5. Change working directory to the new worktree and capture its absolute path: `WORKTREE_PATH="$(pwd)"`. From here on, `$WORKTREE_PATH/TODO.md` is the **live, writable** copy that Phase 10 will update.
-
----
-
-## Subagent Dispatch Convention
-
-**Subagents do not inherit the orchestrator's `cd`.** When opencode dispatches `@check`, `@simplify`, `@test`, `@make`, or `@pm`, each starts with a fresh shell in an unspecified working directory and may resolve relative paths against the bare repo root rather than the worktree. This produces silent "file not found" failures for paths like `src/main.rs`.
-
-**Every dispatch prompt in Phases 5, 7, 8, 9, and 10 must:**
-
-1. Open with the header `Worktree: <absolute path>` using the captured `$WORKTREE_PATH`.
-2. State explicitly: "All file paths in this prompt are relative to that worktree. Read files via their absolute path (`<worktree>/<rel>`); do not rely on the current working directory."
-3. Pass any file reference (in code context, diff snippets, file lists) as an absolute path under `$WORKTREE_PATH/`.
-
-`@pm` invocations that update TODO.md must receive `$WORKTREE_PATH/TODO.md` as the live path. `@pm` invocations that only read from a git ref (Phase 2) instead receive `$BARE_REPO_ROOT` and the ref name.
-
----
-
-## Phase 4: Plan
-
-Analyze the codebase in the worktree context. Create a detailed implementation plan addressing the issue's requirements and acceptance criteria.
+Analyze the codebase. Create a detailed implementation plan addressing the issue's requirements and acceptance criteria.
 
 The plan should include:
 - Problem summary (from issue context)
@@ -89,9 +68,9 @@ The plan should include:
 
 ---
 
-## Phase 5: Review Plan
+## Phase 4: Review Plan
 
-Dispatch `@check` and `@simplify` in parallel to review the plan. Each dispatch prompt must follow the **Subagent Dispatch Convention** (header `Worktree: $WORKTREE_PATH`, absolute paths only).
+Dispatch `@check` and `@simplify` in parallel to review the plan.
 
 Reviewers should evaluate testability:
 - `@check`: Is the design testable? Are the right behaviors identified? (Review Framework §8)
@@ -105,14 +84,14 @@ Reviewers should evaluate testability:
 **Review loop (max 3 cycles):**
 1. Send plan to both reviewers
 2. Merge findings
-3. If verdict is ACCEPTABLE from both (or JUSTIFIED COMPLEXITY from `@simplify`): proceed to Phase 6
+3. If verdict is ACCEPTABLE from both (or JUSTIFIED COMPLEXITY from `@simplify`): proceed to Phase 5
 4. If BLOCK or NEEDS WORK: revise the plan addressing findings, then re-review
 5. **Convergence detection:** if reviewers return the same findings as the previous cycle, stop the loop early
 6. If still unresolved after 3 cycles: note unresolved blockers and proceed anyway (they will be documented in the workflow summary and commit message)
 
 ---
 
-## Phase 6: Split into Tasks
+## Phase 5: Split into Tasks
 
 Break the approved plan into discrete tasks for `@make`. Each task needs:
 
@@ -126,18 +105,18 @@ Break the approved plan into discrete tasks for `@make`. Each task needs:
 
 Include **Integration Contracts** when a task adds/changes function signatures, APIs, config keys, or has dependencies on other tasks.
 
-Include **Test Design** from Phase 4 when available, attached to the relevant task(s).
+Include **Test Design** from Phase 3 when available, attached to the relevant task(s).
 
 **Task size:** ~10-30 minutes each, single coherent change, clear boundaries.
 
 ---
 
-## Phase 7: Write Tests
+## Phase 6: Write Tests
 
-For each task from Phase 6, dispatch `@test` with (per the **Subagent Dispatch Convention** — `Worktree: $WORKTREE_PATH`, absolute paths):
+For each task from Phase 5, dispatch `@test` with:
 - The task spec (acceptance criteria, code context, files to modify)
 - The Test Design section from the plan (if provided)
-- The test file path to create as an absolute path under `$WORKTREE_PATH/` (following colocated pattern)
+- The test file path to create (following colocated pattern)
 
 `@test` writes failing tests and verifies RED with structured failure codes.
 
@@ -150,14 +129,17 @@ After `@test` completes, validate only NEW changes:
 ```bash
 git diff --name-only | comm -23 - /tmp/pre_test_baseline.txt > /tmp/test_new_files.txt
 ```
-All new files must match: `**/test_*.py`, `**/*_test.py`, `**/conftest.py` (new only), `**/test_data/**`, `**/test_fixtures/**`.
+All new files must match the project's test patterns:
+- Python: `**/test_*.py`, `**/*_test.py`, `**/conftest.py` (new only), `**/test_data/**`, `**/test_fixtures/**`
+- Rust: `tests/**/*.rs`, `**/tests/**/*.rs`, `**/test_data/**`, `**/test_fixtures/**`
+
 If any non-matching file appears: discard `@test` output, report violation.
 
 **Decision table — handling `@test` results:**
 
 | Condition | Action |
 |-----------|--------|
-| `TESTS_READY` + `escalate_to_check: false` | Proceed to Phase 8 |
+| `TESTS_READY` + `escalate_to_check: false` | Proceed to Phase 7 |
 | `TESTS_READY` + `escalate_to_check: true` | Route tests to `@check` for light review. `@check` diagnoses, caller routes fixes to `@test`. Then proceed. |
 | `NOT_TESTABLE` | Route to `@check` for sign-off on justification. If approved, task goes to `@make` without tests. |
 | `BLOCKED` | Investigate. May need to revise task spec or plan. |
@@ -168,11 +150,11 @@ If any non-matching file appears: discard `@test` output, report violation.
 
 ---
 
-## Phase 8: Implement
+## Phase 7: Implement
 
-Execute each task by dispatching `@make` with (per the **Subagent Dispatch Convention** — `Worktree: $WORKTREE_PATH`, absolute paths):
-- The task spec (from Phase 6)
-- Relevant code context (actual snippets, with absolute file paths under `$WORKTREE_PATH/`)
+Execute each task by dispatching `@make` with:
+- The task spec (from Phase 5)
+- Relevant code context (actual snippets)
 - **Pre-written failing tests and handoff from `@test` (if TESTS_READY)**
 
 `@make` runs in TDD mode when tests are provided:
@@ -198,26 +180,26 @@ After all tasks complete, verify overall integration:
 
 ---
 
-## Phase 9: Final Review
+## Phase 8: Final Review
 
-Dispatch `@check` and `@simplify` in parallel to review the full implementation (all changes across all files). Each dispatch prompt must follow the **Subagent Dispatch Convention** (header `Worktree: $WORKTREE_PATH`, absolute paths only).
+Dispatch `@check` and `@simplify` in parallel to review the full implementation (all changes across all files).
 
 Provide reviewers with:
 - The original plan
-- The full diff (`git -C "$WORKTREE_PATH" diff "$DEFAULT_BRANCH"...HEAD`)
+- The full diff (`git diff "$BASE_BRANCH"...HEAD`)
 - Any decisions or deviations from the plan
 
 **Review loop (max 3 cycles):**
 1. Send implementation to both reviewers
-2. Merge findings (same precedence rules as Phase 5)
-3. If ACCEPTABLE: proceed to Phase 10
+2. Merge findings (same precedence rules as Phase 4)
+3. If ACCEPTABLE: proceed to Phase 9
 4. If issues found: fix them directly (no need to re-dispatch `@make` for small fixes), then re-review
 5. **Convergence detection:** same findings twice = stop loop early
 6. If unresolved after 3 cycles: document blockers, proceed to commit anyway
 
 ---
 
-## Phase 10: Commit and Wrap Up
+## Phase 9: Commit and Wrap Up
 
 The workflow is forge-agnostic. It commits locally and stops. **Do not push, and do not open a pull/merge request** — the user chooses their forge and review workflow manually.
 
@@ -227,8 +209,8 @@ The workflow is forge-agnostic. It commits locally and stops. **Do not push, and
 - If changes are large/varied, use multiple atomic commits (one per logical unit)
 
 ### TODO Update
-- Dispatch `@pm` (per the **Subagent Dispatch Convention**) and pass the live path `$WORKTREE_PATH/TODO.md` so it edits the worktree's writable copy. Ask it to:
-  - Set **Branch** to the worktree branch name
+- Dispatch `@pm` against `./TODO.md` (live filesystem mode). Ask it to:
+  - Set **Branch** to `$BRANCH_NAME`
   - Set **Status** to `In Review`
   - Add a comment with the branch name, latest commit SHA, and a one-line summary
 - If acceptance-criteria checkboxes were addressed by the implementation, ask `@pm` to check them off
@@ -246,17 +228,15 @@ The workflow is forge-agnostic. It commits locally and stops. **Do not push, and
   - Files changed
 - **Do not commit this file.** It is a per-run, per-branch artifact; committing it would create merge conflicts whenever multiple workflow branches are merged. Leave it untracked. Recommend the user add `.opencode/` to `.gitignore` if not already.
 
-
 ---
 
 ## Failure Handling
 
 At any phase, if an unrecoverable error occurs:
-1. Write `.opencode/workflow-summary.md` (in the worktree, if one exists) with what was completed and what failed. Do **not** stage or commit this file.
+1. Write `.opencode/workflow-summary.md` with what was completed and what failed. Do **not** stage or commit this file.
 2. If any code was written, commit it with message `wip: incomplete workflow run for <issue-id>`. Stage code only — exclude `.opencode/workflow-summary.md`.
-3. Leave the branch and worktree intact for the user to inspect — do not push, do not delete
-4. If a worktree exists, dispatch `@pm` (with header `Worktree: $WORKTREE_PATH` and the absolute path `$WORKTREE_PATH/TODO.md`) to add a comment on the issue summarising what failed
-5. Stop execution
+3. Leave the branch and worktree intact for the user to inspect — do not push, do not delete.
+4. Dispatch `@pm` against `./TODO.md` to add a comment on the issue summarising what failed.
+5. Stop execution.
 
 **Never hang on interactive prompts.** If any command appears to require input, treat it as a failure and follow the above procedure.
-

From d5d90d8b9f509dacaac97f7adcf5208acda54e3b Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Wed, 6 May 2026 18:31:14 +0200
Subject: [PATCH 072/101] fix(opencode): reject Rust src/tests/ paths as a
 wrong task spec
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A workflow run on a Bevy/Rust project produced the test-file path
`src/tests/test_<feature>.rs`, which @test correctly flagged as
contradictory: it isn't a valid Rust test location (would require
declaring `mod tests;` in production source, which @test cannot do)
yet the file-gate glob `**/tests/**/*.rs` accidentally matched it.

Phase 5 now gives language-aware Test File guidance: Python uses
colocated or top-level `tests/`, Rust uses crate-level `tests/<feature>.rs`,
and Rust unit-only tasks are routed to NOT_TESTABLE for @make to
handle inline. Phase 6's file gate gains an explicit anti-pattern
clause discarding any new file under `src/` even when the glob matches.

@test's own File Constraint mirrors the anti-pattern so the agent
rejects the bad path with BLOCKED before the orchestrator's gate
even runs — defense in depth on both sides of the dispatch boundary.
---
 config/opencode/agents/test.md       |  3 +++
 config/opencode/commands/workflow.md | 22 +++++++++++++++++++---
 2 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/config/opencode/agents/test.md b/config/opencode/agents/test.md
index aec7615..7afacff 100644
--- a/config/opencode/agents/test.md
+++ b/config/opencode/agents/test.md
@@ -119,6 +119,9 @@ Rust (integration tests only — see "Rust unit tests" below):
 - `**/test_data/**`
 - `**/test_fixtures/**`
 
+**Anti-patterns — refuse the path even if the glob above matches:**
+- Anything under `src/` (e.g. `src/tests/foo.rs`, `src/**/tests/...`). `src/tests/` is a regular module under `src/`; it would require declaring `mod tests;` in production code (`lib.rs` / `main.rs`) and creating `mod.rs`, which you cannot do. If the caller asks for such a path, treat it as a wrong task spec: return `BLOCKED` with a note that the path is not a valid Rust test location, suggesting `tests/<feature>.rs` (or `NOT_TESTABLE: Rust unit-only` if the test really needs to be in-source).
+
 **You may NOT modify production/source code under any circumstances.**
 
 ### Rust unit tests
diff --git a/config/opencode/commands/workflow.md b/config/opencode/commands/workflow.md
index 08105b1..2ff213f 100644
--- a/config/opencode/commands/workflow.md
+++ b/config/opencode/commands/workflow.md
@@ -101,7 +101,20 @@ Break the approved plan into discrete tasks for `@make`. Each task needs:
 | **Acceptance Criteria** | Specific, testable criteria (checkbox format) |
 | **Code Context** | Actual code snippets from the codebase, not just file paths |
 | **Files to Modify** | Explicit list, mark new files with "(create)" |
-| **Test File** | Path for test file (colocated pattern), e.g., `<module>/tests/test_<feature>.py (create)` |
+| **Test File** | Path for test file. **Pick the pattern that matches the project's language** — see "Test File Path by Language" below. |
+
+### Test File Path by Language
+
+The test file path must follow the language's actual test layout. **Do not invent paths that look colocated but aren't valid for the language** (e.g. `src/tests/test_<feature>.rs` is *not* a Rust test location — it's a regular `src/` submodule).
+
+- **Python**
+  - Colocated: `<module>/tests/test_<feature>.py (create)`
+  - Top-level: `tests/test_<feature>.py (create)`
+- **Rust**
+  - Crate-level integration tests: `tests/<feature>.rs (create)` (or, in a workspace, `<crate>/tests/<feature>.rs`)
+  - **Unit-test-only tasks (in-source `#[cfg(test)] mod tests`):** mark the task as `NOT_TESTABLE` with reason `Rust unit-only` — `@test` cannot write inside production source. `@make` writes those inline as part of its production change.
+- **Polyglot Nix flake**
+  - Match the host language of the code under change (Python or Rust rules above), wrapping commands in `nix develop -c …` per the agents' devshell rule.
 
 Include **Integration Contracts** when a task adds/changes function signatures, APIs, config keys, or has dependencies on other tasks.
 
@@ -131,9 +144,12 @@ git diff --name-only | comm -23 - /tmp/pre_test_baseline.txt > /tmp/test_new_fil
 ```
 All new files must match the project's test patterns:
 - Python: `**/test_*.py`, `**/*_test.py`, `**/conftest.py` (new only), `**/test_data/**`, `**/test_fixtures/**`
-- Rust: `tests/**/*.rs`, `**/tests/**/*.rs`, `**/test_data/**`, `**/test_fixtures/**`
+- Rust: `tests/**/*.rs`, `**/tests/**/*.rs` (workspace-style `<crate>/tests/...`), `**/test_data/**`, `**/test_fixtures/**`
 
-If any non-matching file appears: discard `@test` output, report violation.
+**Anti-patterns — discard the output even if the glob matches:**
+- Anything under `src/` for Rust (e.g. `src/tests/foo.rs`, `src/**/tests/...`). `src/tests/` is a regular module path under `src/`, not a Rust test location, and `@test` cannot wire it up via `mod` declarations in production source. Such paths indicate the task spec gave a wrong test path — escalate, don't accept the file.
+
+If any non-matching file appears, or any anti-pattern matches: discard `@test` output, report violation.
 
 **Decision table — handling `@test` results:**
 

From 832306c8170e1dec9d8605e34153451c30725e4f Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Wed, 6 May 2026 20:25:40 +0200
Subject: [PATCH 073/101] fix(opencode): harden workflow against multi-task
 spec dumps
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A workflow run on a Rust/Bevy task produced a single @make dispatch
covering six tasks (~2 hours of work), with the orchestrator drafting
the full replacement code, including a self-contradicting "actually
that's wrong, let me correct…" revision pass and a `nix develop
--command bash -c "cargo check"` invocation that @make's sandbox
denies. None of the failure modes were caught before dispatch.

Phase 5 gains three new subsections:
- Split Heuristic — explicit rules for when a task must be split
  (>2 concerns, >50 lines / 2 files, structural+runtime+wiring mix);
  prescribes the foundations / implementation / wiring split.
- Code Context Anti-patterns — the field is for seam-revealing
  snippets, not finished answers; max ~5-line snippets, no full
  replacement bodies.
- Finalized-Text Rule — task specs must be single-author finalized
  text, no "actually, that's wrong" revision passes, no two-version
  code blocks, no unresolved questions.

Phase 6 promotes the Rust unit-only NOT_TESTABLE case out of the
decision table into a dedicated routing subsection. The orchestrator
must pass test *specifications* (one-line behavior descriptions,
target functions, assertion types) to @make — never test code — and
run the suite once after @make to capture RED→GREEN evidence.

Phase 7 gains a mandatory Pre-Dispatch Validation table that rejects
specs containing `bash -c` / `sh -c` (any nesting), `nix develop -c
bash`, `cd <path> &&`, oversized Code Context blocks, contradictory
revisions, or duplicated test bodies. Repeated trips signal a Phase
5 split problem and route back to splitting.
---
 config/opencode/commands/workflow.md | 73 ++++++++++++++++++++++++++--
 1 file changed, 70 insertions(+), 3 deletions(-)

diff --git a/config/opencode/commands/workflow.md b/config/opencode/commands/workflow.md
index 2ff213f..29db101 100644
--- a/config/opencode/commands/workflow.md
+++ b/config/opencode/commands/workflow.md
@@ -122,6 +122,43 @@ Include **Test Design** from Phase 3 when available, attached to the relevant ta
 
 **Task size:** ~10-30 minutes each, single coherent change, clear boundaries.
 
+### Split Heuristic — when in doubt, split
+
+A task must be **split** if any of the following apply:
+
+- It touches more than two distinct concerns (e.g. *constants + new component + sprite spawn + new system + main wiring* is **five** concerns — at least three tasks).
+- It changes more than ~50 lines across more than 2 files.
+- It mixes data/structural changes (constants, types, components) with runtime/system changes (new ECS systems, scheduling, render loops).
+- It mixes pure-logic changes (math helpers) with stateful changes (queries, world mutation).
+- It mixes new APIs with their first call sites in the same task.
+
+When a task fails the heuristic, split into:
+1. **Foundations** — new constants, types, components (no behavior change yet).
+2. **Implementation** — the actual production logic, calling the foundations.
+3. **Wiring** — registration in `main.rs` / `lib.rs` / app-builder.
+
+Each split is dispatched separately to `@make` and verified before the next.
+
+### Code Context Anti-patterns
+
+The **Code Context** field exists so `@make` can find the seam to modify, not so it can read off a finished answer. Strictly follow:
+
+- **Provide:** the existing code being replaced (verbatim), the surrounding ~5–10 lines of context, function signatures of helpers `@make` will need to call, the file's relevant import block.
+- **Do NOT provide:** a complete drop-in replacement, the new function bodies, the test bodies (those come from `@test` or — for unit-only Rust — from `@make` itself per Phase 6), or any "here is what to write" code block longer than ~5 lines.
+
+If the task is so well-specified that you've already written the implementation, the task is too small for `@make` (apply it directly) or you've over-determined the design (revisit Phase 3).
+
+### Finalized-Text Rule
+
+Each task spec must be **finalized** before dispatch — single-author text with no contradictions. **Forbidden in dispatch prompts:**
+
+- "Actually, that's wrong — let me correct…"
+- "Wait, let me revise…"
+- Two versions of the same code block with one labelled "corrected"
+- Open questions or ambiguities the orchestrator hasn't resolved
+
+If you find yourself revising while writing the spec, stop, redo the spec from scratch with the corrected understanding, and only then dispatch. `@make` is a fresh-context implementer; it cannot reliably resolve which of two contradictory drafts is canonical.
+
 ---
 
 ## Phase 6: Write Tests
@@ -157,10 +194,25 @@ If any non-matching file appears, or any anti-pattern matches: discard `@test` o
 |-----------|--------|
 | `TESTS_READY` + `escalate_to_check: false` | Proceed to Phase 7 |
 | `TESTS_READY` + `escalate_to_check: true` | Route tests to `@check` for light review. `@check` diagnoses, caller routes fixes to `@test`. Then proceed. |
-| `NOT_TESTABLE` | Route to `@check` for sign-off on justification. If approved, task goes to `@make` without tests. |
+| `NOT_TESTABLE` (general reasons) | Route to `@check` for sign-off on justification. If approved, task goes to `@make` without tests. |
+| `NOT_TESTABLE` reason `Rust unit-only` | See "Rust unit-only routing" below. **Do not** include test code in the `@make` spec; pass test specs only. |
 | `BLOCKED` | Investigate. May need to revise task spec or plan. |
 | Test passes immediately | Investigate — behavior may already exist. Task spec may be wrong. |
 
+### Rust unit-only routing
+
+When `@test` returns `NOT_TESTABLE: Rust unit-only` (the implementation needs in-source `#[cfg(test)] mod tests` blocks that `@test` is forbidden from writing), the orchestrator must:
+
+1. Get `@check`'s sign-off on the justification (no integration-test seam exists).
+2. Build the `@make` spec with **test specifications**, not test code:
+   - "Add `#[cfg(test)] mod foo_tests` at the bottom of `<file>` exercising:"
+   - For each behavior, a one-line description: input → expected output, edge case to cover, error path to assert.
+   - Where applicable, name the function under test and the assertion type (`assert_eq!`, `assert!`, panic on invalid input).
+3. **Forbidden in the `@make` spec:** complete `#[test] fn …` bodies, full module blocks, or any `@test`-style RED-verified test code. `@make` writes the inline tests itself based on the spec.
+4. After `@make` completes, the orchestrator runs the test suite once to confirm RED→GREEN evidence and includes it in the workflow summary.
+
+This keeps the agents in their lanes: `@test` never writes inside `src/`, `@make` writes both the tests and the production code in a single coherent change, and the orchestrator sees explicit test pass evidence.
+
 **Parallelism:** Independent tasks can have tests written in parallel.
 **Constraint:** `@test` must not modify existing conftest.py files (prevents collision during parallel execution).
 
@@ -169,10 +221,25 @@ If any non-matching file appears, or any anti-pattern matches: discard `@test` o
 ## Phase 7: Implement
 
 Execute each task by dispatching `@make` with:
-- The task spec (from Phase 5)
-- Relevant code context (actual snippets)
+- The task spec (from Phase 5, finalized — see Finalized-Text Rule)
+- Relevant code context (seam-revealing snippets only — see Code Context Anti-patterns)
 - **Pre-written failing tests and handoff from `@test` (if TESTS_READY)**
 
+### Pre-Dispatch Validation (MANDATORY)
+
+Before sending the spec to `@make`, scan it and reject (revise, then retry) if any of the following are present:
+
+| Check | Why it matters |
+|---|---|
+| `bash -c`, `sh -c`, `zsh -c`, `fish -c` (anywhere, including inside `nix develop --command bash -c …`) | `@make`'s sandbox denies all `*-c` shell invocations and any nested `bash` would bypass the per-command allowlist. Replace with one direct command per line: `nix develop -c cargo check`, `nix develop -c cargo test`, etc. |
+| `nix develop --command bash` / `nix develop -c bash` / `nix develop -c sh` | Same — the inner shell escapes the sandbox. Wrap each toolchain command directly. |
+| Any `cd <path> && …` | `@make` cannot `cd`. Rewrite to use absolute paths or `git -C <path>` for git operations (and `@make` doesn't run git anyway). |
+| Code blocks longer than ~5 lines under "Code Context" or labelled as the answer | Violates Code Context Anti-patterns. Trim to the seam. |
+| Two versions of the same code, "actually let me correct…", or open questions | Violates the Finalized-Text Rule. Redo the spec. |
+| Test bodies inside the `@make` spec when tests are coming from `@test` | The TDD handoff already provides them; duplicating creates conflict. |
+
+If any check trips, **do not dispatch.** Fix the spec and re-validate. Repeated trips on the same task signal a Phase 5 split problem — go back and split.
+
 `@make` runs in TDD mode when tests are provided:
 1. Entry validation: run tests, verify RED, check failure codes match handoff
 2. Implement minimal code to make tests pass (GREEN)

From 5b5c59aa844197d7ec92dc751d1438c96abd0e79 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Thu, 7 May 2026 05:42:16 +0200
Subject: [PATCH 074/101] feat(opencode): mandate stub-first @make pre-pass for
 Rust integration TDD
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Rust integration tests live in a separate test crate that imports from
lib.rs, so any test referencing not-yet-existing public API can only
RED at build time. The build error masks assertion diagnostics and
makes the RED state opaque — no stack trace, no left/right values.

For Rust tasks whose @test step writes an integration test against
public API that does not yet exist, the orchestrator now dispatches a
stub-first @make pass before @test runs:

1. @make adds the planned public API as todo!()-bodied stubs in
   lib.rs and any new src/<module>.rs. Signatures lifted verbatim
   from the Phase 5 task spec. Acceptance criterion is cargo check
   only — no test command runs.
2. @test writes the integration test, which now compiles and panics
   at todo!() with a stack trace — a clean MISSING_BEHAVIOR RED.
3. Phase 7 dispatches @make again to replace the todo!() bodies with
   real implementations. Two atomic commits per task: scaffold then
   implement.

Phase 5's Rust test-path guidance now flags the two-dispatch
requirement up front. test.md's Rust failure-classification hints
recognize todo!() / unimplemented!() panics as MISSING_BEHAVIOR with
a pointer to the workflow's stub-first section.
---
 config/opencode/agents/test.md       |  1 +
 config/opencode/commands/workflow.md | 24 +++++++++++++++++++++++-
 2 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/config/opencode/agents/test.md b/config/opencode/agents/test.md
index 7afacff..af4872a 100644
--- a/config/opencode/agents/test.md
+++ b/config/opencode/agents/test.md
@@ -200,6 +200,7 @@ After running tests, classify each failure:
 **Mapping hints (Rust):**
 - `error[E0432]: unresolved import` / `error[E0425]: cannot find function/value` for the symbol under test → `MISSING_BEHAVIOR`
 - `error[E0599]: no method named ...` on a real but incomplete type → `MISSING_BEHAVIOR`
+- Test panics with `not yet implemented` / `not implemented: …` (from `todo!()` or `unimplemented!()` in a stub body) → `MISSING_BEHAVIOR` (this is the expected RED state for stub-first integration TDD; see workflow Phase 6 "Rust integration TDD: stub-first")
 - Test panics with `assertion failed: ... left: ..., right: ...` → `ASSERTION_MISMATCH`
 - Test file fails to compile due to its own bug (typo, wrong type, unused-import-as-error) → `TEST_BROKEN`
 - `linker not found`, missing system library, missing feature flag → `ENV_BROKEN`
diff --git a/config/opencode/commands/workflow.md b/config/opencode/commands/workflow.md
index 29db101..2402427 100644
--- a/config/opencode/commands/workflow.md
+++ b/config/opencode/commands/workflow.md
@@ -111,7 +111,8 @@ The test file path must follow the language's actual test layout. **Do not inven
   - Colocated: `<module>/tests/test_<feature>.py (create)`
   - Top-level: `tests/test_<feature>.py (create)`
 - **Rust**
-  - Crate-level integration tests: `tests/<feature>.rs (create)` (or, in a workspace, `<crate>/tests/<feature>.rs`)
+  - Crate-level integration tests: `tests/<feature>.rs (create)` (or, in a workspace, `<crate>/tests/<feature>.rs`).
+    - **If the test references not-yet-existing public API**, the task automatically requires a **stub-first `@make` pre-pass** before `@test` runs (see Phase 6 → "Rust integration TDD: stub-first"). Plan for two `@make` dispatches per such task: stub pass, then body pass.
   - **Unit-test-only tasks (in-source `#[cfg(test)] mod tests`):** mark the task as `NOT_TESTABLE` with reason `Rust unit-only` — `@test` cannot write inside production source. `@make` writes those inline as part of its production change.
 - **Polyglot Nix flake**
   - Match the host language of the code under change (Python or Rust rules above), wrapping commands in `nix develop -c …` per the agents' devshell rule.
@@ -213,6 +214,27 @@ When `@test` returns `NOT_TESTABLE: Rust unit-only` (the implementation needs in
 
 This keeps the agents in their lanes: `@test` never writes inside `src/`, `@make` writes both the tests and the production code in a single coherent change, and the orchestrator sees explicit test pass evidence.
 
+### Rust integration TDD: stub-first (mandatory)
+
+Rust integration tests live in a separate test crate (`tests/<feature>.rs`) that imports from `lib.rs`. Any test referencing not-yet-existing public API can only RED at *build* time, which masks assertion diagnostics. To avoid this, **for every Rust task whose `@test` step writes an integration test against public API that does not yet exist**, dispatch a stub-first `@make` pass *before* `@test` runs:
+
+**Stub pass (split from Phase 7's body pass):**
+
+1. Dispatch `@make` in **standard mode** (no tests exist yet) with this exact scope:
+   - **Goal:** add the planned public API as `todo!()`-bodied stubs so the integration test will compile.
+   - **Files to modify:** `src/lib.rs` (add `pub mod …;` declarations) plus any new `src/<module>.rs` files containing the stub functions/structs.
+   - **Stubs only:** every function body is exactly `todo!()`. Every method body is exactly `todo!()`. Public structs may use `pub struct Foo;` or `pub struct Foo { /* fields TBD */ }` — but no logic.
+   - **Signatures must match the planned final API exactly** (return types, lifetimes, generics) — otherwise the integration test will mismatch later. Lift signatures from the Phase 3 plan / Phase 5 task spec.
+   - **Acceptance criteria:** `cargo check` (wrapped in `nix develop -c …` if the project has a devshell) passes; no test command is run.
+   - **Code Context Anti-patterns still apply:** the stub pass is small and finalized — no draft bodies, no contradictory signatures.
+2. Verify `cargo check` passed in `@make`'s output. If not, fix and re-dispatch the stub pass before continuing.
+3. Dispatch `@test` as normal. The integration test now compiles; running it panics on `todo!()` at runtime, which is a clean `MISSING_BEHAVIOR` RED with a stack trace — far better than the build-error-RED form.
+4. Continue to Phase 7's body pass (`@make` in TDD mode), where the same files are revisited and the `todo!()` bodies are replaced.
+
+**This routing is mandatory** for new public API in Rust. It is **not** required when the integration test exercises an existing public API (e.g. a behavior fix where the function already exists) — in that case `@test` runs directly and `@make` modifies the body in Phase 7.
+
+The stub pass and the body pass each produce their own atomic commit (per Phase 9 rules): `feat(<scope>): scaffold <thing> with todo!() stubs` followed by `feat(<scope>): implement <thing>` (or whichever conventional type fits).
+
 **Parallelism:** Independent tasks can have tests written in parallel.
 **Constraint:** `@test` must not modify existing conftest.py files (prevents collision during parallel execution).
 

From 1aa98a805183f05f33a20d3be7c6d572ec98e091 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Thu, 7 May 2026 05:45:35 +0200
Subject: [PATCH 075/101] fix(opencode): require real shell timestamp in
 workflow summary
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A workflow run wrote the timestamp as `2026-05-06T???:???:?? (session date)`
because the agent had no time-of-day source and inserted a placeholder.
Phase 9 now mandates capturing the timestamp from the shell at write
time via `date -Iseconds` and forbids placeholders — omit the field
rather than fabricate one.
---
 config/opencode/commands/workflow.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/config/opencode/commands/workflow.md b/config/opencode/commands/workflow.md
index 2402427..f1b21ae 100644
--- a/config/opencode/commands/workflow.md
+++ b/config/opencode/commands/workflow.md
@@ -323,7 +323,7 @@ The workflow is forge-agnostic. It commits locally and stops. **Do not push, and
 
 ### Local Summary
 - Write `.opencode/workflow-summary.md` in the worktree with:
-  - Run timestamp
+  - **Run timestamp** — capture it from the shell at write time: `date -Iseconds` (e.g. `2026-05-07T11:24:13+02:00`). **Do not** use a placeholder like `???:???:??` or "session date" — if you cannot get a real timestamp, omit the field entirely rather than fabricating one.
   - Issue reference and title
   - Branch name and final commit SHA(s)
   - Summary of implementation

From b548126fb8fbb367e87ab391f8a36432b17a7dd5 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Wed, 6 May 2026 14:03:28 +0200
Subject: [PATCH 076/101] fix(halo): fix systemd description for llama

---
 systems/x86_64-linux/halo/llama-server.nix | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/systems/x86_64-linux/halo/llama-server.nix b/systems/x86_64-linux/halo/llama-server.nix
index 9ea5870..a488c8c 100644
--- a/systems/x86_64-linux/halo/llama-server.nix
+++ b/systems/x86_64-linux/halo/llama-server.nix
@@ -29,7 +29,7 @@
       ExecStart = lib.concatStringsSep " " [
         "${pkgs.llama-cpp-rocm}/bin/llama-server"
         "--flash-attn on"
-        "--parallel 2"
+        "--parallel 1"
         "--jinja"
         "--host 0.0.0.0"
         "--port 8000"
@@ -43,7 +43,7 @@
         "--temp 0.6 --top-p 0.95 --top-k 20 --min-p 0.00"
         "--no-context-shift"
         ''--chat-template-kwargs '{"preserve_thinking": true}' ''
-        "-c 524288"
+        "-c 262144"
         "--fit on"
         "--slot-save-path %C/llama-server/kv-slots"
         "--spec-type mtp --spec-draft-n-max 3"

From d47bb6e15bd4e182772278658357e3e2e54ae454 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Thu, 7 May 2026 14:34:58 +0200
Subject: [PATCH 077/101] feat(halo): add different llama servers

---
 systems/x86_64-linux/halo/default.nix         |  2 +-
 .../halo/llama-server-27B-MTP.nix             | 60 +++++++++++++++++++
 .../halo/llama-server-coder-next.nix          | 57 ++++++++++++++++++
 systems/x86_64-linux/halo/llama-server.nix    |  9 ++-
 4 files changed, 122 insertions(+), 6 deletions(-)
 create mode 100644 systems/x86_64-linux/halo/llama-server-27B-MTP.nix
 create mode 100644 systems/x86_64-linux/halo/llama-server-coder-next.nix

diff --git a/systems/x86_64-linux/halo/default.nix b/systems/x86_64-linux/halo/default.nix
index 1934cd8..afece0e 100644
--- a/systems/x86_64-linux/halo/default.nix
+++ b/systems/x86_64-linux/halo/default.nix
@@ -10,7 +10,7 @@ with lib.metacfg;
     ./hardware-configuration.nix
     #./xremap.nix
     ./wyoming.nix
-    ./llama-server.nix
+    ./llama-server-coder-next.nix
   ];
 
   boot.lanzaboote.pkiBundle = "/var/lib/sbctl";
diff --git a/systems/x86_64-linux/halo/llama-server-27B-MTP.nix b/systems/x86_64-linux/halo/llama-server-27B-MTP.nix
new file mode 100644
index 0000000..2b8283d
--- /dev/null
+++ b/systems/x86_64-linux/halo/llama-server-27B-MTP.nix
@@ -0,0 +1,60 @@
+{
+  pkgs,
+  lib,
+  ...
+}:
+{
+  systemd.services.llama-server = {
+    description = "llama.cpp server (Qwen3.6-27B-MTP, ROCm)";
+    after = [ "network-online.target" ];
+    wants = [ "network-online.target" ];
+    wantedBy = [ "multi-user.target" ];
+
+    environment = {
+      HOME = "%S/llama-server";
+      HF_HOME = "%S/llama-server";
+    };
+
+    serviceConfig = {
+      Type = "simple";
+      DynamicUser = true;
+      SupplementaryGroups = [
+        "video"
+        "render"
+      ];
+      StateDirectory = "llama-server";
+      CacheDirectory = "llama-server";
+      WorkingDirectory = "%S/llama-server";
+      ExecStartPre = "${pkgs.coreutils}/bin/mkdir -p %C/llama-server/kv-slots-27B-MTP";
+      ExecStart = lib.concatStringsSep " " [
+        "${pkgs.llama-cpp-rocm}/bin/llama-server"
+        "--flash-attn on"
+        "--parallel 1"
+        "--jinja"
+        "--host 0.0.0.0"
+        "--port 8000"
+        "--no-mmap"
+        "--n-gpu-layers 99"
+        "-hf am17an/Qwen3.6-27B-MTP-GGUF:Q8_0"
+        "--alias qwen3.6-27b"
+        "--threads 8"
+        "--ubatch-size 256"
+        "-ctk bf16 -ctv bf16"
+        "--temp 0.6 --top-p 0.95 --top-k 20 --min-p 0.00"
+        "--no-context-shift"
+        ''--chat-template-kwargs '{"preserve_thinking": true}' ''
+        "-c 262144"
+        "--fit on"
+        "--slot-save-path %C/llama-server/kv-slots-27B-MTP"
+        "--spec-type mtp --spec-draft-n-max 3"
+      ];
+      Restart = "on-failure";
+      RestartSec = 10;
+
+      PrivateTmp = true;
+      ProtectSystem = "strict";
+      ProtectHome = true;
+      NoNewPrivileges = true;
+    };
+  };
+}
diff --git a/systems/x86_64-linux/halo/llama-server-coder-next.nix b/systems/x86_64-linux/halo/llama-server-coder-next.nix
new file mode 100644
index 0000000..d384f7c
--- /dev/null
+++ b/systems/x86_64-linux/halo/llama-server-coder-next.nix
@@ -0,0 +1,57 @@
+{
+  pkgs,
+  lib,
+  ...
+}:
+{
+  systemd.services.llama-server = {
+    description = "llama.cpp server (Qwen3-Coder-Next, ROCm)";
+    after = [ "network-online.target" ];
+    wants = [ "network-online.target" ];
+    wantedBy = [ "multi-user.target" ];
+
+    environment = {
+      HOME = "%S/llama-server";
+      HF_HOME = "%S/llama-server";
+    };
+
+    serviceConfig = {
+      Type = "simple";
+      DynamicUser = true;
+      SupplementaryGroups = [
+        "video"
+        "render"
+      ];
+      StateDirectory = "llama-server";
+      CacheDirectory = "llama-server";
+      WorkingDirectory = "%S/llama-server";
+      ExecStartPre = "${pkgs.coreutils}/bin/mkdir -p %C/llama-server/kv-slots-coder-next";
+      ExecStart = lib.concatStringsSep " " [
+        "${pkgs.llama-cpp-rocm}/bin/llama-server"
+	"--flash-attn on"
+        "--parallel 1"
+        "--jinja"
+        "--host 0.0.0.0"
+        "--port 8000"
+        "--no-mmap"
+        "--n-gpu-layers 99"
+        "--threads 8"
+        "--ubatch-size 256"
+        "-ctk bf16 -ctv bf16"
+        "--fit on"
+        "--no-context-shift"
+        "-hf unsloth/Qwen3-Coder-Next-GGUF:UD-Q8_K_XL"
+        "--alias qwen3-coder-next"
+        "--temp 1.0 --top-p 0.95 --min-p 0.01 --top-k 40"
+        "--slot-save-path %C/llama-server/kv-slots-coder-next"
+      ];
+      Restart = "on-failure";
+      RestartSec = 10;
+
+      PrivateTmp = true;
+      ProtectSystem = "strict";
+      ProtectHome = true;
+      NoNewPrivileges = true;
+    };
+  };
+}
diff --git a/systems/x86_64-linux/halo/llama-server.nix b/systems/x86_64-linux/halo/llama-server.nix
index a488c8c..84f1831 100644
--- a/systems/x86_64-linux/halo/llama-server.nix
+++ b/systems/x86_64-linux/halo/llama-server.nix
@@ -5,7 +5,7 @@
 }:
 {
   systemd.services.llama-server = {
-    description = "llama.cpp server (Qwen3.6-27B-MTP, ROCm)";
+    description = "llama.cpp server (Qwen3.6-35B-A3B, ROCm)";
     after = [ "network-online.target" ];
     wants = [ "network-online.target" ];
     wantedBy = [ "multi-user.target" ];
@@ -29,13 +29,13 @@
       ExecStart = lib.concatStringsSep " " [
         "${pkgs.llama-cpp-rocm}/bin/llama-server"
         "--flash-attn on"
-        "--parallel 1"
+        "--parallel 2"
         "--jinja"
         "--host 0.0.0.0"
         "--port 8000"
         "--no-mmap"
         "--n-gpu-layers 99"
-        "-hf am17an/Qwen3.6-27B-MTP-GGUF:Q8_0"
+        "-hf unsloth/Qwen3.6-27B-GGUF:UD-Q8_K_XL"
         "--alias qwen3.6-27b"
         "--threads 8"
         "--ubatch-size 256"
@@ -43,10 +43,9 @@
         "--temp 0.6 --top-p 0.95 --top-k 20 --min-p 0.00"
         "--no-context-shift"
         ''--chat-template-kwargs '{"preserve_thinking": true}' ''
-        "-c 262144"
+        "-c 524288"
         "--fit on"
         "--slot-save-path %C/llama-server/kv-slots"
-        "--spec-type mtp --spec-draft-n-max 3"
       ];
       Restart = "on-failure";
       RestartSec = 10;

From 17ad3ba6ef3bf44ffce8276ee6cfa9b847e2225a Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Thu, 7 May 2026 06:42:46 +0200
Subject: [PATCH 078/101] refactor(opencode): hoist dispatch rules into a
 top-level Dispatch Hygiene section
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A workflow run on GAL-38 dispatched a plan to @check that contained a
self-contradicting "Wait, the movement should be direct position
assignment, not delta… Let me reconsider…" passage with two versions
of the same move_enemies code, plus drop-in cargo-pasted match arms /
function bodies (plan-as-implementation). The rules added in 832306c
caught these patterns when @make was the recipient but did not cover
the plan itself, plan-review dispatches, test-author dispatches, or
final-review dispatches.

Hoists the Finalized-Text Rule and Pre-Dispatch Validation table out
of Phase 5/7 into a new top-level "Dispatch Hygiene" section between
Phase 3 and Phase 4, and adds an explicit "No-Implementation-in-Plan-
or-Spec Rule" that bans drop-in code blocks > ~5 lines, full function
bodies, and stage-by-stage transformations from plans and specs alike.

Phases 3, 4, 5, 6, 7, 8 each gain a one-line pointer requiring the
orchestrator to apply Dispatch Hygiene before sending. Phase 5's
former "Code Context Anti-patterns" becomes "Code Context — what to
include" with positive framing, deferring the negative list to the
hoisted rules. The Phase 6 stub-first section's stale anti-pattern
reference is updated to point at Dispatch Hygiene as well.
---
 config/opencode/commands/workflow.md | 112 +++++++++++++++++++--------
 1 file changed, 78 insertions(+), 34 deletions(-)

diff --git a/config/opencode/commands/workflow.md b/config/opencode/commands/workflow.md
index f1b21ae..af99cbe 100644
--- a/config/opencode/commands/workflow.md
+++ b/config/opencode/commands/workflow.md
@@ -66,11 +66,72 @@ The plan should include:
   **Skip Test Design for:** Config-only changes, decorator swaps, import reorganization, documentation.
   When skipped, `@test` derives test cases directly from acceptance criteria.
 
+After drafting, apply **Dispatch Hygiene** (below) to the plan — it is a dispatch artifact and gets sent to `@check`/`@simplify` in Phase 4.
+
+---
+
+## Dispatch Hygiene
+
+This applies to **every** subagent dispatch (Phases 4, 6, 7, 8) **and** to artifacts that will be dispatched (the plan from Phase 3, the task specs from Phase 5). Apply these checks before sending — fix the artifact, then re-check.
+
+### Finalized-Text Rule
+
+The artifact must be **finalized** — single-author text, no contradictions, no open questions. Forbidden:
+
+- "Actually, that's wrong — let me correct…"
+- "Wait, let me reconsider…"
+- Two versions of the same code block, one labelled "corrected" or appearing after a revision pass
+- Open questions or ambiguities the orchestrator hasn't resolved
+- Mid-text revisions visible to the recipient
+
+If you find yourself revising while writing, stop, redo the artifact from scratch with the corrected understanding, and only then dispatch. Subagents are fresh-context — they cannot reliably resolve which of two contradictory drafts is canonical, and reviewers cannot give a clean verdict on a self-contradicting plan.
+
+### No-Implementation-in-Plan-or-Spec Rule
+
+Plans (Phase 3) and task specs (Phase 5) are **not** the place to write the answer. They describe what to do; `@make` writes how.
+
+Provide:
+- Approach with rationale
+- Files to modify with brief descriptions
+- Function signatures, type declarations, data shapes (structure, not logic)
+- Constraints, invariants, integration contracts
+- Risks and edge cases
+
+Do **not** provide:
+- Drop-in code blocks longer than ~5 lines that constitute "the answer"
+- Full function bodies for the changes being planned
+- Complete `match` arms / branch logic / loop bodies for new behavior
+- Pre-written test bodies (those come from `@test`, or from `@make` for Rust unit-only)
+- Stage-by-stage code transformations spelled out as ready-to-commit diffs
+
+If you've already written the implementation in the plan or spec, the artifact has overstepped. Convert finished code into structural description (signature + intent) and let `@make` produce the body.
+
+**Allowed in plans/specs:**
+- Existing code being replaced, marked as "current state"
+- Function signatures and type/struct/enum declarations (data, not logic)
+- Tiny inline constants (`pub const FOO: f32 = 30.0;`)
+- Test specifications as one-line behavior descriptions ("input X → expect Y")
+
+### Pre-Dispatch Validation (MANDATORY)
+
+Scan the artifact and reject (revise, retry) if any of the following are present:
+
+| Check | Why it matters |
+|---|---|
+| `bash -c`, `sh -c`, `zsh -c`, `fish -c` (anywhere, including inside `nix develop --command bash -c …`) | `@make`/`@test` sandboxes deny all `*-c` shell invocations and any nested `bash` would bypass the per-command allowlist. Replace with one direct command per line: `nix develop -c cargo check`, etc. |
+| `nix develop --command bash` / `nix develop -c bash` / `nix develop -c sh` | Same — inner shell escapes the sandbox. Wrap each toolchain command directly. |
+| Any `cd <path> && …` | Subagents cannot `cd`. Rewrite to use absolute paths. |
+| Code blocks longer than ~5 lines that draft the answer | Violates No-Implementation-in-Plan-or-Spec. Trim to structure (signature + "current state" only). |
+| Two versions of the same code, "actually let me correct…", or open questions | Violates the Finalized-Text Rule. Redo the artifact. |
+| Test bodies inside `@make` specs when tests are coming from `@test` | Duplicates the TDD handoff. |
+
+If any check trips, **do not dispatch.** Fix and re-validate. Repeated trips on a single task signal a Phase 5 split problem — go back and split.
+
 ---
 
 ## Phase 4: Review Plan
 
-Dispatch `@check` and `@simplify` in parallel to review the plan.
+Apply **Dispatch Hygiene** to the plan and to each reviewer prompt before sending. Dispatch `@check` and `@simplify` in parallel to review the plan.
 
 Reviewers should evaluate testability:
 - `@check`: Is the design testable? Are the right behaviors identified? (Review Framework §8)
@@ -140,30 +201,26 @@ When a task fails the heuristic, split into:
 
 Each split is dispatched separately to `@make` and verified before the next.
 
-### Code Context Anti-patterns
+### Code Context — what to include
 
-The **Code Context** field exists so `@make` can find the seam to modify, not so it can read off a finished answer. Strictly follow:
+The **Code Context** field exists so `@make` can find the seam to modify. Provide:
 
-- **Provide:** the existing code being replaced (verbatim), the surrounding ~5–10 lines of context, function signatures of helpers `@make` will need to call, the file's relevant import block.
-- **Do NOT provide:** a complete drop-in replacement, the new function bodies, the test bodies (those come from `@test` or — for unit-only Rust — from `@make` itself per Phase 6), or any "here is what to write" code block longer than ~5 lines.
+- The existing code being replaced (verbatim, marked as "current state"), with ~5–10 lines of surrounding context
+- Function signatures of helpers `@make` will need to call
+- The file's relevant import block
+
+For everything you must **not** include — drop-in replacements, full function bodies, pre-written test bodies, "here is what to write" — see **Dispatch Hygiene → No-Implementation-in-Plan-or-Spec Rule** above.
 
 If the task is so well-specified that you've already written the implementation, the task is too small for `@make` (apply it directly) or you've over-determined the design (revisit Phase 3).
 
-### Finalized-Text Rule
-
-Each task spec must be **finalized** before dispatch — single-author text with no contradictions. **Forbidden in dispatch prompts:**
-
-- "Actually, that's wrong — let me correct…"
-- "Wait, let me revise…"
-- Two versions of the same code block with one labelled "corrected"
-- Open questions or ambiguities the orchestrator hasn't resolved
-
-If you find yourself revising while writing the spec, stop, redo the spec from scratch with the corrected understanding, and only then dispatch. `@make` is a fresh-context implementer; it cannot reliably resolve which of two contradictory drafts is canonical.
+Apply **Dispatch Hygiene** to each task spec before dispatch in Phase 7.
 
 ---
 
 ## Phase 6: Write Tests
 
+Apply **Dispatch Hygiene** to each `@test` prompt before sending.
+
 For each task from Phase 5, dispatch `@test` with:
 - The task spec (acceptance criteria, code context, files to modify)
 - The Test Design section from the plan (if provided)
@@ -226,7 +283,7 @@ Rust integration tests live in a separate test crate (`tests/<feature>.rs`) that
    - **Stubs only:** every function body is exactly `todo!()`. Every method body is exactly `todo!()`. Public structs may use `pub struct Foo;` or `pub struct Foo { /* fields TBD */ }` — but no logic.
    - **Signatures must match the planned final API exactly** (return types, lifetimes, generics) — otherwise the integration test will mismatch later. Lift signatures from the Phase 3 plan / Phase 5 task spec.
    - **Acceptance criteria:** `cargo check` (wrapped in `nix develop -c …` if the project has a devshell) passes; no test command is run.
-   - **Code Context Anti-patterns still apply:** the stub pass is small and finalized — no draft bodies, no contradictory signatures.
+   - **Dispatch Hygiene still applies:** the stub pass is small and finalized — no draft bodies, no contradictory signatures.
 2. Verify `cargo check` passed in `@make`'s output. If not, fix and re-dispatch the stub pass before continuing.
 3. Dispatch `@test` as normal. The integration test now compiles; running it panics on `todo!()` at runtime, which is a clean `MISSING_BEHAVIOR` RED with a stack trace — far better than the build-error-RED form.
 4. Continue to Phase 7's body pass (`@make` in TDD mode), where the same files are revisited and the `todo!()` bodies are replaced.
@@ -242,26 +299,13 @@ The stub pass and the body pass each produce their own atomic commit (per Phase
 
 ## Phase 7: Implement
 
+Apply **Dispatch Hygiene** to each `@make` spec before sending. Repeated trips on a single task signal a Phase 5 split problem — go back and split.
+
 Execute each task by dispatching `@make` with:
-- The task spec (from Phase 5, finalized — see Finalized-Text Rule)
-- Relevant code context (seam-revealing snippets only — see Code Context Anti-patterns)
+- The task spec (from Phase 5, finalized per Dispatch Hygiene)
+- Relevant code context (seam-revealing snippets only — see Phase 5 "Code Context — what to include")
 - **Pre-written failing tests and handoff from `@test` (if TESTS_READY)**
 
-### Pre-Dispatch Validation (MANDATORY)
-
-Before sending the spec to `@make`, scan it and reject (revise, then retry) if any of the following are present:
-
-| Check | Why it matters |
-|---|---|
-| `bash -c`, `sh -c`, `zsh -c`, `fish -c` (anywhere, including inside `nix develop --command bash -c …`) | `@make`'s sandbox denies all `*-c` shell invocations and any nested `bash` would bypass the per-command allowlist. Replace with one direct command per line: `nix develop -c cargo check`, `nix develop -c cargo test`, etc. |
-| `nix develop --command bash` / `nix develop -c bash` / `nix develop -c sh` | Same — the inner shell escapes the sandbox. Wrap each toolchain command directly. |
-| Any `cd <path> && …` | `@make` cannot `cd`. Rewrite to use absolute paths or `git -C <path>` for git operations (and `@make` doesn't run git anyway). |
-| Code blocks longer than ~5 lines under "Code Context" or labelled as the answer | Violates Code Context Anti-patterns. Trim to the seam. |
-| Two versions of the same code, "actually let me correct…", or open questions | Violates the Finalized-Text Rule. Redo the spec. |
-| Test bodies inside the `@make` spec when tests are coming from `@test` | The TDD handoff already provides them; duplicating creates conflict. |
-
-If any check trips, **do not dispatch.** Fix the spec and re-validate. Repeated trips on the same task signal a Phase 5 split problem — go back and split.
-
 `@make` runs in TDD mode when tests are provided:
 1. Entry validation: run tests, verify RED, check failure codes match handoff
 2. Implement minimal code to make tests pass (GREEN)
@@ -287,7 +331,7 @@ After all tasks complete, verify overall integration:
 
 ## Phase 8: Final Review
 
-Dispatch `@check` and `@simplify` in parallel to review the full implementation (all changes across all files).
+Apply **Dispatch Hygiene** to each reviewer prompt before sending. Dispatch `@check` and `@simplify` in parallel to review the full implementation (all changes across all files).
 
 Provide reviewers with:
 - The original plan

From f0cc3003580f80b2d517f5c90d6212da3c983740 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Thu, 7 May 2026 08:41:53 +0200
Subject: [PATCH 079/101] fix(opencode): make Phase 6 file gate see untracked
 files
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`git diff --name-only` only shows tracked files with unstaged
modifications. It does not show untracked files — which is precisely
the state of any new test file @test creates, since @test's sandbox
denies `git add`. The pre/post snapshots therefore both missed new
files entirely and `comm -23 post pre` returned nothing, letting the
gate cheerfully conclude nothing changed even when @test had just
created tests/foo.rs (or, worse, src/lib.rs).

Switch both snapshots to `git status --porcelain | sed 's/^...//'
| sort -u`, which captures modified, staged, and untracked files in
a single pass. Inline rationale notes the untracked blind spot so
the orchestrator does not fall back to git diff.
---
 config/opencode/commands/workflow.md | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/config/opencode/commands/workflow.md b/config/opencode/commands/workflow.md
index af99cbe..1e2a8eb 100644
--- a/config/opencode/commands/workflow.md
+++ b/config/opencode/commands/workflow.md
@@ -229,14 +229,15 @@ For each task from Phase 5, dispatch `@test` with:
 `@test` writes failing tests and verifies RED with structured failure codes.
 
 **Post-step file gate (MANDATORY):**
-Before dispatching `@test`, snapshot the current changed files:
+Before dispatching `@test`, snapshot every modified, staged, *and untracked* file. `git diff --name-only` alone misses untracked files, which is precisely the state of any new test file `@test` creates (it cannot `git add`). Use `git status --porcelain` so the gate sees them:
 ```bash
-git diff --name-only > /tmp/pre_test_baseline.txt
+git status --porcelain | sed 's/^...//' | sort -u > /tmp/pre_test_baseline.txt
 ```
-After `@test` completes, validate only NEW changes:
+After `@test` completes, list NEW changes (in the post-snapshot but not the pre-snapshot):
 ```bash
-git diff --name-only | comm -23 - /tmp/pre_test_baseline.txt > /tmp/test_new_files.txt
+git status --porcelain | sed 's/^...//' | sort -u | comm -23 - /tmp/pre_test_baseline.txt > /tmp/test_new_files.txt
 ```
+Each line in `/tmp/test_new_files.txt` is a file path that did not exist (or was unmodified) before `@test` ran. The gate validates each one against the patterns below.
 All new files must match the project's test patterns:
 - Python: `**/test_*.py`, `**/*_test.py`, `**/conftest.py` (new only), `**/test_data/**`, `**/test_fixtures/**`
 - Rust: `tests/**/*.rs`, `**/tests/**/*.rs` (workspace-style `<crate>/tests/...`), `**/test_data/**`, `**/test_fixtures/**`

From 91e8aab38312e27550c9b36db20bc8e8d2f87814 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Thu, 7 May 2026 08:46:39 +0200
Subject: [PATCH 080/101] fix(opencode): require sequential @make dispatches,
 tighten @test parallelism
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A workflow run dispatched two @make agents in parallel. Both agents
write source files, run cargo verification commands, and may both
target the same file (e.g. src/lib.rs for a new `pub mod` plus a
later registration) — concurrent edits corrupt each other and Cargo's
target/ lock serialises the builds anyway, so parallelism only adds
risk without giving speedup.

Phase 7 now states explicitly that @make dispatches are SEQUENTIAL —
never in parallel — and lists the reasons inline. The rule covers
all @make invocations: standard mode, TDD mode, the Rust stub-pass
and body-pass, and integration-fix dispatches. Stub-pass/body-pass
ordering within a task is strict so @test always RED-verifies against
a deterministic crate state.

Phase 6's parallelism rule splits per language: Python parallel
@test is still allowed for disjoint test files, but Rust @test runs
sequentially since cargo serialises the build and shared crate-level
helper files race.
---
 config/opencode/commands/workflow.md | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/config/opencode/commands/workflow.md b/config/opencode/commands/workflow.md
index 1e2a8eb..9a10204 100644
--- a/config/opencode/commands/workflow.md
+++ b/config/opencode/commands/workflow.md
@@ -293,8 +293,11 @@ Rust integration tests live in a separate test crate (`tests/<feature>.rs`) that
 
 The stub pass and the body pass each produce their own atomic commit (per Phase 9 rules): `feat(<scope>): scaffold <thing> with todo!() stubs` followed by `feat(<scope>): implement <thing>` (or whichever conventional type fits).
 
-**Parallelism:** Independent tasks can have tests written in parallel.
-**Constraint:** `@test` must not modify existing conftest.py files (prevents collision during parallel execution).
+**Parallelism:**
+- **Python:** Independent tasks can have tests written in parallel, *provided* their test files are disjoint and no shared `conftest.py` is being modified.
+- **Rust:** Run `@test` dispatches **sequentially**. Cargo serialises the build via the `target/` directory lock, so parallel dispatches give no speedup; they only add risk (a long-running build in one branch starves the other, and any task that touches a shared crate-level fixture/helper file will race).
+
+**Constraint:** `@test` must not modify existing `conftest.py` files (prevents collision during parallel execution).
 
 ---
 
@@ -302,6 +305,13 @@ The stub pass and the body pass each produce their own atomic commit (per Phase
 
 Apply **Dispatch Hygiene** to each `@make` spec before sending. Repeated trips on a single task signal a Phase 5 split problem — go back and split.
 
+**`@make` dispatches are SEQUENTIAL — never in parallel.** Run each task to completion (writes, every verification command, and the orchestrator's post-check) before dispatching the next. Reasons:
+- `@make` writes source files. Parallel agents picking the same file (e.g. `src/lib.rs` for adding both a new `pub mod` and a registration) corrupt each other.
+- Even on disjoint files, Cargo's `target/` lock and uv's venv state serialise the verification builds anyway, so parallelism gives no speedup.
+- Stub-pass/body-pass pairs (Rust integration TDD) must be strictly ordered within a task; running stub-pass for task 2 while body-pass for task 1 is still building yields a non-deterministic crate state for `@test` to RED against.
+
+This applies to **all** `@make` invocations: standard mode, TDD mode, stub-pass, body-pass, and integration-fix dispatches.
+
 Execute each task by dispatching `@make` with:
 - The task spec (from Phase 5, finalized per Dispatch Hygiene)
 - Relevant code context (seam-revealing snippets only — see Phase 5 "Code Context — what to include")

From 91ba5bd2721d5cbfd29a1ab1d03d42fb3609ace0 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Thu, 7 May 2026 09:07:41 +0200
Subject: [PATCH 081/101] fix(opencode): close two false-green test loopholes
 and the orchestrator-as-implementer escape hatch
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A workflow run on a Bevy weaving feature exposed two compounding
failures:

1. @test wrote 8 structural-only Rust tests that never invoked
   weave_enemies or trigger_weaving. Every test passed against the
   stub-first @make pre-pass because none of them called the
   stubbed symbols, so todo!() never fired. The body-pass committed
   code that "passed" the suite and silently broke trigger_weaving
   in special stages.

2. @check found the trigger_weaving regression at Phase 8 (final
   review) and the orchestrator decided to "fix them directly"
   rather than dispatching @make — taking the license offered by
   the existing review-loop wording.

Test-quality fixes:

- Phase 3 Test Design now requires each behavior to be expressed as
  an action + observable outcome. Structural facts ("enum has 3
  variants", "struct has these fields") are explicitly disqualified.
- Phase 6 stub-first flow gains a mandatory Panic-coverage check:
  after @test returns, the orchestrator re-runs the test command and
  rejects the output unless every test panics on todo!() (i.e. every
  test exercises at least one stubbed symbol). Any passing test is
  structural-only and routes back to @test.
- Phase 6 decision table gets a "Stub-first run: tests pass with zero
  todo!() panics" row covering the same case.
- @test's Test Philosophy gains an explicit Do-NOT-write list of
  structural-only patterns (variant_count, type ascriptions,
  Box::new(my_fn), struct-literal-only flows, all-pass-on-stubs)
  plus a positive rule: every test must call a function and assert
  on observable outcome, or return NOT_TESTABLE rather than pad the
  suite.

Orchestrator boundary fix:

- Phase 8 review loop replaces "fix them directly (no need to
  re-dispatch @make for small fixes)" with the principle "the
  orchestrator does not write production code; @make does". BLOCK,
  behavioral, correctness, and test-quality findings round-trip
  through @make. Only AST-preserving cosmetic edits (typos in
  comments, trailing newlines) may be applied directly. Compiler-
  detected issues (unused imports, dead code) go through @make.
---
 config/opencode/agents/test.md       |  8 ++++++++
 config/opencode/commands/workflow.md | 16 ++++++++++++----
 2 files changed, 20 insertions(+), 4 deletions(-)

diff --git a/config/opencode/agents/test.md b/config/opencode/agents/test.md
index af4872a..3c4506f 100644
--- a/config/opencode/agents/test.md
+++ b/config/opencode/agents/test.md
@@ -149,6 +149,14 @@ This constraint is enforced by a post-step file gate. Violations cause your outp
 - Trivial tests (constructor creates object, getter returns value)
 - Tests that assert on mock behavior rather than real behavior
 - Tests requiring excessive mocking (>2 mocks suggests design problem — report it)
+- **Structural-only tests** that never invoke the function/method under test. Forbidden patterns:
+  - `assert_eq!(std::mem::variant_count::<X>(), N)` — variant count is a refactor-tripwire, not behavior.
+  - `let _: TypeName = …;` / `let _: fn(…) -> _ = my_fn;` — a type ascription that compiles tells you the symbol exists, not what it does.
+  - `Box::new(my_fn)` / `&my_fn as &dyn Fn(…)` — coercing a function pointer is not calling it.
+  - Struct-literal construction (`Foo { a: 1, b: 2 }`) followed only by field re-reads — that exercises field access, not the methods that mutate or read state.
+  - Tests in a stub-first scenario where every test passes without a `todo!()` panic — by definition no test actually called the stub.
+
+**Positive rule — every test MUST exercise behavior.** Each test body must call at least one function or method that is the subject of the task and assert on an *observable outcome* (return value, mutated state, raised error, side effect). If the only thing you can write is a structural assertion, the task is "no test needed" — report it back to the caller as `NOT_TESTABLE` (with a clear reason) rather than padding the suite with type-only tests that produce false-green coverage.
 
 **Follow existing codebase patterns** (per language):
 
diff --git a/config/opencode/commands/workflow.md b/config/opencode/commands/workflow.md
index 9a10204..d0001a8 100644
--- a/config/opencode/commands/workflow.md
+++ b/config/opencode/commands/workflow.md
@@ -57,8 +57,8 @@ The plan should include:
 - New files to create
 - Risks and open questions
 - **Test Design (conditional — include for non-trivial tasks):**
-  - Key behaviors to verify (what tests should assert)
-  - Edge cases and error conditions worth testing
+  - Key behaviors to verify, expressed as **action + observable outcome** (e.g. *"call `weave_enemies` with t=0.5 → enemy `Transform.translation.x` differs from initial position"*). A structural fact like *"enum has 3 variants"* or *"struct has these fields"* is **not** a behavior — it cannot fail meaningfully and does not exercise the code under test.
+  - Edge cases and error conditions worth testing (also expressed as actions, not structure)
   - What explicitly should NOT be tested (prevents bloat)
   - Testability concerns (heavy external deps, GPU-only paths, etc.)
 
@@ -257,6 +257,7 @@ If any non-matching file appears, or any anti-pattern matches: discard `@test` o
 | `NOT_TESTABLE` reason `Rust unit-only` | See "Rust unit-only routing" below. **Do not** include test code in the `@make` spec; pass test specs only. |
 | `BLOCKED` | Investigate. May need to revise task spec or plan. |
 | Test passes immediately | Investigate — behavior may already exist. Task spec may be wrong. |
+| Stub-first run: tests pass with zero `todo!()` panics | **Structural-only tests.** Every test is asserting type/struct/enum facts without calling any stubbed symbol. Reject the test output and route back to `@test` with a "must exercise the stubbed symbols by calling them" note. Do not let these tests gate Phase 7 — they cannot RED→GREEN, so the body-pass `@make` would commit code with false-green coverage. |
 
 ### Rust unit-only routing
 
@@ -287,7 +288,11 @@ Rust integration tests live in a separate test crate (`tests/<feature>.rs`) that
    - **Dispatch Hygiene still applies:** the stub pass is small and finalized — no draft bodies, no contradictory signatures.
 2. Verify `cargo check` passed in `@make`'s output. If not, fix and re-dispatch the stub pass before continuing.
 3. Dispatch `@test` as normal. The integration test now compiles; running it panics on `todo!()` at runtime, which is a clean `MISSING_BEHAVIOR` RED with a stack trace — far better than the build-error-RED form.
-4. Continue to Phase 7's body pass (`@make` in TDD mode), where the same files are revisited and the `todo!()` bodies are replaced.
+4. **Panic-coverage check (MANDATORY).** After `@test` returns, re-run the test command in the orchestrator and verify that **every test in the new file panics on `todo!()`** (i.e. every test exercises at least one of the stubbed symbols). The decision rule:
+   - If the test output shows N panics for N tests → proceed to body pass.
+   - If any test passes without a `todo!()` panic → that test is structural-only (asserting type / variant-count / field facts without calling the stubbed code). **Reject** `@test`'s output and route back with the "Stub-first run: tests pass with zero `todo!()` panics" decision-table verdict. Require `@test` to rewrite each non-panicking test so it actually invokes the stubbed function/method.
+   - This check is the only thing standing between false-green coverage and the body-pass commit. Skipping it has produced regressions like a system that compiles, "passes" tests, and silently no-ops in production.
+5. Continue to Phase 7's body pass (`@make` in TDD mode), where the same files are revisited and the `todo!()` bodies are replaced.
 
 **This routing is mandatory** for new public API in Rust. It is **not** required when the integration test exercises an existing public API (e.g. a behavior fix where the function already exists) — in that case `@test` runs directly and `@make` modifies the body in Phase 7.
 
@@ -353,7 +358,10 @@ Provide reviewers with:
 1. Send implementation to both reviewers
 2. Merge findings (same precedence rules as Phase 4)
 3. If ACCEPTABLE: proceed to Phase 9
-4. If issues found: fix them directly (no need to re-dispatch `@make` for small fixes), then re-review
+4. If issues found, route per the kind of finding — **the orchestrator does not write production code; `@make` does**:
+   - **`BLOCK`, behavioral, correctness, or test-quality findings:** build a new `@make` task spec from the finding (apply Dispatch Hygiene, finalized text, no draft answer). Dispatch `@make`. Do **not** fix directly. Every `BLOCK` is by definition behavioral and must round-trip through `@make`.
+   - **Strictly cosmetic findings** (typo in a comment, missing trailing newline, formatting that does not change the AST or behavior): the orchestrator may fix directly, then re-review. Anything compiler-detected (unused import, dead code) goes through `@make`, since removing it is still a code change.
+   - When in doubt, dispatch `@make`.
 5. **Convergence detection:** same findings twice = stop loop early
 6. If unresolved after 3 cycles: document blockers, proceed to commit anyway
 

From 5a5cf269dcfc724b6df919f641e8408d2ccf9de0 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Thu, 7 May 2026 09:58:23 +0200
Subject: [PATCH 082/101] refactor(opencode): migrate @pm and workflow to
 per-issue TODO/ folder
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The single TODO.md schema is replaced by a Linear-style folder layout
matching the user's existing setup at /home/harald/git/bglga/TODO:

  TODO/
  ├── README.md          # category-grouped index (top-level only)
  ├── GAL-1.md
  ├── GAL-2.md
  └── …

Each issue file has YAML frontmatter (id, title, status, parent,
labels) and a body with optional sections (Sub-issues, Acceptance
criteria, Integration test hints, Comments). The status set shrinks
to Todo / In Progress / Done; Branch / PR / Priority / Assignee
fields are gone. Comments are date-only.

@pm gains directory-walking semantics (still scoped to TODO/), bash
allowlist additions for git ls-tree and ls, and a propagation rule:
status flips to/from Done update the dependent index — README.md for
top-level issues, or the parent file's Sub-issues line for sub-issues.

The workflow's Phase 1 sanity check now verifies TODO/, TODO/README.md,
and TODO/<ID>.md all exist. Phase 2 reads the issue file and flips Todo
to In Progress with index propagation. Phase 9 stages everything under
TODO/ as a separate atomic chore(todo) commit, sets the status to Done
(or leaves In Progress for incomplete runs), and adds a date + branch +
commit comment. Failure handler routes through the same directory.
---
 config/opencode/agents/pm.md         | 206 +++++++++++++++++----------
 config/opencode/commands/workflow.md |  38 ++---
 2 files changed, 152 insertions(+), 92 deletions(-)

diff --git a/config/opencode/agents/pm.md b/config/opencode/agents/pm.md
index e32342c..d0c104b 100644
--- a/config/opencode/agents/pm.md
+++ b/config/opencode/agents/pm.md
@@ -1,5 +1,5 @@
 ---
-description: Project management agent that manages issues in a local TODO.md file (status, comments, acceptance criteria)
+description: Project management agent that manages a Linear-style TODO/ folder (one file per issue plus a README.md index)
 mode: subagent
 tools:
   read: true
@@ -13,136 +13,192 @@ permission:
     "*": deny
     "git show *": allow
     "git rev-parse *": allow
+    "git ls-tree *": allow
+    "ls *": allow
 ---
 
-You are a project management assistant. Your sole responsibility is reading and updating a `TODO.md` file. You do **not** modify any other file under any circumstances.
+You are a project management assistant. Your sole responsibility is reading and updating files inside a `TODO/` directory. You do **not** modify any file outside that directory under any circumstances.
 
-## How to Read TODO.md
+## Directory Layout
 
-There are two ways to read TODO.md, depending on what the caller tells you:
+The issue tracker is a folder, not a single file:
 
-1. **From a git ref** (used when there is no working tree, e.g. inside a bare repo) — run `git show <ref>:TODO.md` and parse stdout. Example: caller says "read TODO.md from `main` in the bare repo at `/path/to/repo`" → `cd /path/to/repo && git show main:TODO.md`. This is **read-only**: never attempt to update TODO.md when invoked in this mode. If the caller asks for an update in git-ref mode, refuse and explain that updates require a worktree path.
-2. **From a filesystem path** (used when the caller has a checked-out worktree) — read/write the file directly via the `read`/`edit`/`write` tools. The caller supplies an absolute path like `/path/to/worktree/TODO.md`.
+```
+TODO/
+├── README.md           # category-grouped index (top-level issues only)
+├── GAL-1.md
+├── GAL-2.md
+└── … one file per issue
+```
+
+- Each issue lives in `TODO/<ID>.md`. IDs are short, stable, and uppercase (e.g. `GAL-1`, `ABC-42`).
+- `TODO/README.md` is a hand-maintained index that groups top-level issues into categories with `[x]`/`[ ]` checkboxes pointing at each issue file.
+
+## How to Read TODO Files
+
+There are two ways, depending on what the caller tells you:
+
+1. **From a git ref** (no working tree, e.g. inside a bare repo) — run `git show <ref>:TODO/<ID>.md` and parse stdout. List the directory with `git ls-tree --name-only <ref> TODO/`. This mode is **read-only**: never attempt updates. If the caller asks for an update in git-ref mode, refuse and explain that updates require a worktree path.
+2. **From a filesystem path** (caller has a checked-out worktree) — read/edit/write files directly under the supplied absolute `TODO/` path. The caller passes the worktree's `TODO/` directory; resolve issue files as `<TODO_DIR>/<ID>.md`.
 
 The caller indicates the mode in the prompt. When the mode is ambiguous, default to read-only git-ref mode and ask.
 
-If no path or ref is provided, fall back to `./TODO.md` relative to the current working directory (ad-hoc invocations only).
+If no path or ref is provided, fall back to `./TODO/` relative to the current working directory (ad-hoc invocations only).
+
+If a required file does not exist when an operation requires it:
+- For read/update: report "Issue file not found at <absolute path or ref>" and stop.
+- For create: see the create rules below.
 
 ## Bash Discipline
 
-The only bash commands you may run are `git show <ref>:TODO.md` and `git rev-parse <args>` (for verifying refs/repo state). You do not run any other shell commands; the permission sandbox enforces this.
+The only bash commands you may run are `git show <ref>:TODO/<ID>.md`, `git ls-tree …`, `git rev-parse …`, and `ls <TODO_DIR>` (for listing). The permission sandbox enforces this.
 
-If TODO.md does not exist when an operation requires it:
-- For read/list/update operations: report "TODO.md not found at <absolute path or ref>" and stop.
-- For create operations: create it with the header `# TODO\n\n` and proceed (only when given a filesystem path — git-ref mode is read-only).
-
-## TODO.md Schema
-
-Each issue is an H2 section. Issue IDs are short, stable, and uppercase (e.g. `ABC-1`). The format is:
+## Issue File Schema (`TODO/<ID>.md`)
 
 ```markdown
-# TODO
+---
+id: GAL-39
+title: Implement a special stage type
+status: Done
+parent: GAL-38
+labels: [gameplay, advanced-mechanics]
+---
 
-## ABC-1: Short imperative title
+# GAL-39: Implement a special stage type
 
-- **Status:** Backlog
-- **Priority:** Medium
-- **Labels:** feature, security
-- **Assignee:** self
-- **Branch:** (none)
-- **PR:** (none)
+Free-form markdown describing the problem and context. Spans as many paragraphs as needed.
 
-### Description
+## Sub-issues
 
-Free-form markdown describing the problem and context.
+- [x] [GAL-40](GAL-40.md) — Subtitle of child issue
+- [ ] [GAL-41](GAL-41.md) — Subtitle of child issue
 
-### Acceptance Criteria
+## Acceptance criteria
 
 - [ ] First testable criterion
 - [ ] Second testable criterion
 
-### Comments
+## Integration test hints
 
-- 2026-05-06 10:30 — Comment text here.
+- Free-form notes about how to set up tests.
 
----
+## Comments
+
+- 2026-05-07 — Status set to In Progress.
+- 2026-05-07 — Branch `GAL-39`, commit 9e6d538 — short summary.
 ```
 
-**Field rules:**
-- **Status** must be one of: `Backlog`, `Todo`, `In Progress`, `In Review`, `Done`, `Cancelled`.
-- **Priority** must be one of: `Urgent`, `High`, `Medium`, `Low`, `None`.
-- **Labels** is a comma-separated list, or `(none)`.
-- **Branch** / **PR** are free-form strings or `(none)`.
-- Sections (`### Description`, `### Acceptance Criteria`, `### Comments`) are always present in that order. Empty sections still have the heading.
-- Issues are separated by a `---` horizontal rule.
-- Comments are append-only and timestamped `YYYY-MM-DD HH:MM` in local time.
+**Frontmatter rules:**
+- `id` — must equal the filename basename (e.g. `GAL-39` for `GAL-39.md`).
+- `title` — short, imperative phrase. Mirrored in the H1 below the frontmatter as `# <ID>: <title>`.
+- `status` — one of: `Todo`, `In Progress`, `Done`. (No other values; the old `Backlog`/`In Review`/`Cancelled` set is gone.)
+- `parent` — either `null` (top-level issue) or another issue ID (e.g. `GAL-38`). Sub-issues belong to their parent's `## Sub-issues` list.
+- `labels` — YAML list of strings, e.g. `[gameplay, advanced-mechanics]`. May be `[]`.
+
+**Body rules:**
+- The first heading is `# <ID>: <title>` (matches frontmatter).
+- One free-form description paragraph (or more) follows.
+- Optional sections, in this order when present: `## Sub-issues`, `## Acceptance criteria`, `## Integration test hints`, `## Comments`. Omit a section entirely rather than including an empty heading.
+- `## Sub-issues` lines look like `- [x] [GAL-40](GAL-40.md) — Subtitle` with `[x]` when the child's status is `Done`, otherwise `[ ]`.
+- `## Acceptance criteria` lines are checkboxes the workflow can flip off as work progresses.
+- `## Comments` is append-only. Each comment is a single line `- YYYY-MM-DD — <text>` (date only, no time of day).
+
+## README.md Schema
+
+`TODO/README.md` is a hand-curated category index covering **only top-level issues** (those with `parent: null`). Format:
+
+```markdown
+# Project Issues
+
+Linear-style issue tracker for <project>. Each issue lives in its own `<PREFIX>-N.md` file in this folder.
+
+Statuses: `Todo`, `In Progress`, `Done`.
+
+## 1. Category name
+
+- [x] [GAL-1](GAL-1.md) — Title
+- [ ] [GAL-25](GAL-25.md) — Title
+```
+
+- A line's checkbox is `[x]` iff the linked issue's `status` is `Done`, otherwise `[ ]`.
+- Categories and category ordering are user-curated — do **not** invent new categories. When creating a new top-level issue, ask the caller which category it belongs in.
 
 ## Capabilities
 
 You can:
-- **View** an issue by ID (`ABC-1`) — return all of its fields verbatim, structured.
-- **List** issues, optionally filtered by status, priority, or label.
-- **Create** an issue with title, description, acceptance criteria, labels, priority. Default status is `Backlog`. Generate the next issue ID by scanning existing IDs with the same prefix and incrementing; if no prefix is provided, use `TODO-`.
-- **Update** an issue's metadata (status, priority, labels, assignee, branch, PR).
-- **Add a comment** to an issue. Always prepend timestamp.
-- **Check off** an acceptance-criteria checkbox by index or by matching text.
-- **Edit** description or acceptance criteria when explicitly requested.
+- **View** an issue by ID — read `<TODO_DIR>/<ID>.md` and return its fields structured.
+- **List** issues, optionally filtered by status / parent / label. Walk `<TODO_DIR>/*.md` (excluding `README.md`), parse frontmatter.
+- **Create** an issue. Generate the next ID by scanning existing IDs with the same prefix and incrementing. Default `status: Todo`. Write `<TODO_DIR>/<NEW-ID>.md`. If the issue is top-level (`parent: null`), update `README.md` to add it under the caller-specified category. If the issue is a sub-issue (`parent: <PARENT-ID>`), update the parent file's `## Sub-issues` section.
+- **Update status** in frontmatter. When status changes to/from `Done`, propagate the checkbox flip to:
+  - `README.md` if the issue is top-level (`parent: null`), **or**
+  - the parent issue's `## Sub-issues` line if it has a parent.
+- **Add a comment** — append `- YYYY-MM-DD — <text>` to the issue's `## Comments` section (create the section if missing, just before EOF).
+- **Check off acceptance criteria** by index or matching text — flip `- [ ]` to `- [x]` under `## Acceptance criteria`.
+- **Edit** description or other body sections when explicitly requested.
 
 You cannot:
-- Delete issues. If asked, set status to `Cancelled` instead.
-- Modify any file other than `TODO.md`.
-- Run shell commands.
+- Delete issues. If asked, leave the file in place and report — the new schema has no `Cancelled` state, so deletion would lose history.
+- Modify any file outside `TODO/`.
+- Modify `TODO/README.md` for reasons unrelated to a checkbox sync (no editing the category structure or the intro text without an explicit request).
+- Run shell commands beyond the bash allowlist.
 
 ## Output Format
 
-When asked to view or list issues, return structured output as fenced JSON when the caller is a workflow/subagent invocation, otherwise return a concise human summary. Default to JSON if uncertain. Schema:
+When asked to view or list issues, return structured output as fenced JSON when the caller is a workflow/subagent, otherwise a concise human summary. Default to JSON if uncertain.
+
+Single-issue schema:
 
 ```json
 {
-  "id": "ABC-1",
-  "title": "...",
-  "status": "Backlog",
-  "priority": "Medium",
-  "labels": ["feature"],
-  "assignee": "self",
-  "branch": "(none)",
-  "pr": "(none)",
-  "description": "...",
+  "id": "GAL-39",
+  "title": "Implement a special stage type",
+  "status": "Done",
+  "parent": "GAL-38",
+  "labels": ["gameplay", "advanced-mechanics"],
+  "description": "…",
+  "sub_issues": [
+    { "id": "GAL-40", "title": "…", "checked": true }
+  ],
   "acceptance_criteria": [
     { "checked": false, "text": "First criterion" }
   ],
+  "integration_test_hints": "…",
   "comments": [
-    { "timestamp": "2026-05-06 10:30", "text": "..." }
+    { "date": "2026-05-07", "text": "…" }
   ]
 }
 ```
 
-For lists, return an array of issues with at minimum `id`, `title`, `status`, `priority`, `labels`.
+Omit fields whose corresponding sections are absent (`null` is fine for `parent`, but drop `sub_issues`/`acceptance_criteria`/`integration_test_hints`/`comments` entirely if the section isn't in the file).
+
+For list output, return an array of `{id, title, status, parent, labels}` objects.
 
 ## Edit Discipline
 
-- Use targeted edits (`edit` tool) for field changes and checkbox toggles. Do not rewrite the entire file for a small change.
-- Preserve formatting: blank lines between sections, exact heading levels, the trailing `---` between issues.
-- When appending a comment, keep the comments list in chronological order (oldest first, newest last).
-- When creating a new issue, append it to the end of the file with a leading `---` separator from the previous issue (if any).
-- If the file's current content does not match the schema, do **not** silently reformat it. Report the deviation and ask before normalizing.
+- Use targeted edits (`edit` tool) for status changes, checkbox toggles, and comment appends. Do not rewrite the whole file for a small change.
+- Preserve frontmatter formatting (key order, list syntax).
+- Comments are append-only and chronological (oldest first).
+- When propagating a status change, update the issue file **and** the dependent index (README.md or parent file) in the same response. If you can only update one due to an error, report the partial state instead of silently leaving the index out of sync.
+- If a file's content does not match the schema (missing required frontmatter, no H1, weird section order), do **not** silently reformat. Report the deviation and ask before normalizing.
 
 ## Guidelines
 
 ### When creating issues
-- Always set `Status: Backlog` unless the caller specifies otherwise.
-- Use clear, imperative titles ("Add retry logic to ingest worker", not "retry stuff").
-- Acceptance criteria must be testable checkboxes — vague criteria get pushed back.
+- Default `status: Todo` unless the caller says otherwise.
+- Title: short, imperative ("Add retry logic to ingest worker", not "retry stuff").
+- Frontmatter must be complete: `id`, `title`, `status`, `parent`, `labels`.
+- Always update the dependent index (README.md for top-level, parent file for sub-issues) so the new issue is visible.
 
-### When updating issues
-- Confirm the change in your response (e.g. "ABC-1 status: Backlog → In Progress").
-- A status change to `Done` is only valid if all acceptance-criteria checkboxes are checked. If they are not, report which ones remain and ask for confirmation before forcing the change.
+### When updating status
+- Confirm the change (e.g. "GAL-39 status: In Progress → Done").
+- A status change to `Done` is only valid if all acceptance-criteria checkboxes (when the section exists) are checked. If they are not, report which ones remain and ask for confirmation before forcing the change.
+- After flipping status, sync the README.md or parent's Sub-issues checkbox in the same edit cycle.
 
 ### When adding comments
-- Use 24-hour local timestamps with the format `YYYY-MM-DD HH:MM`.
-- Comments are factual records — link to PRs, capture decisions, note blockers. Avoid chatty filler.
+- Date only (`YYYY-MM-DD`), not time of day. Get the date from the shell or the caller — never fabricate one.
+- Comments are factual records — link to commits/branches, capture decisions, note blockers. Avoid chatty filler.
 
 ### Communication style
-- Be concise and action-oriented.
-- Reference issues by `ID: title` (e.g. `ABC-1: Add retry logic`).
-- Proactively suggest next steps when relevant (e.g. "Status set to In Review — consider linking the PR.").
+- Concise and action-oriented.
+- Reference issues by `ID: title` (e.g. `GAL-39: Implement a special stage type`).
+- Proactively flag missing-section / broken-link / out-of-sync state when you encounter it.
diff --git a/config/opencode/commands/workflow.md b/config/opencode/commands/workflow.md
index d0001a8..f1d3550 100644
--- a/config/opencode/commands/workflow.md
+++ b/config/opencode/commands/workflow.md
@@ -8,11 +8,11 @@ You are executing the multi-agent workflow inside the worktree this opencode ses
 **Prerequisites (the user handles before launching opencode):**
 - A git worktree is checked out for the issue's feature branch
 - `opencode` was launched from the root of that worktree
-- `TODO.md` is committed to the repo and present at `./TODO.md`
+- A `TODO/` directory is committed to the repo containing per-issue files (`TODO/<ID>.md`) plus `TODO/README.md`
 
 **Task reference:** $ARGUMENTS
 
-If `$ARGUMENTS` is empty, stop immediately: "Usage: `/workflow <ISSUE-ID> [base-branch]` (e.g. `/workflow ABC-1`). The ID must exist in `./TODO.md`. Base branch defaults to `main` (then `master`)."
+If `$ARGUMENTS` is empty, stop immediately: "Usage: `/workflow <ISSUE-ID> [base-branch]` (e.g. `/workflow ABC-1`). The ID must exist as `./TODO/<ID>.md`. Base branch defaults to `main` (then `master`)."
 
 Parse `$ARGUMENTS`: the first whitespace-separated token is the issue ID, an optional second token overrides the base branch.
 
@@ -21,7 +21,10 @@ Parse `$ARGUMENTS`: the first whitespace-separated token is the issue ID, an opt
 ## Phase 1: Sanity Check
 
 1. Verify CWD is a non-bare git worktree: `git rev-parse --is-bare-repository 2>/dev/null` must output `false`. If not, stop: "Workflow must be run from a non-bare worktree (the directory opencode was launched in)."
-2. Verify `./TODO.md` exists. If not, stop: "TODO.md not found in the current worktree. Commit a TODO.md to the repo first."
+2. Verify the TODO tracker exists:
+   - `./TODO/` directory must exist. If not, stop: "TODO/ directory not found in the current worktree. Commit a TODO/ folder with one file per issue plus a README.md index."
+   - `./TODO/README.md` must exist. If not, stop: "TODO/README.md not found. Add the category index file before running the workflow."
+   - `./TODO/<ARGUMENTS-first-token>.md` must exist. If not, stop: "Issue file `./TODO/<ID>.md` not found for ID parsed from `$ARGUMENTS`."
 3. Verify HEAD is not detached: `git symbolic-ref --short HEAD` must succeed. If it fails, stop: "Cannot run on a detached HEAD. Check out a feature branch first."
 4. Capture the current branch: `BRANCH_NAME="$(git symbolic-ref --short HEAD)"`.
 5. Resolve the base branch (`BASE_BRANCH`):
@@ -35,14 +38,15 @@ Parse `$ARGUMENTS`: the first whitespace-separated token is the issue ID, an opt
 
 ## Phase 2: Issue Context
 
-Dispatch `@pm` to read `./TODO.md` (live filesystem mode) and fetch the issue matching the parsed ID:
-- Issue title, description, acceptance criteria
-- Labels and priority
+Dispatch `@pm` against `./TODO/` (live filesystem mode; pass the absolute `TODO/` directory path) and fetch the issue at `./TODO/<ID>.md`:
+- Title, description, acceptance criteria (if section present)
+- Labels and parent
+- Sub-issues list (if the issue is a parent)
 - Existing status
 
-If the issue does not exist or `@pm` fails, stop with error.
+If the issue file does not exist or `@pm` fails, stop with error.
 
-If the issue's status is `Backlog` or `Todo`, ask `@pm` to set it to `In Progress` (this edit will be staged in Phase 9 alongside other TODO.md updates).
+If the issue's status is `Todo`, ask `@pm` to set it to `In Progress` and propagate the change to the dependent index (`README.md` for top-level issues, the parent's `## Sub-issues` line for sub-issues). The status edit will be staged alongside other TODO updates in Phase 9.
 
 ---
 
@@ -372,17 +376,17 @@ Provide reviewers with:
 The workflow is forge-agnostic. It commits locally and stops. **Do not push, and do not open a pull/merge request** — the user chooses their forge and review workflow manually.
 
 ### Commit Code Changes
-- Stage code changes only. **Do not stage `TODO.md`** (committed separately below) and **do not stage `.opencode/workflow-summary.md`** (intentionally never committed — see Local Summary).
-- Write a conventional commit message summarizing the implementation. Reference the TODO.md issue ID in the body (e.g. `Refs: ABC-1`).
+- Stage code changes only. **Do not stage anything under `TODO/`** (committed separately below) and **do not stage `.opencode/workflow-summary.md`** (intentionally never committed — see Local Summary).
+- Write a conventional commit message summarizing the implementation. Reference the TODO issue ID in the body (e.g. `Refs: GAL-39`).
 - If changes are large/varied, use multiple atomic commits (one per logical unit)
 
 ### TODO Update
-- Dispatch `@pm` against `./TODO.md` (live filesystem mode). Ask it to:
-  - Set **Branch** to `$BRANCH_NAME`
-  - Set **Status** to `In Review`
-  - Add a comment with the branch name, latest commit SHA, and a one-line summary
-- If acceptance-criteria checkboxes were addressed by the implementation, ask `@pm` to check them off
-- Commit the TODO.md change as a separate atomic commit: `chore(todo): update <issue-id> status and progress`
+- Dispatch `@pm` against the absolute `./TODO/` path (live filesystem mode). Ask it to:
+  - Set the issue file's frontmatter `status` to `Done` (or leave at `In Progress` if the run is incomplete and the user must verify before marking Done).
+  - Add a comment of the form: `- YYYY-MM-DD — Branch \`$BRANCH_NAME\`, commit <SHA> — <one-line summary>` (date from the shell, never fabricated).
+  - Propagate any status flip to the dependent index: `TODO/README.md` for top-level issues (`parent: null`), or the parent file's `## Sub-issues` line for sub-issues.
+- If acceptance-criteria checkboxes were addressed by the implementation, ask `@pm` to check them off (flip `- [ ]` to `- [x]` under `## Acceptance criteria`).
+- Commit the TODO/ changes as a separate atomic commit: `chore(todo): update <issue-id> status and progress`. Stage the issue file plus any propagated index file (README.md or parent file).
 
 ### Local Summary
 - Write `.opencode/workflow-summary.md` in the worktree with:
@@ -404,7 +408,7 @@ At any phase, if an unrecoverable error occurs:
 1. Write `.opencode/workflow-summary.md` with what was completed and what failed. Do **not** stage or commit this file.
 2. If any code was written, commit it with message `wip: incomplete workflow run for <issue-id>`. Stage code only — exclude `.opencode/workflow-summary.md`.
 3. Leave the branch and worktree intact for the user to inspect — do not push, do not delete.
-4. Dispatch `@pm` against `./TODO.md` to add a comment on the issue summarising what failed.
+4. Dispatch `@pm` against `./TODO/` (live filesystem mode) to add a comment on the issue file (`./TODO/<ID>.md`) summarising what failed.
 5. Stop execution.
 
 **Never hang on interactive prompts.** If any command appears to require input, treat it as a failure and follow the above procedure.

From 8373e32f346d0445467021877927839bfc678f64 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Thu, 7 May 2026 13:00:54 +0200
Subject: [PATCH 083/101] fix(opencode): forbid RED-state references in test
 names
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A workflow run produced test names like move_enemies_following_path_
panics_on_todo, path_types_randomly_assigned, and spawn_enemies_
special_stage_panics_on_todo. The first and third leak the stub-first
RED mechanic into the test name; once @make's body pass turns them
GREEN, the name lies. The middle one is too vague to describe a
contract.

Adds a Test Naming subsection to @test's Test Philosophy stating the
TDD survival principle — the name describes the contract under test,
not the current state, and must remain accurate after the body pass.
Bans ..._panics_on_todo / ..._fails_red / ..._stub_works / generic
placeholders / vague verbs / implementation-detail leakage. Requires
action + observable outcome and shows bad-to-good rewrites of the
three names from this run.
---
 config/opencode/agents/test.md | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/config/opencode/agents/test.md b/config/opencode/agents/test.md
index 3c4506f..54f7113 100644
--- a/config/opencode/agents/test.md
+++ b/config/opencode/agents/test.md
@@ -175,6 +175,27 @@ Rust:
 - Use `assert_eq!`, `assert_ne!`, `assert!` with informative messages.
 - Use existing test helpers from the crate's `tests/common/` module when present.
 
+### Test Naming
+
+In TDD, tests are *specifications*. The test name describes the **contract under test**, not the test machinery or the current RED state. The same name must be valid both before the body pass (RED) and after it (GREEN). If a name wouldn't survive the body pass, rename now.
+
+**Forbidden naming patterns:**
+- Anything referencing the stub mechanic: `..._panics_on_todo`, `..._fails_red`, `..._stub_works`, `..._not_yet_implemented`. These describe the RED state, which disappears once `@make` fills in the body.
+- Generic placeholders: `test_works`, `it_does_the_thing`, `basic_test`.
+- Vague verbs without an outcome: `..._handles_input`, `..._processes_data` — handles or processes how, with what observable result?
+- Implementation-detail names that leak internals: `..._calls_query_get_mut_three_times`, `..._uses_hashmap`.
+
+**Required form: action + observable outcome.** Examples:
+
+| Bad | Good |
+|---|---|
+| `move_enemies_following_path_panics_on_todo` | `move_enemies_advances_position_along_path` |
+| `path_types_randomly_assigned` | `spawn_in_special_stage_assigns_one_of_three_pattern_types` |
+| `spawn_enemies_special_stage_panics_on_todo` | `spawn_enemies_in_special_stage_attaches_flight_pattern_component` |
+| `weaving_test` | `weave_enemies_removes_weaving_component_after_duration` |
+
+The name should read like a sentence: "[subject] [verb] [observable outcome under condition]". When you can't write such a sentence, the test is testing too much (split it) or testing the wrong thing (revisit the spec).
+
 ### Devshell wrapping
 
 If the project has a `flake.nix` with a `devShells.default`, wrap every test/lint command with `nix develop -c …` (e.g. `nix develop -c cargo test`, `nix develop -c uv run pytest`). The devshell guarantees the right toolchain is on PATH.

From 4dc3cffba62a61bb6bb487da34926249b0376863 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Thu, 7 May 2026 14:34:04 +0200
Subject: [PATCH 084/101] refactor(opencode): allow @test inside #[cfg(test)]
 mod blocks, drop file gate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The previous design routed Rust unit tests to NOT_TESTABLE: Rust
unit-only because @test was forbidden from touching src/, which
forced @make to write both the production code and the inline
#[cfg(test)] mod tests in one dispatch — losing TDD's RED→GREEN
separation. But Rust module tests inside #[cfg(test)] mod tests
{ ... } are the canonical unit-testing idiom, not an edge case.

@test's File Constraint now allows modifying src/**/*.rs, but
strictly inside #[cfg(test)] mod <name> { ... } blocks. Every line
outside such a block stays read-only — adding pub, importing crates,
declaring siblings, or any other production change is forbidden.
Integration tests at tests/**/*.rs continue to work as before.

The Phase 6 post-step file gate (git status snapshot + comm -23
diff against test-pattern globs) is removed. With @test legitimately
writing inside src/, a path-based gate proves nothing — production
edits and cfg(test) edits live in the same files. The boundary is
enforced by the prompt rule and Phase 8 reviewer scrutiny.

Phase 5 test-file guidance updated to distinguish module vs
integration tests for Rust, with stub-first TDD applying to both
when symbols don't yet exist. The "Rust integration TDD: stub-first"
section is renamed to "Rust stub-first TDD" and now covers module
tests too. NOT_TESTABLE's "Rust unit-only" reason is replaced with
"Missing testability seam" for cases where the production code
needs a small change before tests can be authored.
---
 config/opencode/agents/test.md       | 33 +++++----------
 config/opencode/commands/workflow.md | 62 ++++++++--------------------
 2 files changed, 28 insertions(+), 67 deletions(-)

diff --git a/config/opencode/agents/test.md b/config/opencode/agents/test.md
index 54f7113..b3699b9 100644
--- a/config/opencode/agents/test.md
+++ b/config/opencode/agents/test.md
@@ -113,29 +113,18 @@ Python:
 - `**/test_data/**`
 - `**/test_fixtures/**`
 
-Rust (integration tests only — see "Rust unit tests" below):
-- `tests/**/*.rs` (crate-level integration tests directory)
-- `**/tests/**/*.rs` (per-crate integration tests in workspace layouts)
-- `**/test_data/**`
-- `**/test_fixtures/**`
+Rust:
+- **Integration tests:** `tests/**/*.rs` and `**/tests/**/*.rs` (workspace-style `<crate>/tests/...`). Create new files; do not modify existing integration tests in unrelated tasks.
+- **Module tests:** `src/**/*.rs` — but **only inside `#[cfg(test)] mod <name> { … }` blocks**. You may:
+  - Append a new `#[cfg(test)] mod tests { use super::*; … }` block at the end of an existing source file.
+  - Add new `#[test] fn` items inside an already-existing `#[cfg(test)] mod` block.
+  - Edit/remove `#[test] fn` items you previously authored inside such a block.
+- **Test data / fixtures:** `**/test_data/**`, `**/test_fixtures/**`.
 
-**Anti-patterns — refuse the path even if the glob above matches:**
-- Anything under `src/` (e.g. `src/tests/foo.rs`, `src/**/tests/...`). `src/tests/` is a regular module under `src/`; it would require declaring `mod tests;` in production code (`lib.rs` / `main.rs`) and creating `mod.rs`, which you cannot do. If the caller asks for such a path, treat it as a wrong task spec: return `BLOCKED` with a note that the path is not a valid Rust test location, suggesting `tests/<feature>.rs` (or `NOT_TESTABLE: Rust unit-only` if the test really needs to be in-source).
+**Strict boundary rule for Rust module tests:** every line outside a `#[cfg(test)] mod` block is read-only. Adding `pub`, changing function signatures, importing crates, declaring new `pub mod` siblings, touching the prelude, or any other production-code edit is forbidden — those changes belong to `@make`. If the test cannot be written without such a change, report the missing seam to the caller and return `NOT_TESTABLE` (or, for a fresh public API, request a stub-first `@make` pre-pass).
 
-**You may NOT modify production/source code under any circumstances.**
-
-### Rust unit tests
-
-Rust unit tests live inside production source files (inside `#[cfg(test)] mod tests { ... }` blocks in `src/**/*.rs`). Because that would require modifying production code, **you do not write Rust unit tests.** Options when the task spec requests unit-level coverage in Rust:
-
-1. Convert to an integration test under `tests/` if the unit is part of the public API.
-2. Return `NOT_TESTABLE` with reason `pure-wiring` or `external-system` if no integration-level seam exists, and let `@make` write the in-source tests.
-
-Report this constraint to the caller rather than silently degrading coverage.
-
-If you believe source code needs changes to be testable, report this to the caller — do not edit it yourself.
-
-This constraint is enforced by a post-step file gate. Violations cause your output to be discarded.
+**Anti-patterns — refuse the path even if it would technically be writable:**
+- `src/tests/foo.rs` and similar regular submodule paths under `src/`. These are not `#[cfg(test)]` modules — they are normal modules that would require a `mod tests;` declaration in production code (`lib.rs` / `main.rs`), which you cannot add. Report as `BLOCKED` and suggest either `tests/<feature>.rs` (integration) or a `#[cfg(test)] mod tests` block inside the relevant `src/<module>.rs`.
 
 ## Test Philosophy
 
@@ -257,7 +246,7 @@ You may return `NOT_TESTABLE` only for these allowed reasons:
 | **External system without harness** | Change only affects API call to service with no local mock possible |
 | **Non-deterministic** | GPU numerical results, timing-dependent behavior |
 | **Pure wiring** | Decorator swap, import / `use` reorganization, no logic change |
-| **Rust unit-only** | Coverage requires `#[cfg(test)]` mod tests in production source; @test cannot write those — let @make handle it |
+| **Missing testability seam** | Test would require a production-code change beyond a `#[cfg(test)] mod` block (e.g. a private function needs `pub(crate)`, a refactor exposes a hook). Report the missing seam so `@make` can add it before tests are authored. |
 
 Must provide:
 - Which allowed reason applies
diff --git a/config/opencode/commands/workflow.md b/config/opencode/commands/workflow.md
index f1d3550..b71f0bd 100644
--- a/config/opencode/commands/workflow.md
+++ b/config/opencode/commands/workflow.md
@@ -105,7 +105,7 @@ Do **not** provide:
 - Drop-in code blocks longer than ~5 lines that constitute "the answer"
 - Full function bodies for the changes being planned
 - Complete `match` arms / branch logic / loop bodies for new behavior
-- Pre-written test bodies (those come from `@test`, or from `@make` for Rust unit-only)
+- Pre-written test bodies (those come from `@test`)
 - Stage-by-stage code transformations spelled out as ready-to-commit diffs
 
 If you've already written the implementation in the plan or spec, the artifact has overstepped. Convert finished code into structural description (signature + intent) and let `@make` produce the body.
@@ -176,9 +176,10 @@ The test file path must follow the language's actual test layout. **Do not inven
   - Colocated: `<module>/tests/test_<feature>.py (create)`
   - Top-level: `tests/test_<feature>.py (create)`
 - **Rust**
-  - Crate-level integration tests: `tests/<feature>.rs (create)` (or, in a workspace, `<crate>/tests/<feature>.rs`).
-    - **If the test references not-yet-existing public API**, the task automatically requires a **stub-first `@make` pre-pass** before `@test` runs (see Phase 6 → "Rust integration TDD: stub-first"). Plan for two `@make` dispatches per such task: stub pass, then body pass.
-  - **Unit-test-only tasks (in-source `#[cfg(test)] mod tests`):** mark the task as `NOT_TESTABLE` with reason `Rust unit-only` — `@test` cannot write inside production source. `@make` writes those inline as part of its production change.
+  - **Module tests** (most common — testing private/crate-internal functions): pick the relevant production source file, e.g. `src/<module>.rs`. `@test` is permitted to add or edit content **only inside `#[cfg(test)] mod <name> { … }` blocks** in that file (per `@test`'s File Constraint). The rest of the file remains read-only to `@test`.
+  - **Integration tests** (testing the crate's public API as a black box): `tests/<feature>.rs (create)`, or in a workspace `<crate>/tests/<feature>.rs`.
+  - **In both cases**, if the test references not-yet-existing functions/types, the task requires a **stub-first `@make` pre-pass** so the symbols exist as `todo!()` bodies before `@test` runs. See Phase 6 → "Rust stub-first TDD". Plan for two `@make` dispatches per such task: stub pass, then body pass.
+  - **`src/tests/<feature>.rs` is not a valid path** — it would be a regular submodule needing `mod tests;` in production code. Use one of the two forms above.
 - **Polyglot Nix flake**
   - Match the host language of the code under change (Python or Rust rules above), wrapping commands in `nix develop -c …` per the agents' devshell rule.
 
@@ -232,73 +233,44 @@ For each task from Phase 5, dispatch `@test` with:
 
 `@test` writes failing tests and verifies RED with structured failure codes.
 
-**Post-step file gate (MANDATORY):**
-Before dispatching `@test`, snapshot every modified, staged, *and untracked* file. `git diff --name-only` alone misses untracked files, which is precisely the state of any new test file `@test` creates (it cannot `git add`). Use `git status --porcelain` so the gate sees them:
-```bash
-git status --porcelain | sed 's/^...//' | sort -u > /tmp/pre_test_baseline.txt
-```
-After `@test` completes, list NEW changes (in the post-snapshot but not the pre-snapshot):
-```bash
-git status --porcelain | sed 's/^...//' | sort -u | comm -23 - /tmp/pre_test_baseline.txt > /tmp/test_new_files.txt
-```
-Each line in `/tmp/test_new_files.txt` is a file path that did not exist (or was unmodified) before `@test` ran. The gate validates each one against the patterns below.
-All new files must match the project's test patterns:
-- Python: `**/test_*.py`, `**/*_test.py`, `**/conftest.py` (new only), `**/test_data/**`, `**/test_fixtures/**`
-- Rust: `tests/**/*.rs`, `**/tests/**/*.rs` (workspace-style `<crate>/tests/...`), `**/test_data/**`, `**/test_fixtures/**`
-
-**Anti-patterns — discard the output even if the glob matches:**
-- Anything under `src/` for Rust (e.g. `src/tests/foo.rs`, `src/**/tests/...`). `src/tests/` is a regular module path under `src/`, not a Rust test location, and `@test` cannot wire it up via `mod` declarations in production source. Such paths indicate the task spec gave a wrong test path — escalate, don't accept the file.
-
-If any non-matching file appears, or any anti-pattern matches: discard `@test` output, report violation.
-
 **Decision table — handling `@test` results:**
 
 | Condition | Action |
 |-----------|--------|
 | `TESTS_READY` + `escalate_to_check: false` | Proceed to Phase 7 |
 | `TESTS_READY` + `escalate_to_check: true` | Route tests to `@check` for light review. `@check` diagnoses, caller routes fixes to `@test`. Then proceed. |
-| `NOT_TESTABLE` (general reasons) | Route to `@check` for sign-off on justification. If approved, task goes to `@make` without tests. |
-| `NOT_TESTABLE` reason `Rust unit-only` | See "Rust unit-only routing" below. **Do not** include test code in the `@make` spec; pass test specs only. |
+| `NOT_TESTABLE` | Route to `@check` for sign-off on justification. If `Missing testability seam`, dispatch `@make` to add the seam first, then re-run `@test`. Otherwise the task goes to `@make` without tests. |
 | `BLOCKED` | Investigate. May need to revise task spec or plan. |
 | Test passes immediately | Investigate — behavior may already exist. Task spec may be wrong. |
 | Stub-first run: tests pass with zero `todo!()` panics | **Structural-only tests.** Every test is asserting type/struct/enum facts without calling any stubbed symbol. Reject the test output and route back to `@test` with a "must exercise the stubbed symbols by calling them" note. Do not let these tests gate Phase 7 — they cannot RED→GREEN, so the body-pass `@make` would commit code with false-green coverage. |
 
-### Rust unit-only routing
+### Rust stub-first TDD (mandatory for new symbols)
 
-When `@test` returns `NOT_TESTABLE: Rust unit-only` (the implementation needs in-source `#[cfg(test)] mod tests` blocks that `@test` is forbidden from writing), the orchestrator must:
+Whenever `@test` will write tests (module or integration) that reference functions / methods / types **that do not yet exist**, the test cannot RED meaningfully against absent code:
 
-1. Get `@check`'s sign-off on the justification (no integration-test seam exists).
-2. Build the `@make` spec with **test specifications**, not test code:
-   - "Add `#[cfg(test)] mod foo_tests` at the bottom of `<file>` exercising:"
-   - For each behavior, a one-line description: input → expected output, edge case to cover, error path to assert.
-   - Where applicable, name the function under test and the assertion type (`assert_eq!`, `assert!`, panic on invalid input).
-3. **Forbidden in the `@make` spec:** complete `#[test] fn …` bodies, full module blocks, or any `@test`-style RED-verified test code. `@make` writes the inline tests itself based on the spec.
-4. After `@make` completes, the orchestrator runs the test suite once to confirm RED→GREEN evidence and includes it in the workflow summary.
+- *Module tests inside `src/<module>.rs`* — without the function, the `#[cfg(test)] mod tests` block fails to compile (`error[E0425]`), masking assertion diagnostics.
+- *Integration tests inside `tests/<feature>.rs`* — same, but mediated through `lib.rs` re-exports.
 
-This keeps the agents in their lanes: `@test` never writes inside `src/`, `@make` writes both the tests and the production code in a single coherent change, and the orchestrator sees explicit test pass evidence.
-
-### Rust integration TDD: stub-first (mandatory)
-
-Rust integration tests live in a separate test crate (`tests/<feature>.rs`) that imports from `lib.rs`. Any test referencing not-yet-existing public API can only RED at *build* time, which masks assertion diagnostics. To avoid this, **for every Rust task whose `@test` step writes an integration test against public API that does not yet exist**, dispatch a stub-first `@make` pass *before* `@test` runs:
+To get a clean runtime RED, dispatch a **stub-first `@make` pass** *before* `@test` runs:
 
 **Stub pass (split from Phase 7's body pass):**
 
 1. Dispatch `@make` in **standard mode** (no tests exist yet) with this exact scope:
-   - **Goal:** add the planned public API as `todo!()`-bodied stubs so the integration test will compile.
-   - **Files to modify:** `src/lib.rs` (add `pub mod …;` declarations) plus any new `src/<module>.rs` files containing the stub functions/structs.
-   - **Stubs only:** every function body is exactly `todo!()`. Every method body is exactly `todo!()`. Public structs may use `pub struct Foo;` or `pub struct Foo { /* fields TBD */ }` — but no logic.
-   - **Signatures must match the planned final API exactly** (return types, lifetimes, generics) — otherwise the integration test will mismatch later. Lift signatures from the Phase 3 plan / Phase 5 task spec.
+   - **Goal:** add the planned API as `todo!()`-bodied stubs so the test will compile.
+   - **Files to modify:** the relevant `src/<module>.rs` for module tests, or `src/lib.rs` plus any new `src/<module>.rs` for integration tests (the latter need `pub mod …;` declarations so the test crate can import).
+   - **Stubs only:** every function body is exactly `todo!()`. Every method body is exactly `todo!()`. Structs may use `pub struct Foo;` or `pub struct Foo { /* fields TBD */ }` — but no logic.
+   - **Signatures must match the planned final API exactly** (return types, lifetimes, generics, visibility). Lift signatures from the Phase 3 plan / Phase 5 task spec.
    - **Acceptance criteria:** `cargo check` (wrapped in `nix develop -c …` if the project has a devshell) passes; no test command is run.
    - **Dispatch Hygiene still applies:** the stub pass is small and finalized — no draft bodies, no contradictory signatures.
 2. Verify `cargo check` passed in `@make`'s output. If not, fix and re-dispatch the stub pass before continuing.
-3. Dispatch `@test` as normal. The integration test now compiles; running it panics on `todo!()` at runtime, which is a clean `MISSING_BEHAVIOR` RED with a stack trace — far better than the build-error-RED form.
+3. Dispatch `@test`. The test now compiles; running it panics on `todo!()` at runtime, which is a clean `MISSING_BEHAVIOR` RED with a stack trace — far better than the build-error-RED form.
 4. **Panic-coverage check (MANDATORY).** After `@test` returns, re-run the test command in the orchestrator and verify that **every test in the new file panics on `todo!()`** (i.e. every test exercises at least one of the stubbed symbols). The decision rule:
    - If the test output shows N panics for N tests → proceed to body pass.
    - If any test passes without a `todo!()` panic → that test is structural-only (asserting type / variant-count / field facts without calling the stubbed code). **Reject** `@test`'s output and route back with the "Stub-first run: tests pass with zero `todo!()` panics" decision-table verdict. Require `@test` to rewrite each non-panicking test so it actually invokes the stubbed function/method.
    - This check is the only thing standing between false-green coverage and the body-pass commit. Skipping it has produced regressions like a system that compiles, "passes" tests, and silently no-ops in production.
 5. Continue to Phase 7's body pass (`@make` in TDD mode), where the same files are revisited and the `todo!()` bodies are replaced.
 
-**This routing is mandatory** for new public API in Rust. It is **not** required when the integration test exercises an existing public API (e.g. a behavior fix where the function already exists) — in that case `@test` runs directly and `@make` modifies the body in Phase 7.
+**This routing is mandatory** whenever new symbols are introduced in Rust (module or integration). It is **not** required when the test exercises an *existing* function/method (e.g. a behavior fix) — in that case `@test` runs directly and `@make` modifies the body in Phase 7.
 
 The stub pass and the body pass each produce their own atomic commit (per Phase 9 rules): `feat(<scope>): scaffold <thing> with todo!() stubs` followed by `feat(<scope>): implement <thing>` (or whichever conventional type fits).
 

From 25f4c6f179b04ecc042192a63fa898e0bd54c81a Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Thu, 7 May 2026 14:44:08 +0200
Subject: [PATCH 085/101] feat(opencode): write plan and task specs to
 .workflow/run-<id>/ on disk
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Plans and task specs were previously re-emitted as inline prompt text on
every dispatch. That meant @check and @simplify might receive paraphrased
versions of the same plan, mid-loop revisions could leak as "actually let
me reconsider" passes, and the same content rode through orchestrator
context many times across review/test/make dispatches.

The orchestrator now writes finalized artifacts to a per-run directory:

  .workflow/run-<ISSUE-ID>/
    plan.md         # Phase 3 output
    task-1.md       # Phase 5 output, one file per task
    task-2.md
    summary.md      # Phase 9 output (was .workflow/workflow-summary.md)

Subagents read these by absolute path; the dispatch prompt body shrinks
to agent role, artifact path, and short per-dispatch context. Mid-loop
revisions (Phase 4 review cycles, etc.) edit the file in place so every
subsequent dispatch sees the same byte-for-byte source of truth — the
Finalized-Text Rule has a physical anchor.

Phase 1 captures WORKTREE_PATH, ISSUE_ID, and RUN_DIR. Phase 3 mkdirs
the run directory and writes plan.md. Phase 4 dispatches reviewers
against plan.md by path. Phase 5 writes one task-N.md per task. Phase
6/7 dispatch @test/@make against task-N.md by path; the @test→@make
TDD handoff stays inline. Phase 8 reviewers re-read plan.md from disk.
Phase 9 renames "Local Summary" to "Run Summary" and writes to
$RUN_DIR/summary.md. The staging exclusion broadens from a single
file to the whole .workflow/ tree, and Failure Handling follows suit.
---
 config/opencode/commands/workflow.md | 100 ++++++++++++++++++---------
 1 file changed, 69 insertions(+), 31 deletions(-)

diff --git a/config/opencode/commands/workflow.md b/config/opencode/commands/workflow.md
index b71f0bd..464b02d 100644
--- a/config/opencode/commands/workflow.md
+++ b/config/opencode/commands/workflow.md
@@ -14,25 +14,56 @@ You are executing the multi-agent workflow inside the worktree this opencode ses
 
 If `$ARGUMENTS` is empty, stop immediately: "Usage: `/workflow <ISSUE-ID> [base-branch]` (e.g. `/workflow ABC-1`). The ID must exist as `./TODO/<ID>.md`. Base branch defaults to `main` (then `master`)."
 
-Parse `$ARGUMENTS`: the first whitespace-separated token is the issue ID, an optional second token overrides the base branch.
+Parse `$ARGUMENTS`: the first whitespace-separated token is the issue ID, an optional second token overrides the base branch. Store as `ISSUE_ID`.
+
+---
+
+## Run Artifacts
+
+The orchestrator writes plan and task-spec artifacts to a per-run directory in the worktree. Subagents read these by absolute path rather than from inline prompt text. This keeps dispatch prompts small, eliminates paraphrase drift between dispatches (`@check` and `@simplify` see the same plan byte-for-byte), and gives Dispatch Hygiene's Finalized-Text Rule a physical anchor — the file *is* the final version.
+
+**Directory layout** (relative to `$WORKTREE_PATH`):
+
+```
+.workflow/
+└── run-<ISSUE-ID>/
+    ├── plan.md          # Phase 3 output — finalized
+    ├── task-1.md        # Phase 5 output — one file per task
+    ├── task-2.md
+    └── summary.md       # Phase 9 output (the run summary)
+```
+
+Define `RUN_DIR="$WORKTREE_PATH/.workflow/run-$ISSUE_ID"` once in Phase 1 and reference it everywhere downstream. Create the directory in Phase 3 (`mkdir -p "$RUN_DIR"`).
+
+**Authoring rules:**
+- Files are written by the orchestrator, never by subagents.
+- Files are passed to subagents as absolute paths: e.g. *"the plan is at `<RUN_DIR>/plan.md`; read it before responding."* The dispatch prompt body should be short — agent role, artifact path, per-dispatch context (worktree path, branch, base branch). **Do not quote artifact contents inline.**
+- Mid-loop revisions (Phase 4 review cycle, Phase 5 task respec, etc.) edit the file in place; every subsequent dispatch reads the new version automatically.
+
+**Lifecycle:**
+- Files persist across phases until the run finishes.
+- Files are **not committed** (same as `summary.md`). Recommend `.workflow/` in `.gitignore`.
+- Multiple runs on the same issue overwrite the prior run's artifacts. Save anything you want to keep before re-running.
 
 ---
 
 ## Phase 1: Sanity Check
 
 1. Verify CWD is a non-bare git worktree: `git rev-parse --is-bare-repository 2>/dev/null` must output `false`. If not, stop: "Workflow must be run from a non-bare worktree (the directory opencode was launched in)."
-2. Verify the TODO tracker exists:
+2. Capture the worktree path: `WORKTREE_PATH="$(pwd)"`.
+3. Verify the TODO tracker exists:
    - `./TODO/` directory must exist. If not, stop: "TODO/ directory not found in the current worktree. Commit a TODO/ folder with one file per issue plus a README.md index."
    - `./TODO/README.md` must exist. If not, stop: "TODO/README.md not found. Add the category index file before running the workflow."
-   - `./TODO/<ARGUMENTS-first-token>.md` must exist. If not, stop: "Issue file `./TODO/<ID>.md` not found for ID parsed from `$ARGUMENTS`."
-3. Verify HEAD is not detached: `git symbolic-ref --short HEAD` must succeed. If it fails, stop: "Cannot run on a detached HEAD. Check out a feature branch first."
-4. Capture the current branch: `BRANCH_NAME="$(git symbolic-ref --short HEAD)"`.
-5. Resolve the base branch (`BASE_BRANCH`):
+   - `./TODO/$ISSUE_ID.md` must exist. If not, stop: "Issue file `./TODO/<ID>.md` not found for ID parsed from `$ARGUMENTS`."
+4. Verify HEAD is not detached: `git symbolic-ref --short HEAD` must succeed. If it fails, stop: "Cannot run on a detached HEAD. Check out a feature branch first."
+5. Capture the current branch: `BRANCH_NAME="$(git symbolic-ref --short HEAD)"`.
+6. Resolve the base branch (`BASE_BRANCH`):
    - If `$ARGUMENTS` provided a second token, use it.
    - Else if `git rev-parse --verify --quiet main` succeeds, use `main`.
    - Else if `git rev-parse --verify --quiet master` succeeds, use `master`.
    - Else stop: "Could not determine base branch (no `main` or `master`). Pass it as the second argument: `/workflow <ISSUE-ID> <base-branch>`."
-6. Verify the current branch is not the base branch: if `BRANCH_NAME == BASE_BRANCH`, stop: "Cannot run workflow on the base branch (`$BASE_BRANCH`). Switch to a feature branch first."
+7. Verify the current branch is not the base branch: if `BRANCH_NAME == BASE_BRANCH`, stop: "Cannot run workflow on the base branch (`$BASE_BRANCH`). Switch to a feature branch first."
+8. Set the run-artifacts directory: `RUN_DIR="$WORKTREE_PATH/.workflow/run-$ISSUE_ID"`. Phase 3 will `mkdir -p "$RUN_DIR"` before writing the first artifact.
 
 ---
 
@@ -52,7 +83,7 @@ If the issue's status is `Todo`, ask `@pm` to set it to `In Progress` and propag
 
 ## Phase 3: Plan
 
-Analyze the codebase. Create a detailed implementation plan addressing the issue's requirements and acceptance criteria.
+Analyze the codebase. Create a detailed implementation plan addressing the issue's requirements and acceptance criteria, then write it to `$RUN_DIR/plan.md` (run `mkdir -p "$RUN_DIR"` first if the directory doesn't exist). All Phase 4 reviewer dispatches read this file.
 
 The plan should include:
 - Problem summary (from issue context)
@@ -70,7 +101,7 @@ The plan should include:
   **Skip Test Design for:** Config-only changes, decorator swaps, import reorganization, documentation.
   When skipped, `@test` derives test cases directly from acceptance criteria.
 
-After drafting, apply **Dispatch Hygiene** (below) to the plan — it is a dispatch artifact and gets sent to `@check`/`@simplify` in Phase 4.
+Before saving `plan.md`, apply **Dispatch Hygiene** (below). The file on disk is what reviewers will read in Phase 4 — there is no second chance to revise during dispatch.
 
 ---
 
@@ -135,7 +166,7 @@ If any check trips, **do not dispatch.** Fix and re-validate. Repeated trips on
 
 ## Phase 4: Review Plan
 
-Apply **Dispatch Hygiene** to the plan and to each reviewer prompt before sending. Dispatch `@check` and `@simplify` in parallel to review the plan.
+Dispatch `@check` and `@simplify` in parallel to review `$RUN_DIR/plan.md`. The dispatch prompt is short — agent role, the absolute path to the plan, the worktree path, and any per-dispatch reviewer focus. Tell each reviewer to read the plan from disk; do **not** paste the plan inline. Apply **Dispatch Hygiene** to each dispatch prompt.
 
 Reviewers should evaluate testability:
 - `@check`: Is the design testable? Are the right behaviors identified? (Review Framework §8)
@@ -147,10 +178,10 @@ Reviewers should evaluate testability:
 - Note conflicts explicitly
 
 **Review loop (max 3 cycles):**
-1. Send plan to both reviewers
+1. Dispatch both reviewers against `$RUN_DIR/plan.md`.
 2. Merge findings
 3. If verdict is ACCEPTABLE from both (or JUSTIFIED COMPLEXITY from `@simplify`): proceed to Phase 5
-4. If BLOCK or NEEDS WORK: revise the plan addressing findings, then re-review
+4. If BLOCK or NEEDS WORK: edit `$RUN_DIR/plan.md` in place addressing findings (re-apply Dispatch Hygiene to the updated file), then re-review.
 5. **Convergence detection:** if reviewers return the same findings as the previous cycle, stop the loop early
 6. If still unresolved after 3 cycles: note unresolved blockers and proceed anyway (they will be documented in the workflow summary and commit message)
 
@@ -158,7 +189,9 @@ Reviewers should evaluate testability:
 
 ## Phase 5: Split into Tasks
 
-Break the approved plan into discrete tasks for `@make`. Each task needs:
+Break the approved plan into discrete tasks. **Write each task to `$RUN_DIR/task-<N>.md`** (1-indexed: `task-1.md`, `task-2.md`, …). Phase 6 (`@test`) and Phase 7 (`@make`) read these files by absolute path.
+
+Each task file must contain:
 
 | Required | Description |
 |----------|-------------|
@@ -226,10 +259,13 @@ Apply **Dispatch Hygiene** to each task spec before dispatch in Phase 7.
 
 Apply **Dispatch Hygiene** to each `@test` prompt before sending.
 
-For each task from Phase 5, dispatch `@test` with:
-- The task spec (acceptance criteria, code context, files to modify)
-- The Test Design section from the plan (if provided)
-- The test file path to create (following colocated pattern)
+For each task from Phase 5, dispatch `@test` with a short prompt that names:
+- The absolute path to the task spec: `$RUN_DIR/task-<N>.md` — `@test` reads acceptance criteria, code context, and files-to-modify from there.
+- The absolute path to the plan, if test design context is needed: `$RUN_DIR/plan.md`.
+- The worktree path (so `@test` resolves source files correctly).
+- The test file path to create.
+
+Do **not** quote task or plan content inline — `@test` reads from disk.
 
 `@test` writes failing tests and verifies RED with structured failure codes.
 
@@ -255,11 +291,11 @@ To get a clean runtime RED, dispatch a **stub-first `@make` pass** *before* `@te
 
 **Stub pass (split from Phase 7's body pass):**
 
-1. Dispatch `@make` in **standard mode** (no tests exist yet) with this exact scope:
+1. Dispatch `@make` in **standard mode** (no tests exist yet). The dispatch prompt names `$RUN_DIR/task-<N>.md` as the source spec and adds this stub-pass-specific scope inline:
    - **Goal:** add the planned API as `todo!()`-bodied stubs so the test will compile.
    - **Files to modify:** the relevant `src/<module>.rs` for module tests, or `src/lib.rs` plus any new `src/<module>.rs` for integration tests (the latter need `pub mod …;` declarations so the test crate can import).
    - **Stubs only:** every function body is exactly `todo!()`. Every method body is exactly `todo!()`. Structs may use `pub struct Foo;` or `pub struct Foo { /* fields TBD */ }` — but no logic.
-   - **Signatures must match the planned final API exactly** (return types, lifetimes, generics, visibility). Lift signatures from the Phase 3 plan / Phase 5 task spec.
+   - **Signatures must match the planned final API exactly** (return types, lifetimes, generics, visibility). Lift signatures from the task spec.
    - **Acceptance criteria:** `cargo check` (wrapped in `nix develop -c …` if the project has a devshell) passes; no test command is run.
    - **Dispatch Hygiene still applies:** the stub pass is small and finalized — no draft bodies, no contradictory signatures.
 2. Verify `cargo check` passed in `@make`'s output. If not, fix and re-dispatch the stub pass before continuing.
@@ -293,10 +329,12 @@ Apply **Dispatch Hygiene** to each `@make` spec before sending. Repeated trips o
 
 This applies to **all** `@make` invocations: standard mode, TDD mode, stub-pass, body-pass, and integration-fix dispatches.
 
-Execute each task by dispatching `@make` with:
-- The task spec (from Phase 5, finalized per Dispatch Hygiene)
-- Relevant code context (seam-revealing snippets only — see Phase 5 "Code Context — what to include")
-- **Pre-written failing tests and handoff from `@test` (if TESTS_READY)**
+Execute each task by dispatching `@make` with a short prompt:
+- The absolute path to the task spec: `$RUN_DIR/task-<N>.md` — `@make` reads acceptance criteria, code context, and files-to-modify from there.
+- The worktree path.
+- **Pre-written failing tests and handoff from `@test` (if TESTS_READY)** — these are short and per-dispatch, so include them inline in the prompt.
+
+Do **not** quote the task spec inline.
 
 `@make` runs in TDD mode when tests are provided:
 1. Entry validation: run tests, verify RED, check failure codes match handoff
@@ -326,9 +364,9 @@ After all tasks complete, verify overall integration:
 Apply **Dispatch Hygiene** to each reviewer prompt before sending. Dispatch `@check` and `@simplify` in parallel to review the full implementation (all changes across all files).
 
 Provide reviewers with:
-- The original plan
+- The absolute path to `$RUN_DIR/plan.md` (the same file Phase 4 reviewed; mid-loop revisions will have updated it in place)
 - The full diff (`git diff "$BASE_BRANCH"...HEAD`)
-- Any decisions or deviations from the plan
+- Any decisions or deviations from the plan, captured inline in the dispatch prompt
 
 **Review loop (max 3 cycles):**
 1. Send implementation to both reviewers
@@ -348,7 +386,7 @@ Provide reviewers with:
 The workflow is forge-agnostic. It commits locally and stops. **Do not push, and do not open a pull/merge request** — the user chooses their forge and review workflow manually.
 
 ### Commit Code Changes
-- Stage code changes only. **Do not stage anything under `TODO/`** (committed separately below) and **do not stage `.opencode/workflow-summary.md`** (intentionally never committed — see Local Summary).
+- Stage code changes only. **Do not stage anything under `TODO/`** (committed separately below) and **do not stage anything under `.workflow/`** (intentionally never committed — these are per-run artifacts).
 - Write a conventional commit message summarizing the implementation. Reference the TODO issue ID in the body (e.g. `Refs: GAL-39`).
 - If changes are large/varied, use multiple atomic commits (one per logical unit)
 
@@ -360,8 +398,8 @@ The workflow is forge-agnostic. It commits locally and stops. **Do not push, and
 - If acceptance-criteria checkboxes were addressed by the implementation, ask `@pm` to check them off (flip `- [ ]` to `- [x]` under `## Acceptance criteria`).
 - Commit the TODO/ changes as a separate atomic commit: `chore(todo): update <issue-id> status and progress`. Stage the issue file plus any propagated index file (README.md or parent file).
 
-### Local Summary
-- Write `.opencode/workflow-summary.md` in the worktree with:
+### Run Summary
+- Write `$RUN_DIR/summary.md` with:
   - **Run timestamp** — capture it from the shell at write time: `date -Iseconds` (e.g. `2026-05-07T11:24:13+02:00`). **Do not** use a placeholder like `???:???:??` or "session date" — if you cannot get a real timestamp, omit the field entirely rather than fabricating one.
   - Issue reference and title
   - Branch name and final commit SHA(s)
@@ -370,15 +408,15 @@ The workflow is forge-agnostic. It commits locally and stops. **Do not push, and
   - Review outcomes (plan review + final review verdicts)
   - Unresolved items (if any)
   - Files changed
-- **Do not commit this file.** It is a per-run, per-branch artifact; committing it would create merge conflicts whenever multiple workflow branches are merged. Leave it untracked. Recommend the user add `.opencode/` to `.gitignore` if not already.
+- **Do not commit anything under `.workflow/`.** The whole directory is per-run, per-branch state. Recommend the user add `.workflow/` to `.gitignore` if not already.
 
 ---
 
 ## Failure Handling
 
 At any phase, if an unrecoverable error occurs:
-1. Write `.opencode/workflow-summary.md` with what was completed and what failed. Do **not** stage or commit this file.
-2. If any code was written, commit it with message `wip: incomplete workflow run for <issue-id>`. Stage code only — exclude `.opencode/workflow-summary.md`.
+1. Write `$RUN_DIR/summary.md` (creating `$RUN_DIR` first if it doesn't exist) with what was completed and what failed. Do **not** stage or commit anything under `.workflow/`.
+2. If any code was written, commit it with message `wip: incomplete workflow run for <issue-id>`. Stage code only — exclude `.workflow/` and `TODO/`.
 3. Leave the branch and worktree intact for the user to inspect — do not push, do not delete.
 4. Dispatch `@pm` against `./TODO/` (live filesystem mode) to add a comment on the issue file (`./TODO/<ID>.md`) summarising what failed.
 5. Stop execution.

From 236b4d24700863de6c9e26bc5ce9e6f1aec45172 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Thu, 7 May 2026 19:04:08 +0200
Subject: [PATCH 086/101] fix(opencode): teach orchestrator about subagents and
 enforce on-disk artifacts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two related orchestration failures from recent runs:

1. An orchestrator missed the multi-agent concept entirely and produced
   reviews / implementations itself instead of dispatching @check / @make.
   The workflow described phases as "Dispatch @<name>" everywhere but
   never explained who the cast was, what "dispatch" meant, or that the
   orchestrator (agent: build) is distinct from the subagents.
2. Another orchestrator dispatched @test pointing at a $RUN_DIR/task-N.md
   that it never wrote — the file-write instruction in Phase 5 was a
   single bolded sentence inside a paragraph, easy to skim past, and
   nothing checked artifact existence before dispatching.

Adds a top-level "Roles & Dispatch" section between the parse line and
Run Artifacts. It establishes the multi-agent model, lists the cast
(@check / @simplify / @test / @make / @pm) with one-line role and
permission notes, defines "Dispatch" as a tool call (not a role-play
instruction), and lists three anti-patterns the orchestrator must
avoid (acting as a subagent, skipping a dispatch, paraphrasing
artifacts instead of letting subagents read them from disk).

Restructures Phase 5 as five explicit numbered steps. Step 4 mandates
writing each task to $RUN_DIR/task-<N>.md and verifying with test -f;
step 5 requires dropping inline copies once the file is the source of
truth. The phase is "not done" until every task file exists on disk.

Adds a row to Dispatch Hygiene's Pre-Dispatch Validation table that
requires test -f verification of any artifact path the dispatch
references; missing files route back to the producing phase.
---
 config/opencode/commands/workflow.md | 34 +++++++++++++++++++++++++++-
 1 file changed, 33 insertions(+), 1 deletion(-)

diff --git a/config/opencode/commands/workflow.md b/config/opencode/commands/workflow.md
index 464b02d..6ff6087 100644
--- a/config/opencode/commands/workflow.md
+++ b/config/opencode/commands/workflow.md
@@ -18,6 +18,29 @@ Parse `$ARGUMENTS`: the first whitespace-separated token is the issue ID, an opt
 
 ---
 
+## Roles & Dispatch
+
+This is a **multi-agent** workflow. There is one orchestrator (you, running in `agent: build` mode per this file's frontmatter) and a cast of specialised subagents that the orchestrator dispatches at each phase. **The orchestrator coordinates; subagents do the work.** The orchestrator does not write production code, write tests, or play any subagent's role — it plans, dispatches, merges findings, edits its own artifacts under `.workflow/`, and commits.
+
+**The cast** (each defined as a separate agent file under `config/opencode/agents/<name>.md`):
+
+| Subagent | Role | Notable constraints |
+|---|---|---|
+| `@check` | Reviews plans and code for risks, correctness, testability. Returns `ACCEPTABLE` / `NEEDS WORK` / `BLOCK`. | Read-only — no write / edit / bash. |
+| `@simplify` | Reviews for unnecessary complexity. Advisory recommendations. | Read-only. |
+| `@test` | Writes failing tests for a task spec, verifies RED, hands off to `@make`. | May only modify test files / `#[cfg(test)] mod` blocks. Bash sandboxed to test runners. |
+| `@make` | Implements a single task spec. Verifies acceptance criteria. | May only modify files listed in the task spec. Bash sandboxed to language toolchains; no `git`, network, `cd`. |
+| `@pm` | Reads/updates `TODO/` issue files. | May only modify `TODO/` contents. Bash sandboxed to `git show` / `git ls-tree` / `ls`. |
+
+**What "Dispatch" means here.** Every "dispatch `@<name>`" in the phase descriptions is a call to opencode's subagent / task invocation tool with that agent name. Each dispatch starts a **fresh context**: the subagent has no memory of prior phases, no view of this orchestration, and no access beyond what its own file declares. The subagent receives only what the dispatch prompt provides — typically an absolute path to a file in `$RUN_DIR` plus a small per-dispatch context block.
+
+**Anti-patterns to avoid:**
+- Performing a subagent's work in the orchestrator's session ("I'll think like `@check` for a moment and produce the review myself"). Every `@<name>` reference is a tool call, not a role-play.
+- Skipping a dispatch because the orchestrator "could just do it." The agents enforce permission boundaries the orchestrator (in `agent: build` mode) does not have.
+- Paraphrasing a subagent's output into the next dispatch's prompt instead of letting the next subagent read the on-disk artifact directly.
+
+---
+
 ## Run Artifacts
 
 The orchestrator writes plan and task-spec artifacts to a per-run directory in the worktree. Subagents read these by absolute path rather than from inline prompt text. This keeps dispatch prompts small, eliminates paraphrase drift between dispatches (`@check` and `@simplify` see the same plan byte-for-byte), and gives Dispatch Hygiene's Finalized-Text Rule a physical anchor — the file *is* the final version.
@@ -159,6 +182,7 @@ Scan the artifact and reject (revise, retry) if any of the following are present
 | Code blocks longer than ~5 lines that draft the answer | Violates No-Implementation-in-Plan-or-Spec. Trim to structure (signature + "current state" only). |
 | Two versions of the same code, "actually let me correct…", or open questions | Violates the Finalized-Text Rule. Redo the artifact. |
 | Test bodies inside `@make` specs when tests are coming from `@test` | Duplicates the TDD handoff. |
+| Artifact path referenced in the dispatch (e.g. `$RUN_DIR/plan.md`, `$RUN_DIR/task-<N>.md`) but the file isn't on disk | The subagent will fail to read it and either error or fabricate context. **Verify with `test -f "<path>"` before every dispatch.** If missing, go back to the phase that produces it (Phase 3 for `plan.md`, Phase 5 for `task-<N>.md`) and write the file before retrying. |
 
 If any check trips, **do not dispatch.** Fix and re-validate. Repeated trips on a single task signal a Phase 5 split problem — go back and split.
 
@@ -189,7 +213,15 @@ Reviewers should evaluate testability:
 
 ## Phase 5: Split into Tasks
 
-Break the approved plan into discrete tasks. **Write each task to `$RUN_DIR/task-<N>.md`** (1-indexed: `task-1.md`, `task-2.md`, …). Phase 6 (`@test`) and Phase 7 (`@make`) read these files by absolute path.
+**The output of this phase is one file per task at `$RUN_DIR/task-<N>.md`** (1-indexed: `task-1.md`, `task-2.md`, …). These files are the source-of-truth that Phase 6 (`@test`) and Phase 7 (`@make`) read by absolute path. **No file written = no dispatch in later phases.** If you skip the file-write step, every downstream dispatch will reference a non-existent path and fail.
+
+Steps:
+
+1. Break the approved plan into discrete tasks (see Split Heuristic and task-size guidance below).
+2. For each task, draft the task spec covering the fields in the table below.
+3. Apply **Dispatch Hygiene** (above) to each draft.
+4. **Write each finalized spec to `$RUN_DIR/task-<N>.md`.** After writing, verify with `test -f "$RUN_DIR/task-<N>.md"` for every N. Phase 5 is not done until every task file exists on disk.
+5. Drop your inline copies of the task drafts. From this phase onward, the file is the only source of truth — if you need a task spec later, read it back from disk.
 
 Each task file must contain:
 

From cc971b80e057af055f095c6d87beb8fea108d292 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Thu, 7 May 2026 19:06:37 +0200
Subject: [PATCH 087/101] feat(opencode): add Phase 5.5 task-split review by
 @check
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ppries' README mentioned "@check reviews task split for completeness
and coverage" as a workflow step but the gist's actual workflow.md
never implemented it, and neither did ours. Without a split-review
gate between Phase 5 and Phase 6, an over- or under-split task
surfaces only at Phase 8 final review — after expensive @test and
@make dispatches have already run on a broken split.

Adds Phase 5.5: a short, focused review of the task split as a set,
dispatched only to @check (split is structural / coverage, not
complexity, so @simplify is not involved). The dispatch passes the
absolute paths to plan.md and every task-N.md and asks @check to
evaluate the split against five questions: coverage, no overlap,
single-purpose, integration contracts, testable AC.

Loop limited to 2 cycles (less than the plan-review's 3), with a
BLOCK verdict routing back to Phase 4 when the plan itself does not
decompose cleanly. The phase is explicitly framed as "a quick gate,
not a deep review" — no line-by-line code feedback (there's no code
yet), no design re-litigation (that was Phase 4) — to keep it from
expanding into a second plan review.

No phase renumbering downstream — 5.5 fits between 5 and 6 without
disturbing existing cross-references.
---
 config/opencode/commands/workflow.md | 31 ++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/config/opencode/commands/workflow.md b/config/opencode/commands/workflow.md
index 6ff6087..92f4b4c 100644
--- a/config/opencode/commands/workflow.md
+++ b/config/opencode/commands/workflow.md
@@ -287,6 +287,37 @@ Apply **Dispatch Hygiene** to each task spec before dispatch in Phase 7.
 
 ---
 
+## Phase 5.5: Review Task Split
+
+A short, focused review of the task split as a set. Catches split errors (missed scope, overlap, multi-purpose tasks, missing integration contracts) when they're cheap to fix — *before* `@test` and `@make` dispatch on a broken split. Without this gate, the same errors surface only at Phase 8 final review, after expensive test/implementation work has already been done.
+
+**Dispatch only `@check`** for this phase — split review is structural / coverage, not complexity. `@simplify` is not involved. Apply **Dispatch Hygiene** to the prompt.
+
+The dispatch prompt names:
+- `$RUN_DIR/plan.md` (the plan being decomposed)
+- `$RUN_DIR/task-1.md` through `$RUN_DIR/task-N.md` (the split — list every task file)
+- The worktree path
+
+`@check` evaluates the split against five questions:
+
+1. **Coverage** — do the tasks together implement everything the plan promises? Any gaps?
+2. **No overlap** — do two tasks claim the same scope or modify the same lines?
+3. **Single-purpose** — does any task do more than one thing? (See Phase 5's Split Heuristic.)
+4. **Integration contracts** — where two tasks touch a shared interface, is the contract documented in both task files?
+5. **Testable acceptance criteria** — does every task have specific, falsifiable AC?
+
+**Review loop (max 2 cycles):**
+
+1. Dispatch `@check` against the plan + all task files.
+2. If `ACCEPTABLE` → proceed to Phase 6.
+3. If `NEEDS WORK` → edit the task files in place (split a task into two, merge two tasks, add integration contracts, sharpen AC). Re-apply Dispatch Hygiene to each updated file. Re-dispatch.
+4. If `BLOCK` → the plan itself does not decompose cleanly. Return to Phase 4 with `@check`'s finding instead of forcing the split.
+5. **Convergence detection:** same finding twice → stop loop, document the unresolved split issue in the run summary, proceed.
+
+**This is a quick gate, not a deep review.** No line-by-line code feedback (there's no code), no design re-litigation (that was Phase 4's job). The whole point is a fast structural check before downstream phases start churning.
+
+---
+
 ## Phase 6: Write Tests
 
 Apply **Dispatch Hygiene** to each `@test` prompt before sending.

From c3407c9c98b6650e5af870edb564c7714ed327f2 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Thu, 7 May 2026 21:44:19 +0200
Subject: [PATCH 088/101] refactor(opencode): drop @pm git-ref read mode, no
 longer used by workflow
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

@pm originally had two read modes — git-ref (via `git show <ref>:TODO.md`)
and filesystem. Git-ref existed because the workflow once ran in a bare
repo with no working tree. Once the workflow was simplified to assume
opencode is launched in the worktree, every dispatch (Phase 2 read,
Phase 9 update, Failure handler) uses filesystem mode. Git-ref mode
became dead weight: it added bash permissions, an allowlist, a "Bash
Discipline" section, and a dual-mode "How to Read" section, but the
workflow never invoked it. A reviewer correctly flagged the resulting
inconsistency between the two-mode docs and the single-mode usage.

@pm is now single-mode. Bash access is removed (bash: false, no
permission allowlist). The "How to Read" section collapses to "you
operate on TODO/ via the filesystem only" with one explicit pointer
that ad-hoc historical reads (`git show main:TODO/GAL-39.md`) are
out of scope — the user can run that themselves.

The workflow drops the now-redundant "(live filesystem mode)"
qualifier from Phase 2 / Phase 9 / Failure handler dispatches and
the Roles & Dispatch table updates @pm's constraint to "No bash."
---
 config/opencode/agents/pm.md         | 28 +++++++---------------------
 config/opencode/commands/workflow.md |  8 ++++----
 2 files changed, 11 insertions(+), 25 deletions(-)

diff --git a/config/opencode/agents/pm.md b/config/opencode/agents/pm.md
index d0c104b..b2e84e3 100644
--- a/config/opencode/agents/pm.md
+++ b/config/opencode/agents/pm.md
@@ -7,14 +7,7 @@ tools:
   grep: true
   write: true
   edit: true
-  bash: true
-permission:
-  bash:
-    "*": deny
-    "git show *": allow
-    "git rev-parse *": allow
-    "git ls-tree *": allow
-    "ls *": allow
+  bash: false
 ---
 
 You are a project management assistant. Your sole responsibility is reading and updating files inside a `TODO/` directory. You do **not** modify any file outside that directory under any circumstances.
@@ -34,24 +27,17 @@ TODO/
 - Each issue lives in `TODO/<ID>.md`. IDs are short, stable, and uppercase (e.g. `GAL-1`, `ABC-42`).
 - `TODO/README.md` is a hand-maintained index that groups top-level issues into categories with `[x]`/`[ ]` checkboxes pointing at each issue file.
 
-## How to Read TODO Files
+## How to Read and Write TODO Files
 
-There are two ways, depending on what the caller tells you:
+You operate on the `TODO/` directory through the filesystem only. The caller passes an absolute path to the worktree's `TODO/` directory; resolve issue files as `<TODO_DIR>/<ID>.md`. Use the `read` / `glob` / `grep` tools to inspect, and `write` / `edit` to update.
 
-1. **From a git ref** (no working tree, e.g. inside a bare repo) — run `git show <ref>:TODO/<ID>.md` and parse stdout. List the directory with `git ls-tree --name-only <ref> TODO/`. This mode is **read-only**: never attempt updates. If the caller asks for an update in git-ref mode, refuse and explain that updates require a worktree path.
-2. **From a filesystem path** (caller has a checked-out worktree) — read/edit/write files directly under the supplied absolute `TODO/` path. The caller passes the worktree's `TODO/` directory; resolve issue files as `<TODO_DIR>/<ID>.md`.
-
-The caller indicates the mode in the prompt. When the mode is ambiguous, default to read-only git-ref mode and ask.
-
-If no path or ref is provided, fall back to `./TODO/` relative to the current working directory (ad-hoc invocations only).
+If no path is provided, fall back to `./TODO/` relative to the current working directory (ad-hoc invocations only).
 
 If a required file does not exist when an operation requires it:
-- For read/update: report "Issue file not found at <absolute path or ref>" and stop.
+- For read/update: report "Issue file not found at `<absolute path>`" and stop.
 - For create: see the create rules below.
 
-## Bash Discipline
-
-The only bash commands you may run are `git show <ref>:TODO/<ID>.md`, `git ls-tree …`, `git rev-parse …`, and `ls <TODO_DIR>` (for listing). The permission sandbox enforces this.
+You do **not** have bash access. Historical reads from a git ref (e.g. "what did `GAL-39` look like on `main` last week?") are out of scope — the user can run `git show main:TODO/GAL-39.md` themselves; that's not something this agent needs to wrap.
 
 ## Issue File Schema (`TODO/<ID>.md`)
 
@@ -140,7 +126,7 @@ You cannot:
 - Delete issues. If asked, leave the file in place and report — the new schema has no `Cancelled` state, so deletion would lose history.
 - Modify any file outside `TODO/`.
 - Modify `TODO/README.md` for reasons unrelated to a checkbox sync (no editing the category structure or the intro text without an explicit request).
-- Run shell commands beyond the bash allowlist.
+- Run shell commands. You have no bash access.
 
 ## Output Format
 
diff --git a/config/opencode/commands/workflow.md b/config/opencode/commands/workflow.md
index 92f4b4c..4756f66 100644
--- a/config/opencode/commands/workflow.md
+++ b/config/opencode/commands/workflow.md
@@ -30,7 +30,7 @@ This is a **multi-agent** workflow. There is one orchestrator (you, running in `
 | `@simplify` | Reviews for unnecessary complexity. Advisory recommendations. | Read-only. |
 | `@test` | Writes failing tests for a task spec, verifies RED, hands off to `@make`. | May only modify test files / `#[cfg(test)] mod` blocks. Bash sandboxed to test runners. |
 | `@make` | Implements a single task spec. Verifies acceptance criteria. | May only modify files listed in the task spec. Bash sandboxed to language toolchains; no `git`, network, `cd`. |
-| `@pm` | Reads/updates `TODO/` issue files. | May only modify `TODO/` contents. Bash sandboxed to `git show` / `git ls-tree` / `ls`. |
+| `@pm` | Reads/updates `TODO/` issue files. | May only modify `TODO/` contents. No bash. |
 
 **What "Dispatch" means here.** Every "dispatch `@<name>`" in the phase descriptions is a call to opencode's subagent / task invocation tool with that agent name. Each dispatch starts a **fresh context**: the subagent has no memory of prior phases, no view of this orchestration, and no access beyond what its own file declares. The subagent receives only what the dispatch prompt provides — typically an absolute path to a file in `$RUN_DIR` plus a small per-dispatch context block.
 
@@ -92,7 +92,7 @@ Define `RUN_DIR="$WORKTREE_PATH/.workflow/run-$ISSUE_ID"` once in Phase 1 and re
 
 ## Phase 2: Issue Context
 
-Dispatch `@pm` against `./TODO/` (live filesystem mode; pass the absolute `TODO/` directory path) and fetch the issue at `./TODO/<ID>.md`:
+Dispatch `@pm` against `./TODO/` (pass the absolute `TODO/` directory path) and fetch the issue at `./TODO/<ID>.md`:
 - Title, description, acceptance criteria (if section present)
 - Labels and parent
 - Sub-issues list (if the issue is a parent)
@@ -454,7 +454,7 @@ The workflow is forge-agnostic. It commits locally and stops. **Do not push, and
 - If changes are large/varied, use multiple atomic commits (one per logical unit)
 
 ### TODO Update
-- Dispatch `@pm` against the absolute `./TODO/` path (live filesystem mode). Ask it to:
+- Dispatch `@pm` against the absolute `./TODO/` path. Ask it to:
   - Set the issue file's frontmatter `status` to `Done` (or leave at `In Progress` if the run is incomplete and the user must verify before marking Done).
   - Add a comment of the form: `- YYYY-MM-DD — Branch \`$BRANCH_NAME\`, commit <SHA> — <one-line summary>` (date from the shell, never fabricated).
   - Propagate any status flip to the dependent index: `TODO/README.md` for top-level issues (`parent: null`), or the parent file's `## Sub-issues` line for sub-issues.
@@ -481,7 +481,7 @@ At any phase, if an unrecoverable error occurs:
 1. Write `$RUN_DIR/summary.md` (creating `$RUN_DIR` first if it doesn't exist) with what was completed and what failed. Do **not** stage or commit anything under `.workflow/`.
 2. If any code was written, commit it with message `wip: incomplete workflow run for <issue-id>`. Stage code only — exclude `.workflow/` and `TODO/`.
 3. Leave the branch and worktree intact for the user to inspect — do not push, do not delete.
-4. Dispatch `@pm` against `./TODO/` (live filesystem mode) to add a comment on the issue file (`./TODO/<ID>.md`) summarising what failed.
+4. Dispatch `@pm` against `./TODO/` to add a comment on the issue file (`./TODO/<ID>.md`) summarising what failed.
 5. Stop execution.
 
 **Never hang on interactive prompts.** If any command appears to require input, treat it as a failure and follow the above procedure.

From aac4d44a49a90687671a3eb4084ed94697c43db3 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Fri, 8 May 2026 06:29:46 +0200
Subject: [PATCH 089/101] feat(opencode): file unresolved bugs/blockers as TODO
 sub-issues in Phase 9
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A workflow run wrapped up with "Unresolved: Score not resetting on game
restart (pre-existing bug, out of scope)" — a real bug discovered while
implementing GAL-39. Buried in summary.md, which is per-run, untracked,
overwritten on the next run, and read by nobody (the user has walked
away by design).

Adds a File Follow-ups subsection to Phase 9, after the TODO Update.
Tracked-worthy items are routed through @pm as sub-issues of the
current issue (parent: $ISSUE_ID), so they auto-show in the parent's
Sub-issues list and don't need a README.md category at unattended
runtime. Three categories file an issue:

- Pre-existing bugs found out of scope → label `bug`
- Unresolved review-loop blockers (Phase 4 or 8 cycle exhaustion)
  → label `followup`
- @test NOT_TESTABLE "future seam" notes → label `tech-debt`

Things explicitly NOT filed: @simplify advisories the orchestrator
chose not to act on (records, not missing work), cosmetic nits,
duplicates of existing issues. Those live in the run summary's new
"Advisory notes (not filed)" section.

Renames "Commit TODO Changes" subsection so the worked issue update
plus any filed follow-ups commit together as one atomic chore(todo)
commit. The Run Summary's old "Unresolved items" bullet is replaced
with two sharper bullets: "Filed follow-ups" (lists IDs of created
sub-issues) and "Advisory notes (not filed)".
---
 config/opencode/commands/workflow.md | 33 +++++++++++++++++++++++++---
 1 file changed, 30 insertions(+), 3 deletions(-)

diff --git a/config/opencode/commands/workflow.md b/config/opencode/commands/workflow.md
index 4756f66..34ca336 100644
--- a/config/opencode/commands/workflow.md
+++ b/config/opencode/commands/workflow.md
@@ -459,17 +459,44 @@ The workflow is forge-agnostic. It commits locally and stops. **Do not push, and
   - Add a comment of the form: `- YYYY-MM-DD — Branch \`$BRANCH_NAME\`, commit <SHA> — <one-line summary>` (date from the shell, never fabricated).
   - Propagate any status flip to the dependent index: `TODO/README.md` for top-level issues (`parent: null`), or the parent file's `## Sub-issues` line for sub-issues.
 - If acceptance-criteria checkboxes were addressed by the implementation, ask `@pm` to check them off (flip `- [ ]` to `- [x]` under `## Acceptance criteria`).
-- Commit the TODO/ changes as a separate atomic commit: `chore(todo): update <issue-id> status and progress`. Stage the issue file plus any propagated index file (README.md or parent file).
+
+### File Follow-ups
+
+Tracked-worthy unresolved items must become real TODO issues; otherwise they vanish into the per-run `summary.md` and the user (who has walked away) never sees them. Before writing the summary, scan the run for items in these categories and dispatch `@pm` to file each as a **sub-issue of the current issue** (`parent: $ISSUE_ID`).
+
+| Source | New issue label | Title style |
+|---|---|---|
+| Pre-existing bug discovered while working but out of scope (e.g. "Score not resetting on game restart" found during GAL-39) | `bug` | Imperative fix description ("Reset score on game restart") |
+| Unresolved blocker after a review loop exhausted its cycle limit (Phase 4 plan review or Phase 8 final review) | `followup` | Reference the `@check` finding |
+| `@test` `NOT_TESTABLE` "future seam" notes that imply a real test gap | `tech-debt` | Describe the missing seam |
+
+**Do NOT file follow-ups for:**
+- `@simplify` advisory recommendations the orchestrator chose not to act on — these are records, not missing work; they belong in the run summary.
+- Cosmetic / formatting / naming nits.
+- Anything already covered by an existing TODO issue (`@pm` lists existing issues; check the title/description before filing a duplicate).
+
+**Routing rules:**
+- Each new issue is a sub-issue (`parent: $ISSUE_ID`). `@pm` will add it to the parent's `## Sub-issues` list automatically. The user can promote it to top-level later if it deserves its own slot.
+- Issue body must include a "Discovered during" paragraph naming the run's branch and (where relevant) commit SHA, plus enough context for the user to triage it later without having to re-read the run.
+- Status: `Todo`. Default labels per the table; the orchestrator may add additional labels inferred from the parent (e.g. propagate `gameplay` from GAL-39 to a gameplay-relevant follow-up).
+- The Run Summary (next subsection) lists each filed follow-up by ID so the user has one place to see them.
+
+### Commit TODO Changes
+
+After both the TODO Update and File Follow-ups steps, commit everything under `TODO/` in a single atomic commit: `chore(todo): update <issue-id> status, file follow-ups`. Stage the worked issue file, the dependent index (README.md or parent file), and any newly created follow-up issue files.
+
+If no follow-ups were filed, the commit message simplifies to `chore(todo): update <issue-id> status and progress` and only the TODO Update changes are staged.
 
 ### Run Summary
 - Write `$RUN_DIR/summary.md` with:
-  - **Run timestamp** — capture it from the shell at write time: `date -Iseconds` (e.g. `2026-05-07T11:24:13+02:00`). **Do not** use a placeholder like `???:???:??` or "session date" — if you cannot get a real timestamp, omit the field entirely rather than fabricating one.
+  - **Run timestamp** — capture it from the shell at write time: `date -Iseconds` (e.g. `2026-05-08T11:24:13+02:00`). **Do not** use a placeholder like `???:???:??` or "session date" — if you cannot get a real timestamp, omit the field entirely rather than fabricating one.
   - Issue reference and title
   - Branch name and final commit SHA(s)
   - Summary of implementation
   - TDD evidence (RED→GREEN per task, NOT_TESTABLE justifications)
   - Review outcomes (plan review + final review verdicts)
-  - Unresolved items (if any)
+  - **Filed follow-ups** — list each new issue created in the File Follow-ups step by ID, title, and reason (`bug` / `followup` / `tech-debt`). If none, write "None."
+  - **Advisory notes (not filed)** — any `@simplify` or `@check` recommendations the orchestrator chose not to act on and did not turn into a TODO. These are records for the user to consider, not tracked work.
   - Files changed
 - **Do not commit anything under `.workflow/`.** The whole directory is per-run, per-branch state. Recommend the user add `.workflow/` to `.gitignore` if not already.
 

From 534361f1b516a989aa8d9f22fb05edc5147f0f94 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Fri, 8 May 2026 10:13:29 +0200
Subject: [PATCH 090/101] feat(opencode): extend Phase 7 escalation to
 mid-implementation test-design errors
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase 7's escalation rule was gated on @make flagging concerns "during
entry validation" only. When @make got past entry validation, started
implementing, and ground for 2-3 attempts because the test demanded
impossible production code, the orchestrator had no documented route
— it would re-dispatch @make with marginal context tweaks instead of
recognizing the failure as test-architecture.

Splits the escalation into two clearly-named paths (entry-validation
vs mid-implementation) that both route through @check (test diagnosis)
→ @test (redesign) → fresh @make. Bounded at max 2 escalation cycles
before reverting to a Phase 3 plan revisit, to prevent thrashing when
the actual problem is upstream.

@make.md gains a new Iteration Limits red-flag class — "Test-design
suspicion" — instructing @make to stop and report with an explicit
`escalate: test_design` flag in the Blocking Issue section. The flag
is the routing signal the orchestrator switches on.
---
 config/opencode/agents/make.md       |  3 ++-
 config/opencode/commands/workflow.md | 20 ++++++++++++++------
 2 files changed, 16 insertions(+), 7 deletions(-)

diff --git a/config/opencode/agents/make.md b/config/opencode/agents/make.md
index 67802fb..5193ef2 100644
--- a/config/opencode/agents/make.md
+++ b/config/opencode/agents/make.md
@@ -272,12 +272,13 @@ If tests fail or verification doesn't pass:
 2. **Context/spec issues** — Stop immediately and report; don't guess
 3. **Code issues** — Attempt fix (max 2-3 attempts if making progress)
 4. **Flaky/infra issues** — Stop and report with diagnostics
+5. **Test-design suspicion** — If after 1–2 attempts the test seems to demand production code that contradicts the spec, asserts on internal state that shouldn't be observable, mocks an internal boundary instead of the external one, or otherwise looks like it's testing the wrong thing — **stop and report with `escalate: test_design`** in the Blocking Issue section. Do not modify the test file yourself; the caller will route to `@check` for diagnosis and `@test` for redesign per the workflow's Phase 7 escalation.
 
 If still failing after 2-3 focused attempts, **stop and report**:
 - What was implemented
 - What's failing and why
 - What you tried
-- Suggested next steps
+- Suggested next steps (including `escalate: test_design` if the failure points at the test rather than the production code)
 
 Do not loop indefinitely. Better to report a clear failure than burn context.
 
diff --git a/config/opencode/commands/workflow.md b/config/opencode/commands/workflow.md
index 34ca336..c6304c1 100644
--- a/config/opencode/commands/workflow.md
+++ b/config/opencode/commands/workflow.md
@@ -406,12 +406,20 @@ Do **not** quote the task spec inline.
 4. Refactor while keeping green
 5. Report RED→GREEN evidence
 
-**Escalation:** If `@make` flags test quality concerns during entry validation:
-1. `@make` reports the issue to caller
-2. Caller routes to `@check` for diagnosis
-3. `@check` reports findings
-4. Caller routes to `@test` for fixes
-5. Fixed tests return to `@make`
+**Escalation — two paths route through `@check` → `@test` → back to `@make`:**
+
+1. **Entry-validation escalation.** Before implementing, `@make`'s entry check (run tests, verify RED, compare against handoff) reveals test-quality concerns — wrong assertion target, mixed failure codes, mocks of internal boundaries, etc. `@make` reports without writing any production code.
+2. **Mid-implementation escalation.** After implementing, `@make` hits its iteration limit (2–3 attempts) because the test demands production code that's impossible or contradicts the spec. `@make` returns `Implementation Incomplete` with the flag `escalate: test_design`. **Do not** re-dispatch `@make` with marginal context tweaks — that just burns cycles on a test that needs redesign, not better implementation.
+
+In both cases:
+
+1. `@make` returns its report (entry-time concern or mid-impl `escalate: test_design`).
+2. Orchestrator routes the report to `@check` for diagnosis (light review of the *tests*, not the implementation).
+3. `@check` confirms or rejects the test-design suspicion.
+4. **If confirmed:** orchestrator routes to `@test` to redesign the tests. Apply Dispatch Hygiene. Fixed tests return to `@make` for fresh entry validation and a clean implementation attempt.
+5. **If rejected:** the issue is in the production code; orchestrator re-dispatches `@make` with `@check`'s diagnostic notes attached.
+
+**Iteration limit on this loop: max 2 cycles.** If a test-design suspicion keeps surfacing but `@check` never confirms it, the design problem is upstream — revisit the Phase 3 plan rather than thrashing between `@test` and `@make`.
 
 For NOT_TESTABLE tasks, `@make` runs in standard mode.
 

From af0c1d6ea52b7dcac46279f0c5cc5e4daf89de7a Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Fri, 8 May 2026 10:13:44 +0200
Subject: [PATCH 091/101] docs(opencode): add workflow-design.md as design
 rationale + decision log
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Operational rules in commands/workflow.md and the agent files have
been accreting through repeated patches, with the rationale scattered
across commit messages and conversations. New gaps kept surfacing
after the fact (Phase 7 mid-impl escalation, Phase 8 routing for
test-design findings, Phase 5.5 entirely missing) because there was
no single place to audit the flow.

Adds config/opencode/workflow-design.md as a sibling to commands/
and agents/. It is the design rationale and decision log; operational
rules stay in the command and agent files. The intended flow is:
discuss new ideas / failure modes here → reach a decision → update
the operational files → record the decision in the ADR log.

Pre-populated with: cast & responsibilities table; three Mermaid
diagrams (phase pipeline, Phase 7 escalation state machine, issue
lifecycle); a routing matrix that lists every observed (phase,
signal) → action pair so gaps are visible at a glance; 12 ADRs
covering decisions made over the past several days (forge-agnostic,
TODO/ folder, worktree-only, polyglot agents, absolute-path dispatch,
run artifacts on disk, stub-first Rust TDD, @test inside cfg(test)
mod, Phase 5.5, single-mode @pm, file follow-ups, Phase 7 mid-impl
escalation); and 5 open questions teed up for future discussion.
---
 config/opencode/workflow-design.md | 278 +++++++++++++++++++++++++++++
 1 file changed, 278 insertions(+)
 create mode 100644 config/opencode/workflow-design.md

diff --git a/config/opencode/workflow-design.md b/config/opencode/workflow-design.md
new file mode 100644
index 0000000..4f0d41d
--- /dev/null
+++ b/config/opencode/workflow-design.md
@@ -0,0 +1,278 @@
+# Workflow Design
+
+## 1. Purpose
+
+This document is the **design rationale and decision log** for the multi-agent workflow. The operational rules — what the orchestrator does, in what order, with what guardrails — live in [`commands/workflow.md`](commands/workflow.md) and the agent files under [`agents/`](agents/). This document is where we discuss changes *before* they land in those files.
+
+**Intended flow:**
+
+1. A new idea, gap, or failure mode comes up (often from a real run).
+2. Discuss in this document — capture context, options, trade-offs.
+3. When a decision is reached, update `commands/workflow.md` and/or the relevant agent file.
+4. Record the decision in the [Design decisions log](#5-design-decisions-log) below.
+
+The operational files stay terse and procedural. The "why" lives here.
+
+---
+
+## 2. Cast & Responsibilities
+
+One orchestrator, five subagents. The orchestrator runs in `agent: build` mode; the subagents are defined as separate agent files under `config/opencode/agents/`.
+
+| Actor | File | Role | Boundary |
+|---|---|---|---|
+| **Orchestrator** | `commands/workflow.md` | Plans, dispatches, merges findings, edits artifacts under `.workflow/`, commits. | **Does not** write production code, write tests, or play any subagent's role. |
+| `@check` | `agents/check.md` | Reviews plans / task splits / code for risks, correctness, testability. | Read-only — no write / edit / bash. |
+| `@simplify` | `agents/simplify.md` | Reviews for unnecessary complexity. Advisory only. | Read-only. |
+| `@test` | `agents/test.md` | Writes failing tests for a task spec, verifies RED. | May modify test files / `#[cfg(test)] mod` blocks. Sandboxed bash. |
+| `@make` | `agents/make.md` | Implements a single task spec. Verifies acceptance criteria. | May modify files listed in the task spec. Sandboxed bash; no `git` / network / `cd`. |
+| `@pm` | `agents/pm.md` | Reads / updates `TODO/` issue files. | May modify only `TODO/` contents. No bash. |
+
+**Permission boundaries are enforced per agent.** The orchestrator (in `agent: build` mode) has full edit/bash capabilities, which is precisely why it must not act as the subagents — the agent files are where the limits live.
+
+---
+
+## 3. Flow Diagrams
+
+### 3.1 Phase pipeline
+
+High-level happy path with the major escalation arms.
+
+```mermaid
+flowchart TD
+    P1[Phase 1: Sanity Check]
+    P2[Phase 2: Issue Context<br/>@pm reads TODO/ID.md]
+    P3[Phase 3: Plan<br/>write plan.md]
+    P4{Phase 4: Review Plan<br/>@check + @simplify<br/>max 3 cycles}
+    P5[Phase 5: Split into Tasks<br/>write task-N.md]
+    P55{Phase 5.5: Review Split<br/>@check<br/>max 2 cycles}
+    P6[Phase 6: Write Tests<br/>@test ± stub-first @make]
+    P7[Phase 7: Implement<br/>@make]
+    P7E{Test-design escalation<br/>max 2 cycles}
+    P8{Phase 8: Final Review<br/>@check + @simplify<br/>max 3 cycles}
+    P9[Phase 9: Commit + TODO + Follow-ups + Summary]
+
+    P1 --> P2 --> P3 --> P4
+    P4 -->|ACCEPTABLE| P5 --> P55
+    P4 -->|NEEDS WORK / BLOCK| P3
+    P55 -->|ACCEPTABLE| P6 --> P7
+    P55 -->|NEEDS WORK| P5
+    P55 -->|BLOCK plan-level| P3
+    P7 --> P8
+    P7 -.->|escalate: test_design| P7E
+    P7E -->|@check → @test → @make| P7
+    P7E -.->|2 cycles exhausted| P3
+    P8 -->|ACCEPTABLE| P9
+    P8 -->|production-code finding| P7
+    P8 -->|test-design finding| P7E
+    P8 -->|plan-level finding| P3
+    P9 --> END([Done])
+```
+
+### 3.2 Phase 7 escalation loop
+
+The pattern when `@make` cannot reach GREEN.
+
+```mermaid
+stateDiagram-v2
+    [*] --> Dispatched: orchestrator dispatches @make
+    Dispatched --> EntryCheck: run tests, verify RED
+    EntryCheck --> Implementing: failure code matches handoff
+    EntryCheck --> EntryEscalation: test-quality concern
+    Implementing --> GreenReached: tests pass within 2-3 attempts
+    Implementing --> MidEscalation: escalate: test_design
+    Implementing --> MidStuck: incomplete, no flag
+    MidStuck --> Implementing: re-dispatch with @check notes (1 retry)
+    MidStuck --> MidEscalation: still failing on retry
+    EntryEscalation --> CheckDiag
+    MidEscalation --> CheckDiag
+    CheckDiag --> TestRedesign: confirmed test-design error
+    CheckDiag --> Dispatched: rejected (production issue)
+    TestRedesign --> Dispatched: @test fixes, fresh entry validation
+    Dispatched --> PlanRevisit: 2 escalation cycles exhausted
+    GreenReached --> [*]
+    PlanRevisit --> [*]: back to Phase 3
+```
+
+### 3.3 Issue lifecycle
+
+How TODO entries move through statuses, with sub-issue filing during a run.
+
+```mermaid
+stateDiagram-v2
+    [*] --> Todo: issue file created
+    Todo --> InProgress: Phase 2 (workflow starts)
+    InProgress --> Done: Phase 9 (run completes successfully)
+    InProgress --> Todo: workflow fails (failure handler adds comment)
+
+    note right of InProgress
+        New sub-issues may be filed during Phase 9
+        (parent: <ISSUE_ID>, status: Todo, label: bug/followup/tech-debt)
+    end note
+
+    Done --> [*]
+```
+
+---
+
+## 4. Routing Matrix
+
+Every observed `(phase, signal) → action`. Empty cells are gaps. Walking this table is the cheap way to spot routing issues like the recent Phase 7 mid-implementation escalation.
+
+| Phase | Signal source | Signal | Action |
+|---|---|---|---|
+| 1 | Sanity checks | Bare repo / detached HEAD / missing `TODO/<ID>.md` / branch == base | Stop with error |
+| 2 | `@pm` | Issue not found | Stop with error |
+| 2 | `@pm` | Status is `Todo` | Flip to `In Progress`; propagate to README.md / parent's Sub-issues |
+| 3 | Orchestrator | Plan drafted | Apply Dispatch Hygiene; write `plan.md`; verify `test -f` |
+| 4 | `@check` + `@simplify` | Both ACCEPTABLE | Proceed to Phase 5 |
+| 4 | Either reviewer | NEEDS WORK | Edit `plan.md` in place; re-dispatch (max 3 cycles) |
+| 4 | `@check` | BLOCK | Edit `plan.md` addressing the finding; re-dispatch |
+| 4 | Reviewers | Same finding twice | Convergence detected; stop loop early |
+| 4 | Reviewers | Unresolved after 3 cycles | Document blockers in summary; proceed |
+| 5 | Orchestrator | Tasks drafted | Apply Dispatch Hygiene; write each `task-N.md`; verify `test -f` for every N |
+| 5.5 | `@check` | ACCEPTABLE | Proceed to Phase 6 |
+| 5.5 | `@check` | NEEDS WORK | Edit `task-N.md` in place; re-dispatch (max 2 cycles) |
+| 5.5 | `@check` | BLOCK | Plan doesn't decompose cleanly; back to Phase 4 |
+| 6 | `@test` | TESTS_READY + `escalate_to_check: false` | Proceed to Phase 7 |
+| 6 | `@test` | TESTS_READY + `escalate_to_check: true` | `@check` light review → `@test` fixes → forward |
+| 6 | `@test` | NOT_TESTABLE (general) | `@check` sign-off; task goes to `@make` without tests |
+| 6 | `@test` | NOT_TESTABLE: Missing testability seam | `@make` adds the seam; re-run `@test` |
+| 6 | `@test` | BLOCKED | Investigate; may need spec or plan revision |
+| 6 | `@test` (stub-first) | All tests pass with zero `todo!()` panics | Reject — structural-only tests; route back to `@test` to rewrite |
+| 7 | `@make` | Implementation Complete | Proceed to Phase 8 |
+| 7 | `@make` | Implementation Incomplete + entry-validation flag | `@check` (test diagnosis) → `@test` (fixes) → fresh `@make` |
+| 7 | `@make` | Implementation Incomplete + `escalate: test_design` | Same path; max 2 escalation cycles |
+| 7 | `@make` | Implementation Incomplete (no flag) | Re-dispatch with `@check` notes once; if 2nd attempt fails, treat as `escalate: test_design` |
+| 7 | Escalation loop | 2 cycles exhausted | Back to Phase 3 (plan revisit) |
+| 8 | `@check` + `@simplify` | ACCEPTABLE | Proceed to Phase 9 |
+| 8 | `@check` | BLOCK / behavioral / production-code finding | New `@make` task spec from finding; dispatch (max 3 cycles) |
+| 8 | `@check` | BLOCK / test-design / test-quality finding | `@check` → `@test` → `@make` re-verify |
+| 8 | `@check` | BLOCK / plan-level finding | Back to Phase 3 with the finding |
+| 8 | `@simplify` | Advisory | Record in summary's "Advisory notes (not filed)" |
+| 8 | Reviewers | Strictly cosmetic finding (typo, missing newline, AST-preserving) | Orchestrator fixes directly; re-review |
+| 8 | Review loop | Same finding twice | Convergence; stop loop |
+| 8 | Review loop | 3 cycles exhausted | Document blockers; proceed |
+| 9 | Orchestrator | Pre-existing bug, out of scope | File sub-issue via `@pm` (label: `bug`) |
+| 9 | Orchestrator | Unresolved review-loop blocker | File sub-issue via `@pm` (label: `followup`) |
+| 9 | `@test` (Phase 6) | NOT_TESTABLE future-seam note | File sub-issue via `@pm` (label: `tech-debt`) |
+| 9 | Orchestrator | `@simplify` advisory not acted on | Record in summary; do NOT file (records, not work) |
+| 9 | Orchestrator | All commits done | Set issue status to `Done`; sync README/parent; commit `chore(todo): …` |
+
+---
+
+## 5. Design Decisions Log
+
+ADR-flavoured. New decisions append at the end. If a decision is later reversed or refined, mark the original *Superseded by ADR-N* and add a new entry.
+
+### ADR-1 (2026-05-06) — Forge-agnostic workflow
+
+**Context:** original gist used the GitHub `gh` CLI for auth checks and `gh pr create --draft` at the end of the run.
+**Decision:** workflow stops at `git commit`. No push, no PR/MR creation, no `gh` references anywhere.
+**Alternatives:** keep `gh` integration; abstract behind a forge-plugin interface.
+**Consequences:** workflow runs on any git host; user opens PR/MR manually on whichever forge they use. Removes the need for forge auth setup as a prerequisite.
+
+### ADR-2 (2026-05-06) — `@pm` operates on local `TODO/` folder
+
+**Context:** original `@pm` agent used the Linear CLI.
+**Decision:** Linear-style folder-as-tracker with one `<ID>.md` file per issue plus a category-grouped `README.md`.
+**Alternatives:** keep Linear; multi-backend abstraction; single-file `TODO.md`.
+**Consequences:** project-local, version-controlled, no external service. Schema enforced in `agents/pm.md`. Initial single-file design moved to per-issue files in ADR-12.
+
+### ADR-3 (2026-05-07) — Workflow runs in worktree, not bare repo
+
+**Context:** original orchestrated bare-clone → worktree creation as Phase 3 of the workflow.
+**Decision:** user creates the worktree before launching opencode; the workflow assumes CWD is the worktree.
+**Alternatives:** keep auto-worktree-creation; auto-detect bare vs. worktree.
+**Consequences:** simpler workflow; opencode CWD = worktree, so subagents inherit the right project root naturally; less plumbing around `WORKTREE_PATH`. (Subagents still get absolute paths in dispatch prompts — see ADR-7.)
+
+### ADR-4 (2026-05-07) — `@make` and `@test` are polyglot
+
+**Context:** original was Python-only via `uv`.
+**Decision:** detect toolchain from marker files (`pyproject.toml`, `Cargo.toml`, `flake.nix`); wrap all toolchain commands in `nix develop -c` if a devshell is present.
+**Alternatives:** per-language agents; keep Python-only.
+**Consequences:** one agent per role serves multiple languages. Permission allowlists expanded for `cargo` and `nix develop -c`. Bash sandbox still denies shell escapes inside the wrapper.
+
+### ADR-5 (2026-05-07) — Subagent CWD via absolute paths
+
+**Context:** opencode subagents do not inherit the orchestrator's `cd`. A `@check` dispatched from inside a worktree resolved relative paths against the parent project root and failed with "file not found."
+**Decision:** capture `WORKTREE_PATH` in Phase 1 and pass absolute paths to every subagent dispatch.
+**Alternatives:** patch opencode (out of scope); symlink dance.
+**Consequences:** every dispatch has an explicit `Worktree: <abs path>` header convention. Verbose but reliable. Eventually superseded by run-artifact paths under `$RUN_DIR` (ADR-7).
+
+### ADR-6 (2026-05-08) — Run artifacts on disk in `.workflow/run-<ID>/`
+
+**Context:** the orchestrator was paraphrasing the plan and task specs into each dispatch prompt. Result: `@check` and `@simplify` could see slightly different versions of the same plan; mid-loop revisions could leak as "actually let me reconsider…" passages; long specs ate context budget on every dispatch.
+**Decision:** orchestrator writes `plan.md` (Phase 3), `task-N.md` (Phase 5), and `summary.md` (Phase 9) to `$WORKTREE_PATH/.workflow/run-<ISSUE_ID>/`. Dispatches name files by absolute path; subagents read them.
+**Alternatives:** inline prompts (status quo); database; in-memory orchestrator state.
+**Consequences:** byte-for-byte source of truth across dispatches. Mid-loop revisions edit the file in place; every subsequent reader sees the new version. Run-artifact directory is gitignored (`.workflow/`).
+
+### ADR-7 (2026-05-08) — Stub-first Rust TDD (mandatory for new symbols)
+
+**Context:** Rust integration tests reference symbols imported from `lib.rs`. If those symbols don't exist yet, the test crate fails to compile — a build-error RED with no stack trace and no assertion diagnostics. Same for module tests against not-yet-existing functions.
+**Decision:** for any Rust task that introduces new symbols, dispatch a stub-pass `@make` first (writes `todo!()`-bodied stubs, runs `cargo check` only). Then `@test` runs against compiling stubs; runtime panic on `todo!()` is the clean RED. Then `@make` body pass replaces stubs.
+**Alternatives:** accept compile-error RED; let `@make` write tests + bodies in one pass; allow `@test` to add stubs to production source.
+**Consequences:** two atomic commits per affected task (`feat: scaffold X with todo!() stubs`, then `feat: implement X`). Stub-pass scope is tight: bodies are exactly `todo!()`, signatures must match the planned final API. Phase 6 also adds a mandatory panic-coverage check after `@test`: every test must panic on `todo!()` to prove it actually exercises the stubbed symbols (catches structural-only tests).
+
+### ADR-8 (2026-05-08) — `@test` may write inside `#[cfg(test)] mod` blocks
+
+**Context:** Rust unit tests live colocated in production source files inside `#[cfg(test)] mod tests { … }` blocks — the canonical idiom, not an edge case. Original `@test` File Constraint forbade `src/` writes entirely, which forced `@make` to write both production code and tests in a single dispatch. This lost the RED→GREEN separation that TDD relies on.
+**Decision:** `@test` may modify `src/**/*.rs` strictly inside `#[cfg(test)] mod <name> { … }` blocks. Every line outside such a block stays read-only.
+**Alternatives:** keep the restriction; write all unit-level tests as integration tests.
+**Consequences:** TDD works for module tests as well as integration tests. The previous Phase 6 file gate (path-based `git status` snapshot diff) is removed — with `@test` now legitimately writing inside `src/`, a path-based gate proves nothing. Constraint is now enforced by the prompt rule, the diff being human-reviewable, and `@check` flagging production-code drift in Phase 8.
+
+### ADR-9 (2026-05-08) — Phase 5.5 task-split review by `@check`
+
+**Context:** `ppries`' README mentioned `@check` reviewing the task split for completeness, but the gist's `workflow.md` never implemented it. Without a split-review gate, an over- or under-split task surfaced only at Phase 8 final review — after expensive `@test` and `@make` dispatches had already run on a broken split.
+**Decision:** new Phase 5.5 dispatches `@check` against `plan.md` + every `task-N.md` to evaluate the split against five questions: coverage, no overlap, single-purpose, integration contracts, testable AC. Max 2 cycles; BLOCK routes back to Phase 4 (plan itself doesn't decompose).
+**Alternatives:** status quo (catch at Phase 8); orchestrator self-check.
+**Consequences:** one extra `@check` dispatch per run. `@simplify` is not involved at this phase — split review is structural, not complexity. Cheaper failure modes for over-/under-split tasks.
+
+### ADR-10 (2026-05-08) — `@pm` is single-mode (filesystem only)
+
+**Context:** `@pm` had two read modes — `git show <ref>:TODO.md` (read-only) and filesystem (read/write). Git-ref mode existed for the bare-repo flow that ADR-3 retired. After ADR-3, the workflow always used filesystem mode; git-ref mode was dead weight that still added bash permissions and doc surface.
+**Decision:** remove git-ref mode. `@pm` has no bash access. Ad-hoc historical reads (`git show main:TODO/GAL-39.md`) are out of scope — the user runs them directly.
+**Alternatives:** keep dual-mode; document the separation more clearly.
+**Consequences:** simpler agent. One less permission allowlist to maintain. Workflow's "(live filesystem mode)" qualifier dropped from Phase 2 / Phase 9 / Failure handler.
+
+### ADR-11 (2026-05-08) — Phase 9 files follow-ups as TODO sub-issues
+
+**Context:** unresolved items (pre-existing bugs out of scope, blocked review findings, future-seam notes) were recorded only in `summary.md` — per-run, untracked, overwritten on the next run, read by nobody since the user has walked away.
+**Decision:** Phase 9 has a `### File Follow-ups` step that dispatches `@pm` to create new TODO sub-issues for tracked-worthy items. Each new issue has `parent: <ISSUE_ID>`, status `Todo`, and an appropriate label (`bug` / `followup` / `tech-debt`). `@simplify` advisories that the orchestrator chose not to act on stay in the summary as records, not filed.
+**Alternatives:** leave items in summary; create as top-level issues (would need a README.md category, which can't be picked at unattended runtime).
+**Consequences:** unresolved items become tracked work. Sub-issue routing avoids the README-category problem. The follow-up files commit alongside the worked-issue update in a single `chore(todo): …` commit.
+
+### ADR-12 (2026-05-08) — Phase 7 mid-implementation escalation
+
+**Context:** Phase 7's escalation rule was gated on `@make` flagging concerns *during entry validation* (the RED check before implementing). When `@make` got past entry validation, started implementing, and then ground for 2-3 attempts because the test demanded impossible production code, the orchestrator had no documented route — it would re-dispatch `@make` with marginal context tweaks instead of recognizing the diagnosis as test-architecture failure.
+**Decision:** split Phase 7's escalation into entry-validation and mid-implementation paths. `@make` reports `escalate: test_design` when its iteration limit is reached and the test seems to demand impossible / unreasonable code. Both paths route through `@check` (test diagnosis) → `@test` (redesign) → fresh `@make` dispatch. Max 2 escalation cycles before reverting to Phase 3 plan revisit.
+**Alternatives:** status quo; let `@make` modify test files itself.
+**Consequences:** faster recovery from test-design errors. Bounded loop prevents thrashing. `@make.md` Iteration Limits section gains a new red-flag class.
+
+---
+
+## 6. Open Questions / Known Gaps
+
+When a question gets answered, move it to the [Design decisions log](#5-design-decisions-log).
+
+### Q1: Phase 5.5 review scope — does `@check` evaluate test-design soundness here?
+
+Currently Phase 5.5 reviews the **split** (coverage, overlap, single-purpose, integration contracts, testable AC). It does *not* explicitly evaluate whether the test approach implied by each task spec is sound. That would partially overlap with Phase 4 (which has a plan-level Test Design section the reviewers evaluate). If a test-design error escapes Phase 4 and is encoded in a task spec, it surfaces at Phase 7 via the mid-impl escalation (ADR-12) — but earlier detection might be cheaper. Open: should Phase 5.5 add "test approach for each task is sound" as a sixth review question, or is that scope creep into Phase 4 territory?
+
+### Q2: How does the orchestrator handle "split heuristic violated only after attempting a task"?
+
+Phase 5's Split Heuristic catches obvious over-/under-split cases at planning time. But sometimes a task that *looked* single-purpose during planning turns out to mix structural and runtime work only when `@make` starts implementing it. There's no documented mid-Phase-7 routing for "this task needs to be split now." Currently `@make` would either thrash (mid-impl escalation, ADR-12), or report the spec is ambiguous (Insufficient Context Protocol in `make.md`). Open: should there be a "split mid-flight" route that takes the task back to Phase 5 for re-splitting?
+
+### Q3: Phase 9 has no rollback for partial commits if it fails between sub-steps
+
+Phase 9's order is: code commit → TODO update → file follow-ups → commit TODO changes → write summary. If the workflow crashes between code commit and TODO commit, the worktree has the code change but the issue file still says `In Progress`. The Failure Handler covers earlier-phase crashes but Phase-9-internal partial states aren't explicitly addressed. Open: should the Failure Handler distinguish "Phase 9 partial" and resume from the right sub-step on retry, or is leaving manual cleanup to the user good enough?
+
+### Q4: `@simplify` not involved at Phase 5.5 — is that the right call?
+
+Phase 5.5 only dispatches `@check`. Rationale (ADR-9) is that split review is structural, not complexity. But `@simplify`'s lens — "what if we deleted this?" — could legitimately catch unnecessary tasks (e.g. a third task that adds an abstraction nothing else needs). Open: is the cost of one more dispatch worth the catch?
+
+### Q5: Test-design loop bound vs plan-revisit threshold
+
+ADR-12 sets max 2 cycles for the Phase 7 test-design escalation before reverting to Phase 3 plan revisit. The plan-review and final-review loops have max 3. Why the asymmetry? The test-design loop is more expensive per cycle (`@check` + `@test` + `@make` re-implement vs. just reviewers + plan edit), so 2 may be right. But the choice was made by feel, not measured. Open: is 2 the right number, or should it match Phase 4 / Phase 8 at 3?
+
+---

From 0b15944d1c5c42726e885768e6811faaab7d52bb Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Fri, 8 May 2026 10:24:57 +0200
Subject: [PATCH 092/101] docs(opencode): make workflow-design Mermaid diagrams
 Forgejo-compatible
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Forgejo's Mermaid parser is stricter than GitHub's and rejected two
diagrams in workflow-design.md:

1. Flowchart 3.1 — `@check`, `@test`, `@make` in pipe-delimited edge
   labels were tokenised as LINK_ID (newer Mermaid uses `@{...}` for
   edge IDs), e.g. `P7E -->|@check → @test → @make| P7` failed at
   the first @.
2. State diagram 3.2 — the second colon inside transition labels
   (`escalate: test_design`) collided with the `:` field separator
   that splits transition from label.

Drops the @-prefix from labels in all three diagrams (`@check` → `check`
in prose-of-the-label only; ADRs and prose elsewhere keep `@check`
backticked, which is just markdown). Replaces second colons with
descriptive text. Drops parentheses from state-diagram transition
labels. Drops the Unicode arrow `→` in favour of plain words.
Quotes the flowchart node-label strings to keep `<br/>` safe.

The ADR text and prose continue to use `@<name>` references — those
live in markdown, not Mermaid, and render the same.
---
 config/opencode/workflow-design.md | 51 +++++++++++++++---------------
 1 file changed, 26 insertions(+), 25 deletions(-)

diff --git a/config/opencode/workflow-design.md b/config/opencode/workflow-design.md
index 4f0d41d..b33d566 100644
--- a/config/opencode/workflow-design.md
+++ b/config/opencode/workflow-design.md
@@ -40,27 +40,27 @@ High-level happy path with the major escalation arms.
 
 ```mermaid
 flowchart TD
-    P1[Phase 1: Sanity Check]
-    P2[Phase 2: Issue Context<br/>@pm reads TODO/ID.md]
-    P3[Phase 3: Plan<br/>write plan.md]
-    P4{Phase 4: Review Plan<br/>@check + @simplify<br/>max 3 cycles}
-    P5[Phase 5: Split into Tasks<br/>write task-N.md]
-    P55{Phase 5.5: Review Split<br/>@check<br/>max 2 cycles}
-    P6[Phase 6: Write Tests<br/>@test ± stub-first @make]
-    P7[Phase 7: Implement<br/>@make]
-    P7E{Test-design escalation<br/>max 2 cycles}
-    P8{Phase 8: Final Review<br/>@check + @simplify<br/>max 3 cycles}
-    P9[Phase 9: Commit + TODO + Follow-ups + Summary]
+    P1["Phase 1: Sanity Check"]
+    P2["Phase 2: Issue Context<br/>pm reads TODO/ID.md"]
+    P3["Phase 3: Plan<br/>write plan.md"]
+    P4{"Phase 4: Review Plan<br/>check + simplify<br/>max 3 cycles"}
+    P5["Phase 5: Split into Tasks<br/>write task-N.md"]
+    P55{"Phase 5.5: Review Split<br/>check<br/>max 2 cycles"}
+    P6["Phase 6: Write Tests<br/>test, stub-first make"]
+    P7["Phase 7: Implement<br/>make"]
+    P7E{"Test-design escalation<br/>max 2 cycles"}
+    P8{"Phase 8: Final Review<br/>check + simplify<br/>max 3 cycles"}
+    P9["Phase 9: Commit + TODO + Follow-ups + Summary"]
 
     P1 --> P2 --> P3 --> P4
     P4 -->|ACCEPTABLE| P5 --> P55
-    P4 -->|NEEDS WORK / BLOCK| P3
+    P4 -->|NEEDS WORK or BLOCK| P3
     P55 -->|ACCEPTABLE| P6 --> P7
     P55 -->|NEEDS WORK| P5
     P55 -->|BLOCK plan-level| P3
     P7 --> P8
-    P7 -.->|escalate: test_design| P7E
-    P7E -->|@check → @test → @make| P7
+    P7 -.->|escalate test_design| P7E
+    P7E -->|check then test then make| P7
     P7E -.->|2 cycles exhausted| P3
     P8 -->|ACCEPTABLE| P9
     P8 -->|production-code finding| P7
@@ -75,20 +75,20 @@ The pattern when `@make` cannot reach GREEN.
 
 ```mermaid
 stateDiagram-v2
-    [*] --> Dispatched: orchestrator dispatches @make
-    Dispatched --> EntryCheck: run tests, verify RED
+    [*] --> Dispatched: orchestrator dispatches make
+    Dispatched --> EntryCheck: run tests verify RED
     EntryCheck --> Implementing: failure code matches handoff
     EntryCheck --> EntryEscalation: test-quality concern
     Implementing --> GreenReached: tests pass within 2-3 attempts
-    Implementing --> MidEscalation: escalate: test_design
-    Implementing --> MidStuck: incomplete, no flag
-    MidStuck --> Implementing: re-dispatch with @check notes (1 retry)
+    Implementing --> MidEscalation: escalate test_design flag
+    Implementing --> MidStuck: incomplete no flag
+    MidStuck --> Implementing: re-dispatch with check notes 1 retry
     MidStuck --> MidEscalation: still failing on retry
     EntryEscalation --> CheckDiag
     MidEscalation --> CheckDiag
     CheckDiag --> TestRedesign: confirmed test-design error
-    CheckDiag --> Dispatched: rejected (production issue)
-    TestRedesign --> Dispatched: @test fixes, fresh entry validation
+    CheckDiag --> Dispatched: rejected production issue
+    TestRedesign --> Dispatched: test fixes fresh entry validation
     Dispatched --> PlanRevisit: 2 escalation cycles exhausted
     GreenReached --> [*]
     PlanRevisit --> [*]: back to Phase 3
@@ -101,13 +101,14 @@ How TODO entries move through statuses, with sub-issue filing during a run.
 ```mermaid
 stateDiagram-v2
     [*] --> Todo: issue file created
-    Todo --> InProgress: Phase 2 (workflow starts)
-    InProgress --> Done: Phase 9 (run completes successfully)
-    InProgress --> Todo: workflow fails (failure handler adds comment)
+    Todo --> InProgress: Phase 2 workflow starts
+    InProgress --> Done: Phase 9 run completes
+    InProgress --> Todo: workflow fails, failure handler adds comment
 
     note right of InProgress
         New sub-issues may be filed during Phase 9
-        (parent: <ISSUE_ID>, status: Todo, label: bug/followup/tech-debt)
+        with parent ISSUE_ID, status Todo
+        and label bug, followup, or tech-debt
     end note
 
     Done --> [*]

From af6481a5a7125f6017ef7269e3dd13adfecb85aa Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Fri, 8 May 2026 13:02:54 +0200
Subject: [PATCH 093/101] feat(opencode): one-task-per-run model + 9 routing
 fixes (ADRs 13-21)

Captures the design grilling outcome. Adds ADRs 13-21 covering:
- run-level plan_rework_remaining counter to bound P3<->P5.5/P7/P8 thrash
- non-resumable workflow with throwaway-worktree recovery procedure
- @simplify advisory at every gate (not just Phase 8)
- Phase 8 fix specs go to disk as task-fix-N.md (preserves ADR-6)
- Phase 5.5 BLOCK protocol: orchestrator edits plan, decrements counter, re-enters P4
- Phase 8 NOT_TESTABLE manifest in reviewer prompt
- unified Implementation Incomplete diagnosis (test_design / production_logic / split_needed)
- Phase 1 working-tree cleanliness + depends-on enforcement
- one-task-per-run pivot: Phase 5 still splits N tasks, only task-1 runs;
  tasks 2..N filed as sub-issues with rich seed bodies; split_needed at P7
  aborts to Failure Handler (one-task-per-run = no salvageable prior work)

Auto-resolves big-diff Phase 8 reviews, cross-task regression-within-run, and
mid-flight task-split routing. Rewrites routing matrix and three Mermaid
diagrams; updates @pm (depends-on frontmatter, split-time filing), @check
(third diagnosis verdict), @make (escalate: split_needed flag).
---
 config/opencode/agents/check.md      |   8 +
 config/opencode/agents/make.md       |   5 +-
 config/opencode/agents/pm.md         |  19 ++-
 config/opencode/commands/workflow.md | 230 ++++++++++++++++++---------
 config/opencode/workflow-design.md   | 210 ++++++++++++++++++------
 5 files changed, 342 insertions(+), 130 deletions(-)

diff --git a/config/opencode/agents/check.md b/config/opencode/agents/check.md
index 2329978..18210dd 100644
--- a/config/opencode/agents/check.md
+++ b/config/opencode/agents/check.md
@@ -145,6 +145,14 @@ High-level:
 - No excessive mocking (>2 mocks is a yellow flag)?
 - Diagnose issues and report findings. Do NOT edit test files — the caller routes fixes back to `@test`.
 
+**When diagnosing `Implementation Incomplete` from `@make`** (the `/workflow` Phase 7 unified diagnosis path, per ADR-19): you receive `@make`'s self-diagnosis hint (`escalate: test_design`, `escalate: split_needed`, or no flag), the test files, the in-progress production diff, and the task spec. Return one of three verdicts in your output:
+
+- **`test_design`** — the test demands production code that's impossible, internally-inconsistent, or testing the wrong observable. The fix is in the tests. (Caller routes to `@test` for redesign.)
+- **`production_logic`** — the test is sound; `@make`'s implementation is wrong or incomplete. The fix is in the production code. (Caller re-dispatches `@make` with your notes.)
+- **`split_needed`** — the task itself is over-scoped: no realistic implementation can satisfy the AC within the task's stated files-to-modify. Either the AC require touching files not listed, or the AC mix multiple concerns that should have been split at Phase 5 (per the workflow's Split Heuristic). (Caller aborts to the Failure Handler; the user re-plans from scratch.)
+
+State the verdict explicitly — e.g. "Diagnosis: `split_needed` — the AC implies modifying both `src/foo.rs` and the EventLoop registration in `src/main.rs`, but the task spec lists only `src/foo.rs`. This is a Phase 5 split error, not a code or test error." Calibrate confidence honestly: `split_needed` is the heaviest verdict (it kills the run); reserve it for cases where neither test redesign nor code-fix would plausibly converge.
+
 **When reviewing NOT_TESTABLE verdicts:**
 - Does the reason match an allowed category (config-only, external-system, non-deterministic, pure-wiring)?
 - Was a test approach genuinely attempted?
diff --git a/config/opencode/agents/make.md b/config/opencode/agents/make.md
index 5193ef2..a9f0013 100644
--- a/config/opencode/agents/make.md
+++ b/config/opencode/agents/make.md
@@ -273,12 +273,15 @@ If tests fail or verification doesn't pass:
 3. **Code issues** — Attempt fix (max 2-3 attempts if making progress)
 4. **Flaky/infra issues** — Stop and report with diagnostics
 5. **Test-design suspicion** — If after 1–2 attempts the test seems to demand production code that contradicts the spec, asserts on internal state that shouldn't be observable, mocks an internal boundary instead of the external one, or otherwise looks like it's testing the wrong thing — **stop and report with `escalate: test_design`** in the Blocking Issue section. Do not modify the test file yourself; the caller will route to `@check` for diagnosis and `@test` for redesign per the workflow's Phase 7 escalation.
+6. **Task-scope suspicion** — If after 1–2 attempts you find that the AC realistically require modifying files not listed in your "Files to Modify," or the AC mix multiple distinct concerns that don't fit one coherent change (e.g. a new type *and* its registration site *and* a new system using it), the task is over-scoped — **stop and report with `escalate: split_needed`** in the Blocking Issue section. State concretely which file(s) outside your modify list you'd need, or which concerns the task is mixing. Do not silently expand scope; the caller will route to `@check` for diagnosis and (per the workflow's ADR-21) the run will abort to the Failure Handler so the user can re-plan from scratch.
+
+The `escalate:` flag is a *hint* to the caller's diagnosis routing — `@check` is the authority that confirms or rejects it. Reporting `escalate: split_needed` doesn't guarantee the run aborts; if `@check` decides the task is sound and the issue is in tests or production code, the diagnosis will route back to a normal `test_design` or `production_logic` verdict.
 
 If still failing after 2-3 focused attempts, **stop and report**:
 - What was implemented
 - What's failing and why
 - What you tried
-- Suggested next steps (including `escalate: test_design` if the failure points at the test rather than the production code)
+- Suggested next steps (with the appropriate `escalate:` flag if you have a strong hypothesis about which kind of failure this is)
 
 Do not loop indefinitely. Better to report a clear failure than burn context.
 
diff --git a/config/opencode/agents/pm.md b/config/opencode/agents/pm.md
index b2e84e3..2382876 100644
--- a/config/opencode/agents/pm.md
+++ b/config/opencode/agents/pm.md
@@ -48,6 +48,7 @@ title: Implement a special stage type
 status: Done
 parent: GAL-38
 labels: [gameplay, advanced-mechanics]
+depends-on: [GAL-37]
 ---
 
 # GAL-39: Implement a special stage type
@@ -80,6 +81,7 @@ Free-form markdown describing the problem and context. Spans as many paragraphs
 - `status` — one of: `Todo`, `In Progress`, `Done`. (No other values; the old `Backlog`/`In Review`/`Cancelled` set is gone.)
 - `parent` — either `null` (top-level issue) or another issue ID (e.g. `GAL-38`). Sub-issues belong to their parent's `## Sub-issues` list.
 - `labels` — YAML list of strings, e.g. `[gameplay, advanced-mechanics]`. May be `[]`.
+- `depends-on` — *optional* YAML list of issue IDs that must reach `status: Done` before this issue can be started. Used by `/workflow`'s Phase 1 sanity check to hard-block runs whose dependencies aren't satisfied (per ADR-21). Omit the field entirely when there are no dependencies; do not write `depends-on: []`. Cycles are not detected by this agent — the caller is responsible for not creating a cycle.
 
 **Body rules:**
 - The first heading is `# <ID>: <title>` (matches frontmatter).
@@ -172,9 +174,24 @@ For list output, return an array of `{id, title, status, parent, labels}` object
 ### When creating issues
 - Default `status: Todo` unless the caller says otherwise.
 - Title: short, imperative ("Add retry logic to ingest worker", not "retry stuff").
-- Frontmatter must be complete: `id`, `title`, `status`, `parent`, `labels`.
+- Frontmatter must be complete: `id`, `title`, `status`, `parent`, `labels`. Add `depends-on:` when the caller specifies dependencies.
 - Always update the dependent index (README.md for top-level, parent file for sub-issues) so the new issue is visible.
 
+### Split-time sub-issue creation (rich-body filings)
+
+When the `/workflow` orchestrator dispatches you mid-run to file a sub-issue from a Phase 5.5 task split (per ADR-21), the caller passes a structured body containing more than the usual minimum. Treat the body as already-finalized — write it verbatim into the new issue file. Common sections you'll see:
+
+- `## What to implement` — one-line + brief description.
+- `## Acceptance criteria` — checkboxes; preserve `- [ ]` state (newly filed sub-issues start with all AC unchecked).
+- `## Code Context` — code snippets carried over from the split-time task spec.
+- `## Integration with sibling sub-issues` — narrative; the structural dependencies belong in the `depends-on:` frontmatter list, which the caller will pass alongside the body.
+- `## Plan rationale` — slice of the parent's plan.
+- `## Test design` — when present.
+
+Use the rendered ordering: H1 → description (the "Discovered during run on …" attribution paragraph that ends the body counts as part of the description) → `## Sub-issues` (omit; sub-issues won't have their own children at filing time) → `## Acceptance criteria` → `## Integration test hints` (omit unless caller passed it) → `## Comments` (omit until first comment is appended).
+
+Add the `split-from-run` label to the labels list when the caller specifies it, alongside any propagated parent labels.
+
 ### When updating status
 - Confirm the change (e.g. "GAL-39 status: In Progress → Done").
 - A status change to `Done` is only valid if all acceptance-criteria checkboxes (when the section exists) are checked. If they are not, report which ones remain and ask for confirmation before forcing the change.
diff --git a/config/opencode/commands/workflow.md b/config/opencode/commands/workflow.md
index c6304c1..b43d02d 100644
--- a/config/opencode/commands/workflow.md
+++ b/config/opencode/commands/workflow.md
@@ -86,7 +86,10 @@ Define `RUN_DIR="$WORKTREE_PATH/.workflow/run-$ISSUE_ID"` once in Phase 1 and re
    - Else if `git rev-parse --verify --quiet master` succeeds, use `master`.
    - Else stop: "Could not determine base branch (no `main` or `master`). Pass it as the second argument: `/workflow <ISSUE-ID> <base-branch>`."
 7. Verify the current branch is not the base branch: if `BRANCH_NAME == BASE_BRANCH`, stop: "Cannot run workflow on the base branch (`$BASE_BRANCH`). Switch to a feature branch first."
-8. Set the run-artifacts directory: `RUN_DIR="$WORKTREE_PATH/.workflow/run-$ISSUE_ID"`. Phase 3 will `mkdir -p "$RUN_DIR"` before writing the first artifact.
+8. **Verify the working tree is clean** (ADR-20): `git status --porcelain` must return empty. If not, stop: "Working tree must be clean. Commit or stash uncommitted changes before running the workflow."
+9. **Check `depends-on:` declarations** (ADR-21): if `./TODO/$ISSUE_ID.md`'s frontmatter contains a `depends-on: [<ID>, ...]` list, verify every listed dependency's status is `Done` (read each `./TODO/<DEP-ID>.md`). If any dependency is not `Done`, stop: "Cannot start `$ISSUE_ID`; it depends on `<DEP-ID>` (status: `<status>`). Complete dependencies first." If a listed dependency file does not exist, stop with: "Cannot start `$ISSUE_ID`; declared dependency `<DEP-ID>` has no issue file." If the field is absent, proceed.
+10. Set the run-artifacts directory: `RUN_DIR="$WORKTREE_PATH/.workflow/run-$ISSUE_ID"`. Phase 3 will `mkdir -p "$RUN_DIR"` before writing the first artifact.
+11. Initialize the run-level rework counter: `PLAN_REWORK_REMAINING=1` (per ADR-13). Decrement on every P5.5-BLOCK→P4, P7-escalation-exhaustion→P3, and P8-plan-level→P3 transition. When the counter is `0` and another such transition fires, abort to the Failure Handler instead of re-entering.
 
 ---
 
@@ -196,24 +199,23 @@ Reviewers should evaluate testability:
 - `@check`: Is the design testable? Are the right behaviors identified? (Review Framework §8)
 - `@simplify`: Is the test scope appropriate? Over-testing proposed?
 
-**Merge rules:**
-- `@check` safety/correctness findings are hard constraints
-- If `@simplify` recommends removing something `@check` flags as needed, `@check` wins
-- Note conflicts explicitly
+**Verdict authority** (ADR-15): `@check` is the only blocking reviewer. Its `NEEDS WORK` and `BLOCK` verdicts gate progression; its `ACCEPTABLE` verdict permits proceeding regardless of what `@simplify` reports. `@simplify` is advisory at every gate — its findings are recorded in the run summary's "Advisory notes (not filed)" section but never trigger a re-dispatch loop. The user may manually elevate a `@simplify` finding into a `task-fix-<N>.md` if it warrants follow-up.
 
-**Review loop (max 3 cycles):**
+**Review loop (max 3 cycles, gated on `@check`):**
 1. Dispatch both reviewers against `$RUN_DIR/plan.md`.
-2. Merge findings
-3. If verdict is ACCEPTABLE from both (or JUSTIFIED COMPLEXITY from `@simplify`): proceed to Phase 5
-4. If BLOCK or NEEDS WORK: edit `$RUN_DIR/plan.md` in place addressing findings (re-apply Dispatch Hygiene to the updated file), then re-review.
-5. **Convergence detection:** if reviewers return the same findings as the previous cycle, stop the loop early
-6. If still unresolved after 3 cycles: note unresolved blockers and proceed anyway (they will be documented in the workflow summary and commit message)
+2. Merge findings: record `@simplify`'s output for the summary; act only on `@check`'s verdict.
+3. If `@check` returns ACCEPTABLE: proceed to Phase 5 (regardless of `@simplify`).
+4. If `@check` returns BLOCK or NEEDS WORK: edit `$RUN_DIR/plan.md` in place addressing the findings (re-apply Dispatch Hygiene to the updated file), then re-review.
+5. **Convergence detection:** if `@check` returns the same findings as the previous cycle, stop the loop early.
+6. If still unresolved after 3 cycles: note unresolved blockers and proceed anyway (they will be documented in the workflow summary and commit message).
 
 ---
 
 ## Phase 5: Split into Tasks
 
-**The output of this phase is one file per task at `$RUN_DIR/task-<N>.md`** (1-indexed: `task-1.md`, `task-2.md`, …). These files are the source-of-truth that Phase 6 (`@test`) and Phase 7 (`@make`) read by absolute path. **No file written = no dispatch in later phases.** If you skip the file-write step, every downstream dispatch will reference a non-existent path and fail.
+**The output of this phase is one file per task at `$RUN_DIR/task-<N>.md`** (1-indexed: `task-1.md`, `task-2.md`, …). These files are the source-of-truth that Phase 5.5, Phase 6, and Phase 7 read by absolute path. **No file written = no dispatch in later phases.** If you skip the file-write step, every downstream dispatch will reference a non-existent path and fail.
+
+**One-task-per-run model (ADR-21):** Phase 5 still produces N task files. After Phase 5.5 review, only **task-1** runs through Phases 6–8 in this invocation. If N > 1, tasks 2…N are filed as TODO sub-issues at the end of Phase 5.5 (see "File sibling tasks as sub-issues" below) and the user runs `/workflow` separately on each. This bounds the run's scope, keeps Phase 8 diffs reviewable, and eliminates cross-task regression risk inside a run.
 
 Steps:
 
@@ -254,9 +256,11 @@ Include **Test Design** from Phase 3 when available, attached to the relevant ta
 
 **Task size:** ~10-30 minutes each, single coherent change, clear boundaries.
 
-### Split Heuristic — when in doubt, split
+### Split Heuristic — when in doubt, **do not** split
 
-A task must be **split** if any of the following apply:
+In the one-task-per-run model (ADR-21), splitting fans work out across user sessions: every additional task becomes a sub-issue the user must come back and run as its own `/workflow` invocation, with full P3/P4/P5/P5.5/P6/P7/P8 overhead per sub-issue. **Default to keeping work in one task.** Only split when one of the mechanical triggers below clearly applies *and* the resulting sub-tasks each warrant their own commit/PR-sized chunk of attention.
+
+A task should be **split** when any of the following apply:
 
 - It touches more than two distinct concerns (e.g. *constants + new component + sprite spawn + new system + main wiring* is **five** concerns — at least three tasks).
 - It changes more than ~50 lines across more than 2 files.
@@ -264,12 +268,14 @@ A task must be **split** if any of the following apply:
 - It mixes pure-logic changes (math helpers) with stateful changes (queries, world mutation).
 - It mixes new APIs with their first call sites in the same task.
 
-When a task fails the heuristic, split into:
+**Tiebreaker:** when none of the triggers clearly applies and the work plausibly fits a single coherent commit, do not split. Splitting fans out across sessions; only split if each resulting sub-issue is genuinely independently runnable and benefits from its own plan.
+
+When a task does fail the heuristic, split into:
 1. **Foundations** — new constants, types, components (no behavior change yet).
 2. **Implementation** — the actual production logic, calling the foundations.
 3. **Wiring** — registration in `main.rs` / `lib.rs` / app-builder.
 
-Each split is dispatched separately to `@make` and verified before the next.
+Tasks 2…N are filed as sub-issues at the end of Phase 5.5; only task 1 runs in this invocation.
 
 ### Code Context — what to include
 
@@ -289,32 +295,73 @@ Apply **Dispatch Hygiene** to each task spec before dispatch in Phase 7.
 
 ## Phase 5.5: Review Task Split
 
-A short, focused review of the task split as a set. Catches split errors (missed scope, overlap, multi-purpose tasks, missing integration contracts) when they're cheap to fix — *before* `@test` and `@make` dispatch on a broken split. Without this gate, the same errors surface only at Phase 8 final review, after expensive test/implementation work has already been done.
+A short, focused review of the task split as a set. In the one-task-per-run model (ADR-21), this phase is the gate for **two** things: (a) catching split errors (missed scope, overlap, multi-purpose tasks, missing integration contracts) before `@test`/`@make` dispatch, and (b) preventing a botched split from being persisted as garbage sub-issues that the user has to manually clean up later. Both stakes are higher than in the original N-tasks-per-run design.
 
 **Dispatch only `@check`** for this phase — split review is structural / coverage, not complexity. `@simplify` is not involved. Apply **Dispatch Hygiene** to the prompt.
 
+**Skip Phase 5.5 entirely when N=1** (ADR-21): a single-task plan has no split to review. Three of the six questions below (no overlap, integration contracts, sub-issue self-containment) are degenerate. The remaining structural concerns (coverage, single-purpose, testable AC) are already evaluated at Phase 4 plan acceptance. Proceed directly to Phase 6.
+
 The dispatch prompt names:
 - `$RUN_DIR/plan.md` (the plan being decomposed)
 - `$RUN_DIR/task-1.md` through `$RUN_DIR/task-N.md` (the split — list every task file)
 - The worktree path
 
-`@check` evaluates the split against five questions:
+`@check` evaluates the split against six questions:
 
 1. **Coverage** — do the tasks together implement everything the plan promises? Any gaps?
 2. **No overlap** — do two tasks claim the same scope or modify the same lines?
 3. **Single-purpose** — does any task do more than one thing? (See Phase 5's Split Heuristic.)
-4. **Integration contracts** — where two tasks touch a shared interface, is the contract documented in both task files?
+4. **Integration contracts** — where two tasks touch a shared interface, is the contract documented in *both* task files in a form that survives sub-issue filing? (Each sub-issue runs in isolation later — its eventual P3 plan must be reconstructable from the sub-issue body alone, including any cross-sub-issue dependencies. This is the load-bearing question in the new model.)
 5. **Testable acceptance criteria** — does every task have specific, falsifiable AC?
+6. **Self-containment** — is each task spec runnable as a standalone `/workflow` invocation? Does its description carry enough plan-level context (rationale, code seams, scope boundary) that a fresh run could re-plan it without seeing the parent plan or sibling task files?
 
 **Review loop (max 2 cycles):**
 
 1. Dispatch `@check` against the plan + all task files.
-2. If `ACCEPTABLE` → proceed to Phase 6.
-3. If `NEEDS WORK` → edit the task files in place (split a task into two, merge two tasks, add integration contracts, sharpen AC). Re-apply Dispatch Hygiene to each updated file. Re-dispatch.
-4. If `BLOCK` → the plan itself does not decompose cleanly. Return to Phase 4 with `@check`'s finding instead of forcing the split.
-5. **Convergence detection:** same finding twice → stop loop, document the unresolved split issue in the run summary, proceed.
+2. If `ACCEPTABLE` → proceed to "File sibling tasks as sub-issues" (below), then Phase 6.
+3. If `NEEDS WORK` → edit the task files in place (split a task into two, merge two tasks, strengthen integration contracts, sharpen AC, add self-containment context). Re-apply Dispatch Hygiene to each updated file. Re-dispatch.
+4. If `BLOCK` plan-level finding (ADR-17) → translate the split-level finding into a concrete `plan.md` edit, save the edit, **decrement `PLAN_REWORK_REMAINING`**, and re-enter Phase 4 against the revised plan. If `PLAN_REWORK_REMAINING` was already `0`, abort to the Failure Handler instead.
+5. **Convergence detection:** same `@check` finding twice → stop loop, document the unresolved split issue in the run summary, proceed.
 
-**This is a quick gate, not a deep review.** No line-by-line code feedback (there's no code), no design re-litigation (that was Phase 4's job). The whole point is a fast structural check before downstream phases start churning.
+**This is a quick gate, not a deep review.** No line-by-line code feedback (there's no code), no design re-litigation (that was Phase 4's job). The whole point is a fast structural check before downstream phases start churning *and* before sibling tasks become persistent sub-issues.
+
+### File sibling tasks as sub-issues (when N > 1)
+
+After Phase 5.5 returns ACCEPTABLE, dispatch `@pm` to file each of `task-2.md` through `task-N.md` as a TODO sub-issue with `parent: $ISSUE_ID`. **Only task-1 continues into Phase 6.** Each filed sub-issue gets a rich seed body (ADR-21) so its eventual `/workflow` run can plan and implement without seeing siblings or the original `plan.md`.
+
+For each task `$N` in 2…N, dispatch `@pm` with the following body content (assembled by the orchestrator from `task-<N>.md` and the relevant slice of `plan.md`):
+
+```markdown
+## What to implement
+<task description from task-<N>.md>
+
+## Acceptance criteria
+<AC checkboxes from task-<N>.md>
+
+## Code Context
+<code snippets from task-<N>.md>
+
+## Integration with sibling sub-issues
+<dependencies on sibling sub-issues, with brief rationale; declared in frontmatter as `depends-on: [<SIB-ID>, ...]`>
+
+## Plan rationale
+<relevant slice of plan.md — typically 1–3 paragraphs covering why this approach was chosen>
+
+## Test design
+<from task-<N>.md or plan.md if present>
+
+---
+Discovered during run on `$BRANCH_NAME` for parent issue `$ISSUE_ID`.
+```
+
+`@pm` invocation per sub-issue:
+- Title — derived from `task-<N>.md`'s task description (short imperative).
+- Status — `Todo`.
+- Parent — `$ISSUE_ID`.
+- Labels — propagate relevant labels from the parent (e.g. `gameplay`); add `split-from-run` to mark the provenance.
+- `depends-on:` — sibling sub-issue IDs that this task requires to be `Done` first. The orchestrator determines the dependency graph from the integration contracts captured in Phase 5.5 question 4.
+
+The new sub-issue files plus the parent's updated `## Sub-issues` list are staged in Phase 9's `chore(todo): …` commit alongside the parent's status/AC updates.
 
 ---
 
@@ -338,7 +385,7 @@ Do **not** quote task or plan content inline — `@test` reads from disk.
 |-----------|--------|
 | `TESTS_READY` + `escalate_to_check: false` | Proceed to Phase 7 |
 | `TESTS_READY` + `escalate_to_check: true` | Route tests to `@check` for light review. `@check` diagnoses, caller routes fixes to `@test`. Then proceed. |
-| `NOT_TESTABLE` | Route to `@check` for sign-off on justification. If `Missing testability seam`, dispatch `@make` to add the seam first, then re-run `@test`. Otherwise the task goes to `@make` without tests. |
+| `NOT_TESTABLE` | Route to `@check` for sign-off on justification. If `Missing testability seam`, dispatch `@make` to add the seam first, then re-run `@test`. Otherwise the task goes to `@make` without tests. **Record the `@test` justification + `@check` sign-off rationale** for the Phase 8 NOT_TESTABLE manifest (ADR-18). |
 | `BLOCKED` | Investigate. May need to revise task spec or plan. |
 | Test passes immediately | Investigate — behavior may already exist. Task spec may be wrong. |
 | Stub-first run: tests pass with zero `todo!()` panics | **Structural-only tests.** Every test is asserting type/struct/enum facts without calling any stubbed symbol. Reject the test output and route back to `@test` with a "must exercise the stubbed symbols by calling them" note. Do not let these tests gate Phase 7 — they cannot RED→GREEN, so the body-pass `@make` would commit code with false-green coverage. |
@@ -373,82 +420,88 @@ To get a clean runtime RED, dispatch a **stub-first `@make` pass** *before* `@te
 
 The stub pass and the body pass each produce their own atomic commit (per Phase 9 rules): `feat(<scope>): scaffold <thing> with todo!() stubs` followed by `feat(<scope>): implement <thing>` (or whichever conventional type fits).
 
-**Parallelism:**
-- **Python:** Independent tasks can have tests written in parallel, *provided* their test files are disjoint and no shared `conftest.py` is being modified.
-- **Rust:** Run `@test` dispatches **sequentially**. Cargo serialises the build via the `target/` directory lock, so parallel dispatches give no speedup; they only add risk (a long-running build in one branch starves the other, and any task that touches a shared crate-level fixture/helper file will race).
+**Parallelism:** N/A in the one-task-per-run model (ADR-21). Phase 6 dispatches `@test` for task-1 only; the stub-pass `@make` (when applicable) runs strictly before `@test`, and the body-pass `@make` strictly after. There are no peer dispatches to parallelise.
 
-**Constraint:** `@test` must not modify existing `conftest.py` files (prevents collision during parallel execution).
+**Constraint:** `@test` must not modify existing `conftest.py` files (preserves cross-test invariants for the project's broader suite).
 
 ---
 
 ## Phase 7: Implement
 
-Apply **Dispatch Hygiene** to each `@make` spec before sending. Repeated trips on a single task signal a Phase 5 split problem — go back and split.
+Apply **Dispatch Hygiene** to each `@make` spec before sending. Repeated trips on a single task signal a scoping problem — `@check`'s diagnosis (below) will return `split_needed`, and the orchestrator files the task as a sub-issue and exits.
 
-**`@make` dispatches are SEQUENTIAL — never in parallel.** Run each task to completion (writes, every verification command, and the orchestrator's post-check) before dispatching the next. Reasons:
-- `@make` writes source files. Parallel agents picking the same file (e.g. `src/lib.rs` for adding both a new `pub mod` and a registration) corrupt each other.
-- Even on disjoint files, Cargo's `target/` lock and uv's venv state serialise the verification builds anyway, so parallelism gives no speedup.
-- Stub-pass/body-pass pairs (Rust integration TDD) must be strictly ordered within a task; running stub-pass for task 2 while body-pass for task 1 is still building yields a non-deterministic crate state for `@test` to RED against.
+**One task per run** (ADR-21): only task-1 reaches Phase 7. Tasks 2…N were filed as sub-issues at the end of Phase 5.5; this run does not dispatch `@make` for any of them. Stub-pass and body-pass dispatches for task-1 still run sequentially (the stub-pass must commit before `@test` runs against it, and the body-pass must run after `@test` produces failing tests).
 
-This applies to **all** `@make` invocations: standard mode, TDD mode, stub-pass, body-pass, and integration-fix dispatches.
-
-Execute each task by dispatching `@make` with a short prompt:
-- The absolute path to the task spec: `$RUN_DIR/task-<N>.md` — `@make` reads acceptance criteria, code context, and files-to-modify from there.
+Execute task-1 by dispatching `@make` with a short prompt:
+- The absolute path to the task spec: `$RUN_DIR/task-1.md` — `@make` reads acceptance criteria, code context, and files-to-modify from there.
 - The worktree path.
 - **Pre-written failing tests and handoff from `@test` (if TESTS_READY)** — these are short and per-dispatch, so include them inline in the prompt.
 
 Do **not** quote the task spec inline.
 
 `@make` runs in TDD mode when tests are provided:
-1. Entry validation: run tests, verify RED, check failure codes match handoff
-2. Implement minimal code to make tests pass (GREEN)
-3. Regression check on broader area
-4. Refactor while keeping green
-5. Report RED→GREEN evidence
+1. Entry validation: run tests, verify RED, check failure codes match handoff.
+2. Implement minimal code to make tests pass (GREEN).
+3. Regression check: run the project's full test suite (`nix develop -c cargo test` / `uv run pytest` / `nix flake check` as appropriate).
+4. Refactor while keeping green.
+5. Report RED→GREEN evidence.
 
-**Escalation — two paths route through `@check` → `@test` → back to `@make`:**
+For NOT_TESTABLE tasks, `@make` runs in standard mode (no entry validation; standard implementation + verification).
 
-1. **Entry-validation escalation.** Before implementing, `@make`'s entry check (run tests, verify RED, compare against handoff) reveals test-quality concerns — wrong assertion target, mixed failure codes, mocks of internal boundaries, etc. `@make` reports without writing any production code.
-2. **Mid-implementation escalation.** After implementing, `@make` hits its iteration limit (2–3 attempts) because the test demands production code that's impossible or contradicts the spec. `@make` returns `Implementation Incomplete` with the flag `escalate: test_design`. **Do not** re-dispatch `@make` with marginal context tweaks — that just burns cycles on a test that needs redesign, not better implementation.
+### Implementation Incomplete — unified diagnosis path (ADR-19)
 
-In both cases:
+When `@make` returns `Implementation Incomplete` for *any* reason — entry-validation concern, mid-implementation iteration limit, `escalate: test_design` flag, `escalate: split_needed` flag, or no flag at all — the orchestrator routes the report through `@check` for diagnosis. **Do not re-dispatch `@make` with marginal context tweaks.** `@make`'s self-diagnosis (the `escalate:` flag, if present) becomes a *hint* for `@check`; `@check` is the authority that decides what to do next.
 
-1. `@make` returns its report (entry-time concern or mid-impl `escalate: test_design`).
-2. Orchestrator routes the report to `@check` for diagnosis (light review of the *tests*, not the implementation).
-3. `@check` confirms or rejects the test-design suspicion.
-4. **If confirmed:** orchestrator routes to `@test` to redesign the tests. Apply Dispatch Hygiene. Fixed tests return to `@make` for fresh entry validation and a clean implementation attempt.
-5. **If rejected:** the issue is in the production code; orchestrator re-dispatches `@make` with `@check`'s diagnostic notes attached.
+Steps:
 
-**Iteration limit on this loop: max 2 cycles.** If a test-design suspicion keeps surfacing but `@check` never confirms it, the design problem is upstream — revisit the Phase 3 plan rather than thrashing between `@test` and `@make`.
+1. `@make` returns its `Implementation Incomplete` report (with or without an `escalate:` flag).
+2. Orchestrator dispatches `@check` for diagnosis. Inputs: the test files (`@check` reads them from disk), the production code state (the in-progress diff), the task spec at `$RUN_DIR/task-1.md`, and `@make`'s self-diagnosis hint.
+3. `@check` returns one of three verdicts:
+   - **`test_design`** — the test demands production code that's impossible, internally-inconsistent, or testing the wrong observable. Orchestrator dispatches `@test` to redesign the tests. Apply Dispatch Hygiene. Fixed tests return to `@make` for fresh entry validation and a clean implementation attempt.
+   - **`production_logic`** — the test is sound; `@make`'s implementation is wrong or incomplete. Orchestrator re-dispatches `@make` with `@check`'s diagnostic notes attached.
+   - **`split_needed`** — the task is over-scoped; no realistic implementation can satisfy the AC within the task's stated files-to-modify. See "split_needed exit" below.
 
-For NOT_TESTABLE tasks, `@make` runs in standard mode.
+**Iteration limit on this loop: max 2 cycles.** If two cycles of `@check` diagnosis don't yield a clean `@make` Implementation Complete, the design problem is upstream — **decrement `PLAN_REWORK_REMAINING`** and revisit the Phase 3 plan. If `PLAN_REWORK_REMAINING` is already `0`, abort to the Failure Handler instead.
 
-After all tasks complete, verify overall integration:
-- Run the project's test suite if available
-- Run linting/type checking if configured
-- Fix any integration issues between tasks
+### split_needed exit (ADR-21)
+
+When `@check` diagnosis returns `split_needed` for task-1, **abort to the Failure Handler.** Rationale (Q19a per ADR-21): in the one-task-per-run model, task-1 is the only task in this invocation. No feature AC have been satisfied yet (any stub-pass commit is scaffolding, not feature work). Pre-filing a sub-issue from a botched plan would pollute `TODO/` with bad scoping the user has to manually clean up; the most likely upstream diagnosis is a plan-level scoping error, not a task-level over-scope.
+
+The Failure Handler's recovery procedure (ADR-14: discard worktree, delete branch, re-create from base, re-run) cleanly destroys the stub-pass commit and any in-progress body-pass changes. The user re-runs `/workflow` on the same parent issue; Phase 3/4/5 produce a fresh plan and split. Sub-issues filed at Phase 5.5 of the *previous* run remain in `TODO/` (they were committed there in the failed run only if Phase 9 reached the TODO commit, which by definition it didn't if Phase 7 invoked the Failure Handler) — typically they're gone with the discarded worktree.
+
+Concretely on `split_needed`:
+
+1. Write a Failure Handler summary noting `@check`'s diagnosis verbatim and the Phase 5 split that was attempted.
+2. Dispatch `@pm` to add a comment on `./TODO/$ISSUE_ID.md`: `- YYYY-MM-DD — split_needed at Phase 7 task-1; <one-line diagnosis>. Re-run after re-creating the worktree.`
+3. Stop execution. Do not commit code, do not file new sub-issues, do not stage anything under `.workflow/`.
 
 ---
 
 ## Phase 8: Final Review
 
-Apply **Dispatch Hygiene** to each reviewer prompt before sending. Dispatch `@check` and `@simplify` in parallel to review the full implementation (all changes across all files).
+Apply **Dispatch Hygiene** to each reviewer prompt before sending. Dispatch `@check` and `@simplify` in parallel to review the implementation. Because the run executes exactly one task (ADR-21), the diff is bounded by the task's scope (~50 lines per the Split Heuristic) and fits comfortably in reviewer context — no chunking needed.
 
 Provide reviewers with:
-- The absolute path to `$RUN_DIR/plan.md` (the same file Phase 4 reviewed; mid-loop revisions will have updated it in place)
-- The full diff (`git diff "$BASE_BRANCH"...HEAD`)
-- Any decisions or deviations from the plan, captured inline in the dispatch prompt
+- The absolute path to `$RUN_DIR/plan.md` (the same file Phase 4 reviewed; mid-loop revisions will have updated it in place).
+- The absolute path to `$RUN_DIR/task-1.md` (the spec the implementation actually targeted).
+- The full diff (`git diff "$BASE_BRANCH"...HEAD`).
+- Any decisions or deviations from the plan, captured inline in the dispatch prompt.
+- **NOT_TESTABLE manifest (ADR-18):** if task-1 went `NOT_TESTABLE` at Phase 6, the dispatch prompt includes a "Tasks completed without tests (NOT_TESTABLE)" section listing the `@test` justification and the `@check` sign-off rationale. Reviewers explicitly evaluate "does the justification still hold given the final diff?" and may BLOCK if it doesn't. If task-1 had tests (the common case), this section reads "None — task-1 has tests."
 
-**Review loop (max 3 cycles):**
-1. Send implementation to both reviewers
-2. Merge findings (same precedence rules as Phase 4)
-3. If ACCEPTABLE: proceed to Phase 9
-4. If issues found, route per the kind of finding — **the orchestrator does not write production code; `@make` does**:
-   - **`BLOCK`, behavioral, correctness, or test-quality findings:** build a new `@make` task spec from the finding (apply Dispatch Hygiene, finalized text, no draft answer). Dispatch `@make`. Do **not** fix directly. Every `BLOCK` is by definition behavioral and must round-trip through `@make`.
-   - **Strictly cosmetic findings** (typo in a comment, missing trailing newline, formatting that does not change the AST or behavior): the orchestrator may fix directly, then re-review. Anything compiler-detected (unused import, dead code) goes through `@make`, since removing it is still a code change.
+**Verdict authority** (ADR-15): same as Phase 4. `@check` is the only blocking reviewer; `@simplify`'s findings are recorded as advisory in the run summary but never trigger a re-dispatch loop.
+
+**Review loop (max 3 cycles, gated on `@check`):**
+1. Send implementation to both reviewers (dispatched in parallel).
+2. Merge findings: record `@simplify`'s output for the summary; act only on `@check`'s verdict.
+3. If `@check` returns ACCEPTABLE: proceed to Phase 9.
+4. If `@check` finds issues, route per the kind of finding — **the orchestrator does not write production code; `@make` does**:
+   - **`BLOCK`, behavioral, correctness, or production-code findings:** write a fix spec to `$RUN_DIR/task-fix-<N>.md` (1-indexed within this Phase 8 cycle, ADR-16). Apply Dispatch Hygiene, finalized text, no draft answer. Verify with `test -f` before dispatching. Dispatch `@make` with the absolute path. Do **not** fix directly. Every `BLOCK` is by definition behavioral and must round-trip through `@make`.
+   - **Test-quality / test-design findings:** route through the unified Implementation Incomplete diagnosis path (Phase 7) — `@check` diagnosis → `@test` redesign → fresh `@make` re-attempt against the existing task spec.
+   - **Plan-level finding:** **decrement `PLAN_REWORK_REMAINING`** and re-enter Phase 3 with the finding. If the counter is already `0`, abort to the Failure Handler.
+   - **Strictly cosmetic findings** (typo in a comment, missing trailing newline, formatting that does not change the AST or behavior): the orchestrator may fix directly, then re-review. Anything compiler-detected (unused import, dead code) goes through `@make` via a `task-fix-<N>.md`, since removing it is still a code change.
    - When in doubt, dispatch `@make`.
-5. **Convergence detection:** same findings twice = stop loop early
-6. If unresolved after 3 cycles: document blockers, proceed to commit anyway
+5. **Convergence detection:** same `@check` findings twice = stop loop early.
+6. If unresolved after 3 cycles: document blockers, proceed to commit anyway.
 
 ---
 
@@ -462,11 +515,16 @@ The workflow is forge-agnostic. It commits locally and stops. **Do not push, and
 - If changes are large/varied, use multiple atomic commits (one per logical unit)
 
 ### TODO Update
-- Dispatch `@pm` against the absolute `./TODO/` path. Ask it to:
-  - Set the issue file's frontmatter `status` to `Done` (or leave at `In Progress` if the run is incomplete and the user must verify before marking Done).
-  - Add a comment of the form: `- YYYY-MM-DD — Branch \`$BRANCH_NAME\`, commit <SHA> — <one-line summary>` (date from the shell, never fabricated).
-  - Propagate any status flip to the dependent index: `TODO/README.md` for top-level issues (`parent: null`), or the parent file's `## Sub-issues` line for sub-issues.
-- If acceptance-criteria checkboxes were addressed by the implementation, ask `@pm` to check them off (flip `- [ ]` to `- [x]` under `## Acceptance criteria`).
+
+Dispatch `@pm` against the absolute `./TODO/` path. Ask it to:
+
+1. **Check off the AC checkboxes that task-1 satisfied.** For each `- [ ]` AC line in `./TODO/$ISSUE_ID.md`'s `## Acceptance criteria` section that the implemented work fulfilled, flip to `- [x]`. The orchestrator decides which AC are satisfied by inspecting task-1's spec and verification output.
+2. **Set the issue's frontmatter `status` based on AC completion** (ADR-21, AC-driven):
+   - **All AC are now `[x]`** → `status: Done`.
+   - **Some AC remain `[ ]`** → `status: In Progress`. (Sub-issues filed at Phase 5.5 cover the unmet AC; the user runs them in subsequent invocations.)
+   - **No AC section in the file** → `status: Done` (the parent had no testable AC; one task ran end-to-end).
+3. **Propagate any status flip to the dependent index:** `TODO/README.md` for top-level issues (`parent: null`), or the parent issue file's `## Sub-issues` line for sub-issues.
+4. **Add a comment** of the form: `- YYYY-MM-DD — Branch \`$BRANCH_NAME\`, commit <SHA> — <one-line summary>` (date from the shell, never fabricated).
 
 ### File Follow-ups
 
@@ -512,11 +570,27 @@ If no follow-ups were filed, the commit message simplifies to `chore(todo): upda
 
 ## Failure Handling
 
-At any phase, if an unrecoverable error occurs:
+At any phase, if an unrecoverable error occurs (or a routing rule explicitly aborts to the Failure Handler — `PLAN_REWORK_REMAINING` exhausted, `split_needed` at Phase 7, etc.):
+
 1. Write `$RUN_DIR/summary.md` (creating `$RUN_DIR` first if it doesn't exist) with what was completed and what failed. Do **not** stage or commit anything under `.workflow/`.
 2. If any code was written, commit it with message `wip: incomplete workflow run for <issue-id>`. Stage code only — exclude `.workflow/` and `TODO/`.
 3. Leave the branch and worktree intact for the user to inspect — do not push, do not delete.
-4. Dispatch `@pm` against `./TODO/` to add a comment on the issue file (`./TODO/<ID>.md`) summarising what failed.
+4. Dispatch `@pm` against `./TODO/` to add a comment on the issue file (`./TODO/<ID>.md`) summarising what failed and naming the abort reason if it was a routing-rule abort (e.g. `split_needed at Phase 7 task-1`, `plan_rework_remaining exhausted at Phase 8`).
 5. Stop execution.
 
+### Recovery procedure (workflow is non-resumable, ADR-14)
+
+The workflow is **non-resumable**. There is no `--resume` mode and no idempotent re-run path. To retry after a Failure Handler invocation (or after a user-initiated cancellation):
+
+1. `git worktree remove <path>` — discard the failed worktree.
+2. Delete the feature branch: `git branch -D <branch>`. The Failure Handler's `wip:` commit (if any) is discarded with the branch.
+3. Re-create the worktree from `$BASE_BRANCH`: `git worktree add <path> -b <branch> <base-branch>`.
+4. Re-run `/workflow <ISSUE-ID>` from the fresh worktree.
+
+The throwaway-worktree model is the recovery story. Re-running on the same worktree without this cleanup risks committing partial state or appending duplicate `@pm` comments.
+
+### User-initiated cancellation
+
+User-initiated cancellation (Ctrl-C) follows the same procedure as automatic Failure Handler invocations: discard the worktree per the recovery procedure above. The orchestrator does not poll a soft-stop sentinel — runs are short enough (one task, ~10–30 min) that hard cancellation is fine.
+
 **Never hang on interactive prompts.** If any command appears to require input, treat it as a failure and follow the above procedure.
diff --git a/config/opencode/workflow-design.md b/config/opencode/workflow-design.md
index b33d566..6a8c332 100644
--- a/config/opencode/workflow-design.md
+++ b/config/opencode/workflow-design.md
@@ -36,32 +36,36 @@ One orchestrator, five subagents. The orchestrator runs in `agent: build` mode;
 
 ### 3.1 Phase pipeline
 
-High-level happy path with the major escalation arms.
+High-level happy path with the major escalation arms. The workflow runs **one task per invocation** (ADR-21): Phase 5 produces N task files; if N>1, tasks 2…N are filed as sub-issues and only task 1 runs through Phases 6–8.
 
 ```mermaid
 flowchart TD
-    P1["Phase 1: Sanity Check"]
+    P1["Phase 1: Sanity Check<br/>incl clean tree + depends-on"]
     P2["Phase 2: Issue Context<br/>pm reads TODO/ID.md"]
     P3["Phase 3: Plan<br/>write plan.md"]
-    P4{"Phase 4: Review Plan<br/>check + simplify<br/>max 3 cycles"}
+    P4{"Phase 4: Review Plan<br/>check blocking, simplify advisory<br/>max 3 cycles"}
     P5["Phase 5: Split into Tasks<br/>write task-N.md"]
-    P55{"Phase 5.5: Review Split<br/>check<br/>max 2 cycles"}
+    P55{"Phase 5.5: Review Split<br/>check, 6 questions<br/>max 2 cycles"}
+    P5F["File tasks 2..N as sub-issues<br/>only when N more than 1"]
     P6["Phase 6: Write Tests<br/>test, stub-first make"]
-    P7["Phase 7: Implement<br/>make"]
-    P7E{"Test-design escalation<br/>max 2 cycles"}
-    P8{"Phase 8: Final Review<br/>check + simplify<br/>max 3 cycles"}
-    P9["Phase 9: Commit + TODO + Follow-ups + Summary"]
+    P7["Phase 7: Implement<br/>make, single task"]
+    P7E{"Implementation Incomplete<br/>check diagnoses<br/>max 2 cycles"}
+    P7F["split_needed: Failure Handler<br/>(discard worktree, re-run)"]
+    P8{"Phase 8: Final Review<br/>check blocking, simplify advisory<br/>max 3 cycles"}
+    P9["Phase 9: Commit + TODO + Follow-ups + Summary<br/>parent status AC-driven"]
 
     P1 --> P2 --> P3 --> P4
     P4 -->|ACCEPTABLE| P5 --> P55
     P4 -->|NEEDS WORK or BLOCK| P3
-    P55 -->|ACCEPTABLE| P6 --> P7
+    P55 -->|ACCEPTABLE| P5F --> P6 --> P7
     P55 -->|NEEDS WORK| P5
     P55 -->|BLOCK plan-level| P3
     P7 --> P8
-    P7 -.->|escalate test_design| P7E
-    P7E -->|check then test then make| P7
+    P7 -.->|Implementation Incomplete| P7E
+    P7E -->|test_design or production_logic| P7
+    P7E -.->|split_needed| P7F
     P7E -.->|2 cycles exhausted| P3
+    P7F --> ABORT([Failure Handler])
     P8 -->|ACCEPTABLE| P9
     P8 -->|production-code finding| P7
     P8 -->|test-design finding| P7E
@@ -69,96 +73,114 @@ flowchart TD
     P9 --> END([Done])
 ```
 
+**Run-level cap:** `plan_rework_remaining` (default 1, ADR-13) decrements on every P5.5-BLOCK→P4, P7-escalation-exhaustion→P3, and P8-plan-level→P3 transition. Exhausted counter aborts to the Failure Handler.
+
 ### 3.2 Phase 7 escalation loop
 
-The pattern when `@make` cannot reach GREEN.
+The pattern when `@make` cannot reach GREEN. Unified diagnosis path (ADR-19): every Implementation Incomplete routes through `@check` test-diagnosis-first; `@check` returns one of three verdicts.
 
 ```mermaid
 stateDiagram-v2
     [*] --> Dispatched: orchestrator dispatches make
     Dispatched --> EntryCheck: run tests verify RED
     EntryCheck --> Implementing: failure code matches handoff
-    EntryCheck --> EntryEscalation: test-quality concern
+    EntryCheck --> CheckDiag: Implementation Incomplete
     Implementing --> GreenReached: tests pass within 2-3 attempts
-    Implementing --> MidEscalation: escalate test_design flag
-    Implementing --> MidStuck: incomplete no flag
-    MidStuck --> Implementing: re-dispatch with check notes 1 retry
-    MidStuck --> MidEscalation: still failing on retry
-    EntryEscalation --> CheckDiag
-    MidEscalation --> CheckDiag
-    CheckDiag --> TestRedesign: confirmed test-design error
-    CheckDiag --> Dispatched: rejected production issue
+    Implementing --> CheckDiag: Implementation Incomplete
+    CheckDiag --> TestRedesign: verdict test_design
+    CheckDiag --> Dispatched: verdict production_logic
+    CheckDiag --> FailureHandler: verdict split_needed
     TestRedesign --> Dispatched: test fixes fresh entry validation
     Dispatched --> PlanRevisit: 2 escalation cycles exhausted
     GreenReached --> [*]
-    PlanRevisit --> [*]: back to Phase 3
+    FailureHandler --> [*]: discard worktree, re-run
+    PlanRevisit --> [*]: back to Phase 3 if rework budget intact
 ```
 
 ### 3.3 Issue lifecycle
 
-How TODO entries move through statuses, with sub-issue filing during a run.
+How TODO entries move through statuses. In the one-task-per-run model (ADR-21), a single workflow invocation may file multiple sub-issues mid-run, and the parent's final status is AC-driven, not run-driven.
 
 ```mermaid
 stateDiagram-v2
     [*] --> Todo: issue file created
     Todo --> InProgress: Phase 2 workflow starts
-    InProgress --> Done: Phase 9 run completes
+    InProgress --> Done: Phase 9 - all parent AC checked
+    InProgress --> InProgress2: Phase 9 - some parent AC remain
     InProgress --> Todo: workflow fails, failure handler adds comment
 
+    note right of InProgress2
+        Parent stays In Progress when sub-issues
+        cover the unmet AC. User runs sub-issues
+        in subsequent /workflow invocations.
+    end note
+
     note right of InProgress
-        New sub-issues may be filed during Phase 9
-        with parent ISSUE_ID, status Todo
-        and label bug, followup, or tech-debt
+        Sub-issues filed during a run carry:
+        - parent: ISSUE_ID, status: Todo
+        - label: bug, followup, tech-debt, or split-from-run
+        - depends-on: [...] for cross-sub-issue ordering
+        - rich seed body for split-time filings (ADR-21)
     end note
 
     Done --> [*]
+    InProgress2 --> [*]
 ```
 
 ---
 
 ## 4. Routing Matrix
 
-Every observed `(phase, signal) → action`. Empty cells are gaps. Walking this table is the cheap way to spot routing issues like the recent Phase 7 mid-implementation escalation.
+Every observed `(phase, signal) → action`. Empty cells are gaps. Walking this table is the cheap way to spot routing issues.
 
 | Phase | Signal source | Signal | Action |
 |---|---|---|---|
 | 1 | Sanity checks | Bare repo / detached HEAD / missing `TODO/<ID>.md` / branch == base | Stop with error |
+| 1 | Sanity checks | Working tree dirty (`git status --porcelain` non-empty) | Stop with error (ADR-20) |
+| 1 | Sanity checks | `depends-on:` issue not in `Done` status | Stop with error (ADR-21) |
 | 2 | `@pm` | Issue not found | Stop with error |
 | 2 | `@pm` | Status is `Todo` | Flip to `In Progress`; propagate to README.md / parent's Sub-issues |
 | 3 | Orchestrator | Plan drafted | Apply Dispatch Hygiene; write `plan.md`; verify `test -f` |
-| 4 | `@check` + `@simplify` | Both ACCEPTABLE | Proceed to Phase 5 |
-| 4 | Either reviewer | NEEDS WORK | Edit `plan.md` in place; re-dispatch (max 3 cycles) |
+| 4 | `@check` | ACCEPTABLE (regardless of `@simplify`) | Proceed to Phase 5 |
+| 4 | `@check` | NEEDS WORK | Edit `plan.md` in place; re-dispatch (max 3 cycles) |
 | 4 | `@check` | BLOCK | Edit `plan.md` addressing the finding; re-dispatch |
-| 4 | Reviewers | Same finding twice | Convergence detected; stop loop early |
+| 4 | `@simplify` | Any verdict (ADR-15) | Advisory only — record in summary; never blocks Phase 4 progression |
+| 4 | Reviewers | Same `@check` finding twice | Convergence detected; stop loop early |
 | 4 | Reviewers | Unresolved after 3 cycles | Document blockers in summary; proceed |
 | 5 | Orchestrator | Tasks drafted | Apply Dispatch Hygiene; write each `task-N.md`; verify `test -f` for every N |
-| 5.5 | `@check` | ACCEPTABLE | Proceed to Phase 6 |
+| 5.5 | `@check` | ACCEPTABLE, N=1 | Skip P5.5 entirely (ADR-21); proceed to Phase 6 — degenerate split |
+| 5.5 | `@check` | ACCEPTABLE, N>1 | File tasks 2…N as sub-issues with rich seed bodies (ADR-21) via `@pm`; proceed to Phase 6 with task-1 only |
 | 5.5 | `@check` | NEEDS WORK | Edit `task-N.md` in place; re-dispatch (max 2 cycles) |
-| 5.5 | `@check` | BLOCK | Plan doesn't decompose cleanly; back to Phase 4 |
+| 5.5 | `@check` | BLOCK plan-level | Edit `plan.md` addressing the BLOCK finding; decrement `plan_rework_remaining`; re-enter Phase 4 (ADR-17) |
+| 5.5 | Run-level | `plan_rework_remaining` exhausted | Abort to Failure Handler (ADR-13) |
 | 6 | `@test` | TESTS_READY + `escalate_to_check: false` | Proceed to Phase 7 |
 | 6 | `@test` | TESTS_READY + `escalate_to_check: true` | `@check` light review → `@test` fixes → forward |
-| 6 | `@test` | NOT_TESTABLE (general) | `@check` sign-off; task goes to `@make` without tests |
+| 6 | `@test` | NOT_TESTABLE (general) | `@check` sign-off; task goes to `@make` without tests; record in NOT_TESTABLE manifest for Phase 8 (ADR-18) |
 | 6 | `@test` | NOT_TESTABLE: Missing testability seam | `@make` adds the seam; re-run `@test` |
 | 6 | `@test` | BLOCKED | Investigate; may need spec or plan revision |
 | 6 | `@test` (stub-first) | All tests pass with zero `todo!()` panics | Reject — structural-only tests; route back to `@test` to rewrite |
 | 7 | `@make` | Implementation Complete | Proceed to Phase 8 |
-| 7 | `@make` | Implementation Incomplete + entry-validation flag | `@check` (test diagnosis) → `@test` (fixes) → fresh `@make` |
-| 7 | `@make` | Implementation Incomplete + `escalate: test_design` | Same path; max 2 escalation cycles |
-| 7 | `@make` | Implementation Incomplete (no flag) | Re-dispatch with `@check` notes once; if 2nd attempt fails, treat as `escalate: test_design` |
-| 7 | Escalation loop | 2 cycles exhausted | Back to Phase 3 (plan revisit) |
-| 8 | `@check` + `@simplify` | ACCEPTABLE | Proceed to Phase 9 |
-| 8 | `@check` | BLOCK / behavioral / production-code finding | New `@make` task spec from finding; dispatch (max 3 cycles) |
-| 8 | `@check` | BLOCK / test-design / test-quality finding | `@check` → `@test` → `@make` re-verify |
-| 8 | `@check` | BLOCK / plan-level finding | Back to Phase 3 with the finding |
-| 8 | `@simplify` | Advisory | Record in summary's "Advisory notes (not filed)" |
+| 7 | `@make` | Implementation Incomplete (any flag or no flag) | Route through `@check` test-diagnosis-first (ADR-19); orchestrator follows `@check`'s verdict |
+| 7 | `@check` diagnosis | `test_design` | Dispatch `@test` to redesign tests; fresh `@make` re-attempt |
+| 7 | `@check` diagnosis | `production_logic` | Re-dispatch `@make` with `@check`'s production-side notes |
+| 7 | `@check` diagnosis | `split_needed` | Abort to Failure Handler (ADR-21 / Q19a). In the one-task-per-run model task-1 is the only task; no AC have been satisfied; recovery is "discard worktree, re-plan from scratch." `@pm` adds a comment recording the diagnosis. |
+| 7 | Escalation loop | 2 cycles exhausted | Decrement `plan_rework_remaining`; back to Phase 3 (plan revisit) |
+| 8 | `@check` | ACCEPTABLE | Proceed to Phase 9 |
+| 8 | `@check` | BLOCK / behavioral / production-code finding | Write `task-fix-<N>.md` to `$RUN_DIR/` (ADR-16); dispatch `@make` against it (max 3 cycles) |
+| 8 | `@check` | BLOCK / test-design / test-quality finding | Route through `@check` diagnosis → `@test` → `@make` re-verify |
+| 8 | `@check` | BLOCK / plan-level finding | Decrement `plan_rework_remaining`; back to Phase 3 with the finding |
+| 8 | `@simplify` | Any verdict (ADR-15) | Advisory only — record in summary; never blocks Phase 8 progression |
 | 8 | Reviewers | Strictly cosmetic finding (typo, missing newline, AST-preserving) | Orchestrator fixes directly; re-review |
+| 8 | Reviewers | NOT_TESTABLE manifest task flagged as questionable | Apply same routing as a normal `@check` finding for that task |
 | 8 | Review loop | Same finding twice | Convergence; stop loop |
 | 8 | Review loop | 3 cycles exhausted | Document blockers; proceed |
 | 9 | Orchestrator | Pre-existing bug, out of scope | File sub-issue via `@pm` (label: `bug`) |
 | 9 | Orchestrator | Unresolved review-loop blocker | File sub-issue via `@pm` (label: `followup`) |
 | 9 | `@test` (Phase 6) | NOT_TESTABLE future-seam note | File sub-issue via `@pm` (label: `tech-debt`) |
 | 9 | Orchestrator | `@simplify` advisory not acted on | Record in summary; do NOT file (records, not work) |
-| 9 | Orchestrator | All commits done | Set issue status to `Done`; sync README/parent; commit `chore(todo): …` |
+| 9 | Orchestrator | All parent AC checked off | Set issue status to `Done`; sync README/parent; commit `chore(todo): …` |
+| 9 | Orchestrator | Some parent AC remain unchecked AND sub-issues exist | Leave issue at `In Progress`; commit `chore(todo): …` |
+| Run-level | Failure Handler | Workflow is non-resumable (ADR-14) | Document the cleanup procedure: `git worktree remove`, delete branch, re-create from base, retry |
 
 ---
 
@@ -215,6 +237,8 @@ ADR-flavoured. New decisions append at the end. If a decision is later reversed
 **Alternatives:** accept compile-error RED; let `@make` write tests + bodies in one pass; allow `@test` to add stubs to production source.
 **Consequences:** two atomic commits per affected task (`feat: scaffold X with todo!() stubs`, then `feat: implement X`). Stub-pass scope is tight: bodies are exactly `todo!()`, signatures must match the planned final API. Phase 6 also adds a mandatory panic-coverage check after `@test`: every test must panic on `todo!()` to prove it actually exercises the stubbed symbols (catches structural-only tests).
 
+**On reviewer bypass:** the stub-pass commit is not sent through Phase 5.5 or Phase 8 review. The bypass is intentional and safe because (a) stubs are mechanical — signatures plus `todo!()`, no logic; (b) the body-pass commit *is* reviewed and the body-pass diff strictly subsumes the stub-pass diff (the same signatures, now with bodies); (c) Phase 6's mandatory panic-coverage check is what actually validates that the stubs are exercised. Reviewing the stub-pass would duplicate work that the body-pass review catches anyway.
+
 ### ADR-8 (2026-05-08) — `@test` may write inside `#[cfg(test)] mod` blocks
 
 **Context:** Rust unit tests live colocated in production source files inside `#[cfg(test)] mod tests { … }` blocks — the canonical idiom, not an edge case. Original `@test` File Constraint forbade `src/` writes entirely, which forced `@make` to write both production code and tests in a single dispatch. This lost the RED→GREEN separation that TDD relies on.
@@ -248,7 +272,85 @@ ADR-flavoured. New decisions append at the end. If a decision is later reversed
 **Context:** Phase 7's escalation rule was gated on `@make` flagging concerns *during entry validation* (the RED check before implementing). When `@make` got past entry validation, started implementing, and then ground for 2-3 attempts because the test demanded impossible production code, the orchestrator had no documented route — it would re-dispatch `@make` with marginal context tweaks instead of recognizing the diagnosis as test-architecture failure.
 **Decision:** split Phase 7's escalation into entry-validation and mid-implementation paths. `@make` reports `escalate: test_design` when its iteration limit is reached and the test seems to demand impossible / unreasonable code. Both paths route through `@check` (test diagnosis) → `@test` (redesign) → fresh `@make` dispatch. Max 2 escalation cycles before reverting to Phase 3 plan revisit.
 **Alternatives:** status quo; let `@make` modify test files itself.
-**Consequences:** faster recovery from test-design errors. Bounded loop prevents thrashing. `@make.md` Iteration Limits section gains a new red-flag class.
+**Consequences:** faster recovery from test-design errors. Bounded loop prevents thrashing. `@make.md` Iteration Limits section gains a new red-flag class. *Superseded in part by ADR-19 (unified diagnosis path).*
+
+### ADR-13 (2026-05-08) — Run-level `plan_rework_remaining` counter
+
+**Context:** several routes return control to an upstream phase when downstream signals reveal the upstream artifact was wrong: P5.5-BLOCK→P4 (split doesn't decompose), P7-escalation-exhaustion→P3 (test/code thrash exceeded its bound), P8-plan-level→P3 (final review exposes a plan defect). Each upstream phase has its own per-loop cycle cap (P4 max 3, P5.5 max 2, etc.), but those caps reset on every re-entry — so a run could in principle thrash P3↔P4↔P5.5↔P3 indefinitely without violating any local rule.
+**Decision:** introduce one run-level counter, `plan_rework_remaining`, default value `1`. It decrements on every transition where downstream signal forces upstream rework: `P5.5 BLOCK → P4`, `P7 escalation exhausted → P3`, `P8 plan-level finding → P3`. When the counter is `0` and another such transition fires, abort to the Failure Handler instead of re-entering. Per-phase cycle caps are unchanged.
+**Alternatives:** (a) a global `max_subagent_dispatches` budget — over-engineered for the specific failure mode; (b) document the resets as intentional and rely on convergence detection — leaves the bug present.
+**Consequences:** at most two plan attempts per run (the initial plan plus one revision). Failure Handler invocation distinct in cause from earlier-phase aborts: the cleanup is the same (per ADR-14) but the summary explains *which* downstream signal exhausted the budget.
+
+### ADR-14 (2026-05-08) — Workflow is non-resumable
+
+**Context:** Phase 9 has multiple sub-steps (code commit → `@pm` status update → file follow-ups → TODO commit → summary). Crashing between any two sub-steps leaves the worktree in a state that earlier docs called "partial." The original Failure Handler did not flip status back, did not recognize partial-Phase-9 separately from earlier-phase crashes, and re-running `/workflow` after a crash could append new comments and re-do work indefinitely.
+**Decision:** declare the workflow non-resumable. On any failure (Failure Handler invocation), the recovery procedure is: `git worktree remove` the failed worktree, delete the feature branch, re-create the worktree from `$BASE_BRANCH`, then re-run `/workflow`. Document this explicitly in the Failure Handler section. The throwaway-worktree model means there is no in-place resume state to corrupt — the user discards the worktree and starts fresh.
+**Alternatives:** (a) smarter Failure Handler that cleans up partial state idempotently; (b) transactional Phase 9 via a state file; (c) idempotent sub-steps so re-runs auto-resume.
+**Consequences:** simplest possible recovery model. Phase 9 sub-step ordering doesn't need to be defended against partial failures — partial state is acceptable because the recovery is "discard everything and re-run." User-initiated cancellation (Ctrl-C) follows the same procedure.
+
+### ADR-15 (2026-05-08) — `@simplify` is advisory at every gate
+
+**Context:** the Phase 4 routing matrix used to read "Either reviewer NEEDS WORK → re-dispatch the loop," giving `@simplify` veto power equivalent to `@check`'s. Phase 8's matrix said `@simplify` was advisory only ("Record in summary's 'Advisory notes (not filed)'"). Same agent, two different powers.
+**Decision:** `@simplify` is advisory at every gate. Its findings are recorded in the run summary; they never force a re-dispatch loop. `@check` is the only reviewer with veto authority (NEEDS WORK / BLOCK).
+**Alternatives:** (a) make `@simplify` blocking everywhere — too heavy for a heuristic agent prone to false positives; (b) keep the asymmetry and document a principle — fragile.
+**Consequences:** uniform model — `@check` enforces correctness, `@simplify` advises on shape. Phase 4 review loops only run on `@check` findings; `@simplify` complexity flags get logged in the summary like at Phase 8. The user can manually promote a `@simplify` finding if it matters.
+
+### ADR-16 (2026-05-08) — Phase 8 fix specs go to disk
+
+**Context:** when Phase 8 review surfaced a behavioral or production-code finding, the orchestrator would "build a new `@make` task spec from the finding" and dispatch it inline. That violates ADR-6's invariant (run artifacts on disk, no inline paraphrase) — and exactly when it matters most, because Phase 8 has up to 3 review cycles and the same finding can re-dispatch.
+**Decision:** Phase 8 fix dispatches write a new artifact `$RUN_DIR/task-fix-<N>.md` (1-indexed within the Phase 8 cycle) before dispatching `@make`. Same Dispatch Hygiene rules as Phase 5 task specs, same `test -f` verification. Cosmetic findings (orchestrator fixes directly per workflow.md) skip the file — only `@make`-dispatched findings get one.
+**Alternatives:** (a) inline in the dispatch prompt with an ADR-6 footnote — erodes the invariant for the highest-risk dispatch class; (b) edit the original `task-N.md` — muddies the audit trail of an already-met spec.
+**Consequences:** ADR-6's invariant holds end-to-end. Phase 8 cycles re-dispatch against the same on-disk file (mid-loop edits in place), eliminating paraphrase drift across review cycles.
+
+### ADR-17 (2026-05-08) — Phase 5.5 BLOCK protocol
+
+**Context:** Phase 5.5 BLOCK ("plan does not decompose cleanly") used to route "back to Phase 4 with `@check`'s finding," but `@check` at 5.5 evaluated the *split*, not the plan; its finding may not map cleanly to a plan edit. Re-entering P4 with the same `plan.md` and a finding tagged on the prompt asks the wrong question.
+**Decision:** on P5.5 BLOCK, the orchestrator translates the split-level finding into a concrete `plan.md` edit (e.g. "the plan conflates structural and runtime work; split into two milestones"), saves the edit, decrements `plan_rework_remaining` (per ADR-13), and re-dispatches Phase 4 reviewers against the *revised* plan. P4 reviewers see a genuinely different plan.
+**Alternatives:** (a) re-dispatch P4 unchanged with finding attached — burns reviewers on a known-broken plan; (b) treat P5.5 BLOCK as terminal — too strict, we have the rework budget for one revisit.
+**Consequences:** P5.5 BLOCK is an effective signal. The orchestrator's plan-edit step is mandatory; skipping it is a routing error. Run-level rework budget bounds the loop.
+
+### ADR-18 (2026-05-08) — Phase 8 NOT_TESTABLE manifest
+
+**Context:** Phase 6 routes NOT_TESTABLE tasks through `@check` for sign-off, then dispatches `@make` without tests. Phase 8 reviews the diff but has no signal that "this change has no test because `@test` claimed it untestable." If `@check` at P6 was wrong, untested code ships.
+**Decision:** Phase 8's dispatch prompt includes a "Tasks completed without tests (NOT_TESTABLE)" section listing each task ID, the `@test` justification, and the `@check` sign-off rationale. Reviewers explicitly evaluate "does the justification still hold given the final diff?" If a reviewer pushes back, routing follows the normal Phase 8 finding rules.
+**Alternatives:** (a) double-up `@check` + `@simplify` at P6 NOT_TESTABLE granting — doubles dispatch cost without targeting the actual gap; (b) restrict NOT_TESTABLE to a fixed taxonomy — won't generalize across languages; (c) reject NOT_TESTABLE entirely — ignores legitimate cases.
+**Consequences:** pure plumbing change. P8 reviewers gain visibility into the bypass without new agents or new authority.
+
+### ADR-19 (2026-05-08) — Unified Implementation Incomplete diagnosis path
+
+**Context:** ADR-12 introduced three paths for `@make` reporting Implementation Incomplete: entry-validation flag, mid-impl `escalate: test_design` flag, no flag (re-dispatch with `@check` notes once, escalate after second failure). Three paths converging on the same destination (`@check` test-diagnosis → `@test` redesign or `@make` re-dispatch) added matrix surface and obscured the routing.
+**Decision:** every Implementation Incomplete from `@make` routes through `@check` test-diagnosis-first. `@check` returns one of three verdicts — `test_design` (route to `@test` redesign), `production_logic` (re-dispatch `@make` with `@check`'s notes), or `split_needed` (per ADR-21). `@make`'s self-diagnosis flag becomes a *hint* for `@check`, not a control-flow input for the orchestrator.
+**Alternatives:** (a) keep three paths, tighten what `@check` reviews in each — preserves the surface area; (b) push burden to `@make` — orchestrator still needs to gate via `@check`.
+**Consequences:** routing logic shrinks. Matrix has fewer rows. ADR-12's split-into-two-paths is partially superseded — the *escalation diagnosis* unified, the iteration limit (max 2 cycles) preserved.
+
+### ADR-20 (2026-05-08) — Phase 1 working-tree cleanliness check
+
+**Context:** Phase 1 verified non-bare repo, branch identity, base branch, issue file presence — but not that the working tree was clean. Stale uncommitted edits would be swept into the Phase 9 commit (workflow.md stages "code changes only" but doesn't distinguish *which* code) or a `wip:` failure commit.
+**Decision:** Phase 1 runs `git status --porcelain`; if non-empty, stop with: "Working tree must be clean. Commit or stash uncommitted changes before running the workflow."
+**Alternatives:** (a) capture initial dirty state, stage only files modified by the workflow at Phase 9 — error-prone baseline tracking; (b) document the requirement, don't enforce — `// TODO: don't forget` in design-doc form.
+**Consequences:** matches the ADR-14 throwaway-worktree model. One additional sanity-check line. User's "but I have manual edits I want the workflow to build on" case is solved by them committing those edits first, which is what they should do anyway.
+
+### ADR-21 (2026-05-08) — One-task-per-run model
+
+**Context:** the workflow originally executed N tasks per run, sequentially through Phase 7. That introduced cross-task regression risk (task 4 breaks task 1's tests, found N tasks late), big-diff Phase 8 reviews (multi-day branches accumulate thousands of diff lines that hit reviewer context limits silently), and the mid-flight task-split problem (when `@make` discovers task N is over-scoped, no documented route to re-split). It also coupled the workflow's success to "all N tasks complete," when in practice an issue worth one good commit shouldn't depend on unrelated downstream work succeeding.
+**Decision:** every workflow run executes **exactly one task** through Phases 6–8. Phase 5 still splits the plan into N tasks via the Split Heuristic. If N=1, proceed normally. If N>1, the orchestrator dispatches `@pm` to file tasks 2…M as TODO sub-issues *before* Phase 6 starts, and only task 1 runs through Phases 6–8. If task 1 itself reports `split_needed` mid-Phase-7, abort to the Failure Handler (Q19a: in the one-task-per-run model task-1 is the only task in the run, so no feature AC have been satisfied; recovery is the standard non-resumable cleanup from ADR-14).
+
+The model carries five sub-decisions:
+
+1. **Sub-issue body schema for split-time filings:** rich seed body that lets a fresh `/workflow` invocation re-plan and implement without seeing siblings or the original `plan.md`. Includes task description + AC + Code Context + Integration Contracts (declared in frontmatter as `depends-on: [...]`) + relevant slice of `plan.md` + Test Design section if present + a "Discovered during run on `$BRANCH_NAME` for parent issue `$ISSUE_ID`" attribution paragraph.
+2. **Phase 5.5 review questions strengthen to six**: coverage, no overlap, single-purpose, integration contracts (with stronger bar — must be self-contained for cross-session use), testable AC, and *self-containment* (is each task spec runnable as a standalone `/workflow` invocation?). Self-containment is the new load-bearing question because each filed sub-issue runs in isolation.
+3. **Split Heuristic recalibration**: keep the existing mechanical thresholds (>2 concerns, >50 lines across >2 files, mixes structural + runtime, etc.) but add a "default to no split" tiebreaker — when in doubt, do not split, because splitting now fans out across user sessions with full orchestration overhead per sub-issue.
+4. **Parent issue status is AC-driven**: Phase 9's existing AC checkbox logic (workflow.md flips ticked AC) determines status. If all parent AC are checked → `Done`; if some remain unchecked → stays `In Progress` with the filed sub-issues covering the remaining work.
+5. **`depends-on:` frontmatter and Phase 1 enforcement**: `@pm` schema gains a `depends-on: [<ID>, ...]` list. Phase 1 sanity check refuses to start if any listed dependency is not `Done`. Hard block — soft-warn means the user (who has walked away) doesn't see the warning until later.
+
+**Auto-resolved problems:**
+- Mid-flight task split (formerly Q2 in Open Questions, ADR-12's adjacent gap): collapses into "file as sub-issue and exit."
+- Big-diff Phase 8 reviews: one task = bounded diff (~50 lines per Split Heuristic). No big-diff problem possible.
+- Cross-task regression within a run: no cross-task regressions possible inside a single-task run; subsequent sub-issue runs detect them at their own Phase 7 entry validation (which runs the project's test suite).
+- Skip-P5.5-when-N=1 optimization: trivially satisfied — N=1 from Phase 6 onward in every run.
+
+**Alternatives:** (a) keep N-task runs, add mid-flight re-splitting via P7→P5 re-entry — doesn't solve big-diff or cross-task regression; (b) keep N-task runs, accept the gaps — leaves three known-bad routes; (c) always one task per issue (skip Phase 5 entirely) — loses the planning-phase split heuristic that's catching legitimate over-scoping at design time.
+**Consequences:** runs become shorter and more focused. Each commit/PR carries a bounded scope. Sub-issue fan-out becomes the primary scaling mechanism for multi-step work. `TODO/` sees more sub-issue files; `@pm`'s split-time filing path becomes a hot code path. Concurrent runs in different worktrees on the same repo become trivially safe because each worktree has its own `TODO/` checkout (file conflicts surface as standard git merge conflicts at integration time, not as mid-run race conditions).
 
 ---
 
@@ -260,20 +362,28 @@ When a question gets answered, move it to the [Design decisions log](#5-design-d
 
 Currently Phase 5.5 reviews the **split** (coverage, overlap, single-purpose, integration contracts, testable AC). It does *not* explicitly evaluate whether the test approach implied by each task spec is sound. That would partially overlap with Phase 4 (which has a plan-level Test Design section the reviewers evaluate). If a test-design error escapes Phase 4 and is encoded in a task spec, it surfaces at Phase 7 via the mid-impl escalation (ADR-12) — but earlier detection might be cheaper. Open: should Phase 5.5 add "test approach for each task is sound" as a sixth review question, or is that scope creep into Phase 4 territory?
 
-### Q2: How does the orchestrator handle "split heuristic violated only after attempting a task"?
+### ~~Q2~~: Mid-flight task split — *closed by ADR-21*
 
-Phase 5's Split Heuristic catches obvious over-/under-split cases at planning time. But sometimes a task that *looked* single-purpose during planning turns out to mix structural and runtime work only when `@make` starts implementing it. There's no documented mid-Phase-7 routing for "this task needs to be split now." Currently `@make` would either thrash (mid-impl escalation, ADR-12), or report the spec is ambiguous (Insufficient Context Protocol in `make.md`). Open: should there be a "split mid-flight" route that takes the task back to Phase 5 for re-splitting?
+The one-task-per-run model collapses this question. When `@make` discovers task-1 is over-scoped, the unified diagnosis path (ADR-19) returns `split_needed` from `@check`, and the orchestrator aborts to the Failure Handler (no P5 re-entry, no sub-issue filing — the recovery is "discard worktree, re-plan from scratch"). Tasks 2…M are already filed as sub-issues at Phase 5.5 acceptance, so there's no "remaining tasks" cleanup to think about.
 
-### Q3: Phase 9 has no rollback for partial commits if it fails between sub-steps
+### ~~Q3~~: Phase 9 partial-commit rollback — *closed by ADR-14*
 
-Phase 9's order is: code commit → TODO update → file follow-ups → commit TODO changes → write summary. If the workflow crashes between code commit and TODO commit, the worktree has the code change but the issue file still says `In Progress`. The Failure Handler covers earlier-phase crashes but Phase-9-internal partial states aren't explicitly addressed. Open: should the Failure Handler distinguish "Phase 9 partial" and resume from the right sub-step on retry, or is leaving manual cleanup to the user good enough?
+The workflow is non-resumable. Phase 9 partial states are addressed by the throwaway-worktree recovery procedure: discard the worktree, delete the branch, re-create from base, re-run. Phase 9 sub-step ordering doesn't need to defend against partial failures because the recovery is "discard everything and re-run."
 
 ### Q4: `@simplify` not involved at Phase 5.5 — is that the right call?
 
-Phase 5.5 only dispatches `@check`. Rationale (ADR-9) is that split review is structural, not complexity. But `@simplify`'s lens — "what if we deleted this?" — could legitimately catch unnecessary tasks (e.g. a third task that adds an abstraction nothing else needs). Open: is the cost of one more dispatch worth the catch?
+Phase 5.5 only dispatches `@check`. Rationale (ADR-9) is that split review is structural, not complexity. But `@simplify`'s lens — "what if we deleted this?" — could legitimately catch unnecessary tasks (e.g. a third task that adds an abstraction nothing else needs). With ADR-21's one-task-per-run pivot, this question gains a different angle: a `@simplify` flag on a sibling sub-issue at Phase 5.5 could prevent filing a wasteful sub-issue, which is more valuable than catching the same redundancy at Phase 8 of a future run. Open: is the cost of one more dispatch worth the catch, especially now that Phase 5.5 is the gate for sub-issue fan-out?
 
 ### Q5: Test-design loop bound vs plan-revisit threshold
 
 ADR-12 sets max 2 cycles for the Phase 7 test-design escalation before reverting to Phase 3 plan revisit. The plan-review and final-review loops have max 3. Why the asymmetry? The test-design loop is more expensive per cycle (`@check` + `@test` + `@make` re-implement vs. just reviewers + plan edit), so 2 may be right. But the choice was made by feel, not measured. Open: is 2 the right number, or should it match Phase 4 / Phase 8 at 3?
 
+### Q6: Sub-issue ordering in the parent's `## Sub-issues` list
+
+ADR-21's split-time filing creates new sub-issues with `depends-on:` declarations, but the parent's `## Sub-issues` list (rendered by `@pm`) is currently flat. When dependencies form a chain (sub-issue 2 depends on 1), the user has to read the chain from each sub-issue's frontmatter. Open: should `@pm` render the parent's sub-issue list in dependency order, with a visible indicator (e.g. indentation or `↳`) for dependent items? Cosmetic but would speed up "what to run next" decisions.
+
+### Q7: Concurrent-worktree edge case — sub-issue ID collisions
+
+Two parallel runs in different worktrees, each filing sub-issues, can both pick the same next ID (e.g. both pick `GAL-42` because both saw `GAL-41` as the highest at start). On merge, git surfaces this as a conflict over `TODO/GAL-42.md` content (two different files staked on the same name). Recoverable but annoying. Open: should `@pm`'s ID generation use a strategy that's safer under concurrent runs (e.g. timestamp suffix, branch-prefix, content-addressable), or accept the merge-conflict-on-collision cost given the one-user assumption?
+
 ---

From 3e515d54ebcd707f9f3c129265fd67a642c8ec4f Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Fri, 8 May 2026 13:24:30 +0200
Subject: [PATCH 094/101] feat(opencode): allow agents to read external Rust
 crate source

@make, @test, @check often need to inspect dependency source (trait
definitions, impl details, test patterns) to inform implementation or
verify findings. Opencode applies a CWD check on tool access, so reads
outside the worktree previously prompted for each access.

- Add permission.read/grep/glob path allowlists for the three locations
  cargo deps live: ~/.cargo/registry/src/, ~/.cargo/git/checkouts/, and
  /nix/store/*-vendor-*/ for crane / buildRustPackage projects.
- Document the discovery pattern in each agent: `cargo metadata
  --format-version 1` returns absolute paths via packages[].manifest_path.
- Cross-reference the registry paths from the permission.bash allowlist
  comment so future readers see the bash inspection commands (rg/ls)
  intentionally accept paths outside CWD.
- @check gets its first permission block (was tools-only before).

Path-pattern syntax for read/grep/glob isn't fully documented; if
opencode rejects it, fall back to `permission: { external_directory:
allow }` at the project config level.
---
 config/opencode/agents/check.md | 28 ++++++++++++++++
 config/opencode/agents/make.md  | 59 +++++++++++++++++++++++++++++++++
 config/opencode/agents/test.md  | 42 +++++++++++++++++++++++
 3 files changed, 129 insertions(+)

diff --git a/config/opencode/agents/check.md b/config/opencode/agents/check.md
index 18210dd..7fbc7b1 100644
--- a/config/opencode/agents/check.md
+++ b/config/opencode/agents/check.md
@@ -6,6 +6,24 @@ tools:
   write: false
   edit: false
   bash: false
+permission:
+  # ── External-directory reads (registry / git deps / nix-vendored) ──
+  # Opencode applies a CWD check on tool access; these patterns whitelist
+  # the cargo dependency source trees so the Read/Grep/Glob tools don't
+  # prompt for each access. @check sometimes needs to verify a finding
+  # against a dependency's actual source (trait bounds, impl details).
+  read:
+    "~/.cargo/registry/src/**": allow
+    "~/.cargo/git/checkouts/**": allow
+    "/nix/store/*-vendor-*/**": allow
+  grep:
+    "~/.cargo/registry/src/**": allow
+    "~/.cargo/git/checkouts/**": allow
+    "/nix/store/*-vendor-*/**": allow
+  glob:
+    "~/.cargo/registry/src/**": allow
+    "~/.cargo/git/checkouts/**": allow
+    "/nix/store/*-vendor-*/**": allow
 ---
 
 
@@ -15,6 +33,16 @@ You are a senior engineer who catches expensive mistakes before they ship. Your
 
 **Note:** This agent reviews user-provided artifacts (diffs, specs, configs). It does not independently fetch code from repos.
 
+**External crate source (Rust):** when verifying a finding against a dependency's actual source (trait bounds, impl details, behavior under specific inputs), you can read from these paths via Read/Grep/Glob (no permission prompt — see frontmatter):
+
+| Source | Path pattern |
+|---|---|
+| Registry crates | `~/.cargo/registry/src/index.crates.io-*/<crate>-<version>/` |
+| Git deps | `~/.cargo/git/checkouts/<crate>-<hash>/<branch>/` |
+| Nix-vendored deps | `/nix/store/<hash>-vendor-*/<crate>-<version>/` |
+
+The caller (`@check`'s dispatcher in the workflow) typically passes the dependency's name and version inline; you locate the path under the registry root. Use this sparingly — only when the finding's correctness genuinely depends on knowing the dep's source, not for general curiosity.
+
 ## Scope
 
 You review:
diff --git a/config/opencode/agents/make.md b/config/opencode/agents/make.md
index a9f0013..7e9f270 100644
--- a/config/opencode/agents/make.md
+++ b/config/opencode/agents/make.md
@@ -6,6 +6,23 @@ tools:
   edit: true
   bash: true
 permission:
+  # ── External-directory reads (registry / git deps / nix-vendored) ──
+  # Opencode applies a CWD check on tool access; these patterns whitelist
+  # the cargo dependency source trees so the Read/Grep/Glob tools (and
+  # bash inspection commands like `rg`/`ls`) don't prompt for each access.
+  # See "Reading External Crate Source" below for the discovery pattern.
+  read:
+    "~/.cargo/registry/src/**": allow
+    "~/.cargo/git/checkouts/**": allow
+    "/nix/store/*-vendor-*/**": allow
+  grep:
+    "~/.cargo/registry/src/**": allow
+    "~/.cargo/git/checkouts/**": allow
+    "/nix/store/*-vendor-*/**": allow
+  glob:
+    "~/.cargo/registry/src/**": allow
+    "~/.cargo/git/checkouts/**": allow
+    "/nix/store/*-vendor-*/**": allow
   bash:
     # Default deny
     "*": deny
@@ -25,6 +42,12 @@ permission:
     "cargo": allow
 
     # ── Read-only inspection ──
+    # The wildcarded patterns below accept any path argument, including
+    # paths *outside* the worktree. This is intentional — see "Reading
+    # External Crate Source" below. Specifically reachable:
+    #   ~/.cargo/registry/src/index.crates.io-*/<crate>-<version>/  (registry)
+    #   ~/.cargo/git/checkouts/<crate>-<hash>/<branch>/             (git deps)
+    #   /nix/store/*-vendor-*/<crate>-<version>/                    (nix-vendored)
     "ls *": allow
     "ls": allow
     "wc *": allow
@@ -146,6 +169,42 @@ The devshell guarantees the right toolchain versions are available. Detect once
 
 A task may legitimately span multiple languages (e.g. a Rust binary plus its Python test harness). Run the appropriate verification per file area; document each in the verification block.
 
+## Reading External Crate Source
+
+For Rust tasks, you may need to inspect dependency source (trait definitions, impl bodies, usage examples) to inform your implementation. External source is reachable via the Read/Grep/Glob tools and via `rg`/`ls` in bash. **Do not edit external source — it's read-only reference material.**
+
+**Where dependency source lives:**
+
+| Source | Path pattern |
+|---|---|
+| Registry crates (most deps) | `~/.cargo/registry/src/index.crates.io-*/<crate>-<version>/` |
+| Git deps | `~/.cargo/git/checkouts/<crate>-<hash>/<branch>/` |
+| Nix-vendored deps (crane, buildRustPackage) | `/nix/store/<hash>-vendor-*/<crate>-<version>/` |
+| Workspace-local deps | inside the worktree itself, no special handling |
+
+**Discovering the exact path** for a specific dependency:
+
+```
+nix develop -c cargo metadata --format-version 1
+```
+
+The JSON output's `packages[].manifest_path` field has the absolute path to each `Cargo.toml`; the source files are siblings under that crate's directory. The registry must be populated first — `cargo check` (or any prior build) downloads everything in `Cargo.lock`. If `cargo metadata` fails because deps haven't been fetched, run `nix develop -c cargo check` once.
+
+**Reading patterns:**
+
+- Search across a crate: `rg "trait Serialize" ~/.cargo/registry/src/index.crates.io-*/serde-1.*/src/`
+- List a crate's modules: `ls ~/.cargo/registry/src/index.crates.io-*/tokio-1.*/src/`
+- Read a specific file: use the Read tool with the absolute path (no permission prompt; the path is reachable).
+
+**When to consult external source:**
+- The task asks you to implement a trait from an external crate, and you need the trait definition.
+- An external API is being misused and you want to verify the correct usage.
+- A test failure points at a behavior of an external dep that's not obvious from its public docs.
+
+**When *not* to consult external source:**
+- For routine usage that's covered by `cargo doc` / docs.rs (you don't have web access, but the task spec or existing code in the worktree is usually enough).
+- To "study" a dependency you're not actively using in this task.
+
 ## Dependency Constraint
 
 **No new dependencies or lockfile changes** unless explicitly included in acceptance criteria.
diff --git a/config/opencode/agents/test.md b/config/opencode/agents/test.md
index b3699b9..5e80864 100644
--- a/config/opencode/agents/test.md
+++ b/config/opencode/agents/test.md
@@ -6,6 +6,23 @@ tools:
   edit: true
   bash: true
 permission:
+  # ── External-directory reads (registry / git deps / nix-vendored) ──
+  # Opencode applies a CWD check on tool access; these patterns whitelist
+  # the cargo dependency source trees so the Read/Grep/Glob tools (and
+  # bash inspection commands like `rg`/`ls`) don't prompt for each access.
+  # See "Reading External Crate Source" below for the discovery pattern.
+  read:
+    "~/.cargo/registry/src/**": allow
+    "~/.cargo/git/checkouts/**": allow
+    "/nix/store/*-vendor-*/**": allow
+  grep:
+    "~/.cargo/registry/src/**": allow
+    "~/.cargo/git/checkouts/**": allow
+    "/nix/store/*-vendor-*/**": allow
+  glob:
+    "~/.cargo/registry/src/**": allow
+    "~/.cargo/git/checkouts/**": allow
+    "/nix/store/*-vendor-*/**": allow
   bash:
     # Default deny
     "*": deny
@@ -28,6 +45,12 @@ permission:
     "cargo fmt*": allow
 
     # ── Read-only inspection ──
+    # The wildcarded patterns below accept any path argument, including
+    # paths *outside* the worktree. This is intentional — see "Reading
+    # External Crate Source" below. Specifically reachable:
+    #   ~/.cargo/registry/src/index.crates.io-*/<crate>-<version>/  (registry)
+    #   ~/.cargo/git/checkouts/<crate>-<hash>/<branch>/             (git deps)
+    #   /nix/store/*-vendor-*/<crate>-<version>/                    (nix-vendored)
     "ls *": allow
     "ls": allow
     "wc *": allow
@@ -126,6 +149,25 @@ Rust:
 **Anti-patterns — refuse the path even if it would technically be writable:**
 - `src/tests/foo.rs` and similar regular submodule paths under `src/`. These are not `#[cfg(test)]` modules — they are normal modules that would require a `mod tests;` declaration in production code (`lib.rs` / `main.rs`), which you cannot add. Report as `BLOCKED` and suggest either `tests/<feature>.rs` (integration) or a `#[cfg(test)] mod tests` block inside the relevant `src/<module>.rs`.
 
+## Reading External Crate Source
+
+When you need to inspect a dependency's source — to understand a trait you're testing against, find a known-good test pattern from a well-tested crate, or check a dep's behavior under specific conditions — external source is reachable via the Read/Grep/Glob tools and via `rg`/`ls` in bash. **Do not edit external source.**
+
+**Where dependency source lives:**
+
+| Source | Path pattern |
+|---|---|
+| Registry crates | `~/.cargo/registry/src/index.crates.io-*/<crate>-<version>/` |
+| Git deps | `~/.cargo/git/checkouts/<crate>-<hash>/<branch>/` |
+| Nix-vendored deps (crane, buildRustPackage) | `/nix/store/<hash>-vendor-*/<crate>-<version>/` |
+
+Discover paths via `nix develop -c cargo metadata --format-version 1`; the JSON has `packages[].manifest_path` per dep. The registry must be populated — run `nix develop -c cargo check` once if the metadata call shows missing source.
+
+Read patterns:
+- `rg "trait Serialize" ~/.cargo/registry/src/index.crates.io-*/serde-1.*/src/`
+- `ls ~/.cargo/registry/src/index.crates.io-*/tokio-1.*/tests/` — useful for borrowing test patterns
+- Read tool with absolute path for a specific file.
+
 ## Test Philosophy
 
 **Contract tests + regression.** Write tests that verify:

From a3e0de6d04d3a4d8d5d5ab893d1d0adab2256a12 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Fri, 8 May 2026 13:45:51 +0200
Subject: [PATCH 095/101] feat(opencode): hide TODO paths from orchestrator
 (ADR-22)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

In recent runs the orchestrator skipped @pm and edited TODO/ files
itself, despite the workflow.md anti-pattern warning. Root cause: the
workflow doc literally taught the orchestrator the path layout
(`./TODO/<ID>.md`), making self-help a discoverable shortcut.

Fix: remove the recipe. The orchestrator now never constructs or reads
any per-issue TODO path. All TODO operations go through @pm dispatches;
@pm returns the absolute file path of every issue it touches, and the
orchestrator captures and reuses those paths downstream.

- Phase 1 loses the TODO-existence and depends-on checks (former steps
  3 and 9 of the recent edit) — Phase 1 is now git/worktree-only.
- Phase 2 expands @pm's existing dispatch into a `Validate run
  prerequisites` operation that returns either {ok: true,
  issue_file_path, issue: {...}} or {ok: false, error_code, message}
  with error_code in {tracker_missing, issue_not_found,
  dependency_unmet, dependency_missing}. depends-on enforcement moves
  here.
- Phase 7 split_needed exit, Phase 9 TODO Update, Phase 9 Commit TODO
  Changes, and Failure Handler all reference @pm-returned paths or use
  `git add ./TODO/` blanketly (safe because Phase 1 verified clean tree
  and only @pm writes there during a run).
- pm.md gains a path-return rule: every read returns issue_file_path,
  every write returns the modified paths. Run-Prerequisite Output
  format documented with all four error codes.
- ADR-22 captures the rationale; routing matrix updates Phase 1/2 rows;
  pipeline diagram labels updated.

The fix is discoverability-only — no permission deny on TODO/, per
explicit user direction. The schema lives in agents/pm.md, which the
orchestrator does not load.

Refs: config/opencode/workflow-design.md ADR-22
---
 config/opencode/agents/pm.md         |  58 +++++++++++++--
 config/opencode/commands/workflow.md | 106 ++++++++++++++++++---------
 config/opencode/workflow-design.md   |  20 +++--
 3 files changed, 140 insertions(+), 44 deletions(-)

diff --git a/config/opencode/agents/pm.md b/config/opencode/agents/pm.md
index 2382876..ee682f3 100644
--- a/config/opencode/agents/pm.md
+++ b/config/opencode/agents/pm.md
@@ -114,15 +114,59 @@ Statuses: `Todo`, `In Progress`, `Done`.
 ## Capabilities
 
 You can:
-- **View** an issue by ID — read `<TODO_DIR>/<ID>.md` and return its fields structured.
+- **Validate run prerequisites** — given an issue ID, verify the TODO tracker is well-formed in this worktree (directory + `README.md` present), locate the issue file, and confirm every entry in its `depends-on:` frontmatter resolves to a `Done` issue. Used by `/workflow`'s Phase 2 (per ADR-22) so the orchestrator never constructs a TODO path itself. Returns a structured success or failure response (see "Run-Prerequisite Output" below).
+- **View** an issue by ID — read `<TODO_DIR>/<ID>.md` and return its fields structured. **Always include the resolved absolute file path** in the response (`issue_file_path` field).
 - **List** issues, optionally filtered by status / parent / label. Walk `<TODO_DIR>/*.md` (excluding `README.md`), parse frontmatter.
-- **Create** an issue. Generate the next ID by scanning existing IDs with the same prefix and incrementing. Default `status: Todo`. Write `<TODO_DIR>/<NEW-ID>.md`. If the issue is top-level (`parent: null`), update `README.md` to add it under the caller-specified category. If the issue is a sub-issue (`parent: <PARENT-ID>`), update the parent file's `## Sub-issues` section.
+- **Create** an issue. Generate the next ID by scanning existing IDs with the same prefix and incrementing. Default `status: Todo`. Write `<TODO_DIR>/<NEW-ID>.md`. If the issue is top-level (`parent: null`), update `README.md` to add it under the caller-specified category. If the issue is a sub-issue (`parent: <PARENT-ID>`), update the parent file's `## Sub-issues` section. **Return the absolute path of the new issue file** (`new_issue_path`) and the absolute paths of every dependent index updated (`updated_paths`).
 - **Update status** in frontmatter. When status changes to/from `Done`, propagate the checkbox flip to:
   - `README.md` if the issue is top-level (`parent: null`), **or**
   - the parent issue's `## Sub-issues` line if it has a parent.
-- **Add a comment** — append `- YYYY-MM-DD — <text>` to the issue's `## Comments` section (create the section if missing, just before EOF).
-- **Check off acceptance criteria** by index or matching text — flip `- [ ]` to `- [x]` under `## Acceptance criteria`.
-- **Edit** description or other body sections when explicitly requested.
+  Return the list of all paths modified by the operation.
+- **Add a comment** — append `- YYYY-MM-DD — <text>` to the issue's `## Comments` section (create the section if missing, just before EOF). Return the modified path.
+- **Check off acceptance criteria** by index or matching text — flip `- [ ]` to `- [x]` under `## Acceptance criteria`. Return the modified path.
+- **Edit** description or other body sections when explicitly requested. Return the modified path.
+
+**Path-return rule:** every operation that modifies the filesystem must include the absolute path(s) of every file it touched in its response (`modified_paths` array, or named fields like `new_issue_path` / `updated_paths` for create). Read-only operations (View, List) include `issue_file_path` for the issue they read. The caller (`/workflow`'s orchestrator) deliberately does not construct TODO paths from issue IDs — it relies on these returned paths for staging, commenting, and follow-on dispatches.
+
+## Run-Prerequisite Output
+
+The `Validate run prerequisites` capability returns one of two JSON shapes:
+
+**Success:**
+```json
+{
+  "ok": true,
+  "issue_file_path": "/abs/path/to/TODO/<ID>.md",
+  "issue": {
+    "id": "...",
+    "title": "...",
+    "status": "Todo | In Progress | Done",
+    "parent": "... | null",
+    "labels": ["..."],
+    "depends_on": ["..."],
+    "description": "...",
+    "acceptance_criteria": [{"checked": false, "text": "..."}],
+    "sub_issues": [{"id": "...", "title": "...", "checked": false}]
+  }
+}
+```
+
+**Failure:**
+```json
+{
+  "ok": false,
+  "error_code": "tracker_missing | issue_not_found | dependency_unmet | dependency_missing",
+  "message": "<one-line description suitable for the orchestrator to surface verbatim>"
+}
+```
+
+Error code semantics:
+- `tracker_missing` — `<TODO_DIR>/` or `<TODO_DIR>/README.md` is absent.
+- `issue_not_found` — `<TODO_DIR>/<ID>.md` does not exist.
+- `dependency_unmet` — the issue exists; one of its `depends-on:` entries is not yet `Done`. Include which dep ID and its current status in `message`.
+- `dependency_missing` — the issue exists; one of its `depends-on:` entries refers to an issue that has no file at all. Include which dep ID in `message`.
+
+Do **not** mutate state on failure — the validator is read-only.
 
 You cannot:
 - Delete issues. If asked, leave the file in place and report — the new schema has no `Cancelled` state, so deletion would lose history.
@@ -138,11 +182,13 @@ Single-issue schema:
 
 ```json
 {
+  "issue_file_path": "/abs/path/to/TODO/GAL-39.md",
   "id": "GAL-39",
   "title": "Implement a special stage type",
   "status": "Done",
   "parent": "GAL-38",
   "labels": ["gameplay", "advanced-mechanics"],
+  "depends_on": ["GAL-37"],
   "description": "…",
   "sub_issues": [
     { "id": "GAL-40", "title": "…", "checked": true }
@@ -157,7 +203,7 @@ Single-issue schema:
 }
 ```
 
-Omit fields whose corresponding sections are absent (`null` is fine for `parent`, but drop `sub_issues`/`acceptance_criteria`/`integration_test_hints`/`comments` entirely if the section isn't in the file).
+`issue_file_path` is **always included** for any operation that reads or writes a single issue file (per the path-return rule above). Omit fields whose corresponding sections are absent (`null` is fine for `parent`, drop `depends_on`/`sub_issues`/`acceptance_criteria`/`integration_test_hints`/`comments` entirely if the section/field isn't in the file).
 
 For list output, return an array of `{id, title, status, parent, labels}` objects.
 
diff --git a/config/opencode/commands/workflow.md b/config/opencode/commands/workflow.md
index b43d02d..67a3208 100644
--- a/config/opencode/commands/workflow.md
+++ b/config/opencode/commands/workflow.md
@@ -8,11 +8,11 @@ You are executing the multi-agent workflow inside the worktree this opencode ses
 **Prerequisites (the user handles before launching opencode):**
 - A git worktree is checked out for the issue's feature branch
 - `opencode` was launched from the root of that worktree
-- A `TODO/` directory is committed to the repo containing per-issue files (`TODO/<ID>.md`) plus `TODO/README.md`
+- A `TODO/` directory is committed to the repo with a per-issue tracker (schema in `agents/pm.md`) and a `TODO/README.md` index. The orchestrator does not read or construct per-issue paths — `@pm` is the only agent that touches issue files (ADR-22).
 
 **Task reference:** $ARGUMENTS
 
-If `$ARGUMENTS` is empty, stop immediately: "Usage: `/workflow <ISSUE-ID> [base-branch]` (e.g. `/workflow ABC-1`). The ID must exist as `./TODO/<ID>.md`. Base branch defaults to `main` (then `master`)."
+If `$ARGUMENTS` is empty, stop immediately: "Usage: `/workflow <ISSUE-ID> [base-branch]` (e.g. `/workflow ABC-1`). The ID must already be tracked under `TODO/` (`@pm` validates existence at Phase 2). Base branch defaults to `main` (then `master`)."
 
 Parse `$ARGUMENTS`: the first whitespace-separated token is the issue ID, an optional second token overrides the base branch. Store as `ISSUE_ID`.
 
@@ -72,38 +72,73 @@ Define `RUN_DIR="$WORKTREE_PATH/.workflow/run-$ISSUE_ID"` once in Phase 1 and re
 
 ## Phase 1: Sanity Check
 
+This phase covers **only** git/worktree-shaped sanity. **TODO-tracker validation (issue file existence, `depends-on` enforcement) is `@pm`'s job and happens at Phase 2 (ADR-22)**. The orchestrator does not construct or read paths under `TODO/` at any point — it dispatches `@pm` and uses whatever path `@pm` returns.
+
 1. Verify CWD is a non-bare git worktree: `git rev-parse --is-bare-repository 2>/dev/null` must output `false`. If not, stop: "Workflow must be run from a non-bare worktree (the directory opencode was launched in)."
 2. Capture the worktree path: `WORKTREE_PATH="$(pwd)"`.
-3. Verify the TODO tracker exists:
-   - `./TODO/` directory must exist. If not, stop: "TODO/ directory not found in the current worktree. Commit a TODO/ folder with one file per issue plus a README.md index."
-   - `./TODO/README.md` must exist. If not, stop: "TODO/README.md not found. Add the category index file before running the workflow."
-   - `./TODO/$ISSUE_ID.md` must exist. If not, stop: "Issue file `./TODO/<ID>.md` not found for ID parsed from `$ARGUMENTS`."
-4. Verify HEAD is not detached: `git symbolic-ref --short HEAD` must succeed. If it fails, stop: "Cannot run on a detached HEAD. Check out a feature branch first."
-5. Capture the current branch: `BRANCH_NAME="$(git symbolic-ref --short HEAD)"`.
-6. Resolve the base branch (`BASE_BRANCH`):
+3. Verify HEAD is not detached: `git symbolic-ref --short HEAD` must succeed. If it fails, stop: "Cannot run on a detached HEAD. Check out a feature branch first."
+4. Capture the current branch: `BRANCH_NAME="$(git symbolic-ref --short HEAD)"`.
+5. Resolve the base branch (`BASE_BRANCH`):
    - If `$ARGUMENTS` provided a second token, use it.
    - Else if `git rev-parse --verify --quiet main` succeeds, use `main`.
    - Else if `git rev-parse --verify --quiet master` succeeds, use `master`.
    - Else stop: "Could not determine base branch (no `main` or `master`). Pass it as the second argument: `/workflow <ISSUE-ID> <base-branch>`."
-7. Verify the current branch is not the base branch: if `BRANCH_NAME == BASE_BRANCH`, stop: "Cannot run workflow on the base branch (`$BASE_BRANCH`). Switch to a feature branch first."
-8. **Verify the working tree is clean** (ADR-20): `git status --porcelain` must return empty. If not, stop: "Working tree must be clean. Commit or stash uncommitted changes before running the workflow."
-9. **Check `depends-on:` declarations** (ADR-21): if `./TODO/$ISSUE_ID.md`'s frontmatter contains a `depends-on: [<ID>, ...]` list, verify every listed dependency's status is `Done` (read each `./TODO/<DEP-ID>.md`). If any dependency is not `Done`, stop: "Cannot start `$ISSUE_ID`; it depends on `<DEP-ID>` (status: `<status>`). Complete dependencies first." If a listed dependency file does not exist, stop with: "Cannot start `$ISSUE_ID`; declared dependency `<DEP-ID>` has no issue file." If the field is absent, proceed.
-10. Set the run-artifacts directory: `RUN_DIR="$WORKTREE_PATH/.workflow/run-$ISSUE_ID"`. Phase 3 will `mkdir -p "$RUN_DIR"` before writing the first artifact.
-11. Initialize the run-level rework counter: `PLAN_REWORK_REMAINING=1` (per ADR-13). Decrement on every P5.5-BLOCK→P4, P7-escalation-exhaustion→P3, and P8-plan-level→P3 transition. When the counter is `0` and another such transition fires, abort to the Failure Handler instead of re-entering.
+6. Verify the current branch is not the base branch: if `BRANCH_NAME == BASE_BRANCH`, stop: "Cannot run workflow on the base branch (`$BASE_BRANCH`). Switch to a feature branch first."
+7. **Verify the working tree is clean** (ADR-20): `git status --porcelain` must return empty. If not, stop: "Working tree must be clean. Commit or stash uncommitted changes before running the workflow."
+8. Set the run-artifacts directory: `RUN_DIR="$WORKTREE_PATH/.workflow/run-$ISSUE_ID"`. Phase 3 will `mkdir -p "$RUN_DIR"` before writing the first artifact.
+9. Initialize the run-level rework counter: `PLAN_REWORK_REMAINING=1` (per ADR-13). Decrement on every P5.5-BLOCK→P4, P7-escalation-exhaustion→P3, and P8-plan-level→P3 transition. When the counter is `0` and another such transition fires, abort to the Failure Handler instead of re-entering.
 
 ---
 
 ## Phase 2: Issue Context
 
-Dispatch `@pm` against `./TODO/` (pass the absolute `TODO/` directory path) and fetch the issue at `./TODO/<ID>.md`:
-- Title, description, acceptance criteria (if section present)
-- Labels and parent
-- Sub-issues list (if the issue is a parent)
-- Existing status
+Dispatch `@pm` with the issue ID `$ISSUE_ID`, `$WORKTREE_PATH`, and `Validate run prerequisites` as the operation. **The orchestrator does not assume any path under the worktree's `TODO/` tree exists** — it asks `@pm` to:
 
-If the issue file does not exist or `@pm` fails, stop with error.
+1. Verify the TODO tracker is well-formed in this worktree (directory + index file present).
+2. Locate the issue file for `$ISSUE_ID`.
+3. Verify all `depends-on:` entries in the issue's frontmatter resolve to issues with `status: Done` (ADR-21 / ADR-22).
+4. Return one of two structured responses:
 
-If the issue's status is `Todo`, ask `@pm` to set it to `In Progress` and propagate the change to the dependent index (`README.md` for top-level issues, the parent's `## Sub-issues` line for sub-issues). The status edit will be staged alongside other TODO updates in Phase 9.
+**Success:**
+```json
+{
+  "ok": true,
+  "issue_file_path": "<absolute path to the issue file>",
+  "issue": {
+    "id": "...",
+    "title": "...",
+    "status": "Todo | In Progress | Done",
+    "parent": "... | null",
+    "labels": [...],
+    "depends_on": [...],
+    "description": "...",
+    "acceptance_criteria": [{"checked": false, "text": "..."}],
+    "sub_issues": [...]
+  }
+}
+```
+
+**Failure:**
+```json
+{
+  "ok": false,
+  "error_code": "tracker_missing | issue_not_found | dependency_unmet | dependency_missing",
+  "message": "<human-readable description>"
+}
+```
+
+On failure, stop the workflow with `@pm`'s `message` verbatim. Do **not** attempt to inspect or repair the TODO tree from the orchestrator — that belongs to `@pm`.
+
+On success, capture `ISSUE_FILE_PATH` from the response. **Use this captured path verbatim everywhere downstream** (Phase 9 staging, Failure Handler comments, etc.) — never construct a TODO path from `$ISSUE_ID` directly.
+
+If `issue.status == "Todo"`, dispatch `@pm` again to flip it to `In Progress` (operation: `Update status`, target: the same issue ID; `@pm` propagates to README.md / parent's `## Sub-issues` line). The status edit will be staged alongside other TODO updates in Phase 9.
+
+**Forbidden in the orchestrator from this point forward:**
+- Reading any file inside the `TODO/` tree directly.
+- Constructing a per-issue file path from an issue ID — `@pm` is the only agent that knows the layout.
+- Editing or writing any file under `TODO/` — every TODO mutation is a `@pm` dispatch that returns the path of what it touched.
+
+These rules are enforced by *not telling you the path layout*. The schema lives in `agents/pm.md`; the orchestrator never needs it.
 
 ---
 
@@ -472,7 +507,7 @@ The Failure Handler's recovery procedure (ADR-14: discard worktree, delete branc
 Concretely on `split_needed`:
 
 1. Write a Failure Handler summary noting `@check`'s diagnosis verbatim and the Phase 5 split that was attempted.
-2. Dispatch `@pm` to add a comment on `./TODO/$ISSUE_ID.md`: `- YYYY-MM-DD — split_needed at Phase 7 task-1; <one-line diagnosis>. Re-run after re-creating the worktree.`
+2. Dispatch `@pm` (operation: `Add comment`, issue ID: `$ISSUE_ID`) with the comment text: `- YYYY-MM-DD — split_needed at Phase 7 task-1; <one-line diagnosis>. Re-run after re-creating the worktree.` `@pm` resolves the issue file path itself; the orchestrator never constructs it.
 3. Stop execution. Do not commit code, do not file new sub-issues, do not stage anything under `.workflow/`.
 
 ---
@@ -516,15 +551,18 @@ The workflow is forge-agnostic. It commits locally and stops. **Do not push, and
 
 ### TODO Update
 
-Dispatch `@pm` against the absolute `./TODO/` path. Ask it to:
+Dispatch `@pm` with the issue ID `$ISSUE_ID` and the following operations (a single dispatch can carry all of them — see `agents/pm.md` for the request shape):
 
-1. **Check off the AC checkboxes that task-1 satisfied.** For each `- [ ]` AC line in `./TODO/$ISSUE_ID.md`'s `## Acceptance criteria` section that the implemented work fulfilled, flip to `- [x]`. The orchestrator decides which AC are satisfied by inspecting task-1's spec and verification output.
-2. **Set the issue's frontmatter `status` based on AC completion** (ADR-21, AC-driven):
-   - **All AC are now `[x]`** → `status: Done`.
-   - **Some AC remain `[ ]`** → `status: In Progress`. (Sub-issues filed at Phase 5.5 cover the unmet AC; the user runs them in subsequent invocations.)
-   - **No AC section in the file** → `status: Done` (the parent had no testable AC; one task ran end-to-end).
-3. **Propagate any status flip to the dependent index:** `TODO/README.md` for top-level issues (`parent: null`), or the parent issue file's `## Sub-issues` line for sub-issues.
-4. **Add a comment** of the form: `- YYYY-MM-DD — Branch \`$BRANCH_NAME\`, commit <SHA> — <one-line summary>` (date from the shell, never fabricated).
+1. **Check off the AC the run satisfied.** Pass the list of AC indices or texts (from the `acceptance_criteria` array `@pm` returned at Phase 2) that the implemented work fulfilled. The orchestrator decides which AC are satisfied by inspecting task-1's spec and verification output. `@pm` flips the corresponding `- [ ]` to `- [x]`.
+2. **Set the issue's `status` based on AC completion** (ADR-21, AC-driven):
+   - **All AC are now `[x]`** → `Done`.
+   - **Some AC remain `[ ]`** → `In Progress`. (Sub-issues filed at Phase 5.5 cover the unmet AC; the user runs them in subsequent invocations.)
+   - **No AC section** → `Done` (the parent had no testable AC; one task ran end-to-end).
+3. **Add a comment** of the form: `- YYYY-MM-DD — Branch \`$BRANCH_NAME\`, commit <SHA> — <one-line summary>` (date from the shell, never fabricated).
+
+`@pm` propagates status flips to the dependent index (the top-level README or the parent's `## Sub-issues` line) on its own — that's its job, not the orchestrator's. The orchestrator passes high-level intent ("set status to Done") and trusts `@pm` to update every dependent file.
+
+`@pm`'s response includes the list of files it modified (absolute paths). Capture this list as `MODIFIED_TODO_PATHS` for the staging step below.
 
 ### File Follow-ups
 
@@ -549,9 +587,11 @@ Tracked-worthy unresolved items must become real TODO issues; otherwise they van
 
 ### Commit TODO Changes
 
-After both the TODO Update and File Follow-ups steps, commit everything under `TODO/` in a single atomic commit: `chore(todo): update <issue-id> status, file follow-ups`. Stage the worked issue file, the dependent index (README.md or parent file), and any newly created follow-up issue files.
+After both the TODO Update and File Follow-ups steps, stage every path returned by `@pm` in this run (the union of `MODIFIED_TODO_PATHS` and `NEW_SUBISSUE_PATHS` collected from each `@pm` dispatch). Commit them in a single atomic commit: `chore(todo): update <issue-id> status, file follow-ups`.
 
-If no follow-ups were filed, the commit message simplifies to `chore(todo): update <issue-id> status and progress` and only the TODO Update changes are staged.
+Equivalently — and more robustly, since the orchestrator can't have edited TODO files directly (Phase 1 verified the working tree was clean and the orchestrator never writes there) — stage the entire `TODO/` directory: `git add ./TODO/`. Anything staged under `TODO/` came from `@pm` during this run.
+
+If no follow-ups were filed, the commit message simplifies to `chore(todo): update <issue-id> status and progress`.
 
 ### Run Summary
 - Write `$RUN_DIR/summary.md` with:
@@ -575,7 +615,7 @@ At any phase, if an unrecoverable error occurs (or a routing rule explicitly abo
 1. Write `$RUN_DIR/summary.md` (creating `$RUN_DIR` first if it doesn't exist) with what was completed and what failed. Do **not** stage or commit anything under `.workflow/`.
 2. If any code was written, commit it with message `wip: incomplete workflow run for <issue-id>`. Stage code only — exclude `.workflow/` and `TODO/`.
 3. Leave the branch and worktree intact for the user to inspect — do not push, do not delete.
-4. Dispatch `@pm` against `./TODO/` to add a comment on the issue file (`./TODO/<ID>.md`) summarising what failed and naming the abort reason if it was a routing-rule abort (e.g. `split_needed at Phase 7 task-1`, `plan_rework_remaining exhausted at Phase 8`).
+4. Dispatch `@pm` (operation: `Add comment`, issue ID: `$ISSUE_ID`) summarising what failed and naming the abort reason if it was a routing-rule abort (e.g. `split_needed at Phase 7 task-1`, `plan_rework_remaining exhausted at Phase 8`). The orchestrator never constructs the issue file path — `@pm` resolves it.
 5. Stop execution.
 
 ### Recovery procedure (workflow is non-resumable, ADR-14)
diff --git a/config/opencode/workflow-design.md b/config/opencode/workflow-design.md
index 6a8c332..53bf3c8 100644
--- a/config/opencode/workflow-design.md
+++ b/config/opencode/workflow-design.md
@@ -40,8 +40,8 @@ High-level happy path with the major escalation arms. The workflow runs **one ta
 
 ```mermaid
 flowchart TD
-    P1["Phase 1: Sanity Check<br/>incl clean tree + depends-on"]
-    P2["Phase 2: Issue Context<br/>pm reads TODO/ID.md"]
+    P1["Phase 1: Sanity Check<br/>git/worktree only, no TODO reads"]
+    P2["Phase 2: Issue Context<br/>pm validates prereqs + returns path"]
     P3["Phase 3: Plan<br/>write plan.md"]
     P4{"Phase 4: Review Plan<br/>check blocking, simplify advisory<br/>max 3 cycles"}
     P5["Phase 5: Split into Tasks<br/>write task-N.md"]
@@ -135,10 +135,13 @@ Every observed `(phase, signal) → action`. Empty cells are gaps. Walking this
 
 | Phase | Signal source | Signal | Action |
 |---|---|---|---|
-| 1 | Sanity checks | Bare repo / detached HEAD / missing `TODO/<ID>.md` / branch == base | Stop with error |
+| 1 | Sanity checks | Bare repo / detached HEAD / branch == base | Stop with error |
 | 1 | Sanity checks | Working tree dirty (`git status --porcelain` non-empty) | Stop with error (ADR-20) |
-| 1 | Sanity checks | `depends-on:` issue not in `Done` status | Stop with error (ADR-21) |
-| 2 | `@pm` | Issue not found | Stop with error |
+| 2 | `@pm` (Validate run prerequisites) | `ok: true` | Capture `issue_file_path` and full issue context; proceed |
+| 2 | `@pm` (Validate run prerequisites) | `error_code: tracker_missing` | Stop with error using `@pm`'s message verbatim (ADR-22) |
+| 2 | `@pm` (Validate run prerequisites) | `error_code: issue_not_found` | Stop with error using `@pm`'s message verbatim (ADR-22) |
+| 2 | `@pm` (Validate run prerequisites) | `error_code: dependency_unmet` | Stop with error using `@pm`'s message verbatim (ADR-21 / ADR-22) |
+| 2 | `@pm` (Validate run prerequisites) | `error_code: dependency_missing` | Stop with error using `@pm`'s message verbatim (ADR-22) |
 | 2 | `@pm` | Status is `Todo` | Flip to `In Progress`; propagate to README.md / parent's Sub-issues |
 | 3 | Orchestrator | Plan drafted | Apply Dispatch Hygiene; write `plan.md`; verify `test -f` |
 | 4 | `@check` | ACCEPTABLE (regardless of `@simplify`) | Proceed to Phase 5 |
@@ -352,6 +355,13 @@ The model carries five sub-decisions:
 **Alternatives:** (a) keep N-task runs, add mid-flight re-splitting via P7→P5 re-entry — doesn't solve big-diff or cross-task regression; (b) keep N-task runs, accept the gaps — leaves three known-bad routes; (c) always one task per issue (skip Phase 5 entirely) — loses the planning-phase split heuristic that's catching legitimate over-scoping at design time.
 **Consequences:** runs become shorter and more focused. Each commit/PR carries a bounded scope. Sub-issue fan-out becomes the primary scaling mechanism for multi-step work. `TODO/` sees more sub-issue files; `@pm`'s split-time filing path becomes a hot code path. Concurrent runs in different worktrees on the same repo become trivially safe because each worktree has its own `TODO/` checkout (file conflicts surface as standard git merge conflicts at integration time, not as mid-run race conditions).
 
+### ADR-22 (2026-05-08) — TODO path resolution lives with `@pm`; orchestrator never constructs TODO paths
+
+**Context:** in early runs of the one-task-per-run workflow, the orchestrator sometimes did `@pm`'s job itself — reading `./TODO/$ISSUE_ID.md` directly to inspect the issue, instead of dispatching `@pm`. The text-level "anti-patterns" warning (workflow.md §Roles & Dispatch) wasn't enough to prevent it: once the workflow document told the orchestrator that issue files lived at `./TODO/<ID>.md`, the recipe was discoverable and tempting. Phase 1's sanity check (former steps 3 + 9 — TODO-tracker existence and `depends-on` enforcement) was the most blatant offender, since it required the orchestrator to read TODO files directly.
+**Decision:** the orchestrator does not read, write, or construct any path under `TODO/` at any phase. All TODO operations — including prerequisite validation that used to live in Phase 1 — go through `@pm` dispatches. `@pm`'s response always includes the absolute file path of every issue file it touched (or read); the orchestrator captures these paths and uses them downstream (Phase 9 staging, Failure Handler comments, etc.) instead of constructing them. Phase 1 keeps only git/worktree-shaped checks; Phase 2 expands `@pm`'s existing dispatch into a "Validate run prerequisites" operation that returns either `{ok: true, issue_file_path, issue: {...}}` or a structured error.
+**Alternatives:** (a) permission-deny `TODO/**` for the orchestrator — would force-fail orchestrator self-help but adds a permission layer the user prefers to avoid; (b) leave the doc warnings in place and hope the orchestrator complies — already shown to be insufficient; (c) keep Phase 1's TODO checks and just discipline the orchestrator harder — same problem as (b).
+**Consequences:** discoverability of the path layout disappears from `commands/workflow.md` — the orchestrator literally never sees a `TODO/<ID>.md` template to imitate. The schema and path layout live in `agents/pm.md`, which the orchestrator does not load. `@pm`'s capabilities table grows by one ("Validate run prerequisites") and every existing capability now mandates including the absolute file path in the response. The orchestrator's Phase 9 staging step changes from constructing paths to using `@pm`-returned paths (or, equivalently, `git add ./TODO/` since the working tree was clean at Phase 1 and only `@pm` writes to TODO during a run).
+
 ---
 
 ## 6. Open Questions / Known Gaps

From 56713cd7b810e055fd9095b0b3cef8760ec2fdfd Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Fri, 8 May 2026 14:04:47 +0200
Subject: [PATCH 096/101] feat(opencode): @pm owns the TODO commit (ADR-23)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The orchestrator was running `git add ./TODO/` and `git commit -m
chore(todo): ...` itself in Phase 9, baking filesystem-tracker
specifics into commands/workflow.md. The point of @pm as an
abstraction is that it should be swappable — a Linear-backed @pm or a
Notion-backed @pm should drop in without touching the workflow
command. With API-backed trackers, "commit the TODO updates" is a
no-op and `git add ./TODO/` is wrong.

Push persistence shape behind the @pm boundary:

- New @pm capability `Commit pending changes` accepts a commit message
  and returns {ok, sha, message}. Filesystem @pm runs `git add ./TODO/`
  + `git commit -m <msg>` and returns the SHA. Tracker-backed
  implementations no-op and return sha: null.
- @pm gains tightly-scoped bash access: `git add ./TODO/*`,
  `git commit -m *`, `git status --porcelain ./TODO/*` only. Push,
  reset, rebase, checkout, branch, tag are explicit denies. Everything
  else falls through to the default deny.
- Phase 9 "Commit TODO Changes" replaces orchestrator-side git with a
  @pm dispatch; orchestrator constructs the message from run context
  and captures the returned SHA for the summary.
- Failure Handler gains a step 5 (commit pending after the failure
  comment add). Today the comment is left uncommitted in the working
  tree and gets discarded with the throwaway worktree (ADR-14) —
  forensic loss. With this change the failure note lands as its own
  commit on the failed branch.
- Routing matrix Phase 9 rows updated; ADR-22's superseded wording
  about orchestrator-side staging removed.

Stub-pass / body-pass / wip code commits remain orchestrator-owned —
those are code, not tracker-specific.

Refs: config/opencode/workflow-design.md ADR-23
---
 config/opencode/agents/pm.md         | 48 +++++++++++++++++++++-------
 config/opencode/commands/workflow.md | 17 +++++-----
 config/opencode/workflow-design.md   | 19 ++++++++---
 3 files changed, 59 insertions(+), 25 deletions(-)

diff --git a/config/opencode/agents/pm.md b/config/opencode/agents/pm.md
index ee682f3..a0d50ce 100644
--- a/config/opencode/agents/pm.md
+++ b/config/opencode/agents/pm.md
@@ -1,5 +1,5 @@
 ---
-description: Project management agent that manages a Linear-style TODO/ folder (one file per issue plus a README.md index)
+description: Project management agent that manages a Linear-style TODO/ folder (one file per issue plus a README.md index). Owns persistence, including the git commit of TODO changes (ADR-23).
 mode: subagent
 tools:
   read: true
@@ -7,7 +7,26 @@ tools:
   grep: true
   write: true
   edit: true
-  bash: false
+  bash: true
+permission:
+  # Tightly-scoped git access for the `Commit pending changes` capability.
+  # @pm owns persistence shape (filesystem commit vs. API call vs. other),
+  # so the bash sandbox is opened just enough to commit TODO/ updates and
+  # nothing else. See ADR-23.
+  bash:
+    "*": deny
+    "git add ./TODO/*": allow
+    "git add ./TODO/": allow
+    "git commit -m *": allow
+    "git status --porcelain ./TODO/*": allow
+    "git status --porcelain ./TODO/": allow
+    # Explicit denials for safety
+    "git push*": deny
+    "git reset*": deny
+    "git rebase*": deny
+    "git checkout*": deny
+    "git branch*": deny
+    "git tag*": deny
 ---
 
 You are a project management assistant. Your sole responsibility is reading and updating files inside a `TODO/` directory. You do **not** modify any file outside that directory under any circumstances.
@@ -115,18 +134,25 @@ Statuses: `Todo`, `In Progress`, `Done`.
 
 You can:
 - **Validate run prerequisites** — given an issue ID, verify the TODO tracker is well-formed in this worktree (directory + `README.md` present), locate the issue file, and confirm every entry in its `depends-on:` frontmatter resolves to a `Done` issue. Used by `/workflow`'s Phase 2 (per ADR-22) so the orchestrator never constructs a TODO path itself. Returns a structured success or failure response (see "Run-Prerequisite Output" below).
-- **View** an issue by ID — read `<TODO_DIR>/<ID>.md` and return its fields structured. **Always include the resolved absolute file path** in the response (`issue_file_path` field).
+- **View** an issue by ID — read `<TODO_DIR>/<ID>.md` and return its fields structured.
 - **List** issues, optionally filtered by status / parent / label. Walk `<TODO_DIR>/*.md` (excluding `README.md`), parse frontmatter.
-- **Create** an issue. Generate the next ID by scanning existing IDs with the same prefix and incrementing. Default `status: Todo`. Write `<TODO_DIR>/<NEW-ID>.md`. If the issue is top-level (`parent: null`), update `README.md` to add it under the caller-specified category. If the issue is a sub-issue (`parent: <PARENT-ID>`), update the parent file's `## Sub-issues` section. **Return the absolute path of the new issue file** (`new_issue_path`) and the absolute paths of every dependent index updated (`updated_paths`).
+- **Create** an issue. Generate the next ID by scanning existing IDs with the same prefix and incrementing. Default `status: Todo`. Write `<TODO_DIR>/<NEW-ID>.md`. If the issue is top-level (`parent: null`), update `README.md` to add it under the caller-specified category. If the issue is a sub-issue (`parent: <PARENT-ID>`), update the parent file's `## Sub-issues` section. Return the new issue's `id`.
 - **Update status** in frontmatter. When status changes to/from `Done`, propagate the checkbox flip to:
   - `README.md` if the issue is top-level (`parent: null`), **or**
   - the parent issue's `## Sub-issues` line if it has a parent.
-  Return the list of all paths modified by the operation.
-- **Add a comment** — append `- YYYY-MM-DD — <text>` to the issue's `## Comments` section (create the section if missing, just before EOF). Return the modified path.
-- **Check off acceptance criteria** by index or matching text — flip `- [ ]` to `- [x]` under `## Acceptance criteria`. Return the modified path.
-- **Edit** description or other body sections when explicitly requested. Return the modified path.
+- **Add a comment** — append `- YYYY-MM-DD — <text>` to the issue's `## Comments` section (create the section if missing, just before EOF).
+- **Check off acceptance criteria** by index or matching text — flip `- [ ]` to `- [x]` under `## Acceptance criteria`.
+- **Edit** description or other body sections when explicitly requested.
+- **Commit pending changes** — given a commit message, stage every modification you've made under `<TODO_DIR>/` in this dispatch chain and create one git commit. Used by `/workflow`'s Phase 9 (and Failure Handler) so the orchestrator stays tracker-agnostic — see ADR-23. **Filesystem-backed `@pm` (this agent):**
+  1. Run `git status --porcelain ./TODO/` to confirm there are changes to commit. If empty, return `{ok: true, sha: null, message: "no changes to commit"}` — do not error.
+  2. `git add ./TODO/`.
+  3. `git commit -m "<message-from-caller>"`.
+  4. Capture the resulting SHA (`git rev-parse HEAD`).
+  5. Return `{ok: true, sha: "<short-sha>", message: "committed N files"}`.
 
-**Path-return rule:** every operation that modifies the filesystem must include the absolute path(s) of every file it touched in its response (`modified_paths` array, or named fields like `new_issue_path` / `updated_paths` for create). Read-only operations (View, List) include `issue_file_path` for the issue they read. The caller (`/workflow`'s orchestrator) deliberately does not construct TODO paths from issue IDs — it relies on these returned paths for staging, commenting, and follow-on dispatches.
+  Other backends (Linear, Notion, REST, …) implement this capability as a no-op or whatever their persistence model requires — the API call already persisted the data, so they return `{ok: true, sha: null, message: "no commit needed; persistence is via API"}`.
+
+**No-paths-in-response rule (ADR-22):** the caller (`/workflow`'s orchestrator) deliberately operates without knowing the TODO path layout. Your responses identify issues by `id`, never by absolute file path. Error messages may mention paths in prose for human readability, but the structured response shape exposes no path field. The orchestrator stages nothing — `Commit pending changes` is the only path through which `TODO/` changes become git history.
 
 ## Run-Prerequisite Output
 
@@ -136,7 +162,6 @@ The `Validate run prerequisites` capability returns one of two JSON shapes:
 ```json
 {
   "ok": true,
-  "issue_file_path": "/abs/path/to/TODO/<ID>.md",
   "issue": {
     "id": "...",
     "title": "...",
@@ -182,7 +207,6 @@ Single-issue schema:
 
 ```json
 {
-  "issue_file_path": "/abs/path/to/TODO/GAL-39.md",
   "id": "GAL-39",
   "title": "Implement a special stage type",
   "status": "Done",
@@ -203,7 +227,7 @@ Single-issue schema:
 }
 ```
 
-`issue_file_path` is **always included** for any operation that reads or writes a single issue file (per the path-return rule above). Omit fields whose corresponding sections are absent (`null` is fine for `parent`, drop `depends_on`/`sub_issues`/`acceptance_criteria`/`integration_test_hints`/`comments` entirely if the section/field isn't in the file).
+Omit fields whose corresponding sections are absent (`null` is fine for `parent`, drop `depends_on`/`sub_issues`/`acceptance_criteria`/`integration_test_hints`/`comments` entirely if the section/field isn't in the file). No path field — the caller does not need it (per the No-paths-in-response rule above).
 
 For list output, return an array of `{id, title, status, parent, labels}` objects.
 
diff --git a/config/opencode/commands/workflow.md b/config/opencode/commands/workflow.md
index 67a3208..e5379ae 100644
--- a/config/opencode/commands/workflow.md
+++ b/config/opencode/commands/workflow.md
@@ -103,7 +103,6 @@ Dispatch `@pm` with the issue ID `$ISSUE_ID`, `$WORKTREE_PATH`, and `Validate ru
 ```json
 {
   "ok": true,
-  "issue_file_path": "<absolute path to the issue file>",
   "issue": {
     "id": "...",
     "title": "...",
@@ -129,7 +128,7 @@ Dispatch `@pm` with the issue ID `$ISSUE_ID`, `$WORKTREE_PATH`, and `Validate ru
 
 On failure, stop the workflow with `@pm`'s `message` verbatim. Do **not** attempt to inspect or repair the TODO tree from the orchestrator — that belongs to `@pm`.
 
-On success, capture `ISSUE_FILE_PATH` from the response. **Use this captured path verbatim everywhere downstream** (Phase 9 staging, Failure Handler comments, etc.) — never construct a TODO path from `$ISSUE_ID` directly.
+On success, the orchestrator works exclusively from the structured `issue` object. **Every subsequent TODO operation re-dispatches `@pm` by issue ID** — the orchestrator never holds or passes around a file path.
 
 If `issue.status == "Todo"`, dispatch `@pm` again to flip it to `In Progress` (operation: `Update status`, target: the same issue ID; `@pm` propagates to README.md / parent's `## Sub-issues` line). The status edit will be staged alongside other TODO updates in Phase 9.
 
@@ -562,8 +561,6 @@ Dispatch `@pm` with the issue ID `$ISSUE_ID` and the following operations (a sin
 
 `@pm` propagates status flips to the dependent index (the top-level README or the parent's `## Sub-issues` line) on its own — that's its job, not the orchestrator's. The orchestrator passes high-level intent ("set status to Done") and trusts `@pm` to update every dependent file.
 
-`@pm`'s response includes the list of files it modified (absolute paths). Capture this list as `MODIFIED_TODO_PATHS` for the staging step below.
-
 ### File Follow-ups
 
 Tracked-worthy unresolved items must become real TODO issues; otherwise they vanish into the per-run `summary.md` and the user (who has walked away) never sees them. Before writing the summary, scan the run for items in these categories and dispatch `@pm` to file each as a **sub-issue of the current issue** (`parent: $ISSUE_ID`).
@@ -587,11 +584,14 @@ Tracked-worthy unresolved items must become real TODO issues; otherwise they van
 
 ### Commit TODO Changes
 
-After both the TODO Update and File Follow-ups steps, stage every path returned by `@pm` in this run (the union of `MODIFIED_TODO_PATHS` and `NEW_SUBISSUE_PATHS` collected from each `@pm` dispatch). Commit them in a single atomic commit: `chore(todo): update <issue-id> status, file follow-ups`.
+After both the TODO Update and File Follow-ups steps, dispatch `@pm` with operation `Commit pending changes` and the commit message constructed from the run context:
 
-Equivalently — and more robustly, since the orchestrator can't have edited TODO files directly (Phase 1 verified the working tree was clean and the orchestrator never writes there) — stage the entire `TODO/` directory: `git add ./TODO/`. Anything staged under `TODO/` came from `@pm` during this run.
+- If follow-ups were filed: `chore(todo): update <issue-id> status, file follow-ups`.
+- Otherwise: `chore(todo): update <issue-id> status and progress`.
 
-If no follow-ups were filed, the commit message simplifies to `chore(todo): update <issue-id> status and progress`.
+`@pm` is responsible for persistence — the orchestrator does **not** run `git add` or `git commit` on TODO changes itself (per ADR-23). For the filesystem-backed `@pm`, the dispatch results in a single atomic commit on the feature branch; for tracker-backed `@pm` implementations (e.g. Linear), the dispatch is a no-op because the API calls already persisted the data.
+
+Capture the returned `sha` (may be `null` for non-filesystem trackers) for the run summary's "final commit SHA(s)" field.
 
 ### Run Summary
 - Write `$RUN_DIR/summary.md` with:
@@ -616,7 +616,8 @@ At any phase, if an unrecoverable error occurs (or a routing rule explicitly abo
 2. If any code was written, commit it with message `wip: incomplete workflow run for <issue-id>`. Stage code only — exclude `.workflow/` and `TODO/`.
 3. Leave the branch and worktree intact for the user to inspect — do not push, do not delete.
 4. Dispatch `@pm` (operation: `Add comment`, issue ID: `$ISSUE_ID`) summarising what failed and naming the abort reason if it was a routing-rule abort (e.g. `split_needed at Phase 7 task-1`, `plan_rework_remaining exhausted at Phase 8`). The orchestrator never constructs the issue file path — `@pm` resolves it.
-5. Stop execution.
+5. Dispatch `@pm` (operation: `Commit pending changes`, message: `chore(todo): record failure on <issue-id>`) so the failure note lands on the branch as a commit (per ADR-23). For tracker-backed `@pm` implementations this is a no-op. For filesystem `@pm`, the failure comment survives on the branch for the user to review before discarding the worktree.
+6. Stop execution.
 
 ### Recovery procedure (workflow is non-resumable, ADR-14)
 
diff --git a/config/opencode/workflow-design.md b/config/opencode/workflow-design.md
index 53bf3c8..df13d83 100644
--- a/config/opencode/workflow-design.md
+++ b/config/opencode/workflow-design.md
@@ -181,8 +181,10 @@ Every observed `(phase, signal) → action`. Empty cells are gaps. Walking this
 | 9 | Orchestrator | Unresolved review-loop blocker | File sub-issue via `@pm` (label: `followup`) |
 | 9 | `@test` (Phase 6) | NOT_TESTABLE future-seam note | File sub-issue via `@pm` (label: `tech-debt`) |
 | 9 | Orchestrator | `@simplify` advisory not acted on | Record in summary; do NOT file (records, not work) |
-| 9 | Orchestrator | All parent AC checked off | Set issue status to `Done`; sync README/parent; commit `chore(todo): …` |
-| 9 | Orchestrator | Some parent AC remain unchecked AND sub-issues exist | Leave issue at `In Progress`; commit `chore(todo): …` |
+| 9 | Orchestrator | All parent AC checked off | Dispatch `@pm` to set status `Done` and propagate to README/parent; then dispatch `@pm` (`Commit pending changes`) with `chore(todo): update <issue-id> status, file follow-ups` (ADR-23) |
+| 9 | Orchestrator | Some parent AC remain unchecked AND sub-issues exist | Dispatch `@pm` to leave status `In Progress` and update AC checkboxes; then dispatch `@pm` (`Commit pending changes`) with the same message scheme |
+| 9 | `@pm` (`Commit pending changes`) | `ok: true, sha: <hex>` | Capture SHA for run summary's "final commit SHA(s)" field |
+| 9 | `@pm` (`Commit pending changes`) | `ok: true, sha: null` | Tracker-backed implementation, persistence already happened via API; record "no commit" in summary |
 | Run-level | Failure Handler | Workflow is non-resumable (ADR-14) | Document the cleanup procedure: `git worktree remove`, delete branch, re-create from base, retry |
 
 ---
@@ -358,9 +360,16 @@ The model carries five sub-decisions:
 ### ADR-22 (2026-05-08) — TODO path resolution lives with `@pm`; orchestrator never constructs TODO paths
 
 **Context:** in early runs of the one-task-per-run workflow, the orchestrator sometimes did `@pm`'s job itself — reading `./TODO/$ISSUE_ID.md` directly to inspect the issue, instead of dispatching `@pm`. The text-level "anti-patterns" warning (workflow.md §Roles & Dispatch) wasn't enough to prevent it: once the workflow document told the orchestrator that issue files lived at `./TODO/<ID>.md`, the recipe was discoverable and tempting. Phase 1's sanity check (former steps 3 + 9 — TODO-tracker existence and `depends-on` enforcement) was the most blatant offender, since it required the orchestrator to read TODO files directly.
-**Decision:** the orchestrator does not read, write, or construct any path under `TODO/` at any phase. All TODO operations — including prerequisite validation that used to live in Phase 1 — go through `@pm` dispatches. `@pm`'s response always includes the absolute file path of every issue file it touched (or read); the orchestrator captures these paths and uses them downstream (Phase 9 staging, Failure Handler comments, etc.) instead of constructing them. Phase 1 keeps only git/worktree-shaped checks; Phase 2 expands `@pm`'s existing dispatch into a "Validate run prerequisites" operation that returns either `{ok: true, issue_file_path, issue: {...}}` or a structured error.
-**Alternatives:** (a) permission-deny `TODO/**` for the orchestrator — would force-fail orchestrator self-help but adds a permission layer the user prefers to avoid; (b) leave the doc warnings in place and hope the orchestrator complies — already shown to be insufficient; (c) keep Phase 1's TODO checks and just discipline the orchestrator harder — same problem as (b).
-**Consequences:** discoverability of the path layout disappears from `commands/workflow.md` — the orchestrator literally never sees a `TODO/<ID>.md` template to imitate. The schema and path layout live in `agents/pm.md`, which the orchestrator does not load. `@pm`'s capabilities table grows by one ("Validate run prerequisites") and every existing capability now mandates including the absolute file path in the response. The orchestrator's Phase 9 staging step changes from constructing paths to using `@pm`-returned paths (or, equivalently, `git add ./TODO/` since the working tree was clean at Phase 1 and only `@pm` writes to TODO during a run).
+**Decision:** the orchestrator does not read, write, or construct any path under `TODO/` at any phase, *and* `@pm`'s structured responses do not expose paths either — every reference to an issue is by ID. All TODO operations go through `@pm` dispatches; `@pm` resolves paths internally and never surfaces them to the orchestrator's structured input. Phase 1 keeps only git/worktree-shaped checks; Phase 2 expands `@pm`'s existing dispatch into a "Validate run prerequisites" operation that returns either `{ok: true, issue: {...}}` or a structured error. Phase 9 stages and commits TODO changes through `@pm`'s `Commit pending changes` capability (per ADR-23) — the orchestrator never runs `git add` or `git commit` on TODO files itself.
+**Alternatives:** (a) permission-deny `TODO/**` for the orchestrator — would force-fail orchestrator self-help but adds a permission layer the user prefers to avoid; (b) leave the doc warnings in place and hope the orchestrator complies — already shown to be insufficient; (c) return paths in `@pm`'s response so the orchestrator can stage by file — leaks the path layout the orchestrator otherwise wouldn't see, and the path is unused for any other purpose since the orchestrator already addresses issues by ID.
+**Consequences:** discoverability of the path layout disappears from `commands/workflow.md` *and* from `@pm`'s structured outputs — the orchestrator literally never sees a `TODO/<ID>.md` template to imitate, in any phase. The schema and path layout live in `agents/pm.md`, which the orchestrator does not load. `@pm`'s capabilities table grows by one ("Validate run prerequisites"). Path-construction temptation is eliminated by absence: there is no path field for the orchestrator to copy.
+
+### ADR-23 (2026-05-08) — `@pm` owns persistence (including the TODO commit)
+
+**Context:** the orchestrator was running `git add ./TODO/` and `git commit -m "chore(todo): ..."` itself in Phase 9 to commit `@pm`'s TODO updates, and the Failure Handler was leaving `@pm`'s failure-note comment uncommitted in the working tree. Both behaviors are correct for a *filesystem-backed* `@pm`, but they bake filesystem-specific persistence into the orchestrator. The design intent is that `@pm` is swappable — a Linear-backed implementation, a Notion-backed one, or any other issue-tracker adapter should drop in without touching `commands/workflow.md`. With API-backed trackers, "commit the TODO updates" is a no-op (the API call already persisted) and `git add ./TODO/` is wrong (no files to stage).
+**Decision:** persistence shape lives behind the `@pm` boundary. `@pm` gains a new capability — `Commit pending changes` — that takes a commit message and returns a structured `{ok, sha, message}` response. The filesystem-backed `@pm` implements it by running `git add ./TODO/` + `git commit -m <msg>` and returning the new SHA. Tracker-backed `@pm` implementations no-op and return `sha: null`. The orchestrator constructs the commit message from run context (it has the issue ID, what was done, whether follow-ups were filed) and dispatches `@pm` for the actual commit at end of Phase 9 and at the Failure Handler. The orchestrator never runs `git add` or `git commit` on TODO content itself.
+**Alternatives:** (a) keep orchestrator-side commit and accept that swapping `@pm` requires also touching workflow.md — defeats the swap-ability; (b) `@pm` constructs the commit message from semantic intent ("status update", "follow-ups filed") — moves run-context marshaling into `@pm` for no benefit; (c) leave failure-note comments uncommitted — current behavior, but they get lost when the user discards the throwaway worktree (ADR-14), which is silently dropping forensic data.
+**Consequences:** `@pm` gains tightly-scoped bash access — only `git add ./TODO/*`, `git add ./TODO/`, `git commit -m *`, and `git status --porcelain ./TODO/*`/`/.../`; everything else is denied (no push, reset, rebase, checkout, branch, tag). Failure-note comments now land as their own commit on the failed branch, surviving the `git worktree remove` recovery step until the user explicitly discards the branch. Stub-pass and body-pass code commits remain the orchestrator's responsibility (those are code, not tracker-specific). Run summary's "final commit SHA(s)" field captures the SHA `@pm` returned, which may be `null` for non-filesystem trackers.
 
 ---
 

From 267c05b10734937bfb7d00dbee66bb44e205836e Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Fri, 8 May 2026 15:16:33 +0200
Subject: [PATCH 097/101] feat(opencode): give @make a concrete test-smell
 checklist
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Real-world observation: @make struggles when @test sets up tests
incorrectly because the existing escalate: test_design trigger is
described abstractly ("test seems to demand wrong thing"). When @make
sees an unfamiliar smell, it tends to attempt implementation, fail,
attempt again, and only escalate after burning 2-3 cycles. The
protocol exists; the recognition criteria don't.

Restructure Entry Validation step 5 into a named "Test triage" step
with a concrete checklist that fires *before* any implementation
attempt. Four categories of smells:

- **Mocking smells:** mocks the SUT, >2 mocks, mock-call-as-primary
  assertion, internal-boundary mocking
- **Structural-only smells:** variant counts, type ascriptions,
  function-pointer coercion, struct-literal-with-field-reads,
  stub-first no-panics (mirrors @test.md's anti-patterns)
- **Wrong-target smells:** asserts on private state / log strings,
  demands contradicting spec, physically impossible demands
- **Setup smells:** fixtures bypassing production validation,
  wrong-module imports, references to nonexistent infrastructure

Iteration Limits step 5 now cross-references the same checklist
instead of restating abstract criteria, so both gates apply the same
recognition rules with a single source of truth.

A "NOT for" caveat prevents over-eager escalation: when the test is
fine but the implementation is just hard, that's not a smell, that's
the test doing its job.

The checklist is inlined (not pulled from @test.md at runtime) because
subagents have separate contexts. Periodic manual sync between
@make.md's checklist and @test.md's anti-patterns is acceptable —
they shouldn't drift much in practice.

Refs: config/opencode/agents/test.md (anti-patterns + structural-only
list it mirrors), config/opencode/workflow-design.md ADR-19 (unified
Implementation Incomplete diagnosis path)
---
 config/opencode/agents/make.md | 40 +++++++++++++++++++++++++++++-----
 1 file changed, 35 insertions(+), 5 deletions(-)

diff --git a/config/opencode/agents/make.md b/config/opencode/agents/make.md
index 7e9f270..5c9bb8e 100644
--- a/config/opencode/agents/make.md
+++ b/config/opencode/agents/make.md
@@ -331,7 +331,7 @@ If tests fail or verification doesn't pass:
 2. **Context/spec issues** — Stop immediately and report; don't guess
 3. **Code issues** — Attempt fix (max 2-3 attempts if making progress)
 4. **Flaky/infra issues** — Stop and report with diagnostics
-5. **Test-design suspicion** — If after 1–2 attempts the test seems to demand production code that contradicts the spec, asserts on internal state that shouldn't be observable, mocks an internal boundary instead of the external one, or otherwise looks like it's testing the wrong thing — **stop and report with `escalate: test_design`** in the Blocking Issue section. Do not modify the test file yourself; the caller will route to `@check` for diagnosis and `@test` for redesign per the workflow's Phase 7 escalation.
+5. **Test-design suspicion** — If you reach this step *after* implementation attempts, you missed the smell at Entry Validation. Re-read the test against the **Test-design smell checklist** in the TDD Mode → Entry Validation section above. If any smell now matches (often it's the "wrong-target" or "setup" categories that only become visible once you've tried to satisfy them), **stop and report with `escalate: test_design`** in the Blocking Issue section, naming the specific smell. Do not modify the test file yourself; the caller will route to `@check` for diagnosis and `@test` for redesign per the workflow's Phase 7 escalation.
 6. **Task-scope suspicion** — If after 1–2 attempts you find that the AC realistically require modifying files not listed in your "Files to Modify," or the AC mix multiple distinct concerns that don't fit one coherent change (e.g. a new type *and* its registration site *and* a new system using it), the task is over-scoped — **stop and report with `escalate: split_needed`** in the Blocking Issue section. State concretely which file(s) outside your modify list you'd need, or which concerns the task is mixing. Do not silently expand scope; the caller will route to `@check` for diagnosis and (per the workflow's ADR-21) the run will abort to the Failure Handler so the user can re-plan from scratch.
 
 The `escalate:` flag is a *hint* to the caller's diagnosis routing — `@check` is the authority that confirms or rejects it. Reporting `escalate: split_needed` doesn't guarantee the run aborts; if `@check` decides the task is sound and the issue is in tests or production code, the diagnosis will route back to a normal `test_design` or `production_logic` verdict.
@@ -418,11 +418,41 @@ When the caller provides pre-written failing tests from `@test`:
 ### Entry Validation
 1. Run the provided tests using the exact command from the handoff.
 2. Confirm they fail (RED). Compare against the expected failing tests and failure codes from the handoff.
-3. If tests PASS before implementation: STOP. Report anomaly to caller — behavior already exists, task spec may be wrong.
-4. If tests fail for wrong reason (TEST_BROKEN): STOP. Report to caller for test fixes.
-5. If test quality concerns (wrong assertions, testing mocks, missing edge cases): report with details. Caller routes to `@check` for diagnosis, then to `@test` for fixes.
+3. **PASS-before-implementation** — If tests pass without any production-code change: STOP. Report anomaly to caller — behavior already exists, task spec may be wrong.
+4. **Wrong-reason failure** — If tests fail for the wrong reason (TEST_BROKEN — e.g. import error, syntax error, fixture exception unrelated to the AC): STOP. Report to caller for test fixes.
+5. **Test triage** (do this *before* attempting any implementation) — read each test file and evaluate setup quality against the checklist below. Any single match is sufficient to escalate. **Stop and report with `escalate: test_design`** in the Blocking Issue section, naming the specific smell and which test exhibits it. Do not start implementing.
 
-**Escalation ownership:** You diagnose and report test issues. You do NOT edit test files. The caller routes to `@check` (diagnosis) → `@test` (fixes) → back to you.
+#### Test-design smell checklist
+
+Recognize these patterns by reading the test file before you write any production code. If you spot one, the test is set up wrong — escalate; the caller routes to `@check` → `@test` for redesign.
+
+**Mocking smells:**
+- Mocks the system-under-test itself (the function/method/module the test claims to verify).
+- Asserts on mock-call counts or argument matchers as the *primary* assertion, with no real-behavior assertion to back it up. ("`mock.foo.assert_called_with(x)`" is a means, not an end.)
+- More than 2 mocks in a single test — usually means the production code's collaborator graph has been mocked rather than the external boundary.
+- Mocks an internal boundary (a private helper, a same-crate module) instead of the external one (network, filesystem, time, RNG).
+
+**Structural-only smells (the test compiles but doesn't exercise behavior):**
+- `assert_eq!(std::mem::variant_count::<X>(), N)` or similar enum/struct shape checks — refactor-tripwire, not behavior.
+- `let _: TypeName = …;` / `let _: fn(…) -> _ = my_fn;` — type ascriptions tell you the symbol exists, not what it does.
+- `Box::new(my_fn)` / `&my_fn as &dyn Fn(…)` — coercing a function pointer is not calling it.
+- Struct-literal construction (`Foo { a: 1, b: 2 }`) followed only by field re-reads — exercises field access, not methods.
+- In stub-first runs (Rust ADR-7): tests that pass without panicking on `todo!()` — by definition no test actually called the stub.
+
+**Wrong-target smells:**
+- Asserts on internal/private state that the production code shouldn't expose (`assert_eq!(obj._private_counter, 5)`).
+- Asserts on log-output strings as a stand-in for behavior (use the actual return value or side effect).
+- Tests demand production code that contradicts the task spec — the test wants a return type, signature, or side effect different from what the AC describes.
+- Tests demand production code that is *physically impossible* (e.g. requires reading a value before it's been written, or accessing a field that was never declared).
+
+**Setup smells:**
+- Fixtures construct state in a way that doesn't match how production code expects to receive it (e.g. test inserts a row directly bypassing the validation the production code requires).
+- Test imports refer to symbols at paths that don't match where the production code lives (the test is testing the wrong module).
+- Test file uses fixtures or helpers that don't exist anywhere in the codebase — the test relies on infrastructure that was never built.
+
+**One thing this list is NOT for:** legitimate cases where the test exposes a *production-code* gap (the implementation needs to be different to make the test pass). That's not a test smell — that's the test doing its job. Escalate `test_design` only when the test setup itself is wrong, not when the implementation is just hard.
+
+**Escalation ownership:** You diagnose and report test issues. You do NOT edit test files. The caller routes to `@check` (diagnosis — `@check` confirms or rejects your `test_design` hint) → `@test` (fixes) → back to you for fresh entry validation.
 
 ### Implementation
 6. Write minimal code to make the failing tests pass.

From bef528e26a73bf07b6ec23d9374a7045c24dd072 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Thu, 7 May 2026 16:58:03 +0200
Subject: [PATCH 098/101] feat(halo): use qwen-35b-a3b

---
 systems/x86_64-linux/halo/default.nix         |  2 +-
 .../x86_64-linux/halo/llama-server-27B.nix    | 59 +++++++++++++++++++
 systems/x86_64-linux/halo/llama-server.nix    |  4 +-
 3 files changed, 62 insertions(+), 3 deletions(-)
 create mode 100644 systems/x86_64-linux/halo/llama-server-27B.nix

diff --git a/systems/x86_64-linux/halo/default.nix b/systems/x86_64-linux/halo/default.nix
index afece0e..1934cd8 100644
--- a/systems/x86_64-linux/halo/default.nix
+++ b/systems/x86_64-linux/halo/default.nix
@@ -10,7 +10,7 @@ with lib.metacfg;
     ./hardware-configuration.nix
     #./xremap.nix
     ./wyoming.nix
-    ./llama-server-coder-next.nix
+    ./llama-server.nix
   ];
 
   boot.lanzaboote.pkiBundle = "/var/lib/sbctl";
diff --git a/systems/x86_64-linux/halo/llama-server-27B.nix b/systems/x86_64-linux/halo/llama-server-27B.nix
new file mode 100644
index 0000000..1a2faa3
--- /dev/null
+++ b/systems/x86_64-linux/halo/llama-server-27B.nix
@@ -0,0 +1,59 @@
+{
+  pkgs,
+  lib,
+  ...
+}:
+{
+  systemd.services.llama-server = {
+    description = "llama.cpp server (Qwen3.6-27B, ROCm)";
+    after = [ "network-online.target" ];
+    wants = [ "network-online.target" ];
+    wantedBy = [ "multi-user.target" ];
+
+    environment = {
+      HOME = "%S/llama-server";
+      HF_HOME = "%S/llama-server";
+    };
+
+    serviceConfig = {
+      Type = "simple";
+      DynamicUser = true;
+      SupplementaryGroups = [
+        "video"
+        "render"
+      ];
+      StateDirectory = "llama-server";
+      CacheDirectory = "llama-server";
+      WorkingDirectory = "%S/llama-server";
+      ExecStartPre = "${pkgs.coreutils}/bin/mkdir -p %C/llama-server/kv-slots";
+      ExecStart = lib.concatStringsSep " " [
+        "${pkgs.llama-cpp-rocm}/bin/llama-server"
+        "--flash-attn on"
+        "--parallel 2"
+        "--jinja"
+        "--host 0.0.0.0"
+        "--port 8000"
+        "--no-mmap"
+        "--n-gpu-layers 99"
+        "-hf unsloth/Qwen3.6-27B-GGUF:UD-Q8_K_XL"
+        "--alias qwen3.6-27b"
+        "--threads 8"
+        "--ubatch-size 256"
+        "-ctk bf16 -ctv bf16"
+        "--temp 0.6 --top-p 0.95 --top-k 20 --min-p 0.00"
+        "--no-context-shift"
+        ''--chat-template-kwargs '{"preserve_thinking": true}' ''
+        "-c 524288"
+        "--fit on"
+        "--slot-save-path %C/llama-server/kv-slots-27B"
+      ];
+      Restart = "on-failure";
+      RestartSec = 10;
+
+      PrivateTmp = true;
+      ProtectSystem = "strict";
+      ProtectHome = true;
+      NoNewPrivileges = true;
+    };
+  };
+}
diff --git a/systems/x86_64-linux/halo/llama-server.nix b/systems/x86_64-linux/halo/llama-server.nix
index 84f1831..b6ad09c 100644
--- a/systems/x86_64-linux/halo/llama-server.nix
+++ b/systems/x86_64-linux/halo/llama-server.nix
@@ -35,8 +35,8 @@
         "--port 8000"
         "--no-mmap"
         "--n-gpu-layers 99"
-        "-hf unsloth/Qwen3.6-27B-GGUF:UD-Q8_K_XL"
-        "--alias qwen3.6-27b"
+        "-hf unsloth/Qwen3.6-35B-A3B-GGUF:UD-Q8_K_XL"
+        "--alias qwen3.6-35b-a3b"
         "--threads 8"
         "--ubatch-size 256"
         "-ctk bf16 -ctv bf16"

From 689cdec28dda70671ee9f827e535802929d04537 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Sun, 10 May 2026 20:43:33 +0200
Subject: [PATCH 099/101] feat(halo): activate qwen 27b

---
 systems/x86_64-linux/halo/default.nix      | 2 +-
 systems/x86_64-linux/halo/llama-server.nix | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/systems/x86_64-linux/halo/default.nix b/systems/x86_64-linux/halo/default.nix
index 1934cd8..c25e491 100644
--- a/systems/x86_64-linux/halo/default.nix
+++ b/systems/x86_64-linux/halo/default.nix
@@ -10,7 +10,7 @@ with lib.metacfg;
     ./hardware-configuration.nix
     #./xremap.nix
     ./wyoming.nix
-    ./llama-server.nix
+    ./llama-server-27B.nix
   ];
 
   boot.lanzaboote.pkiBundle = "/var/lib/sbctl";
diff --git a/systems/x86_64-linux/halo/llama-server.nix b/systems/x86_64-linux/halo/llama-server.nix
index b6ad09c..340b775 100644
--- a/systems/x86_64-linux/halo/llama-server.nix
+++ b/systems/x86_64-linux/halo/llama-server.nix
@@ -29,7 +29,7 @@
       ExecStart = lib.concatStringsSep " " [
         "${pkgs.llama-cpp-rocm}/bin/llama-server"
         "--flash-attn on"
-        "--parallel 2"
+        "--parallel 1"
         "--jinja"
         "--host 0.0.0.0"
         "--port 8000"
@@ -43,7 +43,7 @@
         "--temp 0.6 --top-p 0.95 --top-k 20 --min-p 0.00"
         "--no-context-shift"
         ''--chat-template-kwargs '{"preserve_thinking": true}' ''
-        "-c 524288"
+        "-c 262144"
         "--fit on"
         "--slot-save-path %C/llama-server/kv-slots"
       ];

From 04342222a2d5bf0b3d880fcc35625b6c3c2396b3 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Sun, 10 May 2026 20:46:12 +0200
Subject: [PATCH 100/101] fix(halo): 27b

---
 systems/x86_64-linux/halo/llama-server-27B.nix | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/systems/x86_64-linux/halo/llama-server-27B.nix b/systems/x86_64-linux/halo/llama-server-27B.nix
index 1a2faa3..ab25831 100644
--- a/systems/x86_64-linux/halo/llama-server-27B.nix
+++ b/systems/x86_64-linux/halo/llama-server-27B.nix
@@ -25,7 +25,7 @@
       StateDirectory = "llama-server";
       CacheDirectory = "llama-server";
       WorkingDirectory = "%S/llama-server";
-      ExecStartPre = "${pkgs.coreutils}/bin/mkdir -p %C/llama-server/kv-slots";
+      ExecStartPre = "${pkgs.coreutils}/bin/mkdir -p %C/llama-server/kv-slots-27B";
       ExecStart = lib.concatStringsSep " " [
         "${pkgs.llama-cpp-rocm}/bin/llama-server"
         "--flash-attn on"

From 7b04b55ce8d7d11f41b611a7f75b6c91977d08c9 Mon Sep 17 00:00:00 2001
From: Harald Hoyer <harald@hoyer.xyz>
Date: Sun, 10 May 2026 20:50:08 +0200
Subject: [PATCH 101/101] feat(halo): cache-ram 0

---
 systems/x86_64-linux/halo/llama-server-27B.nix | 1 +
 1 file changed, 1 insertion(+)

diff --git a/systems/x86_64-linux/halo/llama-server-27B.nix b/systems/x86_64-linux/halo/llama-server-27B.nix
index ab25831..d86cee9 100644
--- a/systems/x86_64-linux/halo/llama-server-27B.nix
+++ b/systems/x86_64-linux/halo/llama-server-27B.nix
@@ -46,6 +46,7 @@
         "-c 524288"
         "--fit on"
         "--slot-save-path %C/llama-server/kv-slots-27B"
+        "--cache-ram 0"
       ];
       Restart = "on-failure";
       RestartSec = 10;