gator-command 1.0.0__py3-none-any.whl

gator_command/scripts/gatorize-actions.sh

@@ -0,0 +1,989 @@
+#!/usr/bin/env bash
+# gatorize-actions.sh — Scenario action functions for gatorize.sh
+#
+# Sourced by gatorize.sh. Not a standalone script.
+# Requires: gatorize-lib.sh (for log_step, confirm, detect_*, write_gator_version, etc.)
+# Requires: TEMPLATES, GATOR_BRANCH, GATOR_GEN, TODAY (set by gatorize.sh)
+#
+# Contains: git init, feature branch, hook installation, fresh install,
+# stub writing, upgrade, morph, dual-structure handling.
+
+# =============================================================================
+# Action: Git Init (Scenario 1)
+# =============================================================================
+
+action_git_init() {
+    local target="$1"
+    log_blank
+    echo "  No git repository found in $target."
+    echo "  Gator requires git — the entire governance model depends on commit history,"
+    echo "  branching, and audit trails. Gator cannot function without it."
+    log_blank
+
+    if ! confirm "Initialize a git repo now?" "Y"; then
+        echo "  Aborted. Initialize a git repo in $target and re-run gatorize.sh."
+        exit 1
+    fi
+
+    # Preflight: check git identity
+    local git_user git_email
+    git_user=$(git config user.name 2>/dev/null || true)
+    git_email=$(git config user.email 2>/dev/null || true)
+    if [ -z "$git_user" ] || [ -z "$git_email" ]; then
+        log_blank
+        echo "  Git identity not configured. Git requires user.name and user.email to commit."
+        echo "  Run these commands first, then re-run gatorize.sh:"
+        log_blank
+        echo "    git config --global user.name \"Your Name\""
+        echo "    git config --global user.email \"you@example.com\""
+        log_blank
+        exit 1
+    fi
+
+    (
+        cd "$target"
+        git init
+        local default_branch
+        default_branch=$(git branch --show-current 2>/dev/null || echo "master")
+        if [ "$default_branch" != "main" ]; then
+            git branch -M main 2>/dev/null || true
+        fi
+        # Check for files beyond .git itself
+        if [ -n "$(ls -A 2>/dev/null | grep -v '^\.git$')" ]; then
+            git add -A
+            git commit -m "Initial commit (pre-Gator)"
+        else
+            git commit --allow-empty -m "Initial commit (pre-Gator)"
+        fi
+        git branch dev
+        git checkout -b "$GATOR_BRANCH"
+    )
+    log_blank
+    log_step "Git initialized. Branches: main, dev, $GATOR_BRANCH (current)."
+}
+
+# =============================================================================
+# Action: Feature Branch (mandatory for all git scenarios)
+# =============================================================================
+
+action_feature_branch() {
+    local target="$1"
+
+    # Check for uncommitted changes
+    local dirty current_branch
+    dirty=$(cd "$target" && git status --porcelain 2>/dev/null | head -1)
+    current_branch=$(cd "$target" && git branch --show-current 2>/dev/null)
+
+    if [ -n "$dirty" ]; then
+        log_blank
+        echo "  Warning: uncommitted changes detected in $target."
+        echo "  Strongly recommend committing or stashing before gatorizing."
+        log_blank
+        echo "  Options:"
+        echo "    [c] Continue anyway (changes will mix with Gator install)"
+        echo "    [a] Abort — commit your changes first, then re-run"
+        log_blank
+        read -rp "  Choice [c/a]: " dirty_choice
+        if [[ "$dirty_choice" =~ ^[Aa]$ ]]; then
+            echo "  Aborted. Commit your changes and re-run gatorize.sh."
+            exit 0
+        fi
+    fi
+
+    # Handle existing gator-install branch BEFORE branch selection
+    if (cd "$target" && git rev-parse --verify "$GATOR_BRANCH" >/dev/null 2>&1); then
+        log_blank
+        echo "  Branch '$GATOR_BRANCH' already exists (prior install attempt?)."
+        log_blank
+        echo "    [1] Delete and start fresh (recommended)"
+        echo "    [2] Continue on existing branch"
+        echo "    [x] Cancel installation"
+        log_blank
+        read -rp "  Choice [1/2/x]: " branch_choice
+        case "$branch_choice" in
+            1)
+                (cd "$target" && git checkout dev 2>/dev/null || git checkout main 2>/dev/null)
+                (cd "$target" && git branch -D "$GATOR_BRANCH" 2>/dev/null)
+                log_step "Deleted old '$GATOR_BRANCH' branch."
+                ;;
+            [xX])
+                echo "  Installation cancelled."
+                exit 0
+                ;;
+            *)
+                log_step "Continuing on existing '$GATOR_BRANCH' branch."
+                ;;
+        esac
+    fi
+
+    log_blank
+    echo "  Gator installs on a feature branch ('$GATOR_BRANCH') for safety."
+    echo "  This keeps the install reversible — delete the branch if anything goes wrong,"
+    echo "  merge to dev when you're happy."
+    log_blank
+
+    # Get list of local branches (excluding gator-install itself)
+    local branches=()
+    while IFS= read -r branch; do
+        branch="${branch#\* }"   # strip the * from current branch
+        branch="${branch#"${branch%%[! ]*}"}"  # strip ALL leading spaces
+        [ "$branch" = "$GATOR_BRANCH" ] && continue  # don't list gator-install as a source
+        branches+=("$branch")
+    done < <(cd "$target" && git branch 2>/dev/null)
+
+    if [ ${#branches[@]} -eq 0 ]; then
+        log_step "No branches found (empty repo?). Installing on current state."
+        (
+            cd "$target"
+            git checkout -b "$GATOR_BRANCH" 2>/dev/null || git checkout "$GATOR_BRANCH"
+        )
+        return
+    fi
+
+    local source_branch=""
+
+    if [ ${#branches[@]} -eq 1 ]; then
+        source_branch="${branches[0]}"
+        echo "  Only one branch available: $source_branch"
+        echo "  '$GATOR_BRANCH' will branch from '$source_branch'."
+        log_blank
+        if ! confirm "Proceed?" "Y"; then
+            echo "  Aborted."
+            exit 0
+        fi
+    else
+        echo "  Available branches:"
+        log_blank
+        for i in "${!branches[@]}"; do
+            local marker="  "
+            if [ "${branches[$i]}" = "$current_branch" ]; then
+                marker="* "
+            fi
+            echo "    [$((i+1))] ${marker}${branches[$i]}"
+        done
+        log_blank
+        read -rp "  Which branch should '$GATOR_BRANCH' branch from? [1-${#branches[@]}]: " source_choice
+
+        if [[ "$source_choice" =~ ^[0-9]+$ ]] && [ "$source_choice" -ge 1 ] && [ "$source_choice" -le ${#branches[@]} ]; then
+            source_branch="${branches[$((source_choice-1))]}"
+        else
+            source_branch="$current_branch"
+            echo "  Invalid choice. Branching from '$current_branch'."
+        fi
+    fi
+
+    (
+        cd "$target"
+        git checkout "$source_branch" 2>/dev/null
+        # Ensure dev exists
+        if ! git rev-parse --verify dev >/dev/null 2>&1; then
+            git branch dev 2>/dev/null || true
+            log_step "Created 'dev' branch."
+        fi
+        # Create or switch to gator-install (already handled above if it existed)
+        if git rev-parse --verify "$GATOR_BRANCH" >/dev/null 2>&1; then
+            git checkout "$GATOR_BRANCH"
+        else
+            git checkout -b "$GATOR_BRANCH"
+        fi
+    )
+    log_step "On '$GATOR_BRANCH' (from '$source_branch')."
+}
+
+# =============================================================================
+# Action: Install git hooks (pre-commit + commit-msg)
+# =============================================================================
+
+is_windows_shell() {
+    case "$(uname -s 2>/dev/null)" in
+        MINGW*|MSYS*|CYGWIN*)
+            return 0
+            ;;
+        *)
+            return 1
+            ;;
+    esac
+}
+
+write_windows_hook() {
+    local dest="$1"
+    local hook_name="$2"
+    local py_path
+    py_path=$(python -c "import sys; print(sys.executable.replace('\\\\', '/'))" 2>/dev/null)
+    [ -n "$py_path" ] || return 1
+
+    case "$hook_name" in
+        pre-commit)
+            cat > "$dest" <<EOF
+#!$py_path
+import subprocess
+import sys
+
+raise SystemExit(
+    subprocess.call(["python", ".gator/scripts/gator-pre-commit.py", "--phase", "validate"])
+)
+EOF
+            ;;
+        commit-msg)
+            cat > "$dest" <<EOF
+#!$py_path
+import subprocess
+import sys
+
+raise SystemExit(
+    subprocess.call(["python", ".gator/scripts/gator-pre-commit.py", "--phase", "trailers", *sys.argv[1:]])
+)
+EOF
+            ;;
+        post-commit)
+            cat > "$dest" <<EOF
+#!$py_path
+import subprocess
+
+raise SystemExit(
+    subprocess.call(["python", ".gator/scripts/gator-pre-commit.py", "--phase", "cleanup"])
+)
+EOF
+            ;;
+        *)
+            return 1
+            ;;
+    esac
+
+    chmod +x "$dest"
+}
+
+install_hooks() {
+    local target="$1"
+    local hooks_dir="$target/.git/hooks"
+
+    # Only install if .git exists (it should — we're on a branch)
+    if [ ! -d "$target/.git" ]; then
+        return
+    fi
+
+    mkdir -p "$hooks_dir"
+
+    local installed=0
+    local backed_up=0
+
+    for hook_name in pre-commit commit-msg post-commit; do
+        local src="$TEMPLATES/scripts/hooks/$hook_name"
+        local dest="$hooks_dir/$hook_name"
+
+        [ -f "$src" ] || continue
+
+        if [ -f "$dest" ]; then
+            # Check if it's already a Gator hook (idempotent)
+            if grep -q "Gator" "$dest" 2>/dev/null; then
+                cp "$src" "$dest"
+                chmod +x "$dest"
+                installed=$((installed + 1))
+                continue
+            fi
+
+            # Existing non-Gator hook — back up and replace
+            local backup="$dest.pre-gator"
+            if [ ! -f "$backup" ]; then
+                cp "$dest" "$backup"
+                backed_up=$((backed_up + 1))
+                log_step "Backed up existing $hook_name hook → $hook_name.pre-gator"
+            fi
+        fi
+
+        if is_windows_shell && write_windows_hook "$dest" "$hook_name"; then
+            :
+        else
+            cp "$src" "$dest"
+            chmod +x "$dest"
+        fi
+        installed=$((installed + 1))
+    done
+
+    if [ "$backed_up" -gt 0 ]; then
+        log_step "Git hooks: $installed installed, $backed_up existing hooks backed up"
+        log_step "Your original hooks are preserved as .pre-gator files in .git/hooks/"
+    else
+        log_step "Git hooks installed (pre-commit + commit-msg + post-commit)"
+    fi
+}
+
+# =============================================================================
+# Action: Install .gator/ (fresh, from templates)
+# =============================================================================
+
+action_install_gator() {
+    local target="$1"
+
+    log_step "Installing .gator/ into $target ..."
+
+    # Create directory structure
+    mkdir -p "$target/.gator/charters" "$target/.gator/blueprints" \
+             "$target/.gator/reference-notes" \
+             "$target/.gator/procedures" "$target/.gator/scripts" \
+             "$target/.gator/threads" "$target/.gator/artifacts" \
+             "$target/.gator/vault" "$target/.gator/policies" \
+             "$target/.gator/sessions"
+
+    # Copy constitution, startup guide
+    cp "$TEMPLATES/constitution.md" "$target/.gator/"
+    cp "$TEMPLATES/gator-start-up.md" "$target/.gator/"
+
+    # Copy charters scaffolding
+    cp "$TEMPLATES/charters/README.md" "$target/.gator/charters/"
+    cp "$TEMPLATES/charters/_template.md" "$target/.gator/charters/"
+
+    # Copy blueprints scaffolding
+    cp "$TEMPLATES/blueprints/README.md" "$target/.gator/blueprints/" 2>/dev/null || true
+
+    # Copy reference notes
+    cp "$TEMPLATES/reference-notes/"*.md "$target/.gator/reference-notes/"
+
+    # Copy procedures
+    cp "$TEMPLATES/procedures/"*.md "$target/.gator/procedures/"
+
+    # Copy sessions gitignore (keeps _active/ out of git)
+    if [ -f "$TEMPLATES/sessions/.gitignore" ]; then
+        cp "$TEMPLATES/sessions/.gitignore" "$target/.gator/sessions/"
+    fi
+
+    # Copy scripts (top-level files)
+    cp "$TEMPLATES/scripts/"* "$target/.gator/scripts/" 2>/dev/null || true
+
+    # Copy nested script directories (e.g., scripts/hooks/)
+    for subdir in "$TEMPLATES/scripts/"*/; do
+        [ -d "$subdir" ] || continue
+        local dirname
+        dirname=$(basename "$subdir")
+        mkdir -p "$target/.gator/scripts/$dirname"
+        cp "$subdir"* "$target/.gator/scripts/$dirname/" 2>/dev/null || true
+    done
+
+    # Install slash commands (vendor-neutral source, Claude Code destination)
+    if [ -d "$TEMPLATES/commands" ]; then
+        mkdir -p "$target/.claude/commands"
+        for cmd_file in "$TEMPLATES/commands/"*.md; do
+            [ -f "$cmd_file" ] || continue
+            local cmd_name
+            cmd_name=$(basename "$cmd_file")
+            local cmd_dest="$target/.claude/commands/$cmd_name"
+
+            if [ -f "$cmd_dest" ]; then
+                # Check if it's already a Gator command (idempotent)
+                if grep -qi "gator\|constitution\|charter" "$cmd_dest" 2>/dev/null; then
+                    cp "$cmd_file" "$cmd_dest"
+                    continue
+                fi
+                # Existing non-Gator command — back up
+                local cmd_backup="$cmd_dest.pre-gator"
+                if [ ! -f "$cmd_backup" ]; then
+                    cp "$cmd_dest" "$cmd_backup"
+                    log_step "Backed up existing slash command $cmd_name → $cmd_name.pre-gator"
+                fi
+            fi
+
+            cp "$cmd_file" "$cmd_dest"
+        done
+    fi
+
+    # .gitkeep for empty dirs
+    touch "$target/.gator/threads/.gitkeep"
+    touch "$target/.gator/artifacts/.gitkeep"
+    touch "$target/.gator/vault/.gitkeep"
+
+    # Install git hooks (pre-commit + commit-msg)
+    install_hooks "$target"
+
+    # Write stubs for content files
+    write_stubs "$target"
+
+    # Write version marker
+    write_gator_version "$target" "install"
+}
+
+write_stubs() {
+    local target="$1"
+
+    cat > "$target/.gator/mission.md" << 'STUB'
+# Mission
+
+## What We're Building
+
+[What is this project? One paragraph.]
+
+## Why It Exists
+
+[What problem does it solve? Who is it for?]
+
+## What Success Looks Like
+
+[How do you know when it's working?]
+STUB
+
+    cat > "$target/.gator/roadmap.md" << 'STUB'
+# Roadmap
+
+[Priority-ordered. Updated as items complete or priorities shift.]
+
+[Status key: Done · Building · Designed · Considering · Deferred]
+
+| # | Feature | Status | Next step |
+|---|---------|--------|-----------|
+| 1 | | | |
+| 2 | | | |
+| 3 | | | |
+STUB
+
+    cat > "$target/.gator/inbox.md" << 'STUB'
+# Inbox
+
+[Drop anything here. No formatting needed. The agent triages at session open.]
+
+---
+
+STUB
+
+    cat > "$target/.gator/commit_draft.md" << 'STUB'
+---
+message: ""
+change-type:
+significance:
+decision-tags: []
+agent:
+architect:
+---
+
+# Session Change Log
+
+STUB
+
+    cat > "$target/.gator/whiteboard.md" << 'STUB'
+# Whiteboard
+
+Review log. Enforcer findings land here with timestamps. The Architect and agent review together, then act.
+
+When this file exceeds 100 lines, archive older reviews to `artifacts/review-log.md` and keep the most recent 2–3.
+
+---
+
+STUB
+
+    # Lint allowlist and commit issues — empty by default
+    echo '[]' > "$target/.gator/lint-allow.json"
+    printf "# Commit Issues\n\nNo findings.\n" > "$target/.gator/commit_issues.md"
+
+    # Enforcement config — strict by default
+    if [ ! -f "$target/.gator/config.json" ]; then
+        printf '{\n  "enforcement_level": "strict"\n}\n' > "$target/.gator/config.json"
+    fi
+
+    cat > "$target/.gator/patterns.md" << 'STUB'
+# Patterns
+
+Recurring rhythms, obligations, schedules. Updated as patterns emerge.
+
+---
+
+STUB
+
+    cat > "$target/.gator/charters/INDEX.md" << 'STUB'
+# Charter Index
+
+**Always read first:** [Cross-Cutting](cross-cutting.md) (when it exists)
+
+| If you're changing... | Read these charters |
+|---|---|
+| | |
+STUB
+
+    cat > "$target/.gator/issues.md" << 'STUB'
+# Issues
+
+Active bugs, blockers, and known fragilities. Checked at session open.
+
+**Status key**: Open · Working · Resolved
+
+---
+
+STUB
+}
+
+# =============================================================================
+# Template overlay (used by upgrade and morph)
+# =============================================================================
+
+# Overlay template files into a directory WITHOUT deleting existing extras.
+# Template files overwrite same-named files; files that exist only in the
+# target directory are left untouched.
+overlay_templates() {
+    local src_dir="$1" dest_dir="$2"
+    [ -d "$src_dir" ] || return 0
+    mkdir -p "$dest_dir"
+    local count=0
+    for f in "$src_dir"/*; do
+        [ -f "$f" ] || continue
+        cp "$f" "$dest_dir/"
+        count=$((count + 1))
+    done
+    echo "$count"
+}
+
+# =============================================================================
+# Action: Upgrade existing .gator/ (Scenario 3)
+# =============================================================================
+
+action_upgrade_gator() {
+    local target="$1"
+
+    # --- Detect generation ---
+    local gen
+    gen=$(detect_gator_generation "$target")
+
+    local subcase
+    if [ "$gen" -eq 0 ]; then
+        subcase="3a"
+    elif [ "$gen" -lt "$GATOR_GEN" ]; then
+        subcase="3b"
+    else
+        subcase="3c"
+    fi
+
+    log_blank
+    case "$subcase" in
+        3a)
+            echo "  Pre-gatorize.sh install detected (generation 0)."
+            echo "  No thin link, no registry entry, no outbox."
+            echo "  Upgrade will add these and refresh templates while preserving all"
+            echo "  your content — charters, mission, threads, reference-notes, scripts."
+            echo ""
+            echo "  Note: your existing reference-notes and scripts may include files"
+            echo "  not in the current template. These will be kept intact."
+            ;;
+        3b)
+            echo "  Earlier gatorize.sh install detected (generation $gen → $GATOR_GEN)."
+            echo "  Upgrade will refresh templates while preserving all your content."
+            ;;
+        3c)
+            echo "  Current generation ($gen). Refreshing templates to latest versions."
+            ;;
+    esac
+    log_blank
+
+    if has_gator_knowledge "$target"; then
+        echo "  Existing .gator/ has project knowledge (charters, threads, mission, etc.)."
+        echo "  All content will be preserved."
+        log_blank
+        if ! confirm "Proceed with upgrade?" "Y"; then
+            echo "  Aborted."
+            exit 0
+        fi
+    fi
+
+    # --- Ensure all directories exist (older versions may be missing some) ---
+    mkdir -p "$target/.gator/charters" "$target/.gator/blueprints" \
+             "$target/.gator/reference-notes" \
+             "$target/.gator/procedures" "$target/.gator/scripts" \
+             "$target/.gator/threads" "$target/.gator/artifacts" \
+             "$target/.gator/vault" "$target/.gator/policies" \
+             "$target/.gator/sessions"
+
+    # --- Refresh template-derived files ---
+    # Sessions gitignore (keeps _active/ out of git)
+    if [ -f "$TEMPLATES/sessions/.gitignore" ]; then
+        cp "$TEMPLATES/sessions/.gitignore" "$target/.gator/sessions/"
+    fi
+
+    # Constitution and startup guide: always overwrite (these are authoritative)
+    cp "$TEMPLATES/constitution.md" "$target/.gator/"
+    cp "$TEMPLATES/gator-start-up.md" "$target/.gator/"
+    log_step "Refreshed constitution.md, gator-start-up.md"
+
+    # Charter scaffolding: overwrite templates, preserve user charters
+    cp "$TEMPLATES/charters/README.md" "$target/.gator/charters/"
+    cp "$TEMPLATES/charters/_template.md" "$target/.gator/charters/"
+    cp "$TEMPLATES/blueprints/README.md" "$target/.gator/blueprints/" 2>/dev/null || true
+    log_step "Refreshed charter and blueprint templates"
+
+    # Reference-notes: OVERLAY
+    local rn_refreshed
+    rn_refreshed=$(overlay_templates "$TEMPLATES/reference-notes" "$target/.gator/reference-notes")
+    local rn_total
+    rn_total=$(find "$target/.gator/reference-notes" -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
+    log_step "Reference-notes: $rn_refreshed template files refreshed, $rn_total total (extras preserved)"
+
+    # Procedures: OVERLAY
+    local proc_refreshed
+    proc_refreshed=$(overlay_templates "$TEMPLATES/procedures" "$target/.gator/procedures")
+    local proc_total
+    proc_total=$(find "$target/.gator/procedures" -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
+    log_step "Procedures: $proc_refreshed template files refreshed, $proc_total total (extras preserved)"
+
+    # Scripts: OVERLAY (top-level files)
+    local script_refreshed=0
+    for f in "$TEMPLATES/scripts/"*; do
+        [ -f "$f" ] || continue
+        cp "$f" "$target/.gator/scripts/"
+        script_refreshed=$((script_refreshed + 1))
+    done 2>/dev/null || true
+
+    # Scripts: nested directories (e.g., scripts/hooks/)
+    for subdir in "$TEMPLATES/scripts/"*/; do
+        [ -d "$subdir" ] || continue
+        local dirname
+        dirname=$(basename "$subdir")
+        mkdir -p "$target/.gator/scripts/$dirname"
+        for f in "$subdir"*; do
+            [ -f "$f" ] || continue
+            cp "$f" "$target/.gator/scripts/$dirname/"
+            script_refreshed=$((script_refreshed + 1))
+        done
+    done 2>/dev/null || true
+
+    local script_total
+    script_total=$(find "$target/.gator/scripts" -type f 2>/dev/null | wc -l | tr -d ' ')
+    log_step "Scripts: $script_refreshed template files refreshed, $script_total total (extras preserved)"
+
+    # --- Content files: create stubs only if missing ---
+    for stub_file in mission.md roadmap.md inbox.md commit_draft.md whiteboard.md \
+                     patterns.md issues.md; do
+        if [ ! -f "$target/.gator/$stub_file" ]; then
+            case "$stub_file" in
+                mission.md)    echo "# Mission" > "$target/.gator/$stub_file" ;;
+                roadmap.md)    echo "# Roadmap" > "$target/.gator/$stub_file" ;;
+                inbox.md)      printf "# Inbox\n\n---\n\n" > "$target/.gator/$stub_file" ;;
+                commit_draft.md) cat > "$target/.gator/$stub_file" << 'CDSTUB'
+---
+message: ""
+change-type:
+significance:
+decision-tags: []
+agent:
+architect:
+---
+
+# Session Change Log
+
+CDSTUB
+                ;;
+                whiteboard.md) echo "# Whiteboard" > "$target/.gator/$stub_file" ;;
+                patterns.md)   printf "# Patterns\n\n---\n\n" > "$target/.gator/$stub_file" ;;
+                issues.md)     printf "# Issues\n\n---\n\n" > "$target/.gator/$stub_file" ;;
+            esac
+            log_step "Created missing stub: $stub_file"
+        fi
+    done
+
+    # Identity: create only if missing
+    if [ ! -f "$target/.gator/identity.md" ]; then
+        echo "# Identity" > "$target/.gator/identity.md"
+        log_step "Created missing stub: identity.md"
+    fi
+
+    # Charter INDEX: create only if missing
+    if [ ! -f "$target/.gator/charters/INDEX.md" ]; then
+        cat > "$target/.gator/charters/INDEX.md" << 'STUB'
+# Charter Index
+
+**Always read first:** [Cross-Cutting](cross-cutting.md) (when it exists)
+
+| If you're changing... | Read these charters |
+|---|---|
+| | |
+STUB
+        log_step "Created missing charters/INDEX.md"
+    fi
+
+    # Enforcement config: create only if missing (preserves user changes)
+    if [ ! -f "$target/.gator/config.json" ]; then
+        printf '{\n  "enforcement_level": "strict"\n}\n' > "$target/.gator/config.json"
+        log_step "Created config.json (enforcement: strict)"
+    fi
+
+    # --- .gitkeep for empty dirs ---
+    [ -z "$(ls -A "$target/.gator/threads" 2>/dev/null)" ] && \
+        touch "$target/.gator/threads/.gitkeep"
+    [ -z "$(ls -A "$target/.gator/artifacts" 2>/dev/null)" ] && \
+        touch "$target/.gator/artifacts/.gitkeep"
+
+    # --- Install/refresh git hooks ---
+    install_hooks "$target"
+
+    # --- Write version marker ---
+    write_gator_version "$target" "upgrade"
+
+    log_blank
+    log_step "Upgraded .gator/ (gen $gen → $GATOR_GEN) — templates refreshed, content preserved."
+}
+
+# =============================================================================
+# Action: Morph memex → gator (Scenario 4)
+# =============================================================================
+
+action_morph_memex() {
+    local target="$1"
+
+    detect_legacy_memex "$target"
+
+    log_blank
+    echo "  Legacy memex structure detected:"
+    $HAS_MEMEX_DIR && echo "    memex/                  (content layer)"
+    $HAS_DOT_MEMEX_DIR && echo "    .memex/                 (system layer)"
+    $HAS_ROOT_CONSTITUTION && echo "    constitution.md         (root)"
+    $HAS_ROOT_CONSTITUTION_CORE && echo "    constitution-core.md    (root)"
+    log_blank
+    echo "  Gatorize will morph this into .gator/ structure:"
+    echo "    1. Rename legacy dirs to *.pre-gator/ (preserves history, easy rollback)"
+    echo "    2. Install fresh .gator/ from templates"
+    echo "    3. Copy your content (mission, threads, artifacts, etc.) into .gator/"
+    echo "    4. Archive root constitution files"
+    echo "    5. Leave pre-gator dirs on this branch for review"
+    log_blank
+    if ! confirm "Proceed with morph?" "Y"; then
+        echo "  Aborted."
+        exit 0
+    fi
+
+    # --- Step 1: Rename legacy dirs using git mv where possible ---
+
+    (
+        cd "$target"
+        if $HAS_MEMEX_DIR; then
+            if [ -d "memex.pre-gator" ]; then
+                echo "  memex.pre-gator/ already exists — skipping rename"
+            else
+                git mv "memex" "memex.pre-gator" 2>/dev/null || \
+                    mv "memex" "memex.pre-gator"
+                log_step "Renamed memex/ → memex.pre-gator/"
+            fi
+        fi
+        if $HAS_DOT_MEMEX_DIR; then
+            if [ -d ".memex.pre-gator" ]; then
+                echo "  .memex.pre-gator/ already exists — skipping rename"
+            else
+                git mv ".memex" ".memex.pre-gator" 2>/dev/null || \
+                    mv ".memex" ".memex.pre-gator"
+                log_step "Renamed .memex/ → .memex.pre-gator/"
+            fi
+        fi
+    )
+
+    # --- Step 2: Install .gator/ skeleton (or upgrade existing) ---
+
+    if [ -d "$target/.gator" ]; then
+        log_step "Existing .gator/ found — upgrading templates, preserving content."
+        action_upgrade_gator "$target"
+    else
+        action_install_gator "$target"
+    fi
+
+    # --- Step 3: Overlay content from memex.pre-gator/ ---
+
+    local src="$target/memex.pre-gator"
+
+    if [ -d "$src" ]; then
+        log_step "Migrating content from memex.pre-gator/ into .gator/ ..."
+
+        # Direct-copy content files (overwrite stubs)
+        for f in mission.md roadmap.md identity.md inbox.md issues.md \
+                 commit_draft.md whiteboard.md friction.md audit-tracker.md; do
+            if [ -f "$src/$f" ]; then
+                cp "$src/$f" "$target/.gator/$f"
+                log_step "  Migrated $f"
+            fi
+        done
+
+        # patterns — could be a file or a directory
+        if [ -d "$src/patterns" ]; then
+            mkdir -p "$target/.gator/patterns"
+            cp -r "$src/patterns/"* "$target/.gator/patterns/" 2>/dev/null || true
+            log_step "  Migrated patterns/"
+        elif [ -f "$src/patterns.md" ]; then
+            cp "$src/patterns.md" "$target/.gator/patterns.md"
+            log_step "  Migrated patterns.md"
+        fi
+
+        # active-threads → .gator/threads/ (demoted to reference tier)
+        if [ -d "$src/active-threads" ]; then
+            local at_count=0
+            for f in "$src/active-threads/"*.md; do
+                [ -f "$f" ] || continue
+                local basename_f
+                basename_f=$(basename "$f")
+                [ "$basename_f" = "_TEMPLATE.md" ] && continue
+                [ "$basename_f" = "_template.md" ] && continue
+                if [ -f "$target/.gator/threads/$basename_f" ]; then
+                    cp "$f" "$target/.gator/threads/${basename_f%.md}-legacy.md"
+                else
+                    cp "$f" "$target/.gator/threads/$basename_f"
+                fi
+                at_count=$((at_count + 1))
+            done
+            [ "$at_count" -gt 0 ] && log_step "  Migrated $at_count active threads → threads/ (demoted)"
+        fi
+
+        # threads → .gator/threads/ (merge)
+        if [ -d "$src/threads" ]; then
+            local t_count=0
+            for f in "$src/threads/"*.md; do
+                [ -f "$f" ] || continue
+                local basename_f
+                basename_f=$(basename "$f")
+                if [ -f "$target/.gator/threads/$basename_f" ]; then
+                    cp "$f" "$target/.gator/threads/${basename_f%.md}-legacy.md"
+                else
+                    cp "$f" "$target/.gator/threads/$basename_f"
+                fi
+                t_count=$((t_count + 1))
+            done
+            [ "$t_count" -gt 0 ] && log_step "  Migrated $t_count threads"
+        fi
+
+        # artifacts
+        if [ -d "$src/artifacts" ]; then
+            local a_count=0
+            for f in "$src/artifacts/"*.md; do
+                [ -f "$f" ] || continue
+                cp "$f" "$target/.gator/artifacts/"
+                a_count=$((a_count + 1))
+            done
+            [ "$a_count" -gt 0 ] && log_step "  Migrated $a_count artifacts"
+        fi
+
+        # charters — preserve user charters, gator templates already installed
+        if [ -d "$src/charters" ]; then
+            local c_count=0
+            for f in "$src/charters/"*.md; do
+                [ -f "$f" ] || continue
+                local basename_f
+                basename_f=$(basename "$f")
+                case "$basename_f" in
+                    _template.md|README.md) continue ;;
+                esac
+                cp "$f" "$target/.gator/charters/$basename_f"
+                c_count=$((c_count + 1))
+            done
+            [ "$c_count" -gt 0 ] && log_step "  Migrated $c_count charters"
+        fi
+
+        # vault
+        if [ -d "$src/vault" ] && [ -n "$(ls -A "$src/vault" 2>/dev/null)" ]; then
+            cp -r "$src/vault/"* "$target/.gator/vault/" 2>/dev/null || true
+            log_step "  Migrated vault/"
+        fi
+
+        # reference-notes — legacy notes may conflict with template notes
+        if [ -d "$src/reference-notes" ]; then
+            local rn_count=0 rn_conflict=0
+            for f in "$src/reference-notes/"*.md; do
+                [ -f "$f" ] || continue
+                local basename_f
+                basename_f=$(basename "$f")
+                if [ -f "$target/.gator/reference-notes/$basename_f" ]; then
+                    if ! diff -q "$f" "$target/.gator/reference-notes/$basename_f" >/dev/null 2>&1; then
+                        cp "$f" "$target/.gator/reference-notes/${basename_f%.md}-project.md"
+                        rn_conflict=$((rn_conflict + 1))
+                    fi
+                else
+                    cp "$f" "$target/.gator/reference-notes/$basename_f"
+                    rn_count=$((rn_count + 1))
+                fi
+            done
+            [ "$rn_count" -gt 0 ] && log_step "  Migrated $rn_count reference notes"
+            [ "$rn_conflict" -gt 0 ] && log_step "  Preserved $rn_conflict conflicting notes with -project suffix"
+        fi
+    fi
+
+    # --- Step 4: Overlay from .memex.pre-gator/ ---
+
+    local dotsrc="$target/.memex.pre-gator"
+
+    if [ -d "$dotsrc" ]; then
+        log_step "Migrating system layer from .memex.pre-gator/ ..."
+
+        if [ -f "$dotsrc/roles.yaml" ]; then
+            cp "$dotsrc/roles.yaml" "$target/.gator/roles.yaml"
+            log_step "  Migrated roles.yaml"
+        fi
+
+        if [ -d "$dotsrc/policies" ]; then
+            mkdir -p "$target/.gator/policies"
+            cp "$dotsrc/policies/"*.md "$target/.gator/policies/" 2>/dev/null || true
+            log_step "  Migrated policies/"
+        fi
+
+        log_step "  Skipped .memex/scripts/ (gator provides its own)"
+    fi
+
+    # --- Step 5: Archive root constitution files ---
+
+    (
+        cd "$target"
+        if $HAS_ROOT_CONSTITUTION && [ -f "constitution.md" ]; then
+            git mv "constitution.md" ".gator/legacy-constitution.md" 2>/dev/null || \
+                mv "constitution.md" ".gator/legacy-constitution.md"
+            log_step "Archived constitution.md → .gator/legacy-constitution.md"
+        fi
+        if $HAS_ROOT_CONSTITUTION_CORE && [ -f "constitution-core.md" ]; then
+            git mv "constitution-core.md" ".gator/legacy-constitution-core.md" 2>/dev/null || \
+                mv "constitution-core.md" ".gator/legacy-constitution-core.md"
+            log_step "Archived constitution-core.md → .gator/legacy-constitution-core.md"
+        fi
+    )
+
+    # Remove .gitkeep from dirs that now have content
+    [ -n "$(find "$target/.gator/threads" -name "*.md" 2>/dev/null)" ] && \
+        rm -f "$target/.gator/threads/.gitkeep"
+    [ -n "$(find "$target/.gator/artifacts" -name "*.md" 2>/dev/null)" ] && \
+        rm -f "$target/.gator/artifacts/.gitkeep"
+
+    # Write version marker
+    write_gator_version "$target" "morph"
+
+    log_blank
+    log_step "Morph complete. Pre-gator directories preserved for review:"
+    $HAS_MEMEX_DIR && log_step "  memex.pre-gator/    — your original content"
+    $HAS_DOT_MEMEX_DIR && log_step "  .memex.pre-gator/   — your original system layer"
+    log_step "Review .gator/, then delete pre-gator dirs when satisfied."
+}
+
+# =============================================================================
+# Action: Handle dual memex + gator (Scenario 5)
+# =============================================================================
+
+action_warn_dual() {
+    local target="$1"
+
+    detect_legacy_memex "$target"
+
+    log_blank
+    echo "  Both memex and gator structures found in $target."
+    echo "  This is ambiguous — could be a partial migration or manual setup."
+    log_blank
+    echo "  Legacy memex:"
+    $HAS_MEMEX_DIR && echo "    memex/"
+    $HAS_DOT_MEMEX_DIR && echo "    .memex/"
+    $HAS_ROOT_CONSTITUTION && echo "    constitution.md (root)"
+    $HAS_ROOT_CONSTITUTION_CORE && echo "    constitution-core.md (root)"
+    echo "  Gator:"
+    echo "    .gator/"
+    log_blank
+    echo "  Options:"
+    echo "    [m] Morph — fold memex content into existing .gator/ (recommended)"
+    echo "    [u] Upgrade — refresh .gator/ templates, ignore memex dirs"
+    echo "    [a] Abort — inspect manually first"
+    log_blank
+    read -rp "  Choice [m/u/a]: " dual_choice
+
+    case "$dual_choice" in
+        [Mm])
+            action_morph_memex "$target"
+            ;;
+        [Uu])
+            action_upgrade_gator "$target"
+            ;;
+        *)
+            echo "  Aborted. Inspect the repo manually and re-run when ready."
+            exit 0
+            ;;
+    esac
+}