gator-command 1.0.0__py3-none-any.whl

gator_command/scripts/gator-deploy.py

@@ -0,0 +1,916 @@
+#!/usr/bin/env python3
+"""
+gator-deploy.py - Deploy the public Gator 1.0 repo as a blank command post.
+
+Produces a working command post with:
+  gator-engine/    - product code (scripts, templates, docs, tests)
+  gator-command/   - blank knowledge layer (stubs, empty dirs)
+  .gator/          - self-governance (hooks, constitution, stub charters)
+  README.md        - short, links to docs/
+
+The structural separation means users can update product code via
+`git fetch upstream && git checkout upstream/main -- gator-engine/`
+without touching their content in gator-command/.
+
+Usage:
+    python src/gator_command/scripts/gator-deploy.py ../gator
+    python src/gator_command/scripts/gator-deploy.py ../gator --dry-run
+"""
+
+from __future__ import annotations
+
+import argparse
+import io
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+
+# Preserved across deploys — never deleted by remove_target_contents().
+# gator-command/ is user-owned knowledge; .gator/ has user charters and content.
+PRESERVE = {".git", "LICENSE", "gator-command", ".gator"}
+
+PUBLIC_PROCEDURES = [
+    "branching-standard.md",
+    "charter-lookup.md",
+    "coding-standard.md",
+    "knowledge-capture.md",
+    "gatorize-permutations.md",
+    "session-schema.md",
+    "thin-link-spec.md",
+]
+
+DOC_STUBS = {}  # Real docs now live in docs/ at repo root
+
+COMMAND_POST_STUBS = {
+    "mission.md": (
+        "# Mission\n\n## What We're Building\n\n"
+        "[What is this project? One paragraph.]\n\n"
+        "## Why It Exists\n\n[What problem does it solve?]\n"
+    ),
+    "roadmap.md": (
+        "# Roadmap\n\n[Priority-ordered. Updated as items complete or priorities shift.]\n\n"
+        "**Status key**: Done · Building · Designed · Considering · Deferred\n"
+    ),
+    "inbox.md": (
+        "# Inbox\n\nDrop anything here. No formatting needed. "
+        "The chat agent triages at session open.\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\n"
+        "## Background\n\n[Brief background]\n"
+    ),
+    "issues.md": (
+        "# Issues\n\nActive bugs, blockers, and known fragilities. "
+        "Checked at session open.\n\n**Status key**: Open · Working · Resolved\n\n---\n\n"
+    ),
+    "registry.md": (
+        "# Registry\n\nRepos 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"
+    ),
+    "commit_draft.md": (
+        "---\nmessage: \"\"\nchange-type:\nsignificance:\ndecision-tags: []\n"
+        "agent:\narchitect:\n---\n\n# Session Change Log\n\n"
+    ),
+}
+
+COMMAND_POST_DIRS = [
+    "active-threads",
+    "threads",
+    "artifacts",
+    "vault",
+    "patterns",
+    "policies",
+]
+
+SELF_GOVERNANCE_STUBS = {
+    "commit_draft.md": (
+        "---\nmessage: \"\"\nchange-type:\nsignificance:\ndecision-tags: []\n"
+        "agent:\narchitect:\n---\n\n# Session Change Log\n\n"
+    ),
+    "whiteboard.md": "# Whiteboard\n\nNo findings.\n",
+    "issues.md": "# Issues\n\n---\n\n",
+    "mission.md": (
+        "# Mission\n\n"
+        "This Gator Command post governs AI-assisted development across "
+        "a fleet of project repos.\n\n"
+        "See `gator-command/mission.md` for your project-specific mission "
+        "once populated during the concierge bootstrap.\n"
+    ),
+    "command-post.md": (
+        "command-post: ..\nversion: 2026-05-30\n\n# Gator Command Post\n\n"
+        "This repo is the command post.\n"
+    ),
+}
+
+SELF_GOVERNANCE_DIRS = ["threads", "artifacts", "sessions", "blueprints"]
+
+ENTRY_POINTS = [
+    ("CLAUDE.md", "# Claude Code Entry Point"),
+    ("AGENTS.md", "# Codex Entry Point"),
+    ("GEMINI.md", "# Gemini Entry Point"),
+]
+
+ENTRY_BODY = (
+    "\nThis is a **Gator Command post**.\n\n"
+    "Read [`constitution.md`](constitution.md) before your first response.\n\n"
+    "**Fresh instance detection**: If `gator-command/identity.md` still has bracket "
+    "placeholders (e.g., `[Your name]`), this is a first session. Greet the Architect and "
+    "ask what they're working on.\n\n"
+    "**Returning sessions**: Follow the session-opening procedure in the constitution.\n\n"
+    '**"gator init"**: run `python gator-engine/scripts/gator-init-command-post.py` '
+    "and display the output exactly as printed. This is the command post boot sequence.\n\n"
+    '**"gator dashboard"**: run `python gator-engine/scripts/gator-dashboard.py` '
+    "to open the governance dashboard in your browser.\n"
+)
+
+ROOT_GITIGNORE = (
+    "# Vault — sensitive material and large files that must not be committed\n"
+    "gator-command/vault/\n"
+    ".gator/vault/\n"
+    "\n"
+    "__pycache__/\n"
+    "*.pyc\n"
+    ".pytest_tmp/\n"
+    ".pytest_cache/\n"
+    ".vscode/\n"
+    ".claude/settings.local.json\n"
+    "\n"
+    "# Ephemeral commit artifacts — reset by hooks\n"
+    ".gator/commit_draft.md\n"
+    ".gator/commit_issues.md\n"
+    "gator-command/commit_draft.md\n"
+    "\n"
+    "# Override request/approval artifacts — ephemeral\n"
+    ".gator/override-request.json\n"
+    ".gator/override-approved.json\n"
+    "\n"
+    "# Rolling active session logs\n"
+    ".gator/sessions/_active/\n"
+    "\n"
+    "# Machine-local state (not portable)\n"
+    ".gator/product-source.json\n"
+)
+
+
+def find_command_post():
+    """Find the source command post root."""
+    script_dir = Path(__file__).resolve().parent
+    # Scripts are now at src/gator_command/scripts/ — repo root is 3 levels up
+    candidate = script_dir.parent.parent.parent
+    if (candidate / "gator-command" / "mission.md").exists():
+        return candidate
+    # Fallback: try 2 levels up (old layout or deployed gator-engine/)
+    candidate = script_dir.parent.parent
+    if (candidate / "gator-command" / "mission.md").exists():
+        return candidate
+    return None
+
+
+def get_source_version(source):
+    """Get version string from source repo via git describe.
+
+    Returns a string like 'v1.0.0-5-gabcdef1' between tags, or 'v1.0.0'
+    on an exact tag. Falls back to VERSION file content, then 'dev'.
+    """
+    try:
+        result = subprocess.run(
+            ["git", "describe", "--tags", "--always"],
+            capture_output=True, encoding="utf-8", errors="replace", cwd=source, timeout=5,
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            version = result.stdout.strip()
+            if version.startswith("v"):
+                return version
+    except (OSError, subprocess.TimeoutExpired):
+        pass
+
+    version_file = source / "VERSION"
+    if version_file.exists():
+        text = version_file.read_text(encoding="utf-8").strip()
+        if text:
+            return f"v{text}" if not text.startswith("v") else text
+
+    return "dev"
+
+
+def get_source_short_hash(source):
+    """Get the short commit hash of the source repo HEAD."""
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--short", "HEAD"],
+            capture_output=True, encoding="utf-8", errors="replace", cwd=source, timeout=5,
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            return result.stdout.strip()
+    except (OSError, subprocess.TimeoutExpired):
+        pass
+    return None
+
+
+def stamp_readme_version(target, version, source_hash=None):
+    """Replace the static version in README.md with the deploy version and source hash."""
+    readme = target / "README.md"
+    if not readme.exists():
+        return
+    text = readme.read_text(encoding="utf-8")
+
+    # Build the replacement: "v1.0.0 (b8b1542)  ·  navigation..." or just version
+    version_stamp = version
+    if source_hash:
+        version_stamp = f"{version} ({source_hash})"
+
+    # Match the version line in the ASCII banner: "  v1.0.0  ·  ..." or "  v1.0.0 (hash)  ·  ..."
+    text = re.sub(
+        r"^(  )v[\d]+\.[\d]+\.[\d]+\S*(?:\s+\([a-f0-9]+\))?(  ·  .*)$",
+        rf"\g<1>{version_stamp}\g<2>",
+        text,
+        count=1,
+        flags=re.MULTILINE,
+    )
+    readme.write_text(text, encoding="utf-8")
+
+
+def remove_target_contents(target, dry_run=False):
+    """Remove everything except files explicitly preserved."""
+    removed = []
+    for item in sorted(target.iterdir()):
+        if item.name in PRESERVE:
+            continue
+        if item.is_dir():
+            if not dry_run:
+                shutil.rmtree(item)
+            removed.append(f"{item.name}/")
+        else:
+            if not dry_run:
+                item.unlink()
+            removed.append(item.name)
+    return removed
+
+
+def write_file(path, content, dry_run=False):
+    """Write a file, creating parent dirs."""
+    if dry_run:
+        return
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+
+
+def copy_file(src, dest, dry_run=False):
+    """Copy a file, creating parent dirs."""
+    if dry_run:
+        return
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copy2(src, dest)
+
+
+def copy_tree_mirror(src, dest, dry_run=False):
+    """Mirror a directory tree — exact copy, prune stale destination files.
+
+    Used for product-owned directories (gator-engine/, docs/, .github/)
+    where the deploy output should exactly match the source.
+    """
+    if dry_run:
+        return
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    if dest.exists():
+        shutil.rmtree(dest)
+    shutil.copytree(
+        src, dest,
+        ignore=shutil.ignore_patterns("__pycache__", "*.pyc"),
+    )
+
+
+def copy_tree_overlay(src, dest, dry_run=False):
+    """Overlay a directory tree — update same-named files, preserve extras.
+
+    Used for user-owned directories (gator-command/procedures/,
+    reference-notes/) where user-authored content must survive deploys.
+    """
+    if dry_run:
+        return
+    dest.mkdir(parents=True, exist_ok=True)
+    for item in 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, dry_run)
+        else:
+            shutil.copy2(item, target)
+
+
+def write_stub_files(base_dir, files, dry_run=False):
+    """Write a mapping of relative paths to file contents.
+
+    Only creates files that don't already exist — user-owned content
+    is never overwritten. This is the deploy equivalent of gatorize.sh's
+    overlay-not-replace principle.
+    """
+    for relative_path, content in files.items():
+        dest = base_dir / relative_path
+        if dest.exists():
+            continue
+        write_file(dest, content, dry_run)
+
+
+def ensure_gitkeep_dirs(base_dir, dir_names, dry_run=False):
+    """Create empty directories tracked with .gitkeep."""
+    for dirname in dir_names:
+        path = base_dir / dirname
+        if dry_run:
+            continue
+        path.mkdir(parents=True, exist_ok=True)
+        (path / ".gitkeep").touch()
+
+
+def copy_matching_files(src_dir, dest_dir, suffixes, results, result_prefix, dry_run=False):
+    """Copy files from a directory when their suffix matches."""
+    if not dry_run:
+        dest_dir.mkdir(parents=True, exist_ok=True)
+
+    for src in sorted(src_dir.iterdir()):
+        if src.is_file() and src.suffix in suffixes:
+            copy_file(src, dest_dir / src.name, dry_run)
+            results["created"].append(f"{result_prefix}/{src.name}")
+
+
+def copy_optional_tree(src_dir, dest_dir, results, result_label, dry_run=False,
+                       overlay=False):
+    """Copy a directory if it exists and record a concise result label.
+
+    overlay=False (default): mirror mode — exact copy, prune stale files.
+        Use for product-owned directories.
+    overlay=True: overlay mode — update same-named, preserve extras.
+        Use for user-owned directories.
+    """
+    if not src_dir.is_dir():
+        return
+    if overlay:
+        copy_tree_overlay(src_dir, dest_dir, dry_run)
+    else:
+        copy_tree_mirror(src_dir, dest_dir, dry_run)
+    count = sum(1 for item in src_dir.rglob("*") if item.is_file())
+    results["created"].append(f"{result_label} ({count} files)")
+
+
+def copy_optional_file(src, dest, results, result_label, dry_run=False):
+    """Copy a file if it exists and record the destination label."""
+    if not src.exists():
+        return
+    copy_file(src, dest, dry_run)
+    results["created"].append(result_label)
+
+
+def _fixup_test_paths(tests_dir, dry_run=False):
+    """Rewrite path references in test files for the deployed layout.
+
+    In the command-post layout, tests/ is a sibling of gator-command/scripts/.
+    In the deployed layout, tests live at gator-engine/tests/ and scripts at
+    gator-engine/scripts/. This function patches conftest.py and
+    test_pre_commit.py so imports resolve correctly after deploy.
+    """
+    if dry_run:
+        return
+
+    # conftest.py: SCRIPTS_DIR should resolve to gator-engine/scripts/
+    # (parent.parent / "scripts" from gator-engine/tests/)
+    conftest = tests_dir / "conftest.py"
+    if conftest.is_file():
+        text = conftest.read_text(encoding="utf-8")
+        # Replace any gator-command/scripts path with the deployed relative path
+        text = text.replace(
+            'Path(__file__).parent.parent / "src" / "gator_command" / "scripts"',
+            'Path(__file__).resolve().parent.parent / "scripts"',
+        )
+        conftest.write_text(text, encoding="utf-8")
+
+    # test_pre_commit.py: pre-commit hook lives at repo-root/.gator/scripts/
+    # (parent.parent.parent from gator-engine/tests/)
+    test_pc = tests_dir / "test_pre_commit.py"
+    if test_pc.is_file():
+        text = test_pc.read_text(encoding="utf-8")
+        text = text.replace(
+            'Path(__file__).parent.parent / ".gator" / "scripts"',
+            'Path(__file__).resolve().parent.parent.parent / ".gator" / "scripts"',
+        )
+        test_pc.write_text(text, encoding="utf-8")
+
+
+def build_engine(source, target, results, dry_run=False):
+    """Build gator-engine/, the shipped product surface."""
+    pkg = source / "src" / "gator_command"
+    engine = target / "gator-engine"
+
+    copy_matching_files(
+        pkg / "scripts",
+        engine / "scripts",
+        {".py", ".sh"},
+        results,
+        "gator-engine/scripts",
+        dry_run,
+    )
+
+    copy_optional_tree(
+        pkg / "scripts" / "dashboard",
+        engine / "scripts" / "dashboard",
+        results,
+        "gator-engine/scripts/dashboard/",
+        dry_run,
+    )
+    copy_optional_tree(
+        pkg / "templates" / "gator-starter",
+        engine / "templates" / "gator-starter",
+        results,
+        "gator-engine/templates/gator-starter/",
+        dry_run,
+    )
+    copy_optional_tree(
+        source / "tests",
+        engine / "tests",
+        results,
+        "gator-engine/tests/",
+        dry_run,
+    )
+    _fixup_test_paths(engine / "tests", dry_run)
+
+    docs_dest = engine / "docs"
+    gc = source / "gator-command"  # knowledge layer (didn't move)
+    copy_optional_file(
+        gc / "charters" / "README.md",
+        docs_dest / "charter-philosophy.md",
+        results,
+        "gator-engine/docs/charter-philosophy.md",
+        dry_run,
+    )
+    copy_optional_file(
+        gc / "org-policy.md",
+        docs_dest / "org-policy-example.md",
+        results,
+        "gator-engine/docs/org-policy-example.md",
+        dry_run,
+    )
+
+    for name in PUBLIC_PROCEDURES:
+        copy_optional_file(
+            gc / "procedures" / name,
+            docs_dest / "procedures" / name,
+            results,
+            f"gator-engine/docs/procedures/{name}",
+            dry_run,
+        )
+
+    write_stub_files(docs_dest, DOC_STUBS, dry_run)
+    results["created"].extend(
+        f"gator-engine/docs/{name}" for name in DOC_STUBS
+    )
+
+    copy_optional_file(
+        source / "pytest.ini",
+        engine / "pytest.ini",
+        results,
+        "gator-engine/pytest.ini",
+        dry_run,
+    )
+
+
+def build_command_post_layer(source, target, results, dry_run=False):
+    """Build gator-command/, the blank user-owned knowledge layer."""
+    gc = source / "gator-command"
+    dest = target / "gator-command"
+
+    write_stub_files(dest, COMMAND_POST_STUBS, dry_run)
+    results["created"].append("gator-command/ (knowledge layer stubs)")
+
+    copy_optional_file(
+        gc / "org-policy.md",
+        dest / "org-policy.md",
+        results,
+        "gator-command/org-policy.md",
+        dry_run,
+    )
+
+    ensure_gitkeep_dirs(dest, COMMAND_POST_DIRS, dry_run)
+
+    for subdir in ("procedures", "reference-notes"):
+        copy_optional_tree(
+            gc / subdir,
+            dest / subdir,
+            results,
+            f"gator-command/{subdir}/",
+            dry_run,
+            overlay=True,  # user-owned: preserve extras
+        )
+
+    write_file(
+        dest / "scripts" / "README.md",
+        "# Scripts\n\nProduct scripts live in `gator-engine/scripts/`.\n\n"
+        "This directory is for command-post-specific scripts you create.\n",
+        dry_run,
+    )
+    write_file(
+        dest / "templates" / "README.md",
+        "# Templates\n\nThe gator-starter template lives in "
+        "`gator-engine/templates/gator-starter/`.\n",
+        dry_run,
+    )
+
+
+def copy_template_scripts(starter_scripts, dest_scripts, dry_run=False):
+    """Copy template scripts, including nested hook directories."""
+    if not starter_scripts.is_dir():
+        return
+
+    for src in sorted(starter_scripts.iterdir()):
+        if src.name == "__pycache__":
+            continue
+        if src.is_file():
+            if src.suffix == ".pyc":
+                continue
+            copy_file(src, dest_scripts / src.name, dry_run)
+            continue
+        for nested in sorted(src.iterdir()):
+            if nested.is_file() and nested.suffix != ".pyc":
+                copy_file(nested, dest_scripts / src.name / nested.name, dry_run)
+
+
+def copy_flat_directory(src_dir, dest_dir, dry_run=False):
+    """Copy only direct child files from one directory to another."""
+    if not src_dir.is_dir():
+        return
+    for src in sorted(src_dir.iterdir()):
+        if src.is_file():
+            copy_file(src, dest_dir / src.name, dry_run)
+
+
+def build_self_governance(source, target, results, dry_run=False):
+    """Build .gator/, the repo's own governance scaffolding."""
+    starter = source / "src" / "gator_command" / "templates" / "gator-starter"
+    dest = target / ".gator"
+
+    copy_optional_file(
+        starter / "constitution.md",
+        dest / "constitution.md",
+        results,
+        ".gator/constitution.md",
+        dry_run,
+    )
+    copy_optional_file(
+        starter / "gator-start-up.md",
+        dest / "gator-start-up.md",
+        results,
+        ".gator/gator-start-up.md",
+        dry_run,
+    )
+
+    for name in ("README.md", "_template.md"):
+        copy_optional_file(
+            starter / "charters" / name,
+            dest / "charters" / name,
+            results,
+            f".gator/charters/{name}",
+            dry_run,
+        )
+    index_path = dest / "charters" / "INDEX.md"
+    if not index_path.exists():
+        write_file(
+            index_path,
+            "# Charter Index\n\n| If you're changing... | Read these charters |\n"
+            "|---|---|\n| | |\n",
+            dry_run,
+        )
+
+    copy_template_scripts(starter / "scripts", dest / "scripts", dry_run)
+
+    for subdir in ("reference-notes", "procedures"):
+        copy_flat_directory(starter / subdir, dest / subdir, dry_run)
+
+    write_stub_files(dest, SELF_GOVERNANCE_STUBS, dry_run)
+    ensure_gitkeep_dirs(dest, SELF_GOVERNANCE_DIRS, dry_run)
+    results["created"].append(".gator/ (self-governance)")
+
+
+def build_root_files(source, target, results, dry_run=False):
+    """Build repo-root files for the deployed public command post."""
+    starter = source / "src" / "gator_command" / "templates" / "gator-starter"
+
+    copy_optional_file(
+        starter / "constitution.md",
+        target / "constitution.md",
+        results,
+        "constitution.md",
+        dry_run,
+    )
+
+    for filename, header in ENTRY_POINTS:
+        write_file(target / filename, f"{header}\n{ENTRY_BODY}", dry_run)
+        results["created"].append(filename)
+
+    copy_optional_file(
+        source / "gator-command" / "deploy" / "README.md",
+        target / "README.md",
+        results,
+        "README.md",
+        dry_run,
+    )
+
+    # User-facing docs (persona pages, feature docs)
+    copy_optional_tree(
+        source / "docs",
+        target / "docs",
+        results,
+        "docs/",
+        dry_run,
+    )
+
+    copy_optional_file(
+        source / "VERSION",
+        target / "VERSION",
+        results,
+        "VERSION",
+        dry_run,
+    )
+    copy_optional_file(
+        source / "mkdocs.yml",
+        target / "mkdocs.yml",
+        results,
+        "mkdocs.yml",
+        dry_run,
+    )
+    copy_optional_file(
+        source / "CHANGELOG.md",
+        target / "CHANGELOG.md",
+        results,
+        "CHANGELOG.md",
+        dry_run,
+    )
+
+    copy_optional_file(
+        source / "CONTRIBUTING.md",
+        target / "CONTRIBUTING.md",
+        results,
+        "CONTRIBUTING.md",
+        dry_run,
+    )
+    copy_optional_file(
+        source / "SECURITY.md",
+        target / "SECURITY.md",
+        results,
+        "SECURITY.md",
+        dry_run,
+    )
+    copy_optional_tree(
+        source / ".github",
+        target / ".github",
+        results,
+        ".github/",
+        dry_run,
+    )
+
+    write_file(target / ".gitignore", ROOT_GITIGNORE, dry_run)
+    results["created"].append(".gitignore")
+
+
+def find_last_deploy_source_hash(target):
+    """Find the source repo hash from the most recent deploy commit in the target.
+
+    Looks for "From gator-command <hash>" in recent commit messages.
+    Returns the hash string, or None if not found.
+    """
+    try:
+        result = subprocess.run(
+            ["git", "log", "--format=%B", "-20"],
+            capture_output=True, encoding="utf-8", errors="replace", cwd=target, timeout=5,
+        )
+        if result.returncode != 0:
+            return None
+        for line in result.stdout.splitlines():
+            line = line.strip().lstrip("- ")
+            # Match both "From gator-command <hash>" and "Deploy from gator-command <hash> (...)"
+            if "from gator-command" in line.lower():
+                parts = line.split()
+                # Find the token after "gator-command"
+                for i, token in enumerate(parts):
+                    if token == "gator-command" and i + 1 < len(parts):
+                        return parts[i + 1].rstrip(":").split("(")[0].strip()
+                        break
+    except (OSError, subprocess.TimeoutExpired):
+        pass
+    return None
+
+
+def build_deploy_changelog(source, target):
+    """Build a changelog from source repo commits since the last deploy.
+
+    Returns a list of one-line commit summaries, newest first.
+    """
+    base_hash = find_last_deploy_source_hash(target)
+    if not base_hash:
+        # No previous deploy found — use last 10 commits as context
+        log_range = ["-10"]
+    else:
+        log_range = [f"{base_hash}..HEAD"]
+
+    try:
+        result = subprocess.run(
+            ["git", "log", "--oneline", "--no-decorate"] + log_range,
+            capture_output=True, encoding="utf-8", errors="replace", cwd=source, timeout=10,
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            return result.stdout.strip().splitlines()
+    except (OSError, subprocess.TimeoutExpired):
+        pass
+    return []
+
+
+def write_deploy_commit_draft(target, source, version, dry_run=False):
+    """Write the target repo's commit_draft.md with the deploy changelog.
+
+    Populates the frontmatter and body so the deploy commit carries
+    the full source changelog, not just "deploy from hash."
+    """
+    if dry_run:
+        return
+
+    changelog = build_deploy_changelog(source, target)
+
+    # Get the current source HEAD for the "From" reference
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--short", "HEAD"],
+            capture_output=True, encoding="utf-8", errors="replace", cwd=source, timeout=5,
+        )
+        source_hash = result.stdout.strip() if result.returncode == 0 else "unknown"
+    except (OSError, subprocess.TimeoutExpired):
+        source_hash = "unknown"
+
+    # Build the body
+    body_lines = [f"- Deploy from gator-command {source_hash} ({version})"]
+    for line in changelog:
+        # Each line is "hash summary" — prefix with bullet
+        parts = line.split(" ", 1)
+        if len(parts) == 2:
+            body_lines.append(f"- {parts[1]}")
+        else:
+            body_lines.append(f"- {line}")
+
+    body = "\n".join(body_lines)
+
+    # Summarize for the message field — use first changelog entry as description
+    if changelog:
+        # Each changelog line is "hash summary" — extract the summary part
+        first = changelog[0].split(" ", 1)
+        summary = first[1] if len(first) == 2 else changelog[0]
+        # Strip redundant "Deploy:" prefix to avoid "Deploy v1.0.0: Deploy: ..."
+        if summary.lower().startswith("deploy:"):
+            summary = summary[7:].strip()
+        elif summary.lower().startswith("deploy "):
+            summary = summary[7:].strip()
+        if len(changelog) == 1:
+            message = f"Deploy {version}: {summary}"
+        else:
+            message = f"Deploy {version}: {summary} (+{len(changelog) - 1} more)"
+    else:
+        message = f"Deploy {version} from gator-command {source_hash}"
+
+    draft = (
+        f"---\n"
+        f'message: "{message}"\n'
+        f"change-type: deploy\n"
+        f"significance: routine\n"
+        f"decision-tags: [deploy]\n"
+        f"agent:\n"
+        f"architect:\n"
+        f"---\n\n"
+        f"# Session Change Log\n\n"
+        f"{body}\n"
+    )
+
+    draft_path = target / ".gator" / "commit_draft.md"
+    draft_path.parent.mkdir(parents=True, exist_ok=True)
+    draft_path.write_text(draft, encoding="utf-8")
+
+
+def deploy(source, target, dry_run=False):
+    """Build the complete public repo structure."""
+    results = {"nuked": remove_target_contents(target, dry_run), "created": []}
+    build_engine(source, target, results, dry_run)
+    build_command_post_layer(source, target, results, dry_run)
+    build_self_governance(source, target, results, dry_run)
+    build_root_files(source, target, results, dry_run)
+
+    # Stamp the README with the source repo's git describe version + commit hash
+    version = get_source_version(source)
+    source_hash = get_source_short_hash(source)
+    if not dry_run:
+        stamp_readme_version(target, version, source_hash)
+
+    # Write the deploy commit_draft in the target with source changelog
+    write_deploy_commit_draft(target, source, version, dry_run)
+
+    # Pre-approve charter-skip override — deploy targets typically have blank
+    # charters, so the pre-commit hook would always block on code changes.
+    if not dry_run:
+        override_file = target / ".gator" / ".override"
+        override_file.write_text("charter-skip", encoding="utf-8")
+
+    return results
+
+
+def target_looks_initialized(target):
+    """Detect whether the target appears to contain real command-post content."""
+    identity = target / "gator-command" / "identity.md"
+    threads_dir = target / "gator-command" / "active-threads"
+    if not identity.exists():
+        return False
+
+    text = identity.read_text(encoding="utf-8", errors="replace")
+    if "[Your name]" in text:
+        return False
+
+    if not threads_dir.is_dir():
+        return True
+
+    for entry in threads_dir.iterdir():
+        if entry.name != ".gitkeep":
+            return True
+    return False
+
+
+def print_report(results, dry_run=False):
+    """Render a concise deployment summary."""
+    if sys.stdout.encoding != "utf-8":
+        sys.stdout = io.TextIOWrapper(
+            sys.stdout.buffer,
+            encoding="utf-8",
+            errors="replace",
+        )
+
+    mode = " (dry run)" if dry_run else ""
+    print(f"\n  gator deploy{mode}\n")
+
+    if results["nuked"]:
+        print(f"  Cleaned ({len(results['nuked'])}):")
+        for path in results["nuked"]:
+            print(f"    x {path}")
+        print()
+
+    print(f"  Created ({len(results['created'])}):")
+    for path in results["created"]:
+        print(f"    + {path}")
+    print()
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Deploy Gator 1.0 as a blank command post."
+    )
+    parser.add_argument("target", help="Path to the public gator repo")
+    parser.add_argument("--dry-run", "-n", action="store_true")
+    parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Allow deploying into a target that appears to contain real command-post content.",
+    )
+    args = parser.parse_args()
+
+    source = find_command_post()
+    if not source:
+        print("  Error: not in a gator-command repo.", file=sys.stderr)
+        sys.exit(1)
+
+    target = Path(args.target).resolve()
+    if not target.is_dir():
+        print(f"  Error: target does not exist: {target}", file=sys.stderr)
+        sys.exit(1)
+
+    if target_looks_initialized(target) and not args.force:
+        print("  Error: target appears to be an active command post with real content.", file=sys.stderr)
+        print("  Use --force to override.", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"  Source: {source}")
+    print(f"  Target: {target}")
+
+    results = deploy(source, target, dry_run=args.dry_run)
+    print_report(results, dry_run=args.dry_run)
+
+    if not args.dry_run:
+        print("  Structure:")
+        print("    gator-engine/    <- product code (refreshed each deploy)")
+        print("    gator-command/   <- your knowledge layer (preserved, stubs only if missing)")
+        print("    .gator/          <- self-governance (scripts refreshed, content preserved)")
+        print()
+        print("  Next: cd target && git add -A && git commit")
+        print()
+
+
+if __name__ == "__main__":
+    main()