chore(policy): enforce no-fallbacks inside Nix dev shell; update scripts and shellHook

- Enforce reproducibility policy: when `IN_NIX_SHELL` is set, do not use online or ad‑hoc fallbacks.
- scripts/md-mermaid-validate.sh: remove npx fallback inside Nix shell; outside shell still supports best‑effort npx with system Chrome/Chromium if available.
- Justfile conf-schema-validate: if `ajv` is missing inside Nix shell, exit 127 with guidance to add `pkgs.nodePackages."ajv-cli"` to flake.nix; only use `npx` when outside the shell.
- flake.nix shellHook: wrap `docson` helper to refuse npx fallback inside Nix shell and instruct adding a proper package; allow npx only outside shell.
- Keep earlier Justfile documentation block describing the policy at the top.

This converts the previous docs-only change into an enforced policy across our dev tooling.

Author: zah

Justfile

@@ -1,3 +1,15 @@
+#
+# Nix Dev Shell Policy (reproducibility)
+# -------------------------------------
+# When running inside the Nix dev shell (environment variable `IN_NIX_SHELL` is set),
+# Just tasks and helper scripts MUST NOT use fallbacks such as `npx`, brew installs,
+# network downloads, or any ad-hoc tool bootstrap. If a required command is missing
+# in that context, the correct fix is to add it to `flake.nix` (devShell.buildInputs)
+# and re-enter the shell, not to fall back. Outside of the Nix shell, tasks may use
+# best-effort fallbacks for convenience, but scripts should gate them like:
+#   if [ -n "$IN_NIX_SHELL" ]; then echo "missing <tool>; fix flake.nix" >&2; exit 127; fi
+# This keeps `nix develop` fully reproducible and prevents hidden network variability.
+
 # Run the test suite
 
 test:
@@ -22,7 +34,11 @@ conf-schema-validate:
     if command -v ajv >/dev/null 2>&1; then
         AJV=ajv
     else
-        echo "ajv not found; using npx ajv-cli (requires network)" >&2
+        if [ -n "${IN_NIX_SHELL:-}" ]; then
+            echo "Error: 'ajv' is missing inside Nix dev shell. Add pkgs.nodePackages.\"ajv-cli\" to flake.nix devShell inputs." >&2
+            exit 127
+        fi
+        echo "ajv not found; falling back to 'npx ajv-cli' outside Nix shell (requires network)" >&2
         AJV='npx -y ajv-cli'
     fi
     for f in specs/schemas/*.json; do

flake.nix

@@ -107,8 +107,23 @@
 
         shellHook = ''
           echo "Agent workflow development environment loaded"
-          # Provide a convenience function to launch Docson without global install
-          docson () { npx -y docson "$@"; }
+          # Provide a convenience function for Docson; no fallbacks in Nix shell
+          docson () {
+            if command -v docson >/dev/null 2>&1; then
+              command docson "$@"
+              return
+            fi
+            if [ -n "${IN_NIX_SHELL:-}" ]; then
+              echo "Docson is not available in this Nix dev shell. Add it to flake.nix (or choose an alternative) — no fallbacks allowed." >&2
+              return 127
+            fi
+            if command -v npx >/dev/null 2>&1; then
+              npx -y docson "$@"
+            else
+              echo "Docson not found and npx unavailable. Install Docson or enter nix develop with it provisioned." >&2
+              return 127
+            fi
+          }
           echo "Tip: run: docson -d ./specs/schemas  # then open http://localhost:3000"
           # Ensure mermaid-cli (mmdc) uses system Chrome/Chromium when present
           if command -v chromium >/dev/null 2>&1; then

scripts/md-mermaid-validate.sh

@@ -5,10 +5,14 @@ set -euo pipefail
 if command -v mmdc >/dev/null 2>&1; then
   MMDC_CMD="mmdc"
 else
-  # Fallback to npx if available (requires network on first run)
+  # Inside a Nix dev shell we must not fallback; require fixing flake.nix
+  if [[ -n "${IN_NIX_SHELL:-}" ]]; then
+    echo "mmdc (mermaid-cli) not found in Nix dev shell. Fix flake.nix devShell inputs; no fallbacks allowed." >&2
+    exit 127
+  fi
+  # Outside Nix shell: allow best-effort npx fallback with system Chrome/Chromium
   if command -v npx >/dev/null 2>&1; then
     MMDC_CMD="npx -y @mermaid-js/mermaid-cli"
-    # Prefer system Chrome/Chromium if present to avoid downloads
     for bin in chromium chromium-browser google-chrome google-chrome-stable; do
       if command -v "$bin" >/dev/null 2>&1; then
         export PUPPETEER_EXECUTABLE_PATH="$(command -v "$bin")"
@@ -17,12 +21,8 @@ else
         break
       fi
     done
-    if [[ -z "${PUPPETEER_EXECUTABLE_PATH:-}" ]]; then
-      echo "No system Chrome/Chromium found. Without nix develop this fallback requires network to download a headless browser via npx. If that's not possible here, either install Chrome and re-run, or enter 'nix develop'." >&2
-      exit 127
-    fi
   else
-    echo "mmdc (mermaid-cli) not found and no npx fallback. Install via Nix dev shell or Node." >&2
+    echo "mmdc (mermaid-cli) not found. Install mermaid-cli or run inside Nix dev shell." >&2
     exit 127
   fi
 fi