Merge PR #2073 into stage-338

test: allow top-level markdown docs
by @ai-ag2026

.gitignore

@@ -36,15 +36,20 @@ 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 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.

tests/test_docs_gitignore_policy.py

@@ -0,0 +1,33 @@
+"""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
+
+
+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