Skip to content

Snoozer10/synthesize-skills / .agents/skills/gemini-context-engineer

gemini-context-engineer

Unverified

Use when creating, updating, auditing, or federating GEMINI.md workspace context files, detecting architectural reality drift between code and architecture docs, compiling token-bounded task slices, or verifying workstream proof commands

scripts/validate_gemini_md.py

View on GitHub
import argparse
import json
import re
import shutil
import sys
from datetime import datetime
from pathlib import Path

# Add script directory to sys.path
sys.path.insert(0, str(Path(__file__).parent.resolve()))
from __version__ import __version__

if sys.platform == "win32":
    sys.stdout.reconfigure(encoding="utf-8")
    sys.stderr.reconfigure(encoding="utf-8")

BANNER_BLOCK_RE = re.compile(
    r"<!-- AGENT-SYNC: GEMINI\.md:start -->.*?<!-- AGENT-SYNC: GEMINI\.md:end -->\r?\n*",
    re.DOTALL
)
LEGACY_SHIM_RE = re.compile(
    r"<!-- AGENT-SYNC: GEMINI\.md -->\s*(?:# Synced Context[^\n]*)?\s*(?:This repository uses \[GEMINI\.md\]\(\./GEMINI\.md\)[^\n]*)?\r?\n*",
    re.DOTALL
)
FRONTMATTER_RE = re.compile(
    r"^---\r?\n.*?\r?\n---\r?\n*",
    re.DOTALL
)
MAGIC_TOKEN = "<!-- AGENT-SYNC: GEMINI.md -->"


def get_federation_banner(target_filename: str) -> str:
    return (
        "<!-- AGENT-SYNC: GEMINI.md:start -->\n"
        "<!-- AGENT-SYNC: GEMINI.md -->\n"
        "> [!IMPORTANT]\n"
        "> **AUTHORITATIVE CONTEXT DIRECTIVE**:\n"
        f"> Read [GEMINI.md](./GEMINI.md) now and use it as the current project guidance where it differs from {target_filename}.\n"
        "> `GEMINI.md` is the canonical Single Source of Truth (SSOT) for this repository's architecture, engineering constraints, workflows, and standards.\n"
        "> All rules, commands, and workstream states defined in `GEMINI.md` supersede any conflicting instructions below.\n"
        "<!-- AGENT-SYNC: GEMINI.md:end -->"
    )


def classify_federation_file(fpath: Path) -> tuple[str, str]:
    if not fpath.exists() and not fpath.is_symlink():
        return ("missing", "")
    if fpath.is_symlink():
        return ("symlink", "")
    try:
        content = fpath.read_text(encoding="utf-8")
    except Exception:
        return ("divergent", "")

    has_banner = bool(BANNER_BLOCK_RE.search(content))
    has_magic = MAGIC_TOKEN in content

    if not has_banner and not has_magic:
        return ("divergent", content)

    stripped = BANNER_BLOCK_RE.sub("", content)
    stripped = LEGACY_SHIM_RE.sub("", stripped)
    stripped_text = stripped.strip()

    if not stripped_text or stripped_text.startswith("# Synced Context"):
        return ("pointer_shim", content)
    else:
        return ("federated_hybrid", content)


def inject_or_update_federation(fpath: Path, target_filename: str = None) -> str:
    if target_filename is None:
        target_filename = fpath.name
    status, content = classify_federation_file(fpath)
    if status == "symlink":
        return "symlink"

    banner = get_federation_banner(target_filename)

    if status == "missing" or not content.strip():
        fpath.parent.mkdir(parents=True, exist_ok=True)
        pointer_content = (
            f"{banner}\n\n"
            f"# Synced Context: {target_filename}\n"
            "This repository uses [GEMINI.md](./GEMINI.md) as the authoritative context file. "
            "Please refer to GEMINI.md for all project instructions, architecture, and constraints.\n"
        )
        fpath.write_text(pointer_content, encoding="utf-8")
        return "pointer_shim"

    if BANNER_BLOCK_RE.search(content):
        m = BANNER_BLOCK_RE.search(content)
        prefix = content[:m.start()]
        suffix = content[m.end():].lstrip("\r\n")
        if suffix:
            new_content = f"{prefix}{banner}\n\n{suffix}"
        else:
            new_content = f"{prefix}{banner}\n"
        if new_content != content:
            fpath.write_text(new_content, encoding="utf-8")
        stripped = BANNER_BLOCK_RE.sub("", new_content)
        stripped = LEGACY_SHIM_RE.sub("", stripped).strip()
        if not stripped or stripped.startswith("# Synced Context"):
            return "pointer_shim"
        return "federated_hybrid"

    if MAGIC_TOKEN in content:
        fm = FRONTMATTER_RE.match(content)
        if fm:
            frontmatter_part = content[:fm.end()]
            body_part = content[fm.end():]
            body_no_legacy = LEGACY_SHIM_RE.sub("", body_part).lstrip("\r\n")
            if not body_no_legacy.strip() or body_no_legacy.strip().startswith("# Synced Context"):
                new_content = (
                    f"{frontmatter_part}{banner}\n\n"
                    f"# Synced Context: {target_filename}\n"
                    "This repository uses [GEMINI.md](./GEMINI.md) as the authoritative context file. "
                    "Please refer to GEMINI.md for all project instructions, architecture, and constraints.\n"
                )
                fpath.write_text(new_content, encoding="utf-8")
                return "pointer_shim"
            new_content = f"{frontmatter_part}{banner}\n\n{body_no_legacy}"
        else:
            body_no_legacy = LEGACY_SHIM_RE.sub("", content).lstrip("\r\n")
            if not body_no_legacy.strip() or body_no_legacy.strip().startswith("# Synced Context"):
                new_content = (
                    f"{banner}\n\n"
                    f"# Synced Context: {target_filename}\n"
                    "This repository uses [GEMINI.md](./GEMINI.md) as the authoritative context file. "
                    "Please refer to GEMINI.md for all project instructions, architecture, and constraints.\n"
                )
                fpath.write_text(new_content, encoding="utf-8")
                return "pointer_shim"
            new_content = f"{banner}\n\n{body_no_legacy}"
        fpath.write_text(new_content, encoding="utf-8")
        return "federated_hybrid"

    fm = FRONTMATTER_RE.match(content)
    if fm:
        frontmatter_part = content[:fm.end()]
        body_part = content[fm.end():].lstrip("\r\n")
        new_content = f"{frontmatter_part}{banner}\n\n{body_part}"
    else:
        new_content = f"{banner}\n\n{content.lstrip(chr(10)).lstrip(chr(13))}"
    fpath.write_text(new_content, encoding="utf-8")
    return "federated_hybrid"



def strip_variation_selectors(text: str) -> str:
    return text.replace("\ufe0f", "")


def parse_micro_yaml(frontmatter: str) -> dict:
    frontmatter = frontmatter.lstrip("\ufeff")
    lines = frontmatter.splitlines()
    result = {}
    current_key = None

    for line in lines:
        line_stripped = line.strip()
        if not line_stripped or line_stripped.startswith("#"):
            continue

        # Strip inline comments
        if " #" in line_stripped:
            line_stripped = line_stripped.split(" #")[0].strip()

        if line_stripped.startswith("- "):
            if current_key:
                if not isinstance(result[current_key], list):
                    result[current_key] = [result[current_key]] if result[current_key] else []
                result[current_key].append(line_stripped[2:].strip())
        elif ":" in line_stripped:
            key, val = line_stripped.split(":", 1)
            key = key.strip()
            val = val.strip()
            current_key = key
            if val.startswith("[") and val.endswith("]"):
                # Simple JSON-style flow list
                try:
                    val = json.loads(val)
                except json.JSONDecodeError:
                    pass
            result[key] = val
    return result


def rotate_backups(filepath: Path):
    bak_pattern = f"{filepath.name}.*.bak"
    backups = sorted(filepath.parent.glob(bak_pattern))
    while len(backups) >= 3:
        oldest = backups.pop(0)
        oldest.unlink(missing_ok=True)

    ts = datetime.now().strftime("%Y%m%d_%H%M%S_%f")
    new_bak = filepath.parent / f"{filepath.name}.{ts}.bak"
    shutil.copy2(filepath, new_bak)


def fix_frontmatter(content: str) -> str:
    required_keys = {
        "project_name": '"Default Project"',
        "version": '"1.0.0"',
        "tech_stack": "[]",
        "rules": "[]",
        "exclude_paths": "[]",
        "last_indexed": f'"{datetime.now().isoformat()}"',
    }

    if content.startswith("---\n"):
        parts = content.split("---\n", 2)
        if len(parts) >= 3:
            frontmatter_content = parts[1]
            frontmatter_data = parse_micro_yaml(frontmatter_content)
            lines_to_add = []
            for key, default_val in required_keys.items():
                if key not in frontmatter_data:
                    lines_to_add.append(f"{key}: {default_val}")
            if lines_to_add:
                new_frontmatter = frontmatter_content
                if not new_frontmatter.endswith("\n") and new_frontmatter:
                    new_frontmatter += "\n"
                new_frontmatter += "\n".join(lines_to_add) + "\n"
                return "---\n" + new_frontmatter + "---\n" + parts[2]
            return content

    # Missing frontmatter entirely or malformed
    new_frontmatter = "".join(f"{k}: {v}\n" for k, v in required_keys.items())

    if content.startswith("---\n"):
        # Malformed (missing closing delimiter)
        return "---\n" + new_frontmatter + "---\n\n" + content[4:]

    return "---\n" + new_frontmatter + "---\n\n" + content


def validate_markdown(
    content: str, filepath: Path, repo_root: Path, federate: bool = False, reality: bool = False
):
    import graphlib

    diagnostics = {"warnings": [], "errors": [], "stats": {}}

    lines = content.splitlines()
    line_count = len(lines)
    token_count = len(content) // 4

    diagnostics["stats"]["line_count"] = line_count
    diagnostics["stats"]["token_count"] = token_count

    if line_count <= 350:
        pass
    elif line_count <= 500:
        diagnostics["warnings"].append(f"WARN_BUDGET_APPROACHING: Line count {line_count}")
    else:
        diagnostics["errors"].append(f"ERR_BUDGET_EXCEEDED: Line count {line_count} > 500")

    if token_count <= 2500:
        pass
    elif token_count <= 3500:
        diagnostics["warnings"].append(f"WARN_BUDGET_APPROACHING: Token count {token_count}")
    else:
        diagnostics["errors"].append(f"ERR_BUDGET_EXCEEDED: Token count {token_count} > 3500")

    if content.startswith("---\n"):
        parts = content.split("---\n", 2)
        if len(parts) >= 3:
            frontmatter_data = parse_micro_yaml(parts[1])
            required_keys = [
                "project_name",
                "version",
                "tech_stack",
                "rules",
                "exclude_paths",
                "last_indexed",
            ]
            for key in required_keys:
                if key not in frontmatter_data:
                    diagnostics["errors"].append(
                        f"ERR_SCHEMA_INVALID: Missing required frontmatter key '{key}'"
                    )
        else:
            diagnostics["errors"].append(
                "ERR_SCHEMA_INVALID: Missing closing frontmatter delimiter '---'"
            )
    else:
        diagnostics["errors"].append("ERR_SCHEMA_INVALID: Missing frontmatter delimiter '---'")

    h1_match = re.search(r"^# Project Context: (.*)$", content, re.MULTILINE)
    if not h1_match:
        diagnostics["errors"].append("Missing or invalid H1. Expected '# Project Context: <name>'")

    required_h2s = [
        "## 🎯 Project Overview",
        "## 🏗️ Architecture & Component Mapping",
        "## 🛑 Mandatory Engineering Constraints",
        "## 🛠️ Common Workflows & CLI Commands",
        "## 🔄 Active Workstreams & Verification Status",
    ]

    content_normalized = strip_variation_selectors(content)
    found_h2s = []
    in_code_block = False
    for line in content_normalized.splitlines():
        stripped = line.strip()
        if stripped.startswith("```") or stripped.startswith("~~~"):
            in_code_block = not in_code_block
        elif not in_code_block and line.startswith("## "):
            found_h2s.append("## " + line[3:].strip())

    for req in required_h2s:
        if strip_variation_selectors(req) not in found_h2s:
            diagnostics["errors"].append(f"Missing required H2 section: {req}")

    if len(found_h2s) != 5:
        diagnostics["errors"].append(f"Expected exactly 5 H2 sections, found {len(found_h2s)}")

    # Link resolution
    links = re.findall(r"\[([^\]]+)\]\(([^)]+)\)", content)
    for _text, url in links:
        if url.startswith("http://") or url.startswith("https://"):
            diagnostics["warnings"].append(f"External HTTP(S) link found: {url}")
        elif url.startswith("#"):
            pass
        else:
            path = url
            if path.startswith("file://"):
                path = path.replace("file://", "", 1)
                if (
                    sys.platform == "win32"
                    and path.startswith("/")
                    and len(path) > 2
                    and path[2] == ":"
                ):
                    path = path[1:]  # e.g. /C:/Users -> C:/Users

            # Strip line anchors
            path = re.sub(r"#L\d+(?:-L\d+)?$", "", path)
            path = path.replace("\\", "/")

            try:
                target = Path(path)
                if not target.is_absolute():
                    target = repo_root / target

                if not target.exists():
                    diagnostics["errors"].append(
                        f"ERR_BROKEN_LINK: Referenced file does not exist: {url}"
                    )
            except Exception:
                diagnostics["errors"].append(
                    f"ERR_BROKEN_LINK: Referenced file does not exist: {url}"
                )

    system_excludes = {
        ".git",
        ".svn",
        "node_modules",
        "venv",
        ".venv",
        "dist",
        "build",
        "target",
        ".next",
        ".cache",
        "__pycache__",
    }
    architecture_section_text = ""
    in_arch = False
    in_code_block = False
    for line in lines:
        stripped = line.strip()
        if stripped.startswith("```") or stripped.startswith("~~~"):
            in_code_block = not in_code_block
        elif not in_code_block:
            clean_line = strip_variation_selectors(line).strip()
            if clean_line == strip_variation_selectors("## 🏗️ Architecture & Component Mapping"):
                in_arch = True
            elif line.startswith("## ") and in_arch:
                in_arch = False
        if in_arch:
            architecture_section_text += line + "\n"

    import os

    try:
        for root, dirs, files in os.walk(repo_root):
            dirs[:] = [d for d in dirs if d not in system_excludes]
            if Path(root) != repo_root and "GEMINI.md" in files:
                rel_path = str(Path(root).relative_to(repo_root) / "GEMINI.md").replace("\\", "/")
                if rel_path not in architecture_section_text and rel_path not in content:
                    diagnostics["warnings"].append(
                        f"WARN_CHILD_INDEX_INCOMPLETE: Nested GEMINI.md at '{rel_path}' not indexed in Section 2"
                    )
    except Exception:
        pass

    if reality:
        arch_links = re.findall(r"\[([^\]]+)\]\(([^)]+)\)", architecture_section_text)
        for _text, url in arch_links:
            if not (url.startswith("http://") or url.startswith("https://") or url.startswith("#")):
                path = url
                if path.startswith("file://"):
                    path = path.replace("file://", "", 1)
                    if (
                        sys.platform == "win32"
                        and path.startswith("/")
                        and len(path) > 2
                        and path[2] == ":"
                    ):
                        path = path[1:]
                path = re.sub(r"#L\d+(?:-L\d+)?$", "", path)
                path = path.replace("\\", "/")
                try:
                    target = Path(path)
                    if not target.is_absolute():
                        target = repo_root / target
                    if not target.exists():
                        diagnostics["warnings"].append(
                            f"WARN_REALITY_DRIFT: Documented component does not exist on disk: '{url}'"
                        )
                except Exception:
                    pass

    if "### Domain Lexicon & Ubiquitous Language" in architecture_section_text:
        lexicon_lines = architecture_section_text.split("### Domain Lexicon & Ubiquitous Language")[
            1
        ]
        lexicon_text = re.split(r"\n##?#? ", lexicon_lines)[0]
        has_table = False
        for line in lexicon_text.splitlines():
            if "|" in line:
                headers = [h.strip().lower() for h in line.split("|")]
                if "term" in headers and "canonical meaning" in headers:
                    has_table = True
                    break
        if not has_table:
            diagnostics["errors"].append(
                "ERR_LEXICON_MISSING_TABLE: Domain Lexicon section must contain a table with 'Term' and 'Canonical Meaning' headers"
            )

    section_5_text = ""
    in_sec_5 = False
    in_code_block = False
    for line in lines:
        stripped = line.strip()
        if stripped.startswith("```") or stripped.startswith("~~~"):
            in_code_block = not in_code_block
        elif not in_code_block:
            clean_line = strip_variation_selectors(line).strip()
            if clean_line == "## 🔄 Active Workstreams & Verification Status":
                in_sec_5 = True
            elif line.startswith("## ") and in_sec_5:
                if clean_line != "## 🔄 Active Workstreams & Verification Status":
                    in_sec_5 = False
        if in_sec_5:
            section_5_text += line + "\n"

    graph = {}
    table_lines = [
        line
        for line in section_5_text.splitlines()
        if line.strip().startswith("|") and line.strip().endswith("|")
    ]
    if table_lines:
        headers = [h.strip().lower() for h in table_lines[0].strip().strip("|").split("|")]
        if "id" in headers and "blocked by" in headers:
            id_idx = headers.index("id")
            blocked_idx = headers.index("blocked by")
            for row in table_lines[2:]:
                cols = [c.strip() for c in row.strip().strip("|").split("|")]
                if len(cols) > max(id_idx, blocked_idx):
                    task_id = cols[id_idx]
                    blocked_by = cols[blocked_idx]
                    if task_id and task_id != "-":
                        deps = [
                            d.strip()
                            for d in blocked_by.split(",")
                            if d.strip() and d.strip() != "-"
                        ]
                        graph[task_id] = set(deps)

    for line in section_5_text.splitlines():
        m = re.search(r"\|\s*(?:\[)?(#\d+)(?:\])?\s*\|", line)
        if not m:
            m = re.search(r"\[(#\d+)\]", line)
        if m:
            task_id = m.group(1)
            blocked_m = re.search(r"Blocked [bB]y:\s*([#\d\s,]+)", line)
            deps = []
            if blocked_m:
                deps = [
                    d.strip()
                    for d in blocked_m.group(1).split(",")
                    if d.strip() and d.strip() != "-"
                ]
            if task_id not in graph:
                graph[task_id] = set(deps)

    if graph:
        try:
            ts = graphlib.TopologicalSorter(graph)
            ts.prepare()
        except graphlib.CycleError as e:
            cycle = e.args[1] if len(e.args) > 1 else str(e)
            diagnostics["errors"].append(
                f"ERR_DAG_CYCLE: Circular dependency detected in workstreams: {cycle}"
            )

    for fname in ("CLAUDE.md", "AGENTS.md", ".cursorrules"):
        fpath = repo_root / fname
        status, _ = classify_federation_file(fpath)

        if status == "divergent":
            diagnostics["warnings"].append(
                f"WARN_SPLIT_BRAIN_CONTEXT: '{fname}' exists and diverges from GEMINI.md. Run with --federate to align."
            )

        if federate and status != "symlink":
            inject_or_update_federation(fpath, fname)
            if status == "divergent":
                diagnostics["warnings"] = [
                    w
                    for w in diagnostics["warnings"]
                    if not w.startswith(f"WARN_SPLIT_BRAIN_CONTEXT: '{fname}'")
                ]


    return diagnostics


def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("file_path", nargs="?", default="GEMINI.md", help="Path to markdown file")
    parser.add_argument("--context-file", dest="context_file", help="Path to markdown file (alias)")
    parser.add_argument("--file", dest="context_file", help="Path to markdown file (alias)")
    parser.add_argument("--json", action="store_true", help="JSON output")
    parser.add_argument("--strict", action="store_true", help="Warnings treated as errors")
    parser.add_argument("--fix-frontmatter", action="store_true", help="Fix frontmatter")
    parser.add_argument("--backup", action="store_true", help="Create rotating backup")
    parser.add_argument("--federate", action="store_true", help="Align cross-ecosystem manifests")
    parser.add_argument("--reality", action="store_true", help="Enable reality drift validation")
    parser.add_argument("--version", action="version", version=__version__)

    args = parser.parse_args()

    filepath = Path(args.context_file if args.context_file else args.file_path).resolve()

    if not filepath.exists():
        err = {"error": f"File not found: {filepath}"}
        if args.json:
            print(json.dumps(err))
        else:
            print(err["error"])
        sys.exit(1)

    if args.backup:
        rotate_backups(filepath)

    try:
        with open(filepath, encoding="utf-8") as f:
            content = f.read()
    except Exception as e:
        err = {"error": f"Failed to read file: {e}"}
        if args.json:
            print(json.dumps(err))
        else:
            print(err["error"])
        sys.exit(1)

    if args.fix_frontmatter:
        fixed_content = fix_frontmatter(content)
        if fixed_content != content:
            content = fixed_content
            with open(filepath, "w", encoding="utf-8") as f:
                f.write(content)

    repo_root = filepath.parent
    diagnostics = validate_markdown(content, filepath, repo_root, args.federate, args.reality)

    has_errors = len(diagnostics["errors"]) > 0
    has_warnings = len(diagnostics["warnings"]) > 0
    strict_warnings = [
        w for w in diagnostics["warnings"] if not w.startswith("WARN_BUDGET_APPROACHING")
    ]

    exit_code = 1 if has_errors or (args.strict and len(strict_warnings) > 0) else 0

    if args.json:
        print(json.dumps(diagnostics, indent=2))
    else:
        print(f"Validation for {filepath.name}:")
        print(f"Stats: {diagnostics['stats']}")
        if has_errors:
            print("Errors:")
            for e in diagnostics["errors"]:
                print(f"  - {e}")
        if has_warnings:
            print("Warnings:")
            for w in diagnostics["warnings"]:
                print(f"  - {w}")
        if not has_errors and not has_warnings:
            print("All checks passed!")

    sys.exit(exit_code)


if __name__ == "__main__":
    main()
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall