From efa43aca5554ed00bd1784ea0e9bcb12f48e0e86 Mon Sep 17 00:00:00 2001
From: Joe Amditis <amditisj@mail.montclair.edu>
Date: Sat, 2 May 2026 20:52:02 -0400
Subject: [PATCH] Add copilot-globals sync mechanism (closes #59)

Hoists Joe's user-level review rules out of every project's
.github/copilot-instructions.md (which were pushing 3 repos past the
4k Copilot-read cap) into a path-scoped .github/instructions/globals.instructions.md
file synced from a single source.

- scripts/sync-copilot-globals.py reads ~/.claude/copilot-globals.md
  (hand-curated source) and writes .github/instructions/globals.instructions.md
  into each repo listed in scripts/sync-targets.txt. Supports --dry-run,
  --only NAME filter, and --source / --targets overrides for testing.
  Idempotent (re-runs report 'unchanged').
- scripts/sync-targets.txt: subscribed repos, one absolute path per line,
  '#' for comments, '~' expansion. Initially just tools/.
- .github/instructions/globals.instructions.md: generated output. Has
  applyTo: "**" frontmatter so Copilot's PR reviewer reads it on every
  PR. Contains writing style, banned words, AI-attribution rule, and
  code-quality basics.
- .github/copilot-instructions.md: removed the now-redundant 'Global
  rules to flag' section (down from 2886 to 2845 chars; ~1700 chars
  freed for project-specific bug classes). Tightened the favicon/OG
  rule to scope to resource-kit/docs/**/*.html (the actual deployed
  surface), exempting _archive/**.
- CLAUDE.md: documents the sync workflow, where the source lives,
  and the explicit rule that no project's CLAUDE.md is sliced for the
  Copilot cap. CLAUDE.md remains single source of truth for primary
  coding assistants.

The next 3 PRs (rosen-frontend, class, houseofjawn-bot) add those
repos to sync-targets.txt and slim their copilot-instructions.md
files the same way.
---
 .github/copilot-instructions.md              |  12 +-
 .github/instructions/globals.instructions.md |  29 +++++
 CLAUDE.md                                    |  24 ++++
 scripts/sync-copilot-globals.py              | 128 +++++++++++++++++++
 scripts/sync-targets.txt                     |  16 +++
 5 files changed, 200 insertions(+), 9 deletions(-)
 create mode 100644 .github/instructions/globals.instructions.md
 create mode 100755 scripts/sync-copilot-globals.py
 create mode 100644 scripts/sync-targets.txt

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 913ef2a..a0af98f 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -2,18 +2,12 @@
 
 Project context, architecture, and conventions live in [CLAUDE.md](../CLAUDE.md). Both this file and CLAUDE.md are read by Copilot code review (cap ~4,000 chars each). This file lists the rules worth named attention on every PR.
 
-## Global rules to flag
-
-These are Joe's user-level conventions from `~/.claude/CLAUDE.md`, restated here because Copilot's PR review bot does not read user-level files.
-
-- **Sentence case** in UI text, headings, comments, prose, and commit messages. Code identifiers follow language conventions: camelCase (JS), kebab-case (CSS class names), snake_case (Python). The rule is about not writing English prose in Title Case, not about overriding language naming conventions.
-- **No emojis** in source code, log messages, comments, commits, PR bodies, or any output. Plain text only.
-- **No AI-authorship attribution.** Never include "Generated with Claude Code", `Co-Authored-By: Claude` trailers, or any "AI-assisted"/"Generated by"-style notes in PR bodies, commit trailers, code comments, or committed docs. Mentioning model/company names in technical documentation (including this file's anti-slop guidance) is fine — the ban is on AI authorship credits.
-- **Banned words / anti-slop.** Replace or delete (this list is a review reference and is exempt from its own rule): *comprehensive, sophisticated, robust, transformative, leveraging, seamlessly, innovative, cutting-edge, state-of-the-art, holistic, synergy, ecosystem, paradigm, empower*.
-- **Every public-facing HTML page must include the favicon link tag** `<link rel="icon" type="image/svg+xml" href="...">` (use a relative path from each subdirectory) and full OG/Twitter meta tags: `og:title`, `og:description`, `og:type`, `og:url`, `og:image` (1200x630), `og:image:width=1200`, `og:image:height=630`, `twitter:card=summary_large_image`, `twitter:title`, `twitter:description`, `twitter:image`. Missing favicons are a security signal — automated scanners flag pages without them.
+User-level globals (sentence case, no emojis, banned words, no AI-authorship attribution, code-quality basics) live in [`.github/instructions/globals.instructions.md`](instructions/globals.instructions.md), generated from `~/.claude/copilot-globals.md` by `scripts/sync-copilot-globals.py`. Don't restate them here.
 
 ## Project-specific bug classes to flag
 
+- **Every deployed HTML page** under `resource-kit/docs/**/*.html` (the GitHub Pages source) must include the favicon link tag `<link rel="icon" type="image/svg+xml" href="...">` (relative path from each subdirectory) and full OG/Twitter meta tags: `og:title`, `og:description`, `og:type`, `og:url`, `og:image` (1200x630), `og:image:width=1200`, `og:image:height=630`, `twitter:card=summary_large_image`, `twitter:title`, `twitter:description`, `twitter:image`. Files outside `resource-kit/docs/` (including `_archive/**`) are not deployed and exempt.
+
 - **No hardcoded API keys or secrets.** Static-site repo, no server. Any inline key in HTML/JS is a leak.
 - **Event listeners attached to the wrong scope.** The sidebar and modal in the LLM Advisor live OUTSIDE `#llm-tool-advisor-container`. Listeners attached only to the main container miss those elements.
 - **Generic class names inside SVG `<style>` tags.** SVG styles are not scoped and leak into the whole document. A `.block` rule inside an inline SVG applies to every Tailwind `block` element on the page. Require prefixed names (`svg-block`, `svg-shift`).
diff --git a/.github/instructions/globals.instructions.md b/.github/instructions/globals.instructions.md
new file mode 100644
index 0000000..0b201c8
--- /dev/null
+++ b/.github/instructions/globals.instructions.md
@@ -0,0 +1,29 @@
+---
+applyTo: "**"
+---
+
+<!-- Generated by tools/scripts/sync-copilot-globals.py from ~/.claude/copilot-globals.md. Edit the source, then re-run the script. -->
+
+# Global review rules for Joe's repos
+
+These rules apply to ALL pull requests across Joe's repositories. They live here once and are synced into each subscribed repo's `.github/instructions/globals.instructions.md` by `tools/scripts/sync-copilot-globals.py`. Each project's `.github/copilot-instructions.md` then carries only project-specific bug classes, leaving room under the ~4k-char Copilot read cap for that project's real architecture rules.
+
+The Copilot PR review bot reads this file in addition to `.github/copilot-instructions.md` and the project's `CLAUDE.md` / `AGENTS.md` / `GEMINI.md`. None of those need to restate the rules below.
+
+## Writing style
+
+- **Sentence case** in UI text, headings, comments, prose, and commit messages. Code identifiers follow language conventions: camelCase (JS), kebab-case (CSS class names), snake_case (Python), UPPER_SNAKE_CASE (constants), PascalCase (classes). The rule is about not writing English prose in Title Case, not about overriding language naming conventions.
+- **No emojis** in source code, log messages, comments, commits, PR bodies, or any committed output. Plain text only.
+- **Banned words / anti-slop.** Replace or delete (this list is itself a review reference and is exempt from its own rule): *comprehensive, sophisticated, robust, transformative, leveraging, seamlessly, innovative, cutting-edge, state-of-the-art, holistic, synergy, ecosystem, paradigm, empower*. Substitutes: "full" / "complete" for comprehensive, "using" for leveraging, "stable" / "reliable" for robust, "advanced" or describe specifics for sophisticated.
+- **AP style** for prose: "more than" for quantities (never "over"), Oxford comma, sentence-case headings.
+
+## AI authorship
+
+- **No AI-authorship attribution.** Never include "Generated with Claude Code", `Co-Authored-By: Claude` trailers, "AI-assisted" notes, or any "Generated by [model]"-style credit in PR bodies, commit trailers, code comments, or committed docs. Mentioning model or company names in technical documentation (e.g., "uses Claude Sonnet 4.6 for fast chat") is fine — the ban is specifically on AI authorship credit lines.
+
+## Code quality
+
+- **Test suite first.** Tests must accompany feature code and bug fixes. Lint + tests must pass before requesting review.
+- **No backwards-compatibility shims for unused code.** Don't keep dead `_var` renames, `// removed` comment markers, or feature flags for code being deleted.
+- **No defensive code for impossible states.** Don't add error handling, fallbacks, or validation for scenarios the type system or framework already guarantees. Validate at system boundaries (user input, external APIs) only.
+- **Comments only when WHY is non-obvious.** No multi-paragraph code comments. One short line maximum. Don't restate WHAT the code does — names should already do that. Don't reference current task / fix / callers — that belongs in the PR description.
diff --git a/CLAUDE.md b/CLAUDE.md
index ea734c3..c4db4e0 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -102,6 +102,30 @@ python -m http.server 8000
 **Deploy:** GitHub Actions (`static.yml`) uploads `resource-kit/docs/` as a Pages artifact on push to master
 **Fallback:** `bash deploy.sh` deploys to Cloudflare Pages (`tools-pages.pages.dev`) — only use if GitHub Pages is down
 
+## Copilot review globals (cross-repo sync)
+
+This repo hosts the script that distributes Joe's user-level review rules to every subscribed repo as a path-scoped Copilot instructions file.
+
+**Source of truth:** `~/.claude/copilot-globals.md` (writing style, banned words, no AI-attribution, code-quality basics). Hand-edit there when a rule changes.
+
+**Sync target:** each subscribed repo's `.github/instructions/globals.instructions.md`. Copilot's PR review bot reads these files in addition to `.github/copilot-instructions.md` (with `applyTo` glob and `excludeAgent` opt-out support, per the GitHub Copilot path-specific instructions docs).
+
+**Why:** Each Copilot-readable file has roughly a 4,000-char silent-truncation cap. Restating ~1,700 chars of globals in every project's `copilot-instructions.md` was pushing several past the cap (rosen-frontend, class, houseofjawn-bot at 3995 / 3993 / 3992 chars at the time of #59). Hoisting globals into a separate path-scoped file frees that space for project-specific bug classes.
+
+**Subscribed repos:** listed in `scripts/sync-targets.txt` (one absolute path per line, `#` for comments, `~` expansion supported).
+
+**After editing the source:**
+
+```bash
+~/projects/tools/scripts/sync-copilot-globals.py             # write to all subscribed repos
+~/projects/tools/scripts/sync-copilot-globals.py --dry-run   # preview without writing
+~/projects/tools/scripts/sync-copilot-globals.py --only tools  # filter to one repo by name
+```
+
+Each subscribed repo should commit its `.github/instructions/globals.instructions.md` (the file is generated but committed so Copilot can read it without runtime sync). When a repo first subscribes, also slim its `.github/copilot-instructions.md` by removing the now-redundant "Global rules to flag" section.
+
+This setup does **not** modify any project's `CLAUDE.md`. CLAUDE.md remains the single source of truth for primary coding assistants and is not bound by the 4k Copilot-read cap.
+
 ## LLM Advisor architecture
 
 The LLM Advisor (`resource-kit/docs/llm-advisor/`) uses:
diff --git a/scripts/sync-copilot-globals.py b/scripts/sync-copilot-globals.py
new file mode 100755
index 0000000..2914d90
--- /dev/null
+++ b/scripts/sync-copilot-globals.py
@@ -0,0 +1,128 @@
+#!/usr/bin/env python3
+"""Sync ~/.claude/copilot-globals.md into each subscribed repo's
+.github/instructions/globals.instructions.md.
+
+Background: GitHub Copilot's PR review bot reads `.github/copilot-instructions.md`
+plus any `.github/instructions/*.instructions.md` files (with applyTo glob support
+and excludeAgent opt-out). Each file has roughly a 4,000-char silent-truncation
+cap. Joe's user-level globals previously had to be restated in every project's
+copilot-instructions.md, pushing several past the cap. This script hoists the
+globals into a path-scoped instructions file maintained in one place.
+
+Usage:
+    sync-copilot-globals.py [--source PATH] [--targets PATH] [--dry-run]
+                            [--only NAME[,NAME...]] [REPO ...]
+
+If REPO arguments are given, they override the targets file.
+Default source: ~/.claude/copilot-globals.md
+Default targets file: tools/scripts/sync-targets.txt (sibling to this script).
+
+Exit codes:
+    0  all targets updated (or unchanged)
+    1  one or more targets failed
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+DEFAULT_SOURCE = Path.home() / ".claude" / "copilot-globals.md"
+DEFAULT_TARGETS_FILE = Path(__file__).resolve().parent / "sync-targets.txt"
+GENERATED_HEADER = (
+    "<!-- Generated by tools/scripts/sync-copilot-globals.py "
+    "from ~/.claude/copilot-globals.md. Edit the source, then re-run the script. -->"
+)
+
+
+def load_targets(targets_file: Path) -> list[Path]:
+    if not targets_file.exists():
+        return []
+    out = []
+    for raw in targets_file.read_text().splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        out.append(Path(line).expanduser())
+    return out
+
+
+def render_output(source_text: str) -> str:
+    """Insert the generated-header marker after the YAML frontmatter."""
+    if source_text.startswith("---\n"):
+        end = source_text.find("\n---\n", 4)
+        if end != -1:
+            frontmatter = source_text[: end + 5]
+            body = source_text[end + 5 :].lstrip("\n")
+            return f"{frontmatter}\n{GENERATED_HEADER}\n\n{body}"
+    return f"{GENERATED_HEADER}\n\n{source_text}"
+
+
+def sync_to(repo: Path, content: str, dry_run: bool) -> str:
+    target = repo / ".github" / "instructions" / "globals.instructions.md"
+    existing = target.read_text() if target.exists() else None
+    if existing == content:
+        return f"unchanged: {target}"
+    verb_prefix = "would " if dry_run else ""
+    verb = "create" if existing is None else "update"
+    if dry_run:
+        return f"{verb_prefix}{verb}: {target}"
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(content)
+    return f"{verb}d: {target}"
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--source", type=Path, default=DEFAULT_SOURCE,
+                        help=f"Source file (default: {DEFAULT_SOURCE})")
+    parser.add_argument("--targets", type=Path, default=DEFAULT_TARGETS_FILE,
+                        help=f"Targets list file (default: {DEFAULT_TARGETS_FILE})")
+    parser.add_argument("--dry-run", action="store_true",
+                        help="Print what would change without writing")
+    parser.add_argument("--only", default="",
+                        help="Comma-separated repo names to filter the targets list")
+    parser.add_argument("repos", nargs="*", type=Path,
+                        help="Repo paths (overrides the targets file)")
+    args = parser.parse_args()
+
+    if not args.source.exists():
+        print(f"error: source not found: {args.source}", file=sys.stderr)
+        return 1
+
+    content = render_output(args.source.read_text())
+
+    repos = args.repos or load_targets(args.targets)
+    if not repos:
+        print(
+            f"error: no target repos given and {args.targets} is empty or missing",
+            file=sys.stderr,
+        )
+        return 1
+
+    if args.only:
+        only = {n.strip() for n in args.only.split(",") if n.strip()}
+        repos = [r for r in repos if r.name in only]
+        if not repos:
+            print(f"error: --only {args.only} matched no targets", file=sys.stderr)
+            return 1
+
+    failed = 0
+    for repo in repos:
+        if not (repo / ".git").is_dir():
+            print(f"skip: not a git repo: {repo}", file=sys.stderr)
+            failed += 1
+            continue
+        try:
+            print(sync_to(repo, content, dry_run=args.dry_run))
+        except OSError as exc:
+            print(f"error: {repo}: {exc}", file=sys.stderr)
+            failed += 1
+
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/scripts/sync-targets.txt b/scripts/sync-targets.txt
new file mode 100644
index 0000000..509e6eb
--- /dev/null
+++ b/scripts/sync-targets.txt
@@ -0,0 +1,16 @@
+# Repos subscribed to ~/.claude/copilot-globals.md.
+# One absolute path per line. Lines starting with # are ignored.
+# Tilde expansion is supported.
+#
+# To subscribe a new repo:
+#   1. Add its path here
+#   2. Run scripts/sync-copilot-globals.py
+#   3. In that repo, slim .github/copilot-instructions.md by removing the
+#      "Global rules to flag" section (now lives in
+#      .github/instructions/globals.instructions.md)
+#   4. Open a PR with both files in the same commit
+#
+# After ~/.claude/copilot-globals.md changes, run from anywhere:
+#   ~/projects/tools/scripts/sync-copilot-globals.py
+
+~/projects/tools