feat(specs): add lint-specs command, minimal Vale config, pre-commit via git-hooks.nix; add specs/AGENTS.md

- Add `lint-specs` Just task to run markdownlint, link check, spell check, Vale, and Mermaid validation in one shot.
- Add minimal `.vale.ini` using built-in `Vale` style (no network).
- Integrate `cachix/git-hooks.nix` to run a `pre-commit` hook that executes `just lint-specs`.
- Inject the hook via flake devShell shellHook for auto-install during `nix develop`.
- Add `specs/AGENTS.md` instructing contributors to run `just lint-specs` before committing.
- Ignore generated `.pre-commit-config.yaml`.

Author: zah

.gitignore

@@ -8,3 +8,4 @@ test/logs/
 
 # linter cache
 .rubocop-cache/
+.pre-commit-config.yaml

.obsidian/workspace.json

@@ -194,6 +194,7 @@
   },
   "active": "01bf72509d2b5652",
   "lastOpenFiles": [
+    "specs/AGENTS.md",
     "scripts/md-mermaid-validate.sh",
     "specs/Public/Configuration.md",
     "specs/Public/CLI.md",

.vale.ini

@@ -0,0 +1,5 @@
+# Minimal Vale configuration for repository Markdown
+MinAlertLevel = warning
+
+[*.md]
+BasedOnStyles = Vale

Justfile

@@ -76,3 +76,26 @@ md-links:
 # Spell-check Markdown with cspell (uses default dictionaries unless configured)
 md-spell:
     cspell "specs/**/*.md"
+
+# Run all spec linting/validation in one go
+lint-specs:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    if [ -n "${IN_NIX_SHELL:-}" ]; then
+        echo "Running lint-specs inside Nix dev shell (no fallbacks)." >&2
+    fi
+    just md-lint
+    just md-links
+    just md-spell
+    # Prose/style linting via Vale (requires .vale.ini in repo)
+    if command -v vale >/dev/null 2>&1; then
+        vale specs || exit 1
+    else
+        if [ -n "${IN_NIX_SHELL:-}" ]; then
+            echo "vale is missing inside Nix dev shell; add pkgs.vale to flake.nix." >&2
+            exit 127
+        fi
+        echo "vale not found; skipping outside Nix shell." >&2
+    fi
+    # Mermaid syntax validation
+    just md-mermaid-check

flake.nix

@@ -3,15 +3,34 @@
 
   inputs = {
     nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
+    git-hooks.url = "github:cachix/git-hooks.nix";
   };
 
   outputs = {
     self,
     nixpkgs,
+    git-hooks,
   }: let
     systems = ["x86_64-linux" "aarch64-linux" "x86_64-darwin" "aarch64-darwin"];
     forAllSystems = nixpkgs.lib.genAttrs systems;
   in {
+    checks = forAllSystems (system: let
+      pkgs = import nixpkgs { inherit system; };
+      preCommit = git-hooks.lib.${system}.run {
+        src = ./.;
+        hooks = {
+          lint-specs = {
+            enable = true;
+            name = "Lint Markdown specs";
+            entry = "just lint-specs";
+            language = "system";
+            pass_filenames = false;
+          };
+        };
+      };
+    in {
+      pre-commit-check = preCommit;
+    });
     packages = forAllSystems (
       system: let
         pkgs = import nixpkgs {
@@ -106,6 +125,8 @@
         ];
 
         shellHook = ''
+          # Install git pre-commit hook invoking our Nix-defined hooks
+          ${self.checks.${system}.pre-commit-check.shellHook}
           echo "Agent workflow development environment loaded"
           # Provide a convenience function for Docson; no fallbacks in Nix shell
           docson () {

specs/AGENTS.md

@@ -0,0 +1,6 @@
+# Specs Maintenance
+
+- Before committing any change to the `specs/` folder, run `just lint-specs` from the project root. This performs Markdown linting, link checking, spell checking, prose/style linting, and Mermaid diagram validation.
+- The Nix dev shell is fully reproducible; if a required tool is missing inside the shell, fix `flake.nix` rather than using ad‑hoc fallbacks.
+
+If the pre-commit hook blocks your commit, run `just lint-specs`, address the reported issues, and commit again.