From 80e87cdc1f0efd31da9c85dca1b1efa9e01ff6c0 Mon Sep 17 00:00:00 2001
From: Michael Chus <mike@mchus.pro>
Date: Fri, 12 Jun 2026 09:44:40 +0300
Subject: [PATCH] Deduplicate README structure list and add consistency lint

README no longer mirrors the contract list; the bootstrap router is the
single source of truth. scripts/lint.sh checks router coverage, dead
bootstrap references, and machine-local absolute paths.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 README.md       | 26 ++++++++------------------
 scripts/lint.sh | 34 ++++++++++++++++++++++++++++++++++
 2 files changed, 42 insertions(+), 18 deletions(-)
 create mode 100755 scripts/lint.sh

diff --git a/README.md b/README.md
index c8802db..acfbc2f 100644
--- a/README.md
+++ b/README.md
@@ -33,26 +33,16 @@ git submodule update --remote bible
 ## Structure
 
 ```
-AGENT-BOOTSTRAP.md      — first file agents should read
-rules/patterns/          — shared engineering rule contracts
-  go-logging/            — slog, server-side only
-  go-database/           — cursor safety, soft delete, GORM, N+1
-  go-api/                — REST conventions, error format, status codes
-  go-background-tasks/   — Task Manager pattern, polling
-  go-code-style/         — layering, error wrapping, startup sequence
-  go-project-bible/      — how to write and maintain a project bible
-  bom-decomposition/     — one BOM row to many component/LOT mappings
-  import-export/         — CSV Excel-compatible format, streaming export
-  table-management/      — toolbar, filtering, pagination
-  modal-workflows/       — state machine, htmx pattern, confirmation
-  forms-validation/      — validation, multi-step flows
-  controls-selection/    — buttons, checkboxes, segmented filters
-rules/ai/claude/
-  CLAUDE.template.md     — base CLAUDE.md template for new projects
-rules/ai/codex/
-  AGENTS.template.md     — base AGENTS.md template for new projects
+AGENT-BOOTSTRAP.md         — first file agents should read; contains the full contract router
+rules/patterns/<topic>/    — one contract.md per topic (plus optional README.md with examples)
+rules/ai/claude/           — CLAUDE.template.md for new projects
+rules/ai/codex/            — AGENTS.template.md for new projects
+scripts/lint.sh            — consistency checks (router coverage, broken links)
 ```
 
+The list of contracts is not duplicated here. The single source of truth for what exists
+and when to read it is the router in `AGENT-BOOTSTRAP.md`.
+
 ## Project Setup
 
 Each project needs:
diff --git a/scripts/lint.sh b/scripts/lint.sh
new file mode 100755
index 0000000..c72e6f4
--- /dev/null
+++ b/scripts/lint.sh
@@ -0,0 +1,34 @@
+#!/bin/sh
+# Consistency checks for the rules library. Run from the repo root: sh scripts/lint.sh
+set -u
+
+fail=0
+
+# 1. Every pattern directory must be reachable from the bootstrap router.
+for dir in rules/patterns/*/; do
+    name=$(basename "$dir")
+    if ! grep -q "$name" AGENT-BOOTSTRAP.md; then
+        echo "FAIL: rules/patterns/$name is not mentioned in AGENT-BOOTSTRAP.md"
+        fail=1
+    fi
+done
+
+# 2. Every bible/... path mentioned in the bootstrap must exist in the repo.
+for ref in $(grep -o 'bible/rules/patterns/[a-z-]*/contract\.md' AGENT-BOOTSTRAP.md | sort -u); do
+    path=${ref#bible/}
+    if [ ! -f "$path" ]; then
+        echo "FAIL: AGENT-BOOTSTRAP.md references missing file $path"
+        fail=1
+    fi
+done
+
+# 3. No machine-local absolute paths in committed markdown.
+if grep -rn '/Users/' --include='*.md' . --exclude-dir=.git; then
+    echo "FAIL: machine-local absolute paths found (see above)"
+    fail=1
+fi
+
+if [ "$fail" -eq 0 ]; then
+    echo "OK: all checks passed"
+fi
+exit "$fail"