Establish a safe foundation before implementing the geology RAG system

The project begins with architecture, data governance, reproducible evaluation, deployment boundaries, and secret-handling contracts so later code has measurable acceptance criteria.

Constraint: Real provider credentials, workspace identities, and restricted geological data must never enter Git

Rejected: Add placeholder runnable services in the design commit | would imply unverified implementation readiness

Confidence: high

Scope-risk: narrow

Reversibility: clean

Directive: Run make verify before every commit and update ADRs when architecture boundaries change

Tested: Secret scan, Markdown links, YAML parse, shell syntax, and staged diff validation

Not-tested: Application runtime is intentionally deferred to the implementation stage

scripts/check-secrets.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+mode="${1:---staged}"
+secret_pattern='(sk-(ws[-_]?)?[A-Za-z0-9_-]{24,}|llm-[a-z0-9]{12,}|AKIA[0-9A-Z]{16}|-----BEGIN ([A-Z0-9 ]+ )?PRIVATE KEY-----)'
+found=0
+
+check_file() {
+  local file="$1"
+  if [[ -f "$file" ]] && grep -I -q -E "$secret_pattern" "$file"; then
+    printf 'Potential secret detected in: %s\n' "$file" >&2
+    found=1
+  fi
+}
+
+case "$mode" in
+  --staged)
+    while IFS= read -r -d '' file; do
+      check_file "$file"
+    done < <(git diff --cached --name-only --diff-filter=ACMR -z)
+    ;;
+  --all)
+    while IFS= read -r -d '' file; do
+      check_file "$file"
+    done < <(git ls-files --cached --others --exclude-standard -z)
+    ;;
+  *)
+    printf 'Usage: %s [--staged|--all]\n' "$0" >&2
+    exit 2
+    ;;
+esac
+
+if [[ "$found" -ne 0 ]]; then
+  printf 'Commit blocked. Rotate any exposed credential before continuing.\n' >&2
+  exit 1
+fi
+
+printf 'Secret scan passed.\n'

scripts/check_markdown_links.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+
+LINK_PATTERN = re.compile(r"\[[^\]]*\]\(([^)]+)\)")
+IGNORED_PREFIXES = ("http://", "https://", "mailto:", "#")
+
+
+def markdown_files() -> list[Path]:
+    return [Path("README.md"), *sorted(Path("docs").rglob("*.md"))]
+
+
+def main() -> int:
+    missing: list[tuple[Path, str]] = []
+    for document in markdown_files():
+        for target in LINK_PATTERN.findall(document.read_text(encoding="utf-8")):
+            if target.startswith(IGNORED_PREFIXES):
+                continue
+            path_part = target.split("#", 1)[0]
+            if not (document.parent / path_part).exists():
+                missing.append((document, target))
+
+    if missing:
+        for document, target in missing:
+            print(f"Broken relative link: {document}: {target}", file=sys.stderr)
+        return 1
+
+    print("Markdown relative links passed.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())