infra(dqn-v2): audit doc scaffolding + pre-commit enforcement

Plan 1 Task 1. Creates the five audit docs plus config/metric-bands.toml
that track Invariants 2, 7, 8 per the DQN v2 spec, and extends the
pre-commit hook with two checks:

  - component-adding commits must touch an audit doc (Invariant 7)
  - added code may not contain TODO/FIXME/XXX/HACK/TBD/unimplemented!/
    todo! markers (Invariant 9)

Tests: manually verified by staging a TODO-marked file; commit
rejected with the correct error message.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

scripts/pre-commit-hook.sh

@@ -69,6 +69,45 @@ if [ -x "$SCRIPT_DIR/gpu-hotpath-guard.sh" ]; then
     echo ""
 fi
 
+# DQN v2 Invariant 7 enforcement: component-adding commits must update audit docs.
+check_audit_doc_updates() {
+    local staged=$(git diff --cached --name-only)
+    # Detect "component-adding" commits: new .rs or .cu files, or modifications to
+    # files that define ISV slots (gpu_dqn_trainer.rs), kernels (cuda_pipeline/*.cu),
+    # or state layout (state_layout.cuh).
+    local component_changes=$(echo "$staged" | grep -E '(^crates/ml/src/(cuda_pipeline|trainers/dqn)/|^crates/ml/src/cuda_pipeline/state_layout\.cuh$)')
+    if [ -z "$component_changes" ]; then return 0; fi
+
+    local audit_docs_touched=$(echo "$staged" | grep -E '^docs/(dqn-wire-up-audit|isv-slots|dqn-gpu-hot-path-audit|dqn-named-dims|ml-supervised-to-dqn-concept-audit)\.md$')
+    if [ -z "$audit_docs_touched" ]; then
+        echo "❌ Invariant 7 violation: component changes without audit-doc update"
+        echo "   Changed components:"
+        echo "$component_changes" | sed 's/^/     /'
+        echo "   You must update one of:"
+        echo "     docs/dqn-wire-up-audit.md"
+        echo "     docs/isv-slots.md"
+        echo "     docs/dqn-gpu-hot-path-audit.md"
+        echo "     docs/dqn-named-dims.md"
+        echo "     docs/ml-supervised-to-dqn-concept-audit.md"
+        return 1
+    fi
+}
+
+# DQN v2 Invariant 9 enforcement: reject TODO/FIXME/XXX/HACK/TBD markers in added code.
+check_no_todo_fixme() {
+    local added_lines=$(git diff --cached --diff-filter=AM -U0 -- '*.rs' '*.cu' '*.cuh' \
+        | grep -E '^\+' | grep -vE '^\+\+\+')
+    local bad=$(echo "$added_lines" | grep -E '(TODO|FIXME|\bXXX\b|\bHACK\b|\bTBD\b|unimplemented!|todo!\()')
+    if [ -n "$bad" ]; then
+        echo "❌ Invariant 9 violation: deferred-work markers found in staged code"
+        echo "$bad" | sed 's/^/     /'
+        return 1
+    fi
+}
+
+check_audit_doc_updates || exit 1
+check_no_todo_fixme || exit 1
+
 echo "✅ All pre-commit checks passed!"
 echo ""
 echo "Summary:"