docs(specs): bootstrap linked specs and isolate build sources

AGENTS.md

@@ -1,5 +1,8 @@
 # Flakebox agent notes
 
+This project uses the Linked Specs convention; consult the `linked-specs`
+skill before working with specs or governed code.
+
 ## What this repo is
 
 - Flakebox is a Nix-based Rust dev-env toolkit.

checks/ast-grep-rules.nix

@@ -1,8 +1,14 @@
-{ pkgs }:
+{ pkgs, flakeboxLib }:
 pkgs.runCommand "ast-grep-rules"
   {
     nativeBuildInputs = [ pkgs.ast-grep ];
-    src = pkgs.lib.cleanSource ../.;
+    src = pkgs.lib.sources.cleanSourceWith {
+      src = ../.;
+      filter = flakeboxLib.source.filters.all [
+        pkgs.lib.sources.cleanSourceFilter
+        (flakeboxLib.source.filters.excludeDirectoriesNamed [ "specs" ])
+      ];
+    };
   }
   ''
     cp -r "$src" source

checks/cell-aware-cross-inputs/default.nix

@@ -34,7 +34,17 @@ let
         package = craneLib.buildPackage {
           pname = "cell-aware-cross-inputs";
           version = "0.1.0";
-          src = craneLib.cleanCargoSource ./.;
+          src = craneLib.cleanCargoSource (
+            flakeboxLib.source.fromPaths {
+              root = ./.;
+              paths = [
+                "Cargo.toml"
+                "Cargo.lock"
+                "src"
+              ];
+              filter = flakeboxLib.source.filters.excludeDirectoriesNamed [ "specs" ];
+            }
+          );
           strictDeps = true;
         };
       });

checks/custom-stdenv/default.nix

@@ -29,7 +29,11 @@ let
             cargoArtifacts = null;
             cargoVendorDir = null;
             doInstallCargoArtifacts = false;
-            src = ./.;
+            src = flakeboxLib.source.fromFileset {
+              root = ./.;
+              fileset = ./default.nix;
+              filter = flakeboxLib.source.filters.excludeDirectoriesNamed [ "specs" ];
+            };
             buildPhaseCargoCommand = ''
               set -x
               if [[ "$(${pkgs.which}/bin/which cc)" != *clang-wrapper-${clangMajor}* ]]; then

checks/nextest/default.nix

@@ -14,6 +14,7 @@ let
       src = flakeboxLib.source.fromPaths {
         root = rootDir;
         paths = buildPaths;
+        filter = flakeboxLib.source.filters.excludeDirectoriesNamed [ "specs" ];
       };
 
       craneLib = craneLib'.overrideArgs {

checks/source-tests.nix

@@ -22,8 +22,8 @@ let
     };
 
   baseline = mkFixtureSource (fixture + "/baseline");
-  excludedChange = mkFixtureSource (fixture + "/excluded-change");
-  selectedChange = mkFixtureSource (fixture + "/selected-change");
+  linkedSpecsEdit = mkFixtureSource (fixture + "/excluded-change");
+  selectedInputEdit = mkFixtureSource (fixture + "/selected-change");
 
   buildFiles = source.filesetFromPaths {
     root = fixture + "/baseline";
@@ -67,11 +67,11 @@ let
   fails = value: !(builtins.tryEval (builtins.deepSeq value true)).success;
 in
 assert lib.assertMsg (
-  toString baseline == toString excludedChange
-) "changes to excluded content must preserve the source store path";
+  toString baseline == toString linkedSpecsEdit
+) "Linked Specs edits must preserve the build source store path";
 assert lib.assertMsg (
-  toString baseline != toString selectedChange
-) "changes to selected content must alter the source store path";
+  toString baseline != toString selectedInputEdit
+) "selected build input edits must alter the build source store path";
 assert lib.assertMsg (
   !(source.filters.all [
     (_path: _type: false)

checks/workspace-cross-compile/default.nix

@@ -28,6 +28,7 @@ let
       src = flakeboxLib.source.fromPaths {
         root = rootDir;
         paths = buildPaths;
+        filter = flakeboxLib.source.filters.excludeDirectoriesNamed [ "specs" ];
       };
 
       craneLib =
@@ -87,6 +88,7 @@ let
         src = flakeboxLib.source.fromPaths {
           root = rootDir;
           paths = testPaths;
+          filter = flakeboxLib.source.filters.excludeDirectoriesNamed [ "specs" ];
         };
       };
     }

checks/workspace-sanity/default.nix

@@ -23,6 +23,7 @@ let
       src = flakeboxLib.source.fromPaths {
         root = rootDir;
         paths = buildPaths;
+        filter = flakeboxLib.source.filters.excludeDirectoriesNamed [ "specs" ];
       };
 
       craneLib =
@@ -77,6 +78,7 @@ let
         src = flakeboxLib.source.fromPaths {
           root = rootDir;
           paths = testPaths;
+          filter = flakeboxLib.source.filters.excludeDirectoriesNamed [ "specs" ];
         };
       };
     }

