Add auto-regen state.md pre-commit hook + idempotent generator write (SAN-821) (#89)

Mirror the sanna-ts state.md drift control into sanna-repo: a local
pre-commit hook regenerates docs/state.md and fails the commit if it was
stale - a local mirror of the CI "Validate state doc" --check gate. Make
the generator's write mode idempotent (skip when only the timestamp would
change, reusing _comparable) so the hook does not churn docs/state.md on
every commit.

Author: nicallen-exd

.pre-commit-config.yaml

@@ -4,3 +4,11 @@ repos:
     hooks:
       - id: detect-private-key
         name: Block PEM private keys
+  - repo: local
+    hooks:
+      - id: state-doc
+        name: Regenerate docs/state.md (fails if it was stale)
+        entry: python3 tools/generate_state_doc.py
+        language: system
+        pass_filenames: false
+        always_run: true

tools/generate_state_doc.py

@@ -224,11 +224,16 @@ def main() -> None:
         timestamp = datetime.datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
         content = generate_full(root, timestamp)
         (root / "docs").mkdir(exist_ok=True)
-        state_path.write_text(content)
-        print(
-            f"Generated docs/state.md "
-            f"(version={get_version(root)}, tests={count_test_files(root)})"
-        )
+        if state_path.exists() and _comparable(state_path.read_text()) == _comparable(content):
+            # Idempotent: only the volatile timestamp would change. Skip the write so
+            # the auto-regen pre-commit hook does not churn docs/state.md every commit.
+            print("docs/state.md is already up to date (timestamp-only change skipped).")
+        else:
+            state_path.write_text(content)
+            print(
+                f"Generated docs/state.md "
+                f"(version={get_version(root)}, tests={count_test_files(root)})"
+            )
 
 
 if __name__ == "__main__":