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_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())