From 680d81bc7212edc4cf13e1efdfdedb45f2f57e8e Mon Sep 17 00:00:00 2001
From: Graeme Foster <80714+GraemeF@users.noreply.github.com>
Date: Sun, 2 Aug 2026 19:56:53 +0100
Subject: [PATCH] bd lives in a maintainer shell, so a contributor's dev shell
 is unchanged (comms-v22p)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The maintainers' bd tracker is not part of this repository, but its client
has to be resolvable at a known version — an older bd against a newer tracker
schema exits 0 and corrupts, so "whatever bd is on PATH" is not a safe answer.

Putting bd in the default dev shell would charge every external contributor a
Go toolchain they have no use for. Nix fetches flake inputs per output, so a
`maintainer` shell keeps the cost where the benefit is: with the beads input
reachable only from that shell, `nix develop` and `nix develop .#ci` never
fetch, evaluate or build it. Verified by poisoning the input's narHash in
flake.lock — `.#default` and `.#ci` still evaluate, `.#maintainer` fails.

Selecting the shell is the untracked half: `.envrc` gains a
`source_env_if_exists .envrc.local`, inert when the file is absent, and a
maintainer puts `use flake .#maintainer` in that file. The tracker stays out
of the repository; only the seam for reaching it is in.

Claude-Session: https://claude.ai/code/session_011WxL3mg6KnFnw8jHp31jsU
---
 .envrc     |  3 +++
 .gitignore |  1 +
 flake.lock | 38 +++++++++++++++++++++++++++++++++++++-
 flake.nix  | 23 +++++++++++++++++++++--
 4 files changed, 62 insertions(+), 3 deletions(-)

diff --git a/.envrc b/.envrc
index b050f6f..80a3f87 100644
--- a/.envrc
+++ b/.envrc
@@ -1,2 +1,5 @@
 use flake
 dotenv_if_exists .env.local
+# Optional local overrides, untracked. A maintainer selects the tracker-aware
+# shell here with `use flake .#maintainer`; with no such file this is a no-op.
+source_env_if_exists .envrc.local
diff --git a/.gitignore b/.gitignore
index 7e0b2f5..fc23d19 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,6 +5,7 @@ result
 result-*
 .bun-result
 .env.local
+.envrc.local
 .worktrees/
 CLAUDE.local.md
 
diff --git a/flake.lock b/flake.lock
index 25f9b72..883e67c 100644
--- a/flake.lock
+++ b/flake.lock
@@ -1,6 +1,41 @@
 {
   "nodes": {
+    "beads": {
+      "inputs": {
+        "nixpkgs": "nixpkgs"
+      },
+      "locked": {
+        "lastModified": 1785088246,
+        "narHash": "sha256-5oDI2MunHrOKx1m5mC0ZaIqZ9+f1YBQotMBUj6U5H1I=",
+        "owner": "gastownhall",
+        "repo": "beads",
+        "rev": "20e493e569c922d1253bdeff068c5e56c94957fb",
+        "type": "github"
+      },
+      "original": {
+        "owner": "gastownhall",
+        "ref": "v1.1.2",
+        "repo": "beads",
+        "type": "github"
+      }
+    },
     "nixpkgs": {
+      "locked": {
+        "lastModified": 1781509190,
+        "narHash": "sha256-uJZs9Di8I6ciTp6jiojj0HzlNpBkud8ax5aT/O5aJkw=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "d6df3513510aa548c83868fd22bfddd0a8c0a0d4",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-25.11",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "nixpkgs_2": {
       "locked": {
         "lastModified": 1778274207,
         "narHash": "sha256-I4puXmX1iovcCHZlRmztO3vW0mAbbRvq4F8wgIMQ1MM=",
@@ -18,7 +53,8 @@
     },
     "root": {
       "inputs": {
-        "nixpkgs": "nixpkgs"
+        "beads": "beads",
+        "nixpkgs": "nixpkgs_2"
       }
     }
   },
diff --git a/flake.nix b/flake.nix
index 2203712..8cf866a 100644
--- a/flake.nix
+++ b/flake.nix
@@ -3,10 +3,17 @@
 
   inputs = {
     nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
+
+    # Reached only by `devShells.maintainer`. Nix fetches flake inputs per
+    # output, so `nix develop` and `nix develop .#ci` — everything a
+    # contributor and CI touch — never fetch, evaluate or build this. No
+    # `inputs.nixpkgs.follows`: beads needs Go 1.26 and this flake's nixpkgs
+    # carries 1.25.
+    beads.url = "github:gastownhall/beads/v1.1.2";
   };
 
   outputs =
-    { nixpkgs, ... }:
+    { nixpkgs, beads, ... }:
     let
       systems = [
         "x86_64-linux"
@@ -86,7 +93,7 @@
       };
 
       devShells = forAllSystems (
-        { pkgs, ... }:
+        { pkgs, system }:
         let
           # Tooling the gate needs: bun runs the TS gate, uv drives the
           # clients/hermes Python gate (//#test:hermes → scripts/test.sh).
@@ -108,6 +115,18 @@
           ci = pkgs.mkShell {
             packages = gateTools;
           };
+          # The default shell plus `bd`, the client for the maintainers' issue
+          # tracker. That tracker is not part of this repository — external
+          # contributors don't need it and file GitHub issues instead (see
+          # AGENTS.md) — so `bd` lives here rather than in `default`, and
+          # entering this shell is opt-in. Select it locally with an untracked
+          # `.envrc.local` containing `use flake .#maintainer`.
+          maintainer = pkgs.mkShell {
+            packages = gateTools ++ [
+              pkgs.typescript-language-server
+              beads.packages.${system}.bd
+            ];
+          };
         }
       );
     };