From 34ab5246f19b774cd8355e7d3451e76e2ec475b2 Mon Sep 17 00:00:00 2001
From: Rafael Richards <rmrich5@gmail.com>
Date: Sun, 10 May 2026 20:29:36 -0400
Subject: [PATCH] chore: docs/ prose-only gate (Makefile target + CI step)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds make check-docs-prose as a cross-repo guardrail: docs/ holds only
human-readable prose (.md, .markdown, images, .gitkeep). Non-prose
artifacts — generated data, JSON/TSV output, copy-paste examples,
scaffolding templates — belong under dist/, examples/, templates/, or
a top-level domain-specific directory.

Wires into CI alongside the existing manifest drift gate. Engine-free,
fast, find-based. Currently green (docs/ is already prose-only after
PR #9 moved vista-lint-presets to examples/) — this is preventive, not
corrective.
---
 .github/workflows/ci.yml |  7 +++++++
 Makefile                 | 20 +++++++++++++++++++-
 2 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 6c7ec19..56e8108 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -56,3 +56,10 @@ jobs:
         # Makefile directly — its targets call `.venv/bin/m`, which
         # `uv sync --frozen` populated above.
         run: make check-manifest
+
+      - name: docs/ prose-only gate
+        # Cross-repo guardrail: docs/ holds only human-readable prose.
+        # Non-prose artifacts (data, examples, scaffolding templates)
+        # belong under dist/, examples/, templates/, or a top-level
+        # domain dir. Engine-free find-based check.
+        run: make check-docs-prose
diff --git a/Makefile b/Makefile
index 0d5b92b..46298f5 100644
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,4 @@
-.PHONY: install test test-lf watch lint format mypy cov check lint-modern lint-modern-baseline lint-modern-setup push pull hooks seed unseed test-vista engine-up engine-down engine-status manifest check-manifest
+.PHONY: install test test-lf watch lint format mypy cov check lint-modern lint-modern-baseline lint-modern-setup push pull hooks seed unseed test-vista engine-up engine-down engine-status manifest check-manifest check-docs-prose
 
 PYTHON := .venv/bin/python
 PYTEST := .venv/bin/pytest
@@ -160,3 +160,21 @@ unseed:
 test-vista: seed
 	@$(PYTEST) -m vista || (rc=$$?; $(MAKE) unseed; exit $$rc)
 	@$(MAKE) unseed
+
+# Guardrail: docs/ holds only human-readable prose. Non-prose artifacts
+# (generated data, JSON/TSV output, copy-paste examples, scaffolding
+# templates) belong under dist/, examples/, templates/, or a top-level
+# domain-specific directory — not docs/.
+check-docs-prose:
+	@if [ ! -d docs ]; then echo "check-docs-prose: no docs/ directory ✓"; exit 0; fi; \
+	violations=$$(find docs -type f \
+	    ! -name '*.md' ! -name '*.markdown' \
+	    ! -name '*.png' ! -name '*.jpg' ! -name '*.jpeg' \
+	    ! -name '*.gif' ! -name '*.svg' ! -name '*.webp' \
+	    ! -name '.gitkeep'); \
+	if [ -n "$$violations" ]; then \
+	  echo "ERROR: non-prose files under docs/ — move to dist/, examples/, templates/, or a top-level domain dir:" >&2; \
+	  echo "$$violations" >&2; \
+	  exit 1; \
+	fi; \
+	echo "check-docs-prose: docs/ is prose-only ✓"