From d30263bcf1169bfb2dacb059072648324ef08d25 Mon Sep 17 00:00:00 2001
From: ai-ag2026 <261867348+ai-ag2026@users.noreply.github.com>
Date: Mon, 11 May 2026 12:36:35 +0200
Subject: [PATCH 1/2] test: allow top-level markdown docs

---
 .gitignore                          |  7 +++----
 tests/test_docs_gitignore_policy.py | 25 +++++++++++++++++++++++++
 2 files changed, 28 insertions(+), 4 deletions(-)
 create mode 100644 tests/test_docs_gitignore_policy.py

diff --git a/.gitignore b/.gitignore
index 529563ba..501be1e7 100644
--- a/.gitignore
+++ b/.gitignore
@@ -36,15 +36,14 @@ api/_version.py
 .DS_Store
 Thumbs.db
 
-# Local reference clones — never committed (except tracked design/UI-UX reference pages)
+# Local reference clones/artifacts — never committed by default.
+# Markdown docs at docs/*.md are intentionally trackable for contributor docs.
 docs/*
+!docs/*.md
 !docs/ui-ux/
 !docs/ui-ux/**
 !docs/rfcs/
 !docs/rfcs/**
-!docs/docker.md
-!docs/supervisor.md
-!docs/troubleshooting.md
 
 # Local-only PR review harness: rendering drivers, sample bank, fixtures.
 # Used by Claude during deep reviews; never shared in the repo.
diff --git a/tests/test_docs_gitignore_policy.py b/tests/test_docs_gitignore_policy.py
new file mode 100644
index 00000000..b040aac5
--- /dev/null
+++ b/tests/test_docs_gitignore_policy.py
@@ -0,0 +1,25 @@
+"""Regression tests for docs/ ignore policy."""
+
+import subprocess
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def _git_check_ignore(path: str) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        ["git", "check-ignore", "-q", path],
+        cwd=ROOT,
+        capture_output=True,
+        text=True,
+    )
+
+
+def test_new_top_level_markdown_docs_are_trackable():
+    """New docs/*.md files should be visible to Git, not silently ignored."""
+    assert _git_check_ignore("docs/example-new-guide.md").returncode == 1
+
+
+def test_docs_scratch_files_remain_ignored():
+    """The broad docs/* ignore rule should still keep arbitrary scratch files out."""
+    assert _git_check_ignore("docs/local-scratch.tmp").returncode == 0

From c4b7a65356c6c5b4cca72d01f4fa2f49cbbb0051 Mon Sep 17 00:00:00 2001
From: ai-ag2026 <nezu@posteo.de>
Date: Mon, 11 May 2026 17:09:19 +0200
Subject: [PATCH 2/2] test: keep local context docs ignored

---
 .gitignore                          | 6 ++++++
 tests/test_docs_gitignore_policy.py | 8 ++++++++
 2 files changed, 14 insertions(+)

diff --git a/.gitignore b/.gitignore
index 501be1e7..28316280 100644
--- a/.gitignore
+++ b/.gitignore
@@ -45,6 +45,12 @@ docs/*
 !docs/rfcs/
 !docs/rfcs/**
 
+# Local-only AI assistant context — never committed even under docs/.
+docs/AGENTS.md
+docs/CLAUDE.md
+docs/.cursorrules
+docs/.windsurfrules
+
 # Local-only PR review harness: rendering drivers, sample bank, fixtures.
 # Used by Claude during deep reviews; never shared in the repo.
 .local-review/
diff --git a/tests/test_docs_gitignore_policy.py b/tests/test_docs_gitignore_policy.py
index b040aac5..a2729fae 100644
--- a/tests/test_docs_gitignore_policy.py
+++ b/tests/test_docs_gitignore_policy.py
@@ -23,3 +23,11 @@ def test_new_top_level_markdown_docs_are_trackable():
 def test_docs_scratch_files_remain_ignored():
     """The broad docs/* ignore rule should still keep arbitrary scratch files out."""
     assert _git_check_ignore("docs/local-scratch.tmp").returncode == 0
+
+
+def test_local_only_ai_context_files_remain_ignored_under_docs():
+    """Local AI assistant context files must stay out of commits under docs/."""
+    assert _git_check_ignore("docs/AGENTS.md").returncode == 0
+    assert _git_check_ignore("docs/CLAUDE.md").returncode == 0
+    assert _git_check_ignore("docs/.cursorrules").returncode == 0
+    assert _git_check_ignore("docs/.windsurfrules").returncode == 0