docs/building-new-project.md

@@ -329,6 +329,7 @@ index cb41316..08c8f65 100644
 +            ".cargo"
 +            "src"
 +          ];
++          filter = flakeboxLib.source.filters.excludeDirectoriesNamed [ "specs" ];
 +        };
 +
 +        legacyPackages = (flakeboxLib.craneMultiBuild { }) (craneLib':
@@ -439,6 +440,7 @@ The next binding is:
             ".cargo"
             "src"
           ];
+          filter = flakeboxLib.source.filters.excludeDirectoriesNamed [ "specs" ];
         };
 ```
 

docs/flakeboxLib.md

@@ -21,6 +21,7 @@ let
   src = flakeboxLib.source.fromPaths {
     root = ./.;
     paths = buildPaths;
+    filter = flakeboxLib.source.filters.excludeDirectoriesNamed [ "specs" ];
   };
 in
 # ...
@@ -36,11 +37,13 @@ Reuse path lists when later build stages need extra inputs:
 buildSrc = flakeboxLib.source.fromPaths {
   root = ./.;
   paths = buildPaths;
+  filter = flakeboxLib.source.filters.excludeDirectoriesNamed [ "specs" ];
 };
 
 testSrc = flakeboxLib.source.fromPaths {
   root = ./.;
   paths = buildPaths ++ [ "scripts" ];
+  filter = flakeboxLib.source.filters.excludeDirectoriesNamed [ "specs" ];
 };
 ```
 
@@ -66,10 +69,12 @@ in {
   buildSrc = source.fromFileset {
     root = ./.;
     fileset = buildFiles;
+    filter = source.filters.excludeDirectoriesNamed [ "specs" ];
   };
   testSrc = source.fromFileset {
     root = ./.;
     fileset = fs.union buildFiles ./scripts;
+    filter = source.filters.excludeDirectoriesNamed [ "specs" ];
   };
 }
 ```

docs/getting-started.md

@@ -70,6 +70,7 @@ Following modifications to `flake.nix` are needed:
         buildSrc = flakeboxLib.source.fromPaths {
           root = ./.;
           paths = buildPaths;
+          filter = flakeboxLib.source.filters.excludeDirectoriesNamed [ "specs" ];
         };
 
         # Add toolchain x profile build matrix

flake.nix

@@ -96,6 +96,7 @@
             nixpkgs
             ;
         };
+
     in
     {
       inherit overlays;
@@ -147,6 +148,7 @@
             ".cargo"
             "flakebox-bin"
           ];
+          filter = flakeboxLib.source.filters.excludeDirectoriesNamed [ "specs" ];
         };
 
         outputs = (flakeboxLib.craneMultiBuild { }) (

lib/default.nix

@@ -65,7 +65,10 @@ lib.makeScope pkgs.newScope (
 
     docs = pkgs.stdenv.mkDerivation {
       name = "docs";
-      src = ../docs;
+      src = lib.sources.cleanSourceWith {
+        src = ../docs;
+        filter = self.source.filters.excludeDirectoriesNamed [ "specs" ];
+      };
 
       # Depend on the generated options reference used by the book.
       buildInputs = [ optionsDocMd ];

lib/flakeboxBin.nix

@@ -1,17 +1,16 @@
 {
-  lib,
   pkgs,
+  source,
 }:
 let
-  fs = lib.fileset;
-  fileSet = fs.unions [
-    ../Cargo.toml
-    ../Cargo.lock
-    ../flakebox-bin
-  ];
-  src = fs.toSource {
+  src = source.fromPaths {
     root = ../.;
-    fileset = fileSet;
+    paths = [
+      "Cargo.toml"
+      "Cargo.lock"
+      "flakebox-bin"
+    ];
+    filter = source.filters.excludeDirectoriesNamed [ "specs" ];
   };
 in
 pkgs.rustPlatform.buildRustPackage {

lib/specs/ARCH-flakebox-nix-library.md

@@ -0,0 +1,28 @@
+# ARCH-flakebox-nix-library: Flakebox Nix library architecture
+
+This record refines [ARCH-flakebox](../../specs/ARCH-flakebox.md) for `lib/`.
+
+`mkLib pkgs { modules, config }` is the library composition boundary. It
+evaluates built-in modules, caller extensions, and caller configuration, then
+returns a scoped library instance bound to one package set and system. Modules
+declare options and contribute through shared aggregation points for generated
+repository files, shell environment and hooks, Git hooks, Just rules, and
+GitHub workflows.
+
+The generated root is the declarative desired project state. The library
+materializes it, gives it a content identity, and exposes it and its generated
+shell hook to development shells. The `flakebox` CLI, outside this scope, owns
+comparison and synchronization with a mutable worktree.
+
+Target constructors provide target-specific build arguments and Rust component
+targets. Toolchain constructors combine those descriptions with Fenix and an
+enhanced Crane instance. `craneMultiBuild` maps consumer-defined outputs across
+the configured toolchain and Cargo-profile cells while resolving each cell's
+build-input roles.
+
+Source construction remains explicit and caller-owned. Callers select every
+input their build or check consumes and apply additional predicates where
+needed. Repository-derived sources exclude directories named `specs`
+recursively so governing records do not enter builds or invalidate their
+source identities. `docs/flakeboxLib.md` owns the public source and build-matrix
+API details; checks provide executable conformance coverage.

specs/ARCH-flakebox.md

@@ -0,0 +1,31 @@
+# ARCH-flakebox: Flakebox architecture
+
+Flakebox is a Nix-flake-delivered toolkit for Rust development environments.
+Its main boundaries are the Nix library in `lib/`, the `flakebox` CLI, the
+default project template, user documentation, and checks built against the
+public library.
+
+`flake.nix` exposes the overlay, template, and `mkLib` constructor, then
+instantiates system-specific packages, checks, and development shells. `mkLib`
+evaluates Flakebox's built-in modules together with caller modules and
+configuration. The resulting library instance provides generated project
+state, shells, source selection, target and toolchain construction, Crane
+integration, build-matrix assembly, and supporting helpers. The detailed
+library topology is described by
+[ARCH-flakebox-nix-library](../lib/specs/ARCH-flakebox-nix-library.md).
+
+Modules contribute declarative project state and shell behavior. The library
+materializes that state as an immutable candidate root and exposes it to
+development shells. The CLI is the imperative boundary: it checks the candidate
+against a mutable project checkout and explicitly installs it when requested;
+it also owns local lint and documentation entry points. It does not generate
+the candidate contents.
+
+Rust build inputs flow through explicit source selection into enhanced Crane
+instances and then through the configured profile and toolchain cells.
+Directories named `specs` contain governing documentation, not build inputs,
+and repository-derived build sources prune them recursively. Checks exercise
+the public library with evaluation assertions, realistic fixture builds, and
+generated integration behavior. User procedures and API details remain in
+`docs/`, while generated option documentation owns the complete configuration
+reference.

templates/default/flake.nix

@@ -38,6 +38,7 @@
         buildSrc = flakeboxLib.source.fromPaths {
           root = ./.;
           paths = buildPaths;
+          filter = flakeboxLib.source.filters.excludeDirectoriesNamed [ "specs" ];
         };
 
         multiBuild = (flakeboxLib.craneMultiBuild { }) (