From 58294c7722d9ec6ab2efcb5e962ce916305a06bd Mon Sep 17 00:00:00 2001
From: Shay <assetoverflow@icloud.com>
Date: Thu, 28 May 2026 07:16:21 -0700
Subject: [PATCH] docs(claude-md): document .claude/ scan exclusion requirement
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds 'Architectural Scan Exclusions' section before the PR Checklist.

Agent worktrees under .claude/worktrees/ contain full source copies that
trip every structural invariant scan (vault writers, normalize_to_versor
callsites, recall sites). Without .claude/ in the exclusion set, smoke
failures look exactly like real architectural violations but point at
non-live files — silent killers that mask actual regressions.

Documents the two maintained exclusion sets in
test_architectural_invariants.py and requires new scans to add .claude
before the first commit. Never rely on worktree pruning.
---
 CLAUDE.md | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 83236374..6a2ad303 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -293,6 +293,35 @@ Current near-term sequence:
 Avoid broad docs-first churn, dashboard work, or large infrastructure unless it
 unlocks one of these steps.
 
+## Architectural Scan Exclusions
+
+The invariant tests in `tests/test_architectural_invariants.py` perform
+full source-tree walks to enforce structural claims (INV-02, INV-21,
+INV-24).  These scans **must** exclude `.claude/` from traversal.
+
+**Why this matters:** Agent operators (Claude Code, Codex, Gemini) create
+worktrees under `.claude/worktrees/`.  Those worktrees contain full copies
+of the source tree — including `vault/`, `chat/`, `generate/`, etc. — and
+will trip every structural invariant that scans for forbidden callsites.
+The failures are silent killers: the tests report real-looking violations
+against files that aren't in the live codebase, poisoning the smoke suite
+and masking actual regressions.
+
+**Maintained exclusion sets** (keep `.claude` in both):
+
+```python
+# INV-02  os.walk exclusion (test_normalize_not_called_outside_gate)
+{".git", ".venv", "__pycache__", ".pytest_cache", ".hypothesis", ".claude"}
+
+# INV-21 / INV-24  rglob exclusion (EXCLUDED_DIRS)
+{"tests", "evals", "benchmarks", "scripts", "docs",
+ "core-rs", ".venv", "__pycache__", ".claude"}
+```
+
+If you add a new source-tree scan to the invariant suite, add `.claude`
+to its exclusion set before the first commit.  Never rely on worktrees
+being pruned — they can persist across sessions and CI runs.
+
 ## PR Checklist
 
 Before opening or merging, answer: