gator-command 1.0.0__py3-none-any.whl

gator_command/scripts/gatorize.py

@@ -0,0 +1,1163 @@
+#!/usr/bin/env python3
+"""
+gatorize.py — Install, upgrade, or morph Gator into a project repo.
+
+Cross-platform Python implementation of gatorize.sh. Works on Windows
+CMD/PowerShell, Git Bash, macOS Terminal, and Linux.
+
+Usage:
+    python gatorize.py <target-directory>
+    python gatorize.py .
+
+Handles five scenarios:
+  1. Fresh directory (no git)        → git init + install
+  2. Git repo, clean                 → install
+  3. Git repo, has .gator/           → run update
+  4. Git repo, has memex structure   → morph memex → gator
+  5. Git repo, has both              → warn, let user choose
+
+@reads: templates in gator-starter/
+@writes: target .gator/, entry points, hooks, registry
+"""
+
+import argparse
+import os
+import shutil
+import stat
+import subprocess
+import sys
+from datetime import datetime
+from pathlib import Path
+
+SCRIPTS_DIR = Path(__file__).resolve().parent
+# Scripts are at src/gator_command/scripts/ — repo root is 3 levels up
+COMMAND_POST = SCRIPTS_DIR.parent.parent.parent
+
+sys.path.insert(0, str(SCRIPTS_DIR))
+from gator_core import find_command_post, ensure_utf8_stdout, import_sibling  # noqa: E402
+
+# ── constants ──────────────────────────────────────────────────────────────
+
+GATOR_BRANCH = "gator-install"
+TODAY = datetime.now().strftime("%Y-%m-%d")
+NOW = datetime.now().strftime("%Y-%m-%dT%H:%M:%S")
+GATOR_MARKER = "# --- Gator Navigation Coding ---"
+COMMAND_POST_MARKER = "# --- Gator Command Post ---"
+
+# Detect template directory
+TEMPLATES = None
+for tpl_rel in ("templates/gator-starter", "../templates/gator-starter"):
+    candidate = (SCRIPTS_DIR.parent / tpl_rel).resolve()
+    if candidate.is_dir():
+        TEMPLATES = candidate
+        break
+if not TEMPLATES:
+    # Try gator-engine layout
+    for tpl_rel in ("gator-engine/templates/gator-starter",
+                     "gator-command/templates/gator-starter"):
+        candidate = (COMMAND_POST / tpl_rel).resolve()
+        if candidate.is_dir():
+            TEMPLATES = candidate
+            break
+
+# Read generation from gator_core.py
+GATOR_GEN = 2
+try:
+    from gator_core import CURRENT_GENERATION
+    GATOR_GEN = CURRENT_GENERATION
+except ImportError:
+    pass
+
+
+# ── helpers ────────────────────────────────────────────────────────────────
+
+def git(*args, cwd=None):
+    """Run a git command. Returns (stdout, success)."""
+    try:
+        result = subprocess.run(
+            ["git"] + list(args),
+            capture_output=True, text=True, timeout=30,
+            cwd=str(cwd) if cwd else None,
+        )
+        return result.stdout.strip(), result.returncode == 0
+    except Exception as e:
+        return str(e), False
+
+
+def log_step(msg):
+    print(f"  {msg}")
+
+
+def prompt(question, options="", default=""):
+    """Interactive prompt. Returns user input."""
+    suffix = f" [{options}]: " if options else ": "
+    try:
+        return input(f"  {question}{suffix}").strip()
+    except (EOFError, KeyboardInterrupt):
+        return default
+
+
+def confirm(question, default="Y"):
+    """Y/N confirmation."""
+    choice = prompt(question, "Y/n" if default == "Y" else "y/N")
+    if not choice:
+        return default == "Y"
+    return choice.lower().startswith("y")
+
+
+def copy_tree_overlay(src, dest):
+    """Copy files from src to dest, preserving extras in dest."""
+    dest.mkdir(parents=True, exist_ok=True)
+    for item in sorted(src.iterdir()):
+        if item.name in ("__pycache__",) or item.suffix == ".pyc":
+            continue
+        target = dest / item.name
+        if item.is_dir():
+            copy_tree_overlay(item, target)
+        else:
+            shutil.copy2(item, target)
+
+
+# ── detection ──────────────────────────────────────────────────────────────
+
+def detect_scenario(target):
+    """Returns scenario number 1-5."""
+    has_git = (target / ".git").is_dir()
+    has_gator = (target / ".gator").is_dir()
+    has_memex = (target / "memex").is_dir() or (target / ".memex").is_dir()
+
+    if not has_git and not has_memex and not has_gator:
+        return 1
+    if has_git and not has_memex and not has_gator:
+        return 2
+    if has_git and not has_memex and has_gator:
+        return 3
+    if has_git and has_memex and not has_gator:
+        return 4
+    if has_git and has_memex and has_gator:
+        return 5
+    # Edge: memex without git
+    print("  Error: memex structure found but no git. Initialize git first.")
+    sys.exit(1)
+
+
+def detect_generation(target):
+    """Returns generation number of existing .gator/."""
+    version_file = target / ".gator" / ".gator-version"
+    if version_file.exists():
+        for line in version_file.read_text(encoding="utf-8", errors="replace").splitlines():
+            if line.startswith("generation:"):
+                try:
+                    return int(line.split(":", 1)[1].strip())
+                except ValueError:
+                    pass
+        return 2
+    if (target / ".gator" / "command-post.md").exists():
+        return 1
+    return 0
+
+
+# ── git operations ─────────────────────────────────────────────────────────
+
+def action_git_init(target):
+    """Scenario 1: initialize git in a fresh directory."""
+    print()
+    log_step(f"Initializing git in {target}...")
+    git("init", cwd=target)
+    # Ensure main branch
+    branch, _ = git("branch", "--show-current", cwd=target)
+    if branch != "main":
+        git("branch", "-M", "main", cwd=target)
+    # Initial commit
+    files = [f for f in target.iterdir() if f.name != ".git"]
+    if files:
+        git("add", "-A", cwd=target)
+        git("commit", "-m", "Initial commit (pre-Gator)", cwd=target)
+    else:
+        git("commit", "--allow-empty", "-m", "Initial commit (pre-Gator)", cwd=target)
+    git("branch", "dev", cwd=target)
+    git("checkout", "-b", GATOR_BRANCH, cwd=target)
+    log_step(f"On '{GATOR_BRANCH}' (git initialized).")
+
+
+def action_feature_branch(target):
+    """Create or switch to gator-install branch."""
+    # Check for uncommitted changes
+    status, _ = git("status", "--porcelain", cwd=target)
+    if status:
+        print()
+        print(f"  Warning: uncommitted changes detected in {target}.")
+        print("  Strongly recommend committing or stashing before gatorizing.")
+        print()
+        choice = prompt("Continue anyway or abort?", "c/a")
+        if choice.lower() == "a":
+            print("  Aborted.")
+            sys.exit(0)
+
+    # Handle existing gator-install branch
+    _, has_branch = git("rev-parse", "--verify", GATOR_BRANCH, cwd=target)
+    if has_branch:
+        print()
+        print(f"  Branch '{GATOR_BRANCH}' already exists (prior install attempt?).")
+        print()
+        print("    [1] Delete and start fresh (recommended)")
+        print("    [2] Continue on existing branch")
+        print("    [x] Cancel installation")
+        print()
+        choice = prompt("Choice", "1/2/x")
+        if choice.lower() == "x":
+            print("  Installation cancelled.")
+            sys.exit(0)
+        elif choice == "1":
+            git("checkout", "dev", cwd=target)
+            git("checkout", "main", cwd=target)  # fallback
+            git("branch", "-D", GATOR_BRANCH, cwd=target)
+            log_step(f"Deleted old '{GATOR_BRANCH}' branch.")
+
+    # Get branches (excluding gator-install)
+    branch_out, _ = git("branch", cwd=target)
+    branches = []
+    current = ""
+    for line in (branch_out or "").splitlines():
+        is_current = line.startswith("*")
+        name = line.lstrip("* ").strip()
+        if name == GATOR_BRANCH:
+            continue
+        branches.append(name)
+        if is_current:
+            current = name
+
+    if not branches:
+        log_step("No branches found. Installing on current state.")
+        git("checkout", "-b", GATOR_BRANCH, cwd=target)
+        return
+
+    print()
+    print(f"  Gator installs on a feature branch ('{GATOR_BRANCH}') for safety.")
+    print("  This keeps the install reversible — delete the branch if anything goes wrong,")
+    print("  merge to dev when you're happy.")
+    print()
+
+    source_branch = current
+    if len(branches) == 1:
+        source_branch = branches[0]
+        print(f"  Only one branch: {source_branch}")
+    else:
+        print("  Available branches:")
+        print()
+        for i, b in enumerate(branches):
+            marker = "* " if b == current else "  "
+            print(f"    [{i + 1}] {marker}{b}")
+        print()
+        choice = prompt(f"Which branch should '{GATOR_BRANCH}' branch from?", f"1-{len(branches)}")
+        try:
+            idx = int(choice) - 1
+            if 0 <= idx < len(branches):
+                source_branch = branches[idx]
+        except (ValueError, IndexError):
+            pass
+
+    git("checkout", source_branch, cwd=target)
+    # Ensure dev exists — track origin/dev if available, else create from current
+    _, has_dev = git("rev-parse", "--verify", "dev", cwd=target)
+    if not has_dev:
+        _, has_remote_dev = git("rev-parse", "--verify", "origin/dev", cwd=target)
+        if has_remote_dev:
+            git("branch", "dev", "origin/dev", cwd=target)
+            log_step("Created 'dev' branch tracking origin/dev.")
+        else:
+            git("branch", "dev", cwd=target)
+            log_step("Created 'dev' branch.")
+
+    # Create or switch to gator-install
+    _, has_gi = git("rev-parse", "--verify", GATOR_BRANCH, cwd=target)
+    if has_gi:
+        git("checkout", GATOR_BRANCH, cwd=target)
+    else:
+        git("checkout", "-b", GATOR_BRANCH, cwd=target)
+    log_step(f"On '{GATOR_BRANCH}' (from '{source_branch}').")
+
+
+# ── install ────────────────────────────────────────────────────────────────
+
+def action_install_gator(target):
+    """Fresh install of .gator/ from templates."""
+    log_step(f"Installing .gator/ into {target}...")
+
+    gator_dir = target / ".gator"
+
+    # Create directory structure
+    for d in ["charters", "blueprints", "reference-notes", "procedures",
+              "scripts", "threads", "artifacts", "vault", "policies", "sessions"]:
+        (gator_dir / d).mkdir(parents=True, exist_ok=True)
+
+    # Copy templates
+    for name in ("constitution.md", "gator-start-up.md"):
+        src = TEMPLATES / name
+        if src.exists():
+            shutil.copy2(src, gator_dir / name)
+
+    # Charter scaffolding
+    for name in ("README.md", "_template.md"):
+        src = TEMPLATES / "charters" / name
+        if src.exists():
+            shutil.copy2(src, gator_dir / "charters" / name)
+
+    # Blueprint scaffolding
+    src = TEMPLATES / "blueprints" / "README.md"
+    if src.exists():
+        shutil.copy2(src, gator_dir / "blueprints" / "README.md")
+
+    # Overlay directories
+    for subdir in ("reference-notes", "procedures"):
+        src_dir = TEMPLATES / subdir
+        if src_dir.is_dir():
+            copy_tree_overlay(src_dir, gator_dir / subdir)
+
+    # Scripts (including subdirectories like hooks/)
+    scripts_src = TEMPLATES / "scripts"
+    if scripts_src.is_dir():
+        copy_tree_overlay(scripts_src, gator_dir / "scripts")
+
+    # Slash commands
+    commands_src = TEMPLATES / "commands"
+    if commands_src.is_dir():
+        claude_commands = target / ".claude" / "commands"
+        claude_commands.mkdir(parents=True, exist_ok=True)
+        copy_tree_overlay(commands_src, claude_commands)
+
+    # Install hooks
+    install_hooks(target)
+
+    # Write stubs
+    write_stubs(gator_dir)
+
+    # Write version
+    write_gator_version(gator_dir, "install")
+
+    log_step(".gator/ installed.")
+
+
+def install_hooks(target):
+    """Install git hooks."""
+    hooks_dir = target / ".git" / "hooks"
+    hooks_dir.mkdir(parents=True, exist_ok=True)
+    hook_src = TEMPLATES / "scripts" / "hooks"
+
+    # Use the shared hook builder from gator-update.py — one definition of
+    # "correctly installed hooks" across gatorize, gator-update, and gator-init.
+    gator_update = import_sibling("gator-update")
+    hook_wrappers = gator_update.build_git_hook_wrappers()
+
+    for hook_name, hook_content in hook_wrappers.items():
+        dest = hooks_dir / hook_name
+
+        # Backup existing non-Gator hook
+        if dest.exists():
+            content = dest.read_text(encoding="utf-8", errors="replace")
+            if "Gator" not in content and "gator" not in content:
+                backup = dest.with_suffix(".pre-gator")
+                shutil.copy2(dest, backup)
+
+        dest.write_text(hook_content, encoding="utf-8")
+        # Make executable on Unix
+        if os.name != "nt":
+            dest.chmod(dest.stat().st_mode | stat.S_IEXEC)
+
+    log_step("Git hooks installed.")
+
+
+def write_stubs(gator_dir):
+    """Write stub content files (only if missing)."""
+    stubs = {
+        "mission.md": "# Mission\n\n[What are we building and why?]\n",
+        "roadmap.md": "# Roadmap\n\n[Priority-ordered. Updated as items complete.]\n\n"
+                      "**Status key**: Done · Building · Designed · Considering · Deferred\n",
+        "inbox.md": "# Inbox\n\nDrop anything here. No formatting needed.\n\n---\n\n",
+        "identity.md": "---\noperating-mode: designer\n---\n\n# Identity\n\n"
+                       "## Basics\n\n- **Name**: [Your name]\n- **Location**: [Your timezone]\n"
+                       "- **Role**: [Your role]\n",
+        "issues.md": "# Issues\n\nActive bugs, blockers, and known fragilities.\n\n"
+                     "**Status key**: Open · Working · Resolved\n\n---\n\n",
+        "commit_draft.md": "---\nmessage: \"\"\nchange-type:\nsignificance:\n"
+                           "decision-tags: []\nagent:\narchitect:\n---\n\n"
+                           "# Session Change Log\n\n",
+        "patterns.md": "# Patterns\n\nRecurring rhythms, obligations, schedules.\n\n---\n\n",
+        "whiteboard.md": "# Whiteboard\n\nNo findings.\n",
+    }
+
+    for name, content in stubs.items():
+        path = gator_dir / name
+        if not path.exists():
+            path.write_text(content, encoding="utf-8")
+
+    # JSON stubs
+    lint_allow = gator_dir / "lint-allow.json"
+    if not lint_allow.exists():
+        lint_allow.write_text("[]", encoding="utf-8")
+
+    commit_issues = gator_dir / "commit_issues.md"
+    if not commit_issues.exists():
+        commit_issues.write_text("# Commit Issues\n\nNo findings.\n", encoding="utf-8")
+
+    config = gator_dir / "config.json"
+    if not config.exists():
+        config.write_text('{\n  "enforcement_level": "strict"\n}\n', encoding="utf-8")
+
+    # Charter INDEX
+    index = gator_dir / "charters" / "INDEX.md"
+    if not index.exists():
+        index.write_text(
+            "# Charter Index\n\n**Always read first:** [Cross-Cutting](cross-cutting.md) (when it exists)\n\n"
+            "| If you're changing... | Read these charters |\n|---|---|\n| | |\n",
+            encoding="utf-8",
+        )
+
+    # Sessions .gitignore
+    sessions_gi = gator_dir / "sessions" / ".gitignore"
+    sessions_gi.parent.mkdir(exist_ok=True)
+    if not sessions_gi.exists():
+        sessions_gi.write_text("_active/\n", encoding="utf-8")
+
+    # Vault — gitignored directory for sensitive material and large files
+    vault_dir = gator_dir / "vault"
+    vault_dir.mkdir(exist_ok=True)
+    vault_gitkeep = vault_dir / ".gitkeep"
+    if not vault_gitkeep.exists():
+        vault_gitkeep.write_text("", encoding="utf-8")
+    ensure_repo_gitignore(gator_dir.parent)
+
+
+def ensure_repo_gitignore(repo_root):
+    """Ensure standard gitignore rules exist in the repo's .gitignore.
+
+    Called on both fresh install and upgrade paths so all governed repos
+    converge on the same set of ignore rules.
+    """
+    repo_gi = repo_root / ".gitignore"
+    gi_rules = {
+        ".gator/vault/": "# Vault — sensitive material and large files",
+        ".vscode/": "# IDE settings",
+        "__pycache__/": "# Python cache",
+    }
+    if repo_gi.exists():
+        gi_text = repo_gi.read_text(encoding="utf-8", errors="replace")
+    else:
+        gi_text = ""
+    additions = []
+    for rule, comment in gi_rules.items():
+        if rule not in gi_text:
+            additions.append(f"{comment}\n{rule}")
+    if additions:
+        with open(repo_gi, "a" if gi_text else "w", encoding="utf-8") as f:
+            f.write("\n" + "\n".join(additions) + "\n")
+
+
+def write_gator_version(gator_dir, action):
+    """Write .gator-version with generation and timestamps."""
+    version_file = gator_dir / ".gator-version"
+
+    # Preserve install date on upgrade
+    installed = TODAY
+    if version_file.exists():
+        for line in version_file.read_text(encoding="utf-8", errors="replace").splitlines():
+            if line.startswith("installed:"):
+                prev = line.split(":", 1)[1].strip()
+                if prev:
+                    installed = prev
+
+    version_file.write_text(
+        f"generation: {GATOR_GEN}\n"
+        f"installed: {installed}\n"
+        f"updated: {NOW}\n"
+        f"action: {action}\n"
+        f"installer: gatorize.py\n",
+        encoding="utf-8",
+    )
+
+
+# ── entry points ───────────────────────────────────────────────────────────
+
+GATOR_BEGIN = "<!-- GATOR:BEGIN -->"
+GATOR_END = "<!-- GATOR:END -->"
+
+
+def render_entry_content(has_command_post, agent_type="claude"):
+    """Render the canonical Gator-managed block for an entry point."""
+    gator_init_block = (
+        '**"gator init" means**: run `python .gator/scripts/gator-init.py` '
+        "and display the output exactly as printed. It is NOT a repo bootstrap "
+        "or git init — it is the standardized Gator boot sequence. Run the script, "
+        "show the output, then proceed with session opening.\n\n"
+        '**"gator pulse"**: run `python .gator/scripts/gator-pulse.py` to generate '
+        "`.gator/pulse.md` — a strategic operations brief with next steps, project "
+        "assessment, roadmap check, priorities, and recent activity.\n\n"
+        "**Project assessment**: when the Architect asks for a project assessment, "
+        "write a 2-paragraph expert evaluation to "
+        "`.gator/artifacts/YYYY-MM-DD-project-assessment.md` with YAML frontmatter "
+        "(`date`, `type: project-assessment`, `model: <your model name>`). "
+        "Write as an expert consultant advising an engineering manager. "
+        "The next `gator pulse` will include it automatically."
+    )
+
+    constitution_line = "Read [`.gator/constitution.md`](.gator/constitution.md) before your first response. It governs how you work here."
+    bootstrap_line = "If this is a **fresh project** (charters/ is empty or contains only templates), follow the bootstrap procedure in [`.gator/gator-start-up.md`](.gator/gator-start-up.md)."
+
+    cp_section = ""
+    if has_command_post:
+        cp_section = (
+            f"\n\n{COMMAND_POST_MARKER}\n"
+            "This repo is governed by a Gator Command post. "
+            "Read [`.gator/command-post.md`](.gator/command-post.md) for the command post location. "
+            "Read org standards from there at session open. "
+            "**Never write to the command post from this session.** "
+            "Cross-repo discoveries go in [`outbox.md`](outbox.md)."
+        )
+
+    content = f"{gator_init_block}\n\n{constitution_line}\n\n{bootstrap_line}"
+
+    if agent_type == "agents":
+        content += (
+            "\n\nIf the PI asks for an **enforcer review**, do not repurpose yourself as the enforcer. "
+            "Use the dedicated enforcer prompt at [`.gator/scripts/enforcer-prompt.md`](.gator/scripts/enforcer-prompt.md)."
+        )
+
+    content += cp_section
+    return content
+
+
+def action_install_entry_points(target, has_command_post):
+    """Install or refresh CLAUDE.md, AGENTS.md, GEMINI.md.
+
+    Three cases:
+    - File missing: create with sentinels
+    - Non-Gator file (no markers): interactive prompt (backup/append/overwrite)
+    - Gator-managed file (has markers): refresh managed block in place
+    """
+    entries = [
+        ("CLAUDE.md", "# Claude Code Entry Point", "claude", "CLAUDE_ROLLBACK.md"),
+        ("AGENTS.md", "# Codex Entry Point", "agents", "AGENTS_ROLLBACK.md"),
+        ("GEMINI.md", "# Gemini Entry Point", "gemini", "GEMINI_ROLLBACK.md"),
+    ]
+
+    idx = 0
+    while idx < len(entries):
+        filename, header, agent_type, rollback_name = entries[idx]
+        filepath = target / filename
+        content = render_entry_content(has_command_post, agent_type)
+        managed_block = f"{GATOR_BEGIN}\n{content}\n{GATOR_END}"
+
+        if filepath.exists():
+            existing = filepath.read_text(encoding="utf-8", errors="replace")
+
+            # Case: Gator-managed file — refresh the managed block
+            if GATOR_BEGIN in existing and GATOR_END in existing:
+                # Replace between sentinels
+                before = existing[:existing.index(GATOR_BEGIN)]
+                after = existing[existing.index(GATOR_END) + len(GATOR_END):]
+                filepath.write_text(
+                    f"{before}{managed_block}{after}",
+                    encoding="utf-8",
+                )
+                log_step(f"{filename} — Gator block refreshed")
+                idx += 1
+                continue
+
+            # Case: has old Gator marker OR recognizable Gator content but no sentinels
+            # Detect Gator ownership: markers, or known Gator references
+            is_gator_owned = (
+                GATOR_MARKER in existing
+                or COMMAND_POST_MARKER in existing
+                or "gator-init.py" in existing
+                or ".gator/constitution.md" in existing
+            )
+
+            if is_gator_owned:
+                # Find the split point — where Gator content starts
+                marker_pos = None
+                for marker in (GATOR_MARKER, COMMAND_POST_MARKER):
+                    if marker in existing:
+                        marker_pos = existing.index(marker)
+                        break
+
+                if marker_pos is not None:
+                    pre_gator = existing[:marker_pos].rstrip()
+                    # Preserve post-Gator content (e.g., ## Pre-Gator Instructions)
+                    post_gator = ""
+                    pre_gator_section = "## Pre-Gator Instructions"
+                    if pre_gator_section in existing:
+                        post_gator = "\n\n" + existing[existing.index(pre_gator_section):]
+                else:
+                    # No marker — entire file is Gator-managed (standalone old format)
+                    pre_gator = ""
+                    # Check for rollback reference
+                    post_gator = ""
+                    pre_gator_section = "## Pre-Gator Instructions"
+                    if pre_gator_section in existing:
+                        post_gator = "\n\n" + existing[existing.index(pre_gator_section):]
+
+                if pre_gator:
+                    filepath.write_text(
+                        f"{pre_gator}\n\n{managed_block}{post_gator}\n",
+                        encoding="utf-8",
+                    )
+                else:
+                    filepath.write_text(
+                        f"{header}\n\nYou are the primary agent for this project.\n\n{managed_block}{post_gator}\n",
+                        encoding="utf-8",
+                    )
+                log_step(f"{filename} — upgraded to sentinel format + refreshed")
+                idx += 1
+                continue
+
+            # Case: non-Gator file — interactive prompt
+            line_count = len(existing.splitlines())
+            print()
+            print(f"  {filename} already exists ({line_count} lines).")
+            print()
+            print("  Options:")
+            print()
+            print(f"    [1] Backup & replace (recommended) — save as {rollback_name},")
+            print(f"        create new {filename} with Gator governance + reference to original.")
+            print()
+            print(f"    [2] Append — add Gator lines to the end of the existing file.")
+            print()
+            print(f"    [3] Overwrite — replace entirely (original content lost).")
+            if idx > 0:
+                print(f"    [b] Go back — return to previous entry point.")
+            print(f"    [x] Cancel installation.")
+            print()
+            choice = prompt("Choice", f"1/2/3{'/b' if idx > 0 else ''}/x")
+
+            if choice == "1":
+                shutil.copy2(filepath, target / rollback_name)
+                log_step(f"Saved original as {rollback_name}")
+                filepath.write_text(
+                    f"{header}\n\nYou are the primary agent for this project.\n\n"
+                    f"{managed_block}\n\n"
+                    f"## Pre-Gator Instructions\n\n"
+                    f"This project had an existing {filename} before Gator was installed.\n"
+                    f"Those instructions have been preserved in [`{rollback_name}`]({rollback_name}).\n"
+                    f"**Read that file now** — it may contain skills, custom instructions, personas,\n"
+                    f"or project-specific rules that should still be followed alongside the\n"
+                    f"Gator constitution.\n\n"
+                    f"If any instructions in {rollback_name} conflict with the Gator constitution,\n"
+                    f"the constitution takes precedence for code governance (charters, commit loop,\n"
+                    f"enforcer rules). For everything else (skills, personas, custom workflows),\n"
+                    f"follow {rollback_name}.\n",
+                    encoding="utf-8",
+                )
+                log_step(f"Created new {filename} with Gator governance + reference to {rollback_name}")
+            elif choice == "2":
+                with open(filepath, "a", encoding="utf-8") as f:
+                    f.write(f"\n{managed_block}\n")
+                log_step(f"Appended Gator entry point to {filename}")
+            elif choice == "3":
+                filepath.write_text(
+                    f"{header}\n\nYou are the primary agent for this project.\n\n{managed_block}\n",
+                    encoding="utf-8",
+                )
+                log_step(f"Replaced {filename} (original content lost)")
+            elif choice.lower() == "b" and idx > 0:
+                idx -= 1
+                continue
+            elif choice.lower() == "x":
+                print()
+                print("  Installation cancelled.")
+                print("  To clean up: git checkout dev && git branch -D gator-install")
+                sys.exit(0)
+        else:
+            # New file — create with sentinels
+            filepath.write_text(
+                f"{header}\n\nYou are the primary agent for this project.\n\n{managed_block}\n",
+                encoding="utf-8",
+            )
+            log_step(f"Created {filename}")
+
+        idx += 1
+
+
+# ── post-install ───────────────────────────────────────────────────────────
+
+def action_install_outbox(target):
+    """Create outbox.md stub."""
+    outbox = target / "outbox.md"
+    if outbox.exists():
+        # Check if it has content
+        text = outbox.read_text(encoding="utf-8", errors="replace")
+        lines = [l for l in text.splitlines() if l.strip() and not l.startswith("#") and not l.startswith("---")]
+        if lines:
+            log_step("outbox.md already exists with content — preserved")
+            return
+    outbox.write_text(
+        "# Outbox\n\n"
+        "Messages for Gator Command. The Architect triages these during command post sessions.\n"
+        "Do not clear this file from the project repo — the command post session clears\n"
+        "entries after processing.\n\n---\n\n",
+        encoding="utf-8",
+    )
+    log_step("Created outbox.md")
+
+
+def action_install_thin_link(target):
+    """Create .gator/command-post.md with paths to command post."""
+    cp_path = str(COMMAND_POST)
+    try:
+        rel_path = os.path.relpath(str(COMMAND_POST), str(target))
+    except ValueError:
+        rel_path = cp_path
+
+    (target / ".gator" / "command-post.md").write_text(
+        f"---\ncommand-post: {rel_path}\n"
+        f"command-post-absolute: {cp_path}  # machine-local\n"
+        f"remote: # optional\nversion: {TODAY}\n---\n\n"
+        f"# Gator Command Post\n\nThis repo is governed by [Gator Command]({rel_path}).\n"
+        f"The agent should read org standards from the command post at session open.\n"
+        f"**Do not modify the command post from this repo.**\n",
+        encoding="utf-8",
+    )
+    log_step("Installed thin link (.gator/command-post.md)")
+
+
+def action_install_product_source(target):
+    """Write .gator/product-source.json."""
+    gator_root = str(COMMAND_POST)
+    template_dir = ""
+    if (COMMAND_POST / "gator-engine" / "templates" / "gator-starter").is_dir():
+        template_dir = "gator-engine/templates/gator-starter"
+    elif (COMMAND_POST / "gator-command" / "templates" / "gator-starter").is_dir():
+        template_dir = "gator-command/templates/gator-starter"
+
+    import json
+    (target / ".gator" / "product-source.json").write_text(
+        json.dumps({
+            "gator_root": gator_root,
+            "template_dir": template_dir,
+            "installed": TODAY,
+            "updated": TODAY,
+        }, indent=2) + "\n",
+        encoding="utf-8",
+    )
+    log_step(f"Wrote product-source.json (source: {gator_root})")
+
+
+def action_register(target):
+    """Add repo to registry.md."""
+    registry = COMMAND_POST / "gator-command" / "registry.md"
+    repo_name = target.name
+
+    if not registry.parent.is_dir():
+        return
+
+    if not registry.exists():
+        registry.write_text(
+            "# Registry\n\n"
+            "Repos governed by this Gator Command post. Updated by `gatorize.sh` and maintained by the Architect.\n\n"
+            "| Repo | Local path | Remote | Registered | Status |\n"
+            "|------|-----------|--------|------------|--------|\n",
+            encoding="utf-8",
+        )
+
+    text = registry.read_text(encoding="utf-8", errors="replace")
+    if str(target) in text:
+        log_step(f"{repo_name} already registered.")
+        return
+
+    remote, _ = git("remote", "get-url", "origin", cwd=target)
+    if not remote:
+        remote = "—"
+
+    with open(registry, "a", encoding="utf-8") as f:
+        f.write(f"| {repo_name} | {target} | {remote} | {TODAY} | current |\n")
+    print()
+    log_step(f"Registered {repo_name} in registry.")
+
+
+def print_summary(target, scenario, has_command_post):
+    """Print SUCCESS banner."""
+    repo_name = target.name
+    print()
+    print("  ================================================================")
+    print(f"  Gatorized: {repo_name}")
+    print("  ================================================================")
+    print()
+
+    # Git instructions
+    branch, _ = git("branch", "--show-current", cwd=target)
+    if branch == GATOR_BRANCH:
+        print(f"  You are on the '{GATOR_BRANCH}' branch. To finalize:")
+        print()
+        print(f"      cd {target}")
+        print(f"      git add -A && git commit -m 'Gatorize: install .gator/ governance layer'")
+        print(f"      git checkout dev && git merge {GATOR_BRANCH}")
+        print(f"      git branch -d {GATOR_BRANCH}")
+
+    print()
+    print("  ================================================================")
+    print("  SUCCESS")
+    print("  ================================================================")
+    print()
+    print("  What to do now:")
+    print()
+    print(f"    1. cd {target}")
+    print(f"    2. Launch your AI coding tool (Claude Code, Codex, Gemini, etc.)")
+    print(f"    3. Type: gator init")
+    print(f"    4. The agent will read the constitution and orient to the project.")
+    print(f"       Your first git commit fires the governance hooks.")
+    print()
+    print(f"  Enforcement: strict (commit gate active)")
+    if has_command_post:
+        print(f"  Command post: linked")
+    else:
+        print(f"  Command post: standalone")
+    print()
+
+
+
+# ── memex morph ────────────────────────────────────────────────────────────
+
+def detect_legacy_memex(target):
+    """Detect what legacy memex structure exists."""
+    return {
+        "memex": (target / "memex").is_dir(),
+        "dot_memex": (target / ".memex").is_dir(),
+        "root_constitution": (target / "constitution.md").is_file(),
+        "root_constitution_core": (target / "constitution-core.md").is_file(),
+    }
+
+
+def action_morph_memex(target):
+    """Morph legacy memex structure into .gator/."""
+    legacy = detect_legacy_memex(target)
+
+    print("  Legacy memex structure detected:")
+    if legacy["memex"]:
+        print("    memex/                  (content layer)")
+    if legacy["dot_memex"]:
+        print("    .memex/                 (system layer)")
+    if legacy["root_constitution"]:
+        print("    constitution.md         (root)")
+    if legacy["root_constitution_core"]:
+        print("    constitution-core.md    (root)")
+    print()
+    print("  Gatorize will morph this into .gator/ structure:")
+    print("    1. Rename legacy dirs to *.pre-gator/")
+    print("    2. Install fresh .gator/ from templates")
+    print("    3. Copy your content into .gator/")
+    print("    4. Archive root constitution files")
+    print()
+    if not confirm("Proceed with morph?"):
+        print("  Cancelled.")
+        sys.exit(0)
+
+    # Step 1: Rename legacy dirs
+    if legacy["memex"]:
+        pre = target / "memex.pre-gator"
+        if pre.exists():
+            log_step("memex.pre-gator/ already exists — skipping rename")
+        else:
+            _, ok = git("mv", "memex", "memex.pre-gator", cwd=target)
+            if not ok:
+                shutil.move(str(target / "memex"), str(pre))
+            log_step("Renamed memex/ -> memex.pre-gator/")
+
+    if legacy["dot_memex"]:
+        pre = target / ".memex.pre-gator"
+        if pre.exists():
+            log_step(".memex.pre-gator/ already exists — skipping rename")
+        else:
+            _, ok = git("mv", ".memex", ".memex.pre-gator", cwd=target)
+            if not ok:
+                shutil.move(str(target / ".memex"), str(pre))
+            log_step("Renamed .memex/ -> .memex.pre-gator/")
+
+    # Step 2: Install .gator/ (or upgrade if it exists)
+    if (target / ".gator").is_dir():
+        log_step("Existing .gator/ found — upgrading templates.")
+        subprocess.run(
+            [sys.executable, str(SCRIPTS_DIR / "gator-update.py"),
+             "--path", str(target), "--source", str(COMMAND_POST), "--no-policy"],
+            cwd=str(target),
+        )
+    else:
+        action_install_gator(target)
+
+    # Step 3: Migrate content from memex.pre-gator/
+    src = target / "memex.pre-gator"
+    gator_dir = target / ".gator"
+
+    if src.is_dir():
+        log_step("Migrating content from memex.pre-gator/ into .gator/...")
+
+        # Direct-copy content files
+        for name in ("mission.md", "roadmap.md", "identity.md", "inbox.md",
+                      "issues.md", "commit_draft.md", "whiteboard.md",
+                      "friction.md", "audit-tracker.md"):
+            f = src / name
+            if f.is_file():
+                shutil.copy2(f, gator_dir / name)
+                log_step(f"  Migrated {name}")
+
+        # Patterns
+        if (src / "patterns").is_dir():
+            (gator_dir / "patterns").mkdir(exist_ok=True)
+            copy_tree_overlay(src / "patterns", gator_dir / "patterns")
+            log_step("  Migrated patterns/")
+        elif (src / "patterns.md").is_file():
+            shutil.copy2(src / "patterns.md", gator_dir / "patterns.md")
+            log_step("  Migrated patterns.md")
+
+        # Active threads -> threads/ (demoted)
+        _migrate_md_dir(src / "active-threads", gator_dir / "threads", "active threads -> threads/ (demoted)")
+
+        # Threads -> threads/ (merge)
+        _migrate_md_dir(src / "threads", gator_dir / "threads", "threads")
+
+        # Artifacts
+        _migrate_md_dir(src / "artifacts", gator_dir / "artifacts", "artifacts")
+
+        # Charters (skip templates)
+        if (src / "charters").is_dir():
+            count = 0
+            for f in sorted((src / "charters").glob("*.md")):
+                if f.name in ("_template.md", "README.md"):
+                    continue
+                shutil.copy2(f, gator_dir / "charters" / f.name)
+                count += 1
+            if count:
+                log_step(f"  Migrated {count} charters")
+
+        # Vault
+        if (src / "vault").is_dir() and any((src / "vault").iterdir()):
+            (gator_dir / "vault").mkdir(exist_ok=True)
+            copy_tree_overlay(src / "vault", gator_dir / "vault")
+            log_step("  Migrated vault/")
+
+        # Reference notes (conflict-aware)
+        if (src / "reference-notes").is_dir():
+            rn_count = 0
+            rn_conflict = 0
+            for f in sorted((src / "reference-notes").glob("*.md")):
+                dest = gator_dir / "reference-notes" / f.name
+                if dest.exists():
+                    # Check if different
+                    if f.read_bytes() != dest.read_bytes():
+                        conflict_name = f.stem + "-project.md"
+                        shutil.copy2(f, gator_dir / "reference-notes" / conflict_name)
+                        rn_conflict += 1
+                else:
+                    shutil.copy2(f, dest)
+                    rn_count += 1
+            if rn_count:
+                log_step(f"  Migrated {rn_count} reference notes")
+            if rn_conflict:
+                log_step(f"  Preserved {rn_conflict} conflicting notes with -project suffix")
+
+    # Migrate from .memex.pre-gator/
+    dotsrc = target / ".memex.pre-gator"
+    if dotsrc.is_dir():
+        log_step("Migrating system layer from .memex.pre-gator/...")
+        if (dotsrc / "roles.yaml").is_file():
+            shutil.copy2(dotsrc / "roles.yaml", gator_dir / "roles.yaml")
+            log_step("  Migrated roles.yaml")
+        if (dotsrc / "policies").is_dir():
+            (gator_dir / "policies").mkdir(exist_ok=True)
+            copy_tree_overlay(dotsrc / "policies", gator_dir / "policies")
+            log_step("  Migrated policies/")
+
+    # Step 4: Archive root constitution files
+    if legacy["root_constitution"] and (target / "constitution.md").is_file():
+        _, ok = git("mv", "constitution.md", ".gator/legacy-constitution.md", cwd=target)
+        if not ok:
+            shutil.move(str(target / "constitution.md"),
+                        str(gator_dir / "legacy-constitution.md"))
+        log_step("Archived constitution.md -> .gator/legacy-constitution.md")
+
+    if legacy["root_constitution_core"] and (target / "constitution-core.md").is_file():
+        _, ok = git("mv", "constitution-core.md", ".gator/legacy-constitution-core.md", cwd=target)
+        if not ok:
+            shutil.move(str(target / "constitution-core.md"),
+                        str(gator_dir / "legacy-constitution-core.md"))
+        log_step("Archived constitution-core.md -> .gator/legacy-constitution-core.md")
+
+    # Clean up .gitkeep in dirs that now have content
+    for d in ("threads", "artifacts"):
+        gitkeep = gator_dir / d / ".gitkeep"
+        if gitkeep.exists() and any((gator_dir / d).glob("*.md")):
+            gitkeep.unlink()
+
+    write_gator_version(gator_dir, "morph")
+
+    print()
+    log_step("Morph complete. Pre-gator directories preserved for review:")
+    if legacy["memex"]:
+        log_step("  memex.pre-gator/    — your original content")
+    if legacy["dot_memex"]:
+        log_step("  .memex.pre-gator/   — your original system layer")
+    log_step("Review .gator/, then delete pre-gator dirs when satisfied.")
+
+
+def _migrate_md_dir(src_dir, dest_dir, label):
+    """Migrate .md files from src to dest, handling name collisions."""
+    if not src_dir.is_dir():
+        return
+    count = 0
+    dest_dir.mkdir(exist_ok=True)
+    for f in sorted(src_dir.glob("*.md")):
+        if f.name in ("_TEMPLATE.md", "_template.md"):
+            continue
+        dest = dest_dir / f.name
+        if dest.exists():
+            # Collision — add -legacy suffix
+            dest = dest_dir / (f.stem + "-legacy.md")
+        shutil.copy2(f, dest)
+        count += 1
+    if count:
+        log_step(f"  Migrated {count} {label}")
+
+
+# ── main ───────────────────────────────────────────────────────────────────
+
+def main():
+    ensure_utf8_stdout()
+
+    parser = argparse.ArgumentParser(
+        description="Install Gator governance into a project repo.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("target", help="Target directory to gatorize")
+    args = parser.parse_args()
+
+    target = Path(args.target).resolve()
+
+    # Create directory if it doesn't exist
+    if not target.exists():
+        print()
+        print(f"  Directory does not exist: {target}")
+        if confirm("Create it and gatorize?"):
+            target.mkdir(parents=True)
+        else:
+            print("  Aborted.")
+            sys.exit(0)
+
+    # Self-gatorize guard
+    if target.resolve() == COMMAND_POST.resolve():
+        print("  Error: Target is the command post itself. Gatorize a project repo, not gator-command.")
+        sys.exit(1)
+
+    # Check templates
+    if not TEMPLATES or not TEMPLATES.is_dir():
+        print(f"  Error: Templates not found. Are you running this from the gator repo?")
+        sys.exit(1)
+
+    # Detect scenario
+    scenario = detect_scenario(target)
+
+    print()
+    print("  ================================================================")
+    print(f"  gatorize.py — {target.name}")
+    print("  ================================================================")
+
+    # Detect command post — a bare gator clone is NOT a command post.
+    # Only treat as command post if identity.md has been populated
+    # (bracket placeholders mean it's still a bare clone).
+    cp = find_command_post(str(SCRIPTS_DIR))
+    has_command_post = False
+    if cp:
+        identity = Path(str(cp)) / "gator-command" / "identity.md"
+        if identity.exists():
+            text = identity.read_text(encoding="utf-8", errors="replace")
+            # Populated = no bracket placeholders
+            has_command_post = "[Your name]" not in text and "[Your role]" not in text
+        else:
+            has_command_post = False
+
+    # Dispatch
+    if scenario == 1:
+        print("  Scenario 1: Fresh directory (no git)")
+        print()
+        action_git_init(target)
+        action_install_gator(target)
+    elif scenario == 2:
+        print("  Scenario 2: Git repo, clean")
+        print()
+        action_feature_branch(target)
+        action_install_gator(target)
+    elif scenario == 3:
+        gen = detect_generation(target)
+        print(f"  Gator is already installed (generation {gen}). Running update...")
+        print()
+        result = subprocess.run(
+            [sys.executable, str(SCRIPTS_DIR / "gator-update.py"),
+             "--path", str(target), "--source", str(COMMAND_POST), "--no-policy"],
+            cwd=str(target),
+        )
+        if result.returncode != 0:
+            print()
+            print("  ================================================================")
+            print("  UPDATE FAILED (exit code {})".format(result.returncode))
+            print("  ================================================================")
+            print()
+            sys.exit(result.returncode)
+        # Fall through to common tail — refreshes entry points, outbox, product-source
+    elif scenario == 4:
+        print("  Scenario 4: Legacy memex structure detected")
+        print()
+        action_feature_branch(target)
+        action_morph_memex(target)
+    elif scenario == 5:
+        print("  Scenario 5: Both memex and gator found")
+        print()
+        legacy = detect_legacy_memex(target)
+        print("  Legacy memex:")
+        if legacy["memex"]:
+            print("    memex/")
+        if legacy["dot_memex"]:
+            print("    .memex/")
+        if legacy["root_constitution"]:
+            print("    constitution.md (root)")
+        print("  Gator:")
+        print("    .gator/")
+        print()
+        print("  Options:")
+        print("    [m] Morph — fold memex content into existing .gator/ (recommended)")
+        print("    [u] Upgrade — refresh .gator/ templates, ignore memex dirs")
+        print("    [x] Cancel")
+        print()
+        choice = prompt("Choice", "m/u/x")
+        if choice.lower() == "m":
+            action_feature_branch(target)
+            action_morph_memex(target)
+        elif choice.lower() == "u":
+            gen = detect_generation(target)
+            print(f"  Running update (generation {gen})...")
+            result = subprocess.run(
+                [sys.executable, str(SCRIPTS_DIR / "gator-update.py"),
+                 "--path", str(target), "--source", str(COMMAND_POST), "--no-policy"],
+                cwd=str(target),
+            )
+            if result.returncode != 0:
+                print()
+                print("  ================================================================")
+                print("  UPDATE FAILED (exit code {})".format(result.returncode))
+                print("  ================================================================")
+                print()
+                sys.exit(result.returncode)
+            # Fall through to common tail
+        else:
+            print("  Cancelled.")
+            sys.exit(0)
+
+    # Common tail (all scenarios except cancel/failure)
+    ensure_repo_gitignore(target)
+    if has_command_post:
+        action_install_thin_link(target)
+    action_install_entry_points(target, has_command_post)
+    action_install_outbox(target)
+    action_install_product_source(target)
+    action_register(target)
+    print_summary(target, scenario, has_command_post)
+
+
+if __name__ == "__main__":
+    main()