From cbdb8d5491a74bbeafd73430d952443f66961115 Mon Sep 17 00:00:00 2001
From: Rafael Richards <rmrich5@gmail.com>
Date: Sun, 10 May 2026 20:27:12 -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 engine-free drift gates
(manifest-check / skill-check / doctest-check). Engine-free, fast,
find-based. Currently green (m-stdlib's docs/ is already prose-only —
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 ae5f3cb..d7c28e0 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -108,6 +108,13 @@ jobs:
           export PATH="/tmp/venv/bin:$PATH"
           make doctest-check
 
+      - name: docs/ prose-only gate
+        # Cross-repo guardrail: docs/ holds only human-readable prose.
+        # Non-prose artifacts (generated data, JSON/TSV output, examples,
+        # scaffolding templates) belong elsewhere (dist/, examples/,
+        # templates/, top-level domain dirs). Engine-free find-based check.
+        run: make check-docs-prose
+
       # The historical `make setup-ydb` step was removed: the Track A3
       # Makefile refactor (commit 6ff7c6d) dropped that target along
       # with the vista-meta seeding model. The new flow runs `m test`
diff --git a/Makefile b/Makefile
index fce47b8..2520c46 100644
--- a/Makefile
+++ b/Makefile
@@ -20,7 +20,7 @@ M ?= m
 # Override if you cloned it elsewhere.
 M_TEST_ENGINE ?= $(HOME)/projects/m-test-engine
 
-.PHONY: all fmt fmt-check lint test safe-test coverage check ci clean print-env seed unseed manifest manifest-check check-manifest frontmatter skill skill-check skill-install doctest doctest-check doctest-run engine-up engine-down engine-status
+.PHONY: all fmt fmt-check lint test safe-test coverage check ci clean print-env seed unseed manifest manifest-check check-manifest frontmatter skill skill-check skill-install doctest doctest-check doctest-run engine-up engine-down engine-status check-docs-prose
 
 # vista-meta connection contract — silently included if present.
 # Preserves the maintainer's existing workflow but no longer hard-errors
@@ -213,3 +213,21 @@ doctest-run:
 
 clean:
 	rm -rf coverage.lcov test-results.tap coverage.json
+
+# 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 ✓"