gator-command 1.0.0__py3-none-any.whl

gator_command/templates/gator-starter/scripts/gator-pre-commit.py

@@ -0,0 +1,2670 @@
+#!/usr/bin/env python3
+"""
+gator-pre-commit.py — Deterministic governance gate for gator-managed repos.
+
+Called from three git hooks:
+  pre-commit:  --phase validate
+  commit-msg:  --phase trailers <msg-file>
+  post-commit: --phase cleanup
+
+Phase 1 (validate): Checks structural rules, writes status.json and
+whiteboard.md, stages both. Blocks the commit if hard rules fail.
+
+Phase 2 (trailers): Reads commit_draft.md frontmatter and .gator/ state,
+assembles Gator-* trailers, appends them to the commit message.
+
+Phase 3 (cleanup): Resets .gator/commit_draft.md to the blank stub after a
+successful commit so stale content does not leak into the next session.
+Also appends the commit metadata to the agent's rolling active session file.
+
+No LLM. No interpretation. Same result every time regardless of which
+model produced the session work or how deep into context it was.
+
+@reads: .gator/, commit_draft.md, git diff --cached
+@writes: .gator/status.json, .gator/whiteboard.md, commit message (trailers),
+         .gator/sessions/_active/*.md, .gator/session-snippets/*.json, .gator/commit_draft.md
+@does-not-own: the code changes themselves (the LLM/PI did that)
+"""
+
+import argparse
+import io
+import json
+import os
+import re
+import subprocess
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+def _git_version():
+    """Version from git tags, resolved from this script's location."""
+    import subprocess
+    from pathlib import Path
+    # Walk up from script location to find .git
+    p = Path(__file__).resolve().parent
+    for _ in range(10):
+        if (p / ".git").is_dir():
+            break
+        p = p.parent
+    try:
+        r = subprocess.run(["git", "describe", "--tags", "--always"],
+                           capture_output=True, text=True, cwd=p, timeout=5)
+        if r.returncode == 0 and r.stdout.strip():
+            return r.stdout.strip()
+    except Exception:
+        pass
+    return "dev"
+
+VERSION = _git_version()
+
+# Extensions that don't require a charter update when changed
+EXEMPT_EXTENSIONS = {
+    ".md", ".txt", ".json", ".yaml", ".yml", ".toml", ".cfg", ".ini",
+    ".gitignore", ".gitkeep", ".env.example", ".lock",
+}
+
+# Paths that never require a charter update
+EXEMPT_PATHS = {
+    "LICENSE", "README.md", "CLAUDE.md", "AGENTS.md",
+    ".claude/", ".github/", ".vscode/", ".gitignore",
+}
+
+CHARTER_SCAFFOLD_FILES = {"_template.md", "README.md", "INDEX.md", ".gitkeep"}
+COMMIT_DRAFT_STUB = (
+    "---\n"
+    "message: \"\"\n"
+    "change-type:\n"
+    "significance:\n"
+    "decision-tags: []\n"
+    "agent:\n"
+    "architect:\n"
+    "---\n\n"
+    "# Session Change Log\n"
+)
+ACTIVE_SESSIONS_DIRNAME = "_active"
+
+# ---------------------------------------------------------------------------
+# Layer 1 lint rules — dangerous code patterns (from enforcer-review.py)
+# Embedded here so the hook is self-contained with no import path fragility.
+# ---------------------------------------------------------------------------
+
+LINT_RULES = [
+    # Secrets & credentials
+    {
+        "id": "SEC-001", "name": "Hardcoded password",
+        "pattern": r"""(?i)(password|passwd|pwd)\s*=\s*['\"][^'\"]+['\"]""",
+        "severity": "HIGH",
+        "message": "Possible hardcoded password. Use environment variables or a secrets manager.",
+        "exclude_extensions": {".md", ".txt", ".rst"},
+    },
+    {
+        "id": "SEC-002", "name": "API key in source",
+        "pattern": r"""(?i)(api[_-]?key|secret[_-]?key|access[_-]?token)\s*=\s*['\"][A-Za-z0-9+/=_-]{16,}['\"]""",
+        "severity": "HIGH",
+        "message": "Possible API key or secret in source code.",
+        "exclude_extensions": {".md", ".txt", ".rst"},
+    },
+    {
+        "id": "SEC-003", "name": "Private key material",
+        "pattern": r"""-----BEGIN\s+(RSA\s+)?PRIVATE\s+KEY-----""",
+        "severity": "CRITICAL",
+        "message": "Private key material in source file.",
+        "exclude_extensions": set(),
+        # Downgrade to warning in documentation directories — these contain example text
+        "doc_paths": ["reference-notes/", "procedures/", "docs/"],
+        # Outside doc paths: require base64-looking key body within context_window lines
+        # A lone PEM header without key body is almost always documentation or a stub
+        "context_required": r"""[A-Za-z0-9+/]{40,}={0,2}\s*$""",
+        "context_window": 10,
+    },
+    # SQL dangers
+    {
+        "id": "SQL-001", "name": "DROP TABLE",
+        "pattern": r"""(?i)\bDROP\s+TABLE\b""",
+        "severity": "HIGH",
+        "message": "DROP TABLE detected. Verify this is intentional and scoped correctly.",
+        "exclude_extensions": {".md"},
+    },
+    {
+        "id": "SQL-002", "name": "DELETE without WHERE",
+        "pattern": r"""(?i)\bDELETE\s+FROM\s+\w+\s*(?:;|\n|$)""",
+        "severity": "HIGH",
+        "message": "DELETE FROM without WHERE clause — this deletes all rows.",
+        "exclude_extensions": {".md"},
+    },
+    {
+        "id": "SQL-003", "name": "TRUNCATE",
+        "pattern": r"""(?i)\bTRUNCATE\s+(?:TABLE\s+)?\w+""",
+        "severity": "HIGH",
+        "message": "TRUNCATE detected. Irreversible bulk deletion.",
+        "exclude_extensions": {".md"},
+    },
+    {
+        "id": "SQL-004", "name": "SQL string concatenation",
+        "pattern": r"""(?:execute|cursor\.execute|query)\s*\(.*(?:\+|%\s|\.format|f['\"])""",
+        "severity": "MEDIUM",
+        "message": "Possible SQL injection — string concatenation in query. Use parameterized queries.",
+        "exclude_extensions": {".md"},
+    },
+    # Code safety
+    {
+        "id": "CODE-001", "name": "eval() usage",
+        "pattern": r"""\beval\s*\(""",
+        "severity": "MEDIUM",
+        "message": "eval() executes arbitrary code. Verify input is trusted.",
+        "exclude_extensions": {".md", ".txt"},
+    },
+    {
+        "id": "CODE-002", "name": "shell=True in subprocess",
+        "pattern": r"""subprocess\.\w+\(.*shell\s*=\s*True""",
+        "severity": "MEDIUM",
+        "message": "subprocess with shell=True — command injection risk.",
+        "exclude_extensions": {".md"},
+    },
+    {
+        "id": "CODE-003", "name": "os.system usage",
+        "pattern": r"""\bos\.system\s*\(""",
+        "severity": "MEDIUM",
+        "message": "os.system() is a command injection risk. Use subprocess with shell=False.",
+        "exclude_extensions": {".md"},
+    },
+]
+
+# Files that should never be committed
+DANGEROUS_FILENAMES = {".env"}
+DANGEROUS_PREFIXES = {".env."}
+DANGEROUS_SAFE = {".env.example"}
+
+
+def parse_diff_added_lines(repo_root):
+    """Parse git diff --cached to extract only added lines per file.
+
+    Returns dict: {filepath: [(lineno, line_text), ...]}
+    Only includes lines starting with '+' (additions), excluding
+    diff headers. Line numbers are mapped to the target file.
+    """
+    raw_diff = git("diff", "--cached", "-U0", "--no-color", cwd=repo_root)
+    if not raw_diff:
+        return {}
+
+    added = {}
+    current_file = None
+    target_lineno = 0
+
+    for line in raw_diff.splitlines():
+        # New file header: +++ b/path/to/file
+        if line.startswith("+++ b/"):
+            current_file = line[6:]
+            added.setdefault(current_file, [])
+            continue
+
+        # Hunk header: @@ -old,count +new,count @@
+        if line.startswith("@@") and current_file:
+            match = re.search(r'\+(\d+)', line)
+            if match:
+                target_lineno = int(match.group(1))
+            continue
+
+        # Added line
+        if line.startswith("+") and not line.startswith("+++") and current_file:
+            added[current_file].append((target_lineno, line[1:]))
+            target_lineno += 1
+            continue
+
+        # Context or removed line — just advance target lineno for context
+        if not line.startswith("-") and current_file:
+            target_lineno += 1
+
+    return added
+
+
+def load_lint_allowlist(gator_dir):
+    """Load the PI-approved lint allowlist from .gator/lint-allow.json.
+
+    Each entry is: {"rule": "SQL-001", "file": "path", ...}
+    Returns a set of (rule, file) tuples for fast lookup.
+    """
+    allowlist_file = gator_dir / "lint-allow.json"
+    if not allowlist_file.exists():
+        return set()
+    try:
+        entries = json.loads(allowlist_file.read_text(encoding="utf-8"))
+        return {(e["rule"], e["file"]) for e in entries if "rule" in e and "file" in e}
+    except (json.JSONDecodeError, OSError, KeyError):
+        return set()
+
+
+def _effective_severity(rule, filepath, surrounding_lines):
+    """Compute context-aware effective severity for a lint match.
+
+    context_required takes priority over doc_paths: if corroborating evidence
+    (e.g. a base64 key body) is present in surrounding lines, the match is
+    treated as real secret material at original severity regardless of file
+    location. doc_paths only downgrades when evidence is absent — distinguishing
+    a lone example header in a reference doc from an actual committed key.
+    """
+    severity = rule["severity"]
+
+    # Context-required check first — real evidence overrides location heuristics.
+    if severity in ("CRITICAL", "HIGH") and rule.get("context_required"):
+        context_found = any(
+            re.search(rule["context_required"], line) for line in surrounding_lines
+        )
+        if context_found:
+            # Corroborating evidence present — real key material, keep severity.
+            return severity
+        # No body found — likely documentation or stub. Fall through to
+        # location-based downgrade or unconditional downgrade below.
+        if rule.get("doc_paths"):
+            f_norm = filepath.replace("\\", "/")
+            if any(dp in f_norm for dp in rule["doc_paths"]):
+                return "MEDIUM"
+        return "MEDIUM"
+
+    # Rules without context_required: apply doc_paths location-based downgrade.
+    if rule.get("doc_paths"):
+        f_norm = filepath.replace("\\", "/")
+        if any(dp in f_norm for dp in rule["doc_paths"]):
+            return "MEDIUM"
+
+    return severity
+
+
+def run_layer1_lint(staged_files, repo_root):
+    """Run mechanical lint rules against ADDED lines only (from git diff).
+
+    Only lines being introduced in this commit are checked. Existing
+    code is implicitly approved by virtue of being in the codebase.
+    This eliminates false alarm fatigue and means the PI only reviews
+    what they're actually introducing.
+
+    The allowlist (.gator/lint-allow.json) handles the rare case where
+    new dangerous code is intentional.
+    """
+    findings = []
+    gator_dir = repo_root / ".gator"
+    allowed = load_lint_allowlist(gator_dir)
+
+    # Self-exclude patterns (these files contain or quote the patterns they detect)
+    self_excludes = {"gator-pre-commit.py", "enforcer-review.py", "enforcer-prompt.md", "lint-allow.json", "commit_issues.md", "whiteboard.md"}
+
+    # Path-scoped excludes for Gator-provided documentation that quotes dangerous
+    # patterns as examples. Unlike self_excludes (basename-only), these check the
+    # normalized path so a user file with the same name is still scanned.
+    gator_doc_excludes = {"reference-notes/dangerous-patterns.md"}
+
+    # Check for dangerous filenames in staged files (these are always checked
+    # regardless of diff — staging a .env file is the danger)
+    for filepath in staged_files:
+        basename = os.path.basename(filepath)
+        if basename in self_excludes:
+            continue
+        if basename in DANGEROUS_FILENAMES or (
+            any(basename.startswith(p) for p in DANGEROUS_PREFIXES)
+            and basename not in DANGEROUS_SAFE
+        ):
+            if ("HYG-002", filepath) not in allowed:
+                findings.append({
+                    "rule": "HYG-002",
+                    "severity": "HIGH",
+                    "file": filepath,
+                    "line": 0,
+                    "message": f"{basename} should not be committed. Add to .gitignore.",
+                })
+
+    # Parse diff for added lines only
+    added_lines = parse_diff_added_lines(repo_root)
+
+    for filepath, lines in added_lines.items():
+        basename = os.path.basename(filepath)
+        if basename in self_excludes:
+            continue
+        f_norm = filepath.replace("\\", "/")
+        if any(f_norm.endswith(dp) for dp in gator_doc_excludes):
+            continue
+
+        _, ext = os.path.splitext(filepath)
+
+        for rule in LINT_RULES:
+            if ext in rule.get("exclude_extensions", set()):
+                continue
+            if (rule["id"], filepath) in allowed:
+                continue
+            pattern = rule["pattern"]
+            for i, (lineno, line_text) in enumerate(lines):
+                if re.search(pattern, line_text):
+                    window = rule.get("context_window", 10)
+                    if rule.get("context_required"):
+                        # Read full file content so a key body already in the
+                        # file (not newly added in this diff) is still detected.
+                        try:
+                            file_lines = (repo_root / filepath).read_text(
+                                encoding="utf-8", errors="replace"
+                            ).splitlines()
+                            line_idx = lineno - 1
+                            ctx = file_lines[
+                                max(0, line_idx - window):line_idx + window + 1
+                            ]
+                        except OSError:
+                            ctx = [lt for _, lt in lines[max(0, i - window):i + window + 1]]
+                    else:
+                        ctx = [lt for _, lt in lines[max(0, i - window):i + window + 1]]
+                    effective_sev = _effective_severity(rule, filepath, ctx)
+                    findings.append({
+                        "rule": rule["id"],
+                        "severity": effective_sev,
+                        "file": filepath,
+                        "line": lineno,
+                        "message": rule["message"],
+                        "match": line_text.strip()[:120],
+                    })
+
+    return findings
+
+
+# High file count threshold for soft warning
+HIGH_FILE_COUNT = 20
+
+
+# ---------------------------------------------------------------------------
+# Git helpers
+# ---------------------------------------------------------------------------
+
+def git(*args, cwd=None):
+    """Run a git command, return stdout. Returns empty string on failure."""
+    try:
+        result = subprocess.run(
+            ["git"] + list(args),
+            capture_output=True, text=True, cwd=cwd,
+            encoding="utf-8", errors="replace",
+        )
+        return (result.stdout or "").strip()
+    except OSError:
+        return ""
+
+
+def get_staged_files(repo_root):
+    """Return list of staged file paths (relative to repo root)."""
+    output = git("diff", "--cached", "--name-only", cwd=repo_root)
+    if not output:
+        return []
+    return [line for line in output.splitlines() if line.strip()]
+
+
+def get_current_branch(repo_root):
+    """Return current branch name."""
+    return git("branch", "--show-current", cwd=repo_root) or "unknown"
+
+
+def stage_file(filepath, repo_root):
+    """Stage a single file."""
+    git("add", str(filepath), cwd=repo_root)
+
+
+# ---------------------------------------------------------------------------
+# .gator/ state readers
+# ---------------------------------------------------------------------------
+
+def find_gator_root(start_path=None):
+    """Walk up from start_path looking for .gator/ directory."""
+    path = Path(start_path) if start_path else Path.cwd()
+    path = path.resolve()
+    if (path / ".gator").is_dir():
+        return path
+    for parent in path.parents:
+        if (parent / ".gator").is_dir():
+            return parent
+    return None
+
+
+def _resolve_charter_surface(repo_root):
+    """Resolve the charter surface for this repo.
+
+    Tries gator_core.resolve_charter_surface() first (canonical resolver),
+    falls back to inline heuristic for self-contained operation.
+
+    Returns (charter_dir: Path, cross_cutting_name: str|None).
+    """
+    try:
+        scripts_dir = repo_root / "src" / "gator_command" / "scripts"
+        if not scripts_dir.is_dir():
+            scripts_dir = repo_root / "gator-command" / "scripts"
+        if not scripts_dir.is_dir():
+            scripts_dir = repo_root / ".gator" / "scripts"
+        if scripts_dir.is_dir() and str(scripts_dir) not in sys.path:
+            sys.path.insert(0, str(scripts_dir))
+        from gator_core import resolve_charter_surface
+        surface = resolve_charter_surface(repo_root)
+        return Path(surface["charter_dir"]), surface.get("cross_cutting")
+    except (ImportError, Exception):
+        pass
+
+    # Fallback: inline resolution (self-contained for fleet repos)
+    command_post_charters = repo_root / "gator-command" / "charters"
+    command_post_scripts = repo_root / "gator-command" / "scripts"
+    if command_post_charters.is_dir() and command_post_scripts.is_dir():
+        charter_dir = command_post_charters
+    else:
+        charter_dir = repo_root / ".gator" / "charters"
+
+    cross_cutting = None
+    if charter_dir.is_dir():
+        for f in charter_dir.iterdir():
+            if "cross-cutting" in f.name and f.suffix == ".md":
+                cross_cutting = f.name
+                break
+    return charter_dir, cross_cutting
+
+
+def _resolve_charter_dir(repo_root):
+    """Convenience: return just the charter directory Path."""
+    charter_dir, _ = _resolve_charter_surface(repo_root)
+    return charter_dir
+
+
+def _iter_charter_files(repo_root):
+    """Yield real charter files from the governed repo's charter surface."""
+    charter_dir = _resolve_charter_dir(repo_root)
+    if not charter_dir.is_dir():
+        return
+    for charter_file in charter_dir.iterdir():
+        if charter_file.suffix != ".md":
+            continue
+        if charter_file.name in CHARTER_SCAFFOLD_FILES:
+            continue
+        yield charter_file
+
+
+def count_charters(gator_dir):
+    """Count charter files and documented functions."""
+    repo_root = gator_dir.parent
+    charter_files = list(_iter_charter_files(repo_root))
+
+    function_count = 0
+    for cf in charter_files:
+        try:
+            text = cf.read_text(encoding="utf-8", errors="replace")
+            for line in text.splitlines():
+                if line.strip().startswith("### ") and "(" in line:
+                    function_count += 1
+        except OSError:
+            continue
+
+    return len(charter_files), function_count
+
+
+def count_threads(gator_dir):
+    """Count threads across active-threads/ and threads/."""
+    total = 0
+    for subdir_name in ("active-threads", "threads"):
+        subdir = gator_dir / subdir_name
+        if subdir.is_dir():
+            total += len([
+                f for f in subdir.iterdir()
+                if f.suffix == ".md" and f.name != ".gitkeep"
+            ])
+    return total
+
+
+def read_generation(gator_dir):
+    """Read generation from .gator-version."""
+    version_file = gator_dir / ".gator-version"
+    if not version_file.exists():
+        return 0
+    text = version_file.read_text(encoding="utf-8", errors="replace")
+    for line in text.splitlines():
+        if line.startswith("generation:"):
+            try:
+                return int(line.split(":", 1)[1].strip())
+            except ValueError:
+                return 0
+    return 0
+
+
+def read_policy_version(gator_dir):
+    """Read policy version date from command-post.md."""
+    cp_file = gator_dir / "command-post.md"
+    if not cp_file.exists():
+        return None
+    text = cp_file.read_text(encoding="utf-8", errors="replace")
+    for line in text.splitlines():
+        if line.startswith("version:"):
+            return line.split(":", 1)[1].strip()
+    return None
+
+
+def count_issues(gator_dir):
+    """Count open/working issues."""
+    issues_file = gator_dir / "issues.md"
+    if not issues_file.exists():
+        return 0
+    text = issues_file.read_text(encoding="utf-8", errors="replace")
+    count = 0
+    for line in text.splitlines():
+        if "**Status**: Open" in line or "**Status**: Working" in line:
+            count += 1
+    return count
+
+
+def read_tripwire_patterns(gator_dir):
+    """Extract @tripwire file patterns from charters."""
+    patterns = set()
+    repo_root = gator_dir.parent
+    for cf in _iter_charter_files(repo_root):
+        try:
+            text = cf.read_text(encoding="utf-8", errors="replace")
+            for line in text.splitlines():
+                if "@tripwire" in line.lower():
+                    # Extract file paths mentioned on tripwire lines
+                    # Look for backtick-quoted paths or bare paths
+                    for match in re.finditer(r'`([^`]+\.\w+)`', line):
+                        patterns.add(match.group(1))
+        except OSError:
+            continue
+    return patterns
+
+
+# ---------------------------------------------------------------------------
+# commit_draft.md parsing
+# ---------------------------------------------------------------------------
+
+def parse_commit_draft(gator_dir):
+    """Parse commit_draft.md into frontmatter dict and body string.
+
+    Returns (frontmatter, body, error).
+    - frontmatter: dict of YAML fields, or {} if no frontmatter
+    - body: string of everything after frontmatter
+    - error: string if frontmatter is present but malformed, else None
+    """
+    draft_file = gator_dir / "commit_draft.md"
+    if not draft_file.exists():
+        return {}, "", None
+
+    text = draft_file.read_text(encoding="utf-8", errors="replace")
+    if not text.strip():
+        return {}, "", None
+
+    # Check for YAML frontmatter (--- delimited)
+    if text.startswith("---"):
+        parts = text.split("---", 2)
+        if len(parts) >= 3:
+            yaml_text = parts[1].strip()
+            body = parts[2].strip()
+            frontmatter = _parse_simple_yaml(yaml_text)
+            if frontmatter is None:
+                return {}, body, "Malformed YAML frontmatter in commit_draft.md"
+            return frontmatter, body, None
+
+    # No frontmatter — entire file is body
+    # Strip the "# Session Change Log" header if present
+    lines = text.splitlines()
+    body_lines = [l for l in lines if not l.startswith("# ")]
+    return {}, "\n".join(body_lines).strip(), None
+
+
+def _parse_simple_yaml(text):
+    """Minimal YAML parser for commit_draft frontmatter.
+
+    Handles flat key: value pairs and simple lists [a, b, c].
+    No external dependency needed. Returns None on parse failure.
+    """
+    result = {}
+    try:
+        for line in text.splitlines():
+            line = line.strip()
+            if not line or line.startswith("#"):
+                continue
+            if ":" not in line:
+                return None  # malformed
+            key, _, value = line.partition(":")
+            key = key.strip()
+            value = value.strip()
+
+            # Handle YAML list syntax: [a, b, c]
+            if value.startswith("[") and value.endswith("]"):
+                inner = value[1:-1]
+                items = [item.strip().strip("'\"") for item in inner.split(",")]
+                result[key] = [i for i in items if i]
+            # Handle quoted strings
+            elif (value.startswith('"') and value.endswith('"')) or \
+                 (value.startswith("'") and value.endswith("'")):
+                result[key] = value[1:-1]
+            else:
+                result[key] = value
+
+        return result
+    except Exception:
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Fallback heuristics (body text inference)
+# ---------------------------------------------------------------------------
+
+def extract_tags_from_body(body):
+    """Extract [#tag] patterns from commit_draft body."""
+    if not body:
+        return []
+    tags = set()
+    for match in re.finditer(r'\[#([a-zA-Z0-9_-]+)\]', body):
+        tags.add(match.group(1))
+    return sorted(tags)
+
+
+def infer_change_type(body, has_code_staged):
+    """Infer change type from body tags, gated on staged reality.
+
+    Per Codex review: body-text inference must never produce a stronger
+    signal than the staged files justify. If no code is staged, cap at
+    docs/policy regardless of tags.
+    """
+    if not body:
+        return None
+
+    text = body.lower()
+
+    if not has_code_staged:
+        # No code files staged — this is docs/policy work at most
+        if "[#policy]" in text or "[#governance]" in text:
+            return "policy"
+        return "docs"
+
+    # Code is staged — full inference
+    if "[#security]" in text:
+        return "security"
+    if "[#bugfix]" in text or "[#fix]" in text:
+        return "fix"
+    if "[#refactor]" in text:
+        return "refactor"
+    if "[#architecture]" in text or "[#decision]" in text or "[#feature]" in text:
+        return "feature"
+    if "[#policy]" in text or "[#governance]" in text:
+        return "policy"
+    if "[#docs]" in text or "[#charter]" in text:
+        return "docs"
+    return None
+
+
+def infer_significance(body, charter_changed, has_code_staged):
+    """Infer significance from body signals, gated on staged reality.
+
+    Per Codex review: if no code files staged, cap at routine regardless
+    of tags in the body.
+    """
+    if not body or not has_code_staged:
+        return "routine"
+
+    text = body.lower()
+    if any(tag in text for tag in ["[#security]", "[#architecture]", "[#breaking]"]):
+        return "high"
+    if charter_changed or "[#decision]" in text or "[#feature]" in text:
+        return "notable"
+    return "routine"
+
+
+def detect_agent_from_body(body):
+    """Extract agent attribution from body text."""
+    if not body:
+        return None
+    agents = set()
+    for line in body.splitlines():
+        stripped = line.rstrip()
+        # Match org policy format: -claude, -codex, -gemini at end of line
+        if stripped.endswith("-claude"):
+            agents.add("claude")
+        elif stripped.endswith("-codex"):
+            agents.add("codex")
+        elif stripped.endswith("-gemini"):
+            agents.add("gemini")
+        # Also match — claude, — codex style
+        for model in ("claude", "codex", "gemini"):
+            if f"— {model}" in stripped.lower():
+                agents.add(model)
+    if agents:
+        return ",".join(sorted(agents))
+    return None
+
+
+def detect_architect_from_body(body):
+    """Extract Architect attribution from body text.
+
+    Per Codex review: must match the actual org policy format (— AG),
+    not the old -pi suffix pattern. If no real value found, return None
+    rather than 'architect'.
+    """
+    if not body:
+        return None
+    for line in body.splitlines():
+        # Match "— AG" or "— JD" (em dash + space + 2-4 uppercase letters)
+        match = re.search(r'—\s+([A-Z]{2,4})(?:\s|$)', line)
+        if match:
+            return match.group(1)
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Validation rules
+# ---------------------------------------------------------------------------
+
+def classify_staged_files(staged_files, _charter_patterns_cache=[None]):
+    """Classify staged files into code and charter changes.
+
+    Returns (has_code, has_charter, code_files, charter_files).
+    Uses the resolved charter directory to identify charter files.
+    """
+    # Resolve charter path patterns once per process
+    if _charter_patterns_cache[0] is None:
+        try:
+            repo_root = Path.cwd()
+            for _ in range(10):
+                if (repo_root / ".gator").is_dir():
+                    break
+                repo_root = repo_root.parent
+            surface = _resolve_charter_surface(repo_root)
+            charter_dir = surface[0]
+            # Build both absolute and relative patterns for matching
+            # Git staged paths are relative; resolved dir is absolute
+            abs_str = str(charter_dir).replace("\\", "/")
+            try:
+                rel_str = str(charter_dir.relative_to(repo_root)).replace("\\", "/")
+            except ValueError:
+                rel_str = abs_str
+            _charter_patterns_cache[0] = [
+                rel_str + "/",   # relative: gator-command/charters/
+                abs_str + "/",   # absolute: C:/.../gator-command/charters/
+                ".gator/charters/",  # always recognize standard path
+            ]
+        except Exception:
+            _charter_patterns_cache[0] = [".gator/charters/"]
+
+    charter_patterns = _charter_patterns_cache[0]
+
+    code_files = []
+    charter_files = []
+
+    for f in staged_files:
+        # Normalize path separators
+        f_normalized = f.replace("\\", "/")
+
+        # Charter files — match against resolved charter directory patterns
+        is_charter = any(p in f_normalized for p in charter_patterns)
+        if is_charter:
+            basename = f_normalized.split("/")[-1]
+            if basename not in CHARTER_SCAFFOLD_FILES:
+                charter_files.append(f)
+            continue
+
+        # Other .gator/ internal files — exempt
+        if ".gator/" in f_normalized:
+            continue
+
+        # Check exempt paths
+        is_exempt = False
+        for exempt in EXEMPT_PATHS:
+            if f_normalized.startswith(exempt) or f_normalized == exempt:
+                is_exempt = True
+                break
+        if is_exempt:
+            continue
+
+        # Check exempt extensions
+        _, ext = os.path.splitext(f_normalized)
+        if ext.lower() in EXEMPT_EXTENSIONS:
+            continue
+
+        # Everything else is a code file
+        code_files.append(f)
+
+    return bool(code_files), bool(charter_files), code_files, charter_files
+
+
+def _generate_block_id():
+    """Generate a short unique block ID for override tracking."""
+    import hashlib
+    import time
+    raw = f"{time.time()}-{os.getpid()}"
+    return hashlib.sha256(raw.encode()).hexdigest()[:8]
+
+
+def _write_override_request(gator_dir, failure_type, files, override_type="charter-skip"):
+    """Write an override request for PI review."""
+    import time
+    request = {
+        "block_id": _generate_block_id(),
+        "failure_type": failure_type,
+        "override_type": override_type,
+        "files": files[:10],
+        "timestamp": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S%z"),
+        "epoch": time.time(),
+    }
+    request_file = gator_dir / "override-request.json"
+    request_file.write_text(
+        json.dumps(request, indent=2) + "\n",
+        encoding="utf-8",
+    )
+    return request
+
+
+OVERRIDE_DELAY_SECONDS = 10
+
+
+def check_override(gator_dir):
+    """Check for a PI-approved two-phase override.
+
+    Two-phase override flow:
+      1. Hook blocks → writes override-request.json (block ID, failure)
+      2. PI reviews findings, runs gator-approve.py → writes override-approved.json
+      3. Agent retries git commit → hook checks approval matches request
+
+    Approval is valid only if:
+      - Both request and approval files exist
+      - Block IDs match
+      - Approval timestamp is later than request
+      - Minimum delay has passed (agent cannot instantly self-approve)
+
+    Also supports legacy .override file for backward compatibility,
+    but prints a deprecation notice.
+
+    Returns the override value if approved, None otherwise.
+    """
+    import time
+
+    # --- New two-phase flow ---
+    request_file = gator_dir / "override-request.json"
+    approved_file = gator_dir / "override-approved.json"
+
+    two_phase_valid = False
+    if request_file.exists() and approved_file.exists():
+        try:
+            request = json.loads(request_file.read_text(encoding="utf-8"))
+            approval = json.loads(approved_file.read_text(encoding="utf-8"))
+
+            ids_match = request.get("block_id") == approval.get("block_id")
+
+            req_epoch = request.get("epoch", 0)
+            try:
+                appr_str = approval["approved_at"]
+                # Parse with timezone offset (e.g. 2026-06-04T10:58:37-0400)
+                # Python 3.7+ fromisoformat handles most ISO formats;
+                # strptime with %z handles the +HHMM offset reliably.
+                try:
+                    appr_dt = datetime.fromisoformat(appr_str)
+                except ValueError:
+                    appr_dt = datetime.strptime(appr_str[:24], "%Y-%m-%dT%H:%M:%S%z")
+                appr_epoch = appr_dt.timestamp()
+            except (KeyError, ValueError):
+                appr_epoch = 0
+
+            timing_ok = appr_epoch >= req_epoch
+            delay_ok = time.time() - req_epoch >= OVERRIDE_DELAY_SECONDS
+
+            two_phase_valid = ids_match and timing_ok and delay_ok
+        except (json.JSONDecodeError, OSError):
+            two_phase_valid = False
+
+    if two_phase_valid:
+        # Valid two-phase approval — consume both files (one-shot)
+        override_type = approval.get("override_type", "charter-skip")
+        approved_by = approval.get("approved_by", "unknown")
+        reason = approval.get("reason", "")
+
+        for f in (request_file, approved_file):
+            try:
+                f.unlink()
+            except OSError:
+                pass
+            git("rm", "--cached", "--quiet", "--force", "--",
+                str(f.relative_to(gator_dir.parent)),
+                cwd=gator_dir.parent)
+
+        # Stash approval metadata for trailer assembly
+        _override_meta = {
+            "type": override_type,
+            "approved_by": approved_by,
+            "reason": reason,
+            "block_id": request.get("block_id", ""),
+        }
+        meta_file = gator_dir / ".override-meta.json"
+        meta_file.write_text(json.dumps(_override_meta), encoding="utf-8")
+
+        return override_type
+
+    # --- Legacy .override file (fallback when two-phase fails or is absent) ---
+    override_file = gator_dir / ".override"
+    if override_file.exists():
+        value = override_file.read_text(encoding="utf-8").strip()
+        try:
+            override_file.unlink()
+        except OSError:
+            pass
+        git("rm", "--cached", "--quiet", "--force", "--",
+            str(override_file.relative_to(gator_dir.parent)),
+            cwd=gator_dir.parent)
+
+        if value:
+            # Write minimal meta for trailers
+            meta_file = gator_dir / ".override-meta.json"
+            meta_file.write_text(json.dumps({
+                "type": value,
+                "approved_by": "legacy-override",
+                "reason": "",
+                "block_id": "",
+            }), encoding="utf-8")
+        return value or None
+
+    return None
+
+
+def validate_hard_rules(staged_files, frontmatter, body, parse_error, gator_dir, override=None):
+    """Check hard rules. Returns list of (rule_name, message) for failures."""
+    failures = []
+
+    # 1. Frontmatter parse failure
+    if parse_error:
+        failures.append(("frontmatter-parse", parse_error))
+
+    # 2. Empty commit_draft
+    if not frontmatter and not body:
+        failures.append((
+            "empty-commit-draft",
+            "commit_draft.md is empty or missing. The agent must document "
+            "what changed and why before committing."
+        ))
+
+    # 3. Charter-alongside-code
+    has_code, has_charter, code_files, charter_files_staged = classify_staged_files(staged_files)
+
+    if has_code and override != "charter-skip":
+        files_str = ", ".join(code_files[:5])
+        if len(code_files) > 5:
+            files_str += f" (and {len(code_files) - 5} more)"
+
+        if not has_charter:
+            # No charter at all — block. Use INDEX to tell the agent
+            # exactly which charters are needed.
+            required = _required_charters_for_files(code_files, gator_dir.parent)
+            if required:
+                charters_str = ", ".join(sorted(required))
+                failures.append((
+                    "charter-alongside-code",
+                    f"Code files changed ({files_str}) but no charters "
+                    f"were updated. INDEX.md requires: {charters_str}. "
+                    f"Update the affected charters and retry."
+                ))
+            else:
+                failures.append((
+                    "charter-alongside-code",
+                    f"Code files changed ({files_str}) but no charters "
+                    f"were updated. "
+                    f"Update the affected charters and retry."
+                ))
+        else:
+            # Charter(s) staged — check if all INDEX-required charters
+            # are covered. This catches the case where the module charter
+            # is staged but cross-cutting (or another required charter)
+            # is not.
+            required = _required_charters_for_files(code_files, gator_dir.parent)
+            if required:
+                staged_names = set()
+                for f in charter_files_staged:
+                    fn = f.replace("\\", "/").rsplit("/", 1)[-1]
+                    staged_names.add(fn)
+                missing = required - staged_names
+                if missing:
+                    missing_str = ", ".join(sorted(missing))
+                    failures.append((
+                        "charter-index-gap",
+                        f"Code files changed ({files_str}). INDEX.md requires "
+                        f"charters: {', '.join(sorted(required))}. "
+                        f"Missing from staged files: {missing_str}. "
+                        f"Update the missing charters and retry."
+                    ))
+
+    # 4. Missing commit message
+    has_message = bool(frontmatter.get("message"))
+    # The stub heading "# Session Change Log" alone should not count
+    # as real body content. Only strip that exact stub line — preserve
+    # all other #-prefixed lines (e.g. "#123 fix", markdown headings).
+    _STUB_HEADING = "# Session Change Log"
+    body_lines = [l for l in (body or "").splitlines()
+                  if l.strip() and l.strip() != _STUB_HEADING]
+    has_body_content = bool(body_lines)
+    if not has_message and not has_body_content:
+        failures.append((
+            "missing-message",
+            "No commit message found. Add a 'message' field to "
+            "commit_draft.md frontmatter, or add content to the body."
+        ))
+
+    return failures
+
+
+def _check_charter_function_refs(charter_files, repo_root):
+    """Check that ### func() entries in staged charters reference real functions.
+
+    Parses charter for '### name(' entries and the 'Covers:' line, then greps
+    the covered files for those function names. Returns list of names not found.
+    Self-contained — no gator_core imports.
+    """
+    stale = []
+    for cf in charter_files:
+        cf_path = Path(cf) if Path(cf).is_absolute() else repo_root / cf
+        if not cf_path.is_file():
+            continue
+        try:
+            text = cf_path.read_text(encoding="utf-8", errors="replace")
+        except (OSError, UnicodeDecodeError):
+            continue
+
+        # Extract function names from ### entries
+        func_names = []
+        for line in text.splitlines():
+            stripped = line.strip()
+            if stripped.startswith("### ") and "(" in stripped:
+                # "### foo_bar(args)" → "foo_bar"
+                name = stripped[4:].split("(")[0].strip()
+                if name:
+                    func_names.append(name)
+
+        if not func_names:
+            continue
+
+        # Extract covered files from Covers: line
+        covered_files = []
+        for line in text.splitlines():
+            if line.startswith("**Covers**:") or line.startswith("**Covers:**"):
+                # Parse backtick-quoted paths
+                import re as _re
+                covered_files = _re.findall(r'`([^`]+)`', line)
+                break
+
+        if not covered_files:
+            continue
+
+        # Read covered file contents
+        covered_content = ""
+        for rel_path in covered_files:
+            full = repo_root / rel_path
+            if full.is_file():
+                try:
+                    covered_content += full.read_text(encoding="utf-8", errors="replace")
+                except (OSError, UnicodeDecodeError):
+                    pass
+
+        if not covered_content:
+            continue
+
+        # Check each function name exists somewhere in covered files
+        for name in func_names:
+            if name not in covered_content:
+                stale.append(name)
+
+    return stale
+
+
+def _detect_new_functions(staged_files, repo_root):
+    """Detect new function definitions in staged code and new ### entries in charters.
+
+    Uses git diff --cached to find added lines. Returns (new_code_funcs, new_charter_entries).
+    Self-contained — no gator_core imports.
+    """
+    new_code_funcs = []
+    new_charter_entries = []
+
+    try:
+        result = subprocess.run(
+            ["git", "diff", "--cached", "-U0", "--no-color"],
+            capture_output=True, text=True, cwd=str(repo_root),
+            encoding="utf-8", errors="replace",
+        )
+        if result.returncode != 0:
+            return [], []
+    except (OSError, subprocess.TimeoutExpired):
+        return [], []
+
+    for line in result.stdout.splitlines():
+        if not line.startswith("+") or line.startswith("+++"):
+            continue
+        added = line[1:].strip()
+
+        # New function definitions in code
+        if (added.startswith("def ") or
+                added.startswith("function ") or
+                added.startswith("func ")):
+            # Extract name: "def foo(..." → "foo"
+            for prefix in ("def ", "function ", "func "):
+                if added.startswith(prefix):
+                    rest = added[len(prefix):]
+                    name = rest.split("(")[0].strip()
+                    if name and not name.startswith("_"):
+                        new_code_funcs.append(name)
+                    break
+
+        # New charter entries
+        if added.startswith("### ") and "(" in added:
+            name = added[4:].split("(")[0].strip()
+            if name:
+                new_charter_entries.append(name)
+
+    return new_code_funcs, new_charter_entries
+
+
+def _parse_charter_index(repo_root):
+    """Parse INDEX.md to build a map of file patterns → required charter names.
+
+    Returns list of (pattern_str, set_of_charter_filenames) or empty list
+    if INDEX is missing or unparseable.
+    Self-contained — no gator_core imports.
+    """
+    charter_dir = _resolve_charter_dir(repo_root)
+    index_path = charter_dir / "INDEX.md"
+    if not index_path.is_file():
+        return []
+
+    try:
+        text = index_path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return []
+
+    mappings = []
+    for line in text.splitlines():
+        line = line.strip()
+        if not line.startswith("|") or line.startswith("| If") or line.startswith("|---"):
+            continue
+        parts = [p.strip() for p in line.split("|") if p.strip()]
+        if len(parts) < 2:
+            continue
+
+        # Parse file patterns from first column
+        # Format: `file.py`, `file2.py`, ... or prose like "Any pattern..."
+        patterns = re.findall(r'`([^`]+)`', parts[0])
+        if not patterns:
+            continue
+
+        # Parse charter refs from second column
+        # Format: [Name](filename.md) · [Name2](filename2.md)
+        charter_refs = set(re.findall(r'\(([^)]+\.md)\)', parts[1]))
+        if not charter_refs:
+            continue
+
+        for pattern in patterns:
+            mappings.append((pattern, charter_refs))
+
+    return mappings
+
+
+def _required_charters_for_files(code_files, repo_root):
+    """Given a list of changed code files, return the set of charter filenames
+    that INDEX.md says should be consulted.
+
+    Returns set of charter filenames (e.g. {"scripts-fleet-intelligence.md",
+    "scripts-cross-cutting.md"}).
+    """
+    mappings = _parse_charter_index(repo_root)
+    if not mappings:
+        return set()
+
+    import fnmatch as _fnmatch
+    required = set()
+    for code_file in code_files:
+        f_normalized = code_file.replace("\\", "/")
+        f_basename = f_normalized.rsplit("/", 1)[-1]
+        for pattern, charter_refs in mappings:
+            if "*" in pattern or "?" in pattern:
+                if _fnmatch.fnmatch(f_basename, pattern) or _fnmatch.fnmatch(f_normalized, pattern):
+                    required.update(charter_refs)
+            elif f_basename == pattern or pattern in f_normalized:
+                required.update(charter_refs)
+
+    return required
+
+
+def validate_soft_rules(staged_files, frontmatter, body, gator_dir):
+    """Check soft rules. Returns list of (rule_name, message) for warnings."""
+    warnings = []
+
+    has_code, has_charter, code_files, _ = classify_staged_files(staged_files)
+
+    # 1. No significance assessment
+    if has_code and not frontmatter.get("significance"):
+        inferred = infer_significance(body, has_charter, has_code)
+        if inferred == "routine":
+            warnings.append((
+                "no-significance",
+                "commit_draft.md has no 'significance' field and no "
+                "inferrable signals. Consider adding a significance "
+                "assessment before committing."
+            ))
+
+    # 2. No decision tags
+    if not frontmatter.get("decision-tags") and not extract_tags_from_body(body):
+        warnings.append((
+            "no-decision-tags",
+            "No decision tags found in commit_draft.md frontmatter or body. "
+            "Untagged commits are harder to query later."
+        ))
+
+    # 3. Tripwire files touched
+    tripwires = read_tripwire_patterns(gator_dir)
+    if tripwires:
+        touched = []
+        for f in staged_files:
+            f_normalized = f.replace("\\", "/")
+            for pattern in tripwires:
+                if pattern in f_normalized or f_normalized.endswith(pattern):
+                    touched.append(f)
+                    break
+        if touched:
+            files_str = ", ".join(touched[:3])
+            warnings.append((
+                "tripwire-touched",
+                f"Tripwire-tagged file(s) touched: {files_str}. "
+                f"Verify the PI is aware of these changes."
+            ))
+
+    # 4. High file count
+    if len(staged_files) > HIGH_FILE_COUNT:
+        warnings.append((
+            "high-file-count",
+            f"{len(staged_files)} files staged (threshold: {HIGH_FILE_COUNT}). "
+            f"Large commits may indicate skipped incremental steps."
+        ))
+
+    # 5. Charter function-name smoke test: check that ### func() entries in
+    #    staged charters still reference functions that exist in the code.
+    if has_charter:
+        _, _, _, charter_files = classify_staged_files(staged_files)
+        stale_refs = _check_charter_function_refs(
+            charter_files, gator_dir.parent
+        )
+        if stale_refs:
+            refs_str = ", ".join(stale_refs[:5])
+            if len(stale_refs) > 5:
+                refs_str += f" (+{len(stale_refs) - 5} more)"
+            warnings.append((
+                "stale-charter-refs",
+                f"Charter references function(s) not found in covered files: "
+                f"{refs_str}. Verify these weren't renamed or removed."
+            ))
+
+    # 6. New code functions without charter entries: if code added new def/func
+    #    lines but charter didn't add corresponding ### entries, warn.
+    #    Compares specific names, not just counts — adding an unrelated charter
+    #    entry doesn't suppress the warning for undocumented functions.
+    if has_code and has_charter:
+        new_code_funcs, new_charter_entries = _detect_new_functions(
+            staged_files, gator_dir.parent
+        )
+        charter_entry_names = set(new_charter_entries)
+        undocumented = [f for f in new_code_funcs if f not in charter_entry_names]
+        if undocumented:
+            funcs_str = ", ".join(undocumented[:5])
+            if len(undocumented) > 5:
+                funcs_str += f" (+{len(undocumented) - 5} more)"
+            warnings.append((
+                "new-functions-undocumented",
+                f"New function(s) in code ({funcs_str}) without matching ### "
+                f"entries in charters. Consider documenting them."
+            ))
+
+    # 7. Cross-module imports — now enforced as a hard block in
+    #    validate_hard_rules() when cross-cutting charter is not staged.
+    #    No soft warning needed; the hard check covers it.
+
+    return warnings
+
+
+# ---------------------------------------------------------------------------
+# Trailer assembly
+# ---------------------------------------------------------------------------
+
+def assemble_trailers(frontmatter, body, gator_dir, staged_files, override=None):
+    """Build Gator-* trailer lines from all available sources."""
+    charter_count, func_count = count_charters(gator_dir)
+    thread_count = count_threads(gator_dir)
+    generation = read_generation(gator_dir)
+    policy_version = read_policy_version(gator_dir)
+    issue_count = count_issues(gator_dir)
+
+    _, has_charter, _, _ = classify_staged_files(staged_files)
+    has_code, _, _, _ = classify_staged_files(staged_files)
+
+    trailers = []
+
+    # Core metrics (always from file state — deterministic)
+    trailers.append(f"Gator-Charters: {charter_count}")
+    trailers.append(f"Gator-Functions: {func_count}")
+    trailers.append(f"Gator-Threads: {thread_count}")
+    trailers.append(f"Gator-Generation: {generation}")
+
+    if policy_version:
+        trailers.append(f"Gator-Policy-Version: {policy_version}")
+    if issue_count > 0:
+        trailers.append(f"Gator-Issues: {issue_count}")
+
+    # Charter changed (from git diff --cached — deterministic)
+    if override == "charter-skip":
+        trailers.append("Gator-Charter-Changed: override-skip")
+        # Include PI attribution from approval metadata
+        meta_file = gator_dir / ".override-meta.json"
+        if meta_file.exists():
+            try:
+                meta = json.loads(meta_file.read_text(encoding="utf-8"))
+                approved_by = meta.get("approved_by", "")
+                block_id = meta.get("block_id", "")
+                if approved_by and approved_by != "legacy-override":
+                    trailers.append(f"Gator-Override-Approved-By: {approved_by}")
+                if block_id:
+                    trailers.append(f"Gator-Override-Block: {block_id}")
+                # Consume the meta file
+                meta_file.unlink(missing_ok=True)
+            except (json.JSONDecodeError, OSError):
+                pass
+    else:
+        trailers.append(f"Gator-Charter-Changed: {'yes' if has_charter else 'no'}")
+
+    # Change type (frontmatter preferred, fallback to inference)
+    change_type = frontmatter.get("change-type") or infer_change_type(body, has_code)
+    if change_type:
+        trailers.append(f"Gator-Change-Type: {change_type}")
+
+    # Decision tags (frontmatter preferred, fallback to body extraction)
+    tags = frontmatter.get("decision-tags")
+    if isinstance(tags, list):
+        tag_str = ",".join(tags)
+    elif isinstance(tags, str):
+        tag_str = tags
+    else:
+        extracted = extract_tags_from_body(body)
+        tag_str = ",".join(extracted) if extracted else ""
+    if tag_str:
+        trailers.append(f"Gator-Decision-Tags: {tag_str}")
+
+    # Significance (frontmatter preferred, fallback to inference)
+    significance = (
+        frontmatter.get("significance")
+        or infer_significance(body, has_charter, has_code)
+    )
+    trailers.append(f"Gator-Significance: {significance}")
+
+    # Agent attribution (frontmatter preferred, fallback to body)
+    agent = frontmatter.get("agent") or detect_agent_from_body(body)
+    if agent:
+        trailers.append(f"Gator-Agent: {agent}")
+
+    # Architect attribution (frontmatter preferred, fallback to body)
+    # Accepts both "architect:" (current) and "pi:" (legacy) from frontmatter
+    architect = frontmatter.get("architect") or frontmatter.get("pi") or detect_architect_from_body(body)
+    if architect:
+        trailers.append(f"Gator-Architect: {architect}")
+
+    return trailers
+
+
+# ---------------------------------------------------------------------------
+# Status snapshot
+# ---------------------------------------------------------------------------
+
+def build_status(gator_dir, staged_files, frontmatter, body, override=None):
+    """Build the status.json content."""
+    charter_count, func_count = count_charters(gator_dir)
+    thread_count = count_threads(gator_dir)
+    generation = read_generation(gator_dir)
+    policy_version = read_policy_version(gator_dir)
+    issue_count = count_issues(gator_dir)
+
+    has_code, has_charter, _, _ = classify_staged_files(staged_files)
+
+    change_type = frontmatter.get("change-type") or infer_change_type(body, has_code)
+    significance = (
+        frontmatter.get("significance")
+        or infer_significance(body, has_charter, has_code)
+    )
+
+    tags = frontmatter.get("decision-tags")
+    if isinstance(tags, str):
+        tags = [t.strip() for t in tags.split(",")]
+    elif not isinstance(tags, list):
+        tags = extract_tags_from_body(body)
+
+    agent = frontmatter.get("agent") or detect_agent_from_body(body)
+    architect = frontmatter.get("architect") or frontmatter.get("pi") or detect_architect_from_body(body)
+
+    charter_changed = "override-skip" if override == "charter-skip" else has_charter
+
+    return {
+        "repo": gator_dir.parent.name,
+        "timestamp": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "branch": get_current_branch(gator_dir.parent),
+        "charters": charter_count,
+        "functions": func_count,
+        "threads": thread_count,
+        "generation": generation,
+        "policy_version": policy_version,
+        "issues": issue_count,
+        "charter_changed": charter_changed,
+        "change_type": change_type,
+        "significance": significance,
+        "decision_tags": tags,
+        "agent": agent,
+        "architect": architect,
+        "draft_body": body.strip(),
+        "files_touched": [str(f) for f in staged_files],
+    }
+
+
+def write_status_json(gator_dir, status):
+    """Write .gator/status.json."""
+    status_file = gator_dir / "status.json"
+    status_file.write_text(
+        json.dumps(status, indent=2) + "\n",
+        encoding="utf-8",
+    )
+    return status_file
+
+
+def normalize_agent_name(agent_value):
+    """Normalize agent attribution to a filesystem-safe rolling-session key."""
+    if not agent_value:
+        return "unknown"
+    agent = str(agent_value).split(",")[0].strip().lower()
+    agent = re.sub(r"[^a-z0-9_-]+", "-", agent).strip("-")
+    return agent or "unknown"
+
+
+def _update_frontmatter(text, updates):
+    """Update flat frontmatter keys in a markdown document."""
+    if not text.startswith("---\n"):
+        return text
+    parts = text.split("---\n", 2)
+    if len(parts) < 3:
+        return text
+
+    header_lines = parts[1].splitlines()
+    seen = set()
+    new_lines = []
+    for line in header_lines:
+        if ":" not in line:
+            new_lines.append(line)
+            continue
+        key, _, value = line.partition(":")
+        key = key.strip()
+        if key in updates:
+            new_lines.append(f"{key}: {updates[key]}")
+            seen.add(key)
+        else:
+            new_lines.append(line)
+
+    for key, value in updates.items():
+        if key not in seen:
+            new_lines.append(f"{key}: {value}")
+
+    return "---\n" + "\n".join(new_lines) + "\n---\n" + parts[2]
+
+
+def _extract_note_lines(body, limit=8):
+    """Extract concise note lines from commit_draft body text."""
+    if not body:
+        return []
+    notes = []
+    for raw_line in body.splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("- "):
+            line = line[2:].strip()
+        notes.append(line)
+        if len(notes) >= limit:
+            break
+    return notes
+
+
+SESSION_TIMEOUT_HOURS = 4
+
+
+def _find_active_session(active_dir, repo_name, agent_key):
+    """Find an existing active session file that's still fresh (< SESSION_TIMEOUT_HOURS old).
+
+    Returns the path if a fresh session exists, None otherwise.
+    Session files are named <repo>-<agent>-<start_timestamp>.md.
+    """
+    prefix = f"{repo_name}-{agent_key}-"
+    candidates = sorted(
+        (f for f in active_dir.iterdir() if f.name.startswith(prefix) and f.suffix == ".md"),
+        key=lambda f: f.stat().st_mtime,
+        reverse=True,
+    ) if active_dir.is_dir() else []
+
+    if not candidates:
+        return None
+
+    newest = candidates[0]
+    age_hours = (datetime.now(timezone.utc).timestamp() - newest.stat().st_mtime) / 3600
+    if age_hours < SESSION_TIMEOUT_HOURS:
+        return newest
+    return None
+
+
+def _read_machine_id():
+    """Read the stable machine UUID from ~/.gator/machine-id.
+
+    The file has key: value lines (id, hostname, label, created).
+    Returns just the id value, not the whole file.
+    """
+    machine_id_path = Path.home() / ".gator" / "machine-id"
+    try:
+        for line in machine_id_path.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if line.startswith("id:"):
+                return line.partition(":")[2].strip()
+        return ""
+    except OSError:
+        return ""
+
+
+def _read_machine_label():
+    """Read the human-friendly machine label from ~/.gator/machine-id."""
+    machine_id_path = Path.home() / ".gator" / "machine-id"
+    try:
+        for line in machine_id_path.read_text(encoding="utf-8").splitlines():
+            line = line.strip()
+            if line.startswith("label:"):
+                return line.partition(":")[2].strip()
+        return ""
+    except OSError:
+        return ""
+
+
+def _derive_intent(entry):
+    """Derive a human-readable intent from the commit entry.
+
+    Derivation order:
+    1. Cleaned commit subject: strip mechanical prefixes (Fix:, Deploy:, etc.)
+    2. First substantive note if subject is empty or generic
+    3. Raw subject as fallback
+    """
+    subject = entry.get("subject", "")
+    # Strip mechanical prefixes that duplicate change_type
+    cleaned = re.sub(
+        r'^(Fix|Deploy|Blueprint|Docs|Refactor|Test|Plan):\s*',
+        '', subject, flags=re.IGNORECASE,
+    ).strip()
+    if cleaned:
+        return cleaned
+    # Fallback to first note
+    notes = entry.get("notes", [])
+    return notes[0] if notes else subject
+
+
+def parse_ledger(path):
+    """Parse a session ledger file into structured data.
+
+    Returns {"frontmatter": dict, "entries": list[dict], "raw_body": str}
+    where raw_body is the text after frontmatter (for reassembly).
+    """
+    result = {"frontmatter": {}, "entries": [], "raw_body": ""}
+    if not path or not path.exists():
+        return result
+
+    text = path.read_text(encoding="utf-8", errors="replace")
+    # Normalize CRLF to LF — Windows write_text() produces CRLF,
+    # but our delimiters and regexes assume LF.
+    text = text.replace("\r\n", "\n")
+
+    # Parse frontmatter
+    if text.startswith("---\n"):
+        parts = text.split("---\n", 2)
+        if len(parts) >= 3:
+            for line in parts[1].splitlines():
+                if ":" in line:
+                    key, _, value = line.partition(":")
+                    result["frontmatter"][key.strip()] = value.strip()
+            result["raw_body"] = parts[2]
+
+    # Parse commit entry blocks from body
+    body = result["raw_body"]
+    heading_re = re.compile(r"^### (\S+) - (.+)$")
+    kv_re = re.compile(r"^- ([a-z][a-z0-9-]*): (.+)$")
+    section_re = re.compile(r"^([A-Z][a-zA-Z-]+):$")
+    item_re = re.compile(r"^- (.+)$")
+
+    current_entry = None
+    current_section = None
+
+    for line in body.splitlines():
+        heading_match = heading_re.match(line)
+        if heading_match:
+            if current_entry:
+                result["entries"].append(current_entry)
+            current_entry = {
+                "short_commit": heading_match.group(1),
+                "subject": heading_match.group(2),
+                "commit": "",
+                "commit_index": 0,
+                "timestamp": "",
+                "previous_commit": None,
+                "branch": "",
+                "change_type": "",
+                "significance": "",
+                "decision_tags": [],
+                "charter_changed": False,
+                "files_touched": [],
+                "files_touched_source": "",
+                "snippet_id": "",
+                "notes": [],
+            }
+            current_section = None
+            continue
+
+        if current_entry is None:
+            continue
+
+        section_match = section_re.match(line)
+        if section_match:
+            current_section = section_match.group(1)
+            continue
+
+        if current_section:
+            item_match = item_re.match(line)
+            if item_match:
+                item_value = item_match.group(1)
+                if current_section == "Files-Touched":
+                    current_entry["files_touched"].append(item_value)
+                elif current_section == "Notes":
+                    current_entry["notes"].append(item_value)
+                continue
+            # Non-item line ends the section block
+            if line.strip():
+                current_section = None
+
+        kv_match = kv_re.match(line)
+        if kv_match:
+            current_section = None  # key-value ends any active section
+            key, value = kv_match.group(1), kv_match.group(2)
+            if key == "commit":
+                current_entry["commit"] = value
+            elif key == "commit-index":
+                try:
+                    current_entry["commit_index"] = int(value)
+                except ValueError:
+                    pass
+            elif key == "timestamp":
+                current_entry["timestamp"] = value
+            elif key == "previous-commit-in-session":
+                current_entry["previous_commit"] = value if value != "~" else None
+            elif key == "branch":
+                current_entry["branch"] = value
+            elif key == "change-type":
+                current_entry["change_type"] = value
+            elif key == "significance":
+                current_entry["significance"] = value
+            elif key == "decision-tags":
+                current_entry["decision_tags"] = [t.strip() for t in value.split(",") if t.strip()]
+            elif key == "charter-changed":
+                current_entry["charter_changed"] = value.lower() in ("true", "yes")
+            elif key == "files-touched-source":
+                current_entry["files_touched_source"] = value
+            elif key == "snippet-id":
+                current_entry["snippet_id"] = value
+
+    if current_entry:
+        result["entries"].append(current_entry)
+
+    return result
+
+
+def build_commit_entry(gator_dir, status, session_meta):
+    """Build a canonical entry_record dict from status.json + git state + session_meta.
+
+    session_meta is the parsed ledger frontmatter dict (or empty dict for new sessions).
+    This function never reads the ledger file itself — the caller provides session_meta.
+    This is the single source of truth for both ledger blocks and snippets.
+    """
+    repo_root = gator_dir.parent
+    latest = git("log", "-1", "--pretty=format:%H%n%h%n%s", cwd=repo_root).splitlines()
+    if len(latest) < 3:
+        return None
+    commit_hash, short_hash, subject = latest[0], latest[1], latest[2]
+
+    timestamp = status.get("timestamp") or datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    branch = status.get("branch") or get_current_branch(repo_root)
+    architect = status.get("architect") or status.get("pi") or ""
+
+    # previous_commit from ledger frontmatter (not body grep)
+    previous_commit = session_meta.get("last-commit-hash") or None
+
+    # commit_index from ledger frontmatter
+    try:
+        commit_count = int(session_meta.get("commits", 0))
+    except (ValueError, TypeError):
+        commit_count = 0
+    commit_index = commit_count + 1
+
+    # files_touched: prefer status.json, fall back to git diff-tree
+    files_touched = status.get("files_touched") or []
+    files_touched_source = "status-json"
+    if not files_touched:
+        try:
+            dt_output = git("diff-tree", "--no-commit-id", "--name-only", "-r", "HEAD", cwd=repo_root)
+            files_touched = [f for f in dt_output.splitlines() if f.strip()]
+            files_touched_source = "diff-tree"
+        except Exception:
+            files_touched = []
+            files_touched_source = "unavailable"
+
+    snippet_id = f"snippet-{commit_hash[:13]}"
+    notes = _extract_note_lines(status.get("draft_body", ""))
+
+    return {
+        "commit": commit_hash,
+        "short_commit": short_hash,
+        "subject": subject,
+        "timestamp": timestamp,
+        "branch": branch,
+        "architect": architect,
+        "change_type": status.get("change_type") or "",
+        "significance": status.get("significance") or "",
+        "decision_tags": status.get("decision_tags") or [],
+        "charter_changed": status.get("charter_changed", False),
+        "commit_index": commit_index,
+        "previous_commit": previous_commit,
+        "files_touched": files_touched,
+        "files_touched_source": files_touched_source,
+        "snippet_id": snippet_id,
+        "notes": notes,
+    }
+
+
+def render_ledger_block(entry):
+    """Render a ledger commit entry block from the canonical entry_record dict.
+
+    Uses two element types:
+    - Key-value lines: '- key: value' for scalar fields
+    - Section blocks: 'Section-Name:' followed by '- item' lines for lists
+    """
+    prev = entry["previous_commit"] or "~"
+    lines = [
+        f"### {entry['short_commit']} - {entry['subject']}",
+        f"- commit-index: {entry['commit_index']}",
+        f"- timestamp: {entry['timestamp']}",
+        f"- commit: {entry['commit']}",
+        f"- previous-commit-in-session: {prev}",
+        f"- branch: {entry['branch']}",
+        f"- change-type: {entry['change_type']}",
+        f"- significance: {entry['significance']}",
+        f"- decision-tags: {','.join(entry['decision_tags'])}",
+        f"- charter-changed: {entry['charter_changed']}",
+        f"- files-touched-source: {entry['files_touched_source']}",
+        f"- snippet-id: {entry['snippet_id']}",
+    ]
+
+    if entry["files_touched"]:
+        lines.append("Files-Touched:")
+        for f in entry["files_touched"]:
+            lines.append(f"- {f}")
+
+    if entry["notes"]:
+        lines.append("Notes:")
+        for note in entry["notes"]:
+            lines.append(f"- {note}")
+
+    lines.append("")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def _infer_vendor_from_agent(agent_key):
+    """Best-effort vendor inference from the agent key. Returns (vendor, model) tuple."""
+    key = (agent_key or "").lower()
+    if "claude" in key:
+        return "anthropic", agent_key
+    if "codex" in key or "gpt" in key or "openai" in key or key == "o3" or key == "o4-mini":
+        return "openai", agent_key
+    if "gemini" in key:
+        return "google", agent_key
+    return "unknown", agent_key
+
+
+def render_snippet(entry, session_meta):
+    """Render a durable session snippet from the canonical entry record.
+
+    Returns the full markdown string for the snippet file.
+    """
+    session_id = session_meta.get("session-id", "")
+    started_at = session_meta.get("started-at", entry["timestamp"])
+    agent_key = session_meta.get("agent", "")
+    # Architect from the current commit's entry, not session start
+    architect = entry.get("architect", session_meta.get("architect", ""))
+    machine_id = session_meta.get("machine-id", "")
+    vendor_inferred, model_inferred = _infer_vendor_from_agent(agent_key)
+
+    prev = entry["previous_commit"] or "~"
+
+    # Build YAML frontmatter
+    fm_lines = [
+        "---",
+        "schema: gator-session-snippet-v1",
+        "type: session-snippet",
+        f"snippet-id: {entry['snippet_id']}",
+        f"session-id: {session_id}",
+        f"repo: {session_meta.get('repo', '')}",
+        f"commit: {entry['commit']}",
+        f"short-commit: {entry['short_commit']}",
+        f"previous-commit-in-session: {prev}",
+        f"commit-index: {entry['commit_index']}",
+        f"agent: {agent_key}",
+        f"architect: {architect}",
+        f"branch: {entry['branch']}",
+        f"started-at: {started_at}",
+        f"ended-at: {entry['timestamp']}",
+        f"vendor-inferred: {vendor_inferred}",
+        f"model-inferred: {model_inferred}",
+    ]
+
+    # decision-tags as YAML flow list
+    tags = entry["decision_tags"]
+    if tags:
+        fm_lines.append(f"decision-tags: [{', '.join(tags)}]")
+    else:
+        fm_lines.append("decision-tags: []")
+
+    fm_lines.append(f"change-type: {entry['change_type']}")
+    fm_lines.append(f"significance: {entry['significance']}")
+    fm_lines.append(f"charter-changed: {'yes' if entry['charter_changed'] else 'no'}")
+
+    # files-touched as YAML block list
+    if entry["files_touched"]:
+        fm_lines.append("files-touched:")
+        for f in entry["files_touched"]:
+            fm_lines.append(f"  - {f}")
+    else:
+        fm_lines.append("files-touched: []")
+
+    fm_lines.append(f"files-touched-source: {entry['files_touched_source']}")
+
+    if machine_id:
+        fm_lines.append(f"machine-id: {machine_id}")
+
+    fm_lines.append("---")
+
+    # Build body
+    body_lines = [""]
+
+    # ## Interval
+    if entry["commit_index"] == 1:
+        interval_text = "First commit in session."
+    else:
+        total = session_meta.get("commits", "?")
+        # total is the count *before* this commit, so the session will have commit_index commits after
+        interval_text = (
+            f"Session commit {entry['commit_index']}. "
+            f"Covers the working interval since `{entry['short_commit'] if not entry['previous_commit'] else entry['previous_commit'][:7]}`."
+        )
+    body_lines.extend(["## Interval", "", interval_text, ""])
+
+    # ## Notes
+    if entry["notes"]:
+        body_lines.append("## Notes")
+        body_lines.append("")
+        for note in entry["notes"]:
+            body_lines.append(f"- {note}")
+        body_lines.append("")
+
+    # ## Files Touched
+    if entry["files_touched"]:
+        body_lines.append("## Files Touched")
+        body_lines.append("")
+        for f in entry["files_touched"]:
+            body_lines.append(f"- `{f}`")
+        body_lines.append("")
+
+    # ## Commit
+    body_lines.extend([
+        "## Commit",
+        "",
+        f"- `{entry['short_commit']}` {entry['subject']}",
+        "",
+    ])
+
+    return "\n".join(fm_lines) + "\n" + "\n".join(body_lines)
+
+
+def render_snippet_json(entry, session_meta):
+    """Render a session snippet as JSON (v2 canonical format).
+
+    Immutable once committed. Transcript anchors live in the enrichment
+    overlay, not here. Field order is deliberate: architect-relevant
+    fields first, structural fields next, transcript join keys last.
+    """
+    from collections import OrderedDict
+
+    agent_key = session_meta.get("agent", "")
+    vendor_inferred, model_inferred = _infer_vendor_from_agent(agent_key)
+
+    snippet = OrderedDict([
+        ("schema", "gator-session-snippet-v2"),
+        ("type", "session_snippet"),
+        # --- architect-relevant (top) ---
+        ("architect", entry.get("architect", session_meta.get("architect", ""))),
+        ("agent", agent_key),
+        ("repo", session_meta.get("repo", "")),
+        ("branch", entry["branch"]),
+        ("commit", entry["commit"]),
+        ("short_commit", entry["short_commit"]),
+        ("started_at", session_meta.get("started-at", entry["timestamp"])),
+        ("ended_at", entry["timestamp"]),
+        ("intent", _derive_intent(entry)),
+        ("notes", entry["notes"]),
+        ("files_touched", entry["files_touched"]),
+        # --- identity and lineage ---
+        ("snippet_id", entry["snippet_id"]),
+        ("session_id", session_meta.get("session-id", "")),
+        ("previous_commit_in_session", entry["previous_commit"]),
+        ("commit_index", entry["commit_index"]),
+        ("decision_tags", entry["decision_tags"]),
+        ("change_type", entry["change_type"]),
+        ("significance", entry["significance"]),
+        ("charter_changed", entry["charter_changed"]),
+        ("machine_id", session_meta.get("machine-id", "")),
+        ("machine_label", _read_machine_label()),
+        ("vendor_inferred", vendor_inferred),
+        ("model_inferred", model_inferred),
+        ("files_touched_source", entry["files_touched_source"]),
+        # --- transcript join keys (null at commit time, never mutated) ---
+        ("transcript_session_id", None),
+        ("transcript_ref", None),
+    ])
+    return json.dumps(snippet, indent=2, default=str)
+
+
+def _reassemble_ledger(session_meta, raw_body, new_block, entry):
+    """Reassemble a complete ledger file from updated frontmatter + existing body + new block.
+
+    Returns the full file content as a string.
+    """
+    # Update frontmatter fields
+    updated_meta = dict(session_meta)
+    updated_meta["last-updated"] = entry["timestamp"]
+    updated_meta["commits"] = str(entry["commit_index"])
+    updated_meta["last-commit-hash"] = entry["commit"]
+    updated_meta["architect"] = entry.get("architect", session_meta.get("architect", ""))
+    updated_meta["branch"] = entry["branch"]
+
+    # Render frontmatter
+    fm_lines = ["---"]
+    for key, value in updated_meta.items():
+        fm_lines.append(f"{key}: {value}")
+    fm_lines.append("---")
+
+    return "\n".join(fm_lines) + "\n" + raw_body + new_block
+
+
+def record_commit_and_emit_snippet(gator_dir, status):
+    """Record a commit to the session ledger and emit a durable snippet.
+
+    Returns (ledger_path, snippet_path) or (ledger_path, None) if snippet
+    emission fails or commit was already recorded (idempotent).
+    """
+    repo_root = gator_dir.parent
+    agent_key = normalize_agent_name(status.get("agent"))
+    repo_name = repo_root.name
+    active_dir = gator_dir / "sessions" / ACTIVE_SESSIONS_DIRNAME
+    active_dir.mkdir(parents=True, exist_ok=True)
+
+    # Find or create ledger file
+    ledger_path = _find_active_session(active_dir, repo_name, agent_key)
+    is_new_session = ledger_path is None
+
+    if is_new_session:
+        start_ts = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M%S-%f")
+        ledger_path = active_dir / f"{repo_name}-{agent_key}-{start_ts}.md"
+
+    # Parse existing ledger (or empty for new session)
+    parsed = parse_ledger(ledger_path if not is_new_session else None)
+    session_meta = parsed["frontmatter"]
+    raw_body = parsed["raw_body"]
+
+    # Idempotency: if HEAD matches last-commit-hash, this commit is already recorded
+    try:
+        head_hash = git("rev-parse", "HEAD", cwd=repo_root).strip()
+    except Exception:
+        return (ledger_path, None)
+
+    if session_meta.get("last-commit-hash") == head_hash:
+        return (ledger_path, None)  # already recorded
+
+    # Initialize session_meta for new sessions
+    timestamp = status.get("timestamp") or datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    architect = status.get("architect") or status.get("pi") or ""
+    branch = status.get("branch") or get_current_branch(repo_root)
+
+    if is_new_session:
+        session_id = datetime.now(timezone.utc).strftime(f"%Y%m%d-{agent_key}-%H%M%S")
+        machine_id = _read_machine_id()
+        session_meta = {
+            "schema": "gator-active-session-ledger-v1",
+            "type": "active-session-ledger",
+            "status": "active",
+            "session-id": session_id,
+            "repo": repo_name,
+            "agent": agent_key,
+            "architect": architect,
+            "branch": branch,
+            "started-at": timestamp,
+            "last-updated": timestamp,
+            "commits": "0",
+            "last-commit-hash": "",
+            "machine-id": machine_id,
+        }
+        raw_body = "\n# Active Session\n\n## Commit Log\n\n"
+
+    # Build the canonical entry record
+    entry = build_commit_entry(gator_dir, status, session_meta)
+    if entry is None:
+        return (ledger_path, None)
+
+    # Render ledger block and reassemble file atomically
+    block = render_ledger_block(entry)
+    full_content = _reassemble_ledger(session_meta, raw_body, block, entry)
+
+    # Atomic write: temp file + rename
+    tmp_path = ledger_path.with_suffix(".tmp")
+    try:
+        tmp_path.write_text(full_content, encoding="utf-8", newline="\n")
+        os.replace(str(tmp_path), str(ledger_path))
+    except OSError as e:
+        print(f"Warning: ledger write failed: {e}", file=sys.stderr)
+        try:
+            tmp_path.unlink(missing_ok=True)
+        except OSError:
+            pass
+        return (ledger_path, None)
+
+    # Emit snippet (secondary — failure does not corrupt ledger)
+    snippet_path = None
+    try:
+        snippets_dir = gator_dir / "session-snippets"
+        snippets_dir.mkdir(parents=True, exist_ok=True)
+
+        date_str = timestamp[:10]  # YYYY-MM-DD from ISO timestamp
+        snippet_filename = f"{date_str}-{repo_name}-{entry['commit'][:13]}.json"
+        snippet_path = snippets_dir / snippet_filename
+
+        snippet_content = render_snippet_json(entry, session_meta)
+
+        if snippet_path.exists():
+            existing = snippet_path.read_text(encoding="utf-8", errors="replace")
+            if existing == snippet_content:
+                pass  # idempotent: same content, no-op
+            else:
+                print(
+                    f"Warning: Snippet {entry['snippet_id']} already exists with different content. Skipping.",
+                    file=sys.stderr,
+                )
+                snippet_path = None
+        else:
+            snippet_path.write_text(snippet_content, encoding="utf-8", newline="\n")
+    except Exception as e:
+        print(
+            f"Warning: Snippet emission failed for {entry['short_commit']}: {e}. Ledger entry preserved.",
+            file=sys.stderr,
+        )
+        snippet_path = None
+
+    return (ledger_path, snippet_path)
+
+
+# ---------------------------------------------------------------------------
+# Commit summary (structural audit trail)
+# ---------------------------------------------------------------------------
+
+def write_commit_summary(gator_dir, frontmatter, body, trailers, commit_msg_line):
+    """Write a commit-level summary to .gator/sessions/.
+
+    This is the structural audit trail — written automatically on every
+    commit, no manual command needed. Each commit gets a small markdown
+    file with the metadata from commit_draft.md and the trailer values.
+
+    The archaeology-based summaries (gator sessions commit-summaries)
+    are the enrichment layer — they add session-level context from raw
+    vendor logs. This function provides the baseline that's always present.
+    """
+    sessions_dir = gator_dir / "sessions"
+    sessions_dir.mkdir(parents=True, exist_ok=True)
+
+    now = datetime.now(timezone.utc)
+    timestamp = now.strftime("%Y-%m-%dT%H:%M:%SZ")
+    date_str = now.strftime("%Y-%m-%d")
+    time_slug = now.strftime("%H%M%S")
+    repo_name = gator_dir.parent.name
+
+    filename = f"{date_str}-{repo_name}-commit-{time_slug}.md"
+    summary_path = sessions_dir / filename
+
+    # Build trailer dict for frontmatter
+    trailer_dict = {}
+    for t in trailers:
+        if ": " in t:
+            key, _, value = t.partition(": ")
+            trailer_dict[key] = value
+
+    # Extract decisions from body (same signals as extract_tags_from_body
+    # but captures the full line for audit value)
+    decisions = []
+    if body:
+        for line in body.splitlines():
+            stripped = line.strip()
+            if not stripped or stripped.startswith("#"):
+                continue
+            # Lines with decision tags or Architect attribution
+            if "[#" in stripped or stripped.endswith(("— AG",)):
+                decisions.append(stripped)
+            # Lines starting with decision-like bullets
+            elif stripped.startswith("- ") and len(stripped) > 20:
+                decisions.append(stripped[2:])
+
+    # Vendor attribution — the agent trailer carries the vendor identity
+    agent = trailer_dict.get('Gator-Agent', frontmatter.get('agent', ''))
+    vendor = agent.split(",")[0] if agent else ""  # "claude,codex" → "claude"
+
+    lines = [
+        "---",
+        "schema: gator-commit-summary-v1",
+        f"type: commit",
+        f"date: {date_str}",
+        f"timestamp: {timestamp}",
+        f"repo: {repo_name}",
+        f"vendor: {vendor}",
+        f"message: {frontmatter.get('message', commit_msg_line)!s}",
+        f"change-type: {trailer_dict.get('Gator-Change-Type', '')}",
+        f"significance: {trailer_dict.get('Gator-Significance', '')}",
+        f"decision-tags: {trailer_dict.get('Gator-Decision-Tags', '')}",
+        f"agent: {trailer_dict.get('Gator-Agent', '')}",
+        f"architect: {trailer_dict.get('Gator-Architect', trailer_dict.get('Gator-PI', ''))}",
+        f"charter-changed: {trailer_dict.get('Gator-Charter-Changed', '')}",
+        "---",
+        "",
+    ]
+
+    if decisions:
+        lines.append("## Decisions")
+        lines.append("")
+        for d in decisions[:10]:
+            lines.append(f"- {d}")
+        lines.append("")
+
+    if body and body.strip():
+        lines.append("## Session Notes")
+        lines.append("")
+        # Include body but cap at 30 lines to keep summaries small
+        body_lines = body.strip().splitlines()[:30]
+        lines.extend(body_lines)
+        if len(body.strip().splitlines()) > 30:
+            lines.append("")
+            lines.append(f"*({len(body.strip().splitlines()) - 30} more lines in commit_draft.md)*")
+        lines.append("")
+
+    try:
+        summary_path.write_text("\n".join(lines), encoding="utf-8")
+        # Stage it so it's included in this commit
+        git("add", str(summary_path), cwd=gator_dir.parent)
+    except OSError:
+        pass  # Non-fatal — don't block the commit for a summary write failure
+
+
+# ---------------------------------------------------------------------------
+# Whiteboard output
+# ---------------------------------------------------------------------------
+
+def write_whiteboard(gator_dir, failures, warnings, override,
+                     enforcement_level="strict"):
+    """Write findings to .gator/whiteboard.md."""
+    whiteboard = gator_dir / "whiteboard.md"
+    timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    lines = [
+        "# Enforcer Whiteboard",
+        "",
+        f"Last updated: {timestamp} (pre-commit hook)",
+        "",
+    ]
+
+    if enforcement_level == "off":
+        lines.append("**Enforcement level: off** — governance checks disabled.")
+        lines.append("")
+    elif enforcement_level == "warn":
+        lines.append("**Enforcement level: warn** — findings are advisory, "
+                      "commit was not blocked.")
+        lines.append("")
+
+    if failures:
+        lines.append("## Blocked")
+        lines.append("")
+        for rule, msg in failures:
+            lines.append(f"- **{rule}**: {msg}")
+        lines.append("")
+
+    if warnings:
+        lines.append("## Warnings")
+        lines.append("")
+        for rule, msg in warnings:
+            lines.append(f"- **{rule}**: {msg}")
+        lines.append("")
+
+    if override:
+        lines.append("## Overrides")
+        lines.append("")
+        override_detail = f"{override} (committed at {timestamp})"
+        meta_file = gator_dir / ".override-meta.json"
+        if meta_file.exists():
+            try:
+                meta = json.loads(meta_file.read_text(encoding="utf-8"))
+                approved_by = meta.get("approved_by", "")
+                reason = meta.get("reason", "")
+                block_id = meta.get("block_id", "")
+                if approved_by and approved_by != "legacy-override":
+                    override_detail += f" — approved by {approved_by}"
+                if reason:
+                    override_detail += f" — reason: {reason}"
+                if block_id:
+                    override_detail += f" — block: {block_id}"
+            except (json.JSONDecodeError, OSError):
+                pass
+        lines.append(f"- **Gator-Override**: {override_detail}")
+        lines.append("")
+
+    if not failures and not warnings and not override:
+        lines.append("No findings.")
+        lines.append("")
+
+    whiteboard.write_text("\n".join(lines), encoding="utf-8")
+    return whiteboard
+
+
+# ---------------------------------------------------------------------------
+# Commit issues output (lint findings for PI review)
+# ---------------------------------------------------------------------------
+
+def write_commit_issues(gator_dir, findings):
+    """Write lint findings to .gator/commit_issues.md for PI review.
+
+    This is the PI-facing surface for reviewing dangerous code findings.
+    The PI reads this, decides which are intentional, and the agent writes
+    approvals to lint-allow.json. Separate from whiteboard.md (which is
+    for enforcer/governance findings).
+    """
+    ci_file = gator_dir / "commit_issues.md"
+    timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    lines = [
+        "# Commit Issues",
+        "",
+        f"Lint findings from pre-commit hook — {timestamp}",
+        "",
+        "Review each finding. If intentional, tell the agent to approve it.",
+        "The agent will add the approval to `.gator/lint-allow.json` and retry the commit.",
+        "",
+    ]
+
+    for f in findings:
+        sev = f["severity"]
+        lines.append(f"- **{sev}** `{f['rule']}` in `{f['file']}:{f['line']}`")
+        lines.append(f"  {f['message']}")
+        if f.get("match"):
+            lines.append(f"  `> {f['match']}`")
+        lines.append("")
+
+    ci_file.write_text("\n".join(lines), encoding="utf-8")
+    return ci_file
+
+
+def clear_commit_issues(gator_dir):
+    """Clear commit_issues.md after a clean pass."""
+    ci_file = gator_dir / "commit_issues.md"
+    if ci_file.exists():
+        ci_file.write_text("# Commit Issues\n\nNo findings.\n", encoding="utf-8")
+
+
+def clear_lint_allowlist(gator_dir, repo_root):
+    """Clear lint-allow.json after a successful commit.
+
+    The allowlist is a one-shot approval mechanism. Once the commit lands,
+    the dangerous code is in the codebase and future diffs won't show it
+    as new — so the allowlist entry is no longer needed. Clear it to
+    prevent stale approvals from accumulating.
+    """
+    allowlist_file = gator_dir / "lint-allow.json"
+    if not allowlist_file.exists():
+        return
+    try:
+        entries = json.loads(allowlist_file.read_text(encoding="utf-8"))
+        if entries:  # Only clear if non-empty (was actually used)
+            allowlist_file.write_text("[]\n", encoding="utf-8")
+            stage_file(allowlist_file, repo_root)
+    except (json.JSONDecodeError, OSError):
+        pass
+
+
+# ---------------------------------------------------------------------------
+# Phase 1: validate (called from pre-commit hook)
+# ---------------------------------------------------------------------------
+
+def _read_enforcement_level(gator_dir):
+    """Read enforcement level from .gator/config.json. Default: strict."""
+    config_path = gator_dir / "config.json"
+    if config_path.exists():
+        try:
+            config = json.loads(config_path.read_text(encoding="utf-8"))
+            level = config.get("enforcement_level", "strict")
+            if level in ("strict", "warn", "off"):
+                return level
+        except (json.JSONDecodeError, OSError):
+            pass
+    return "strict"
+
+
+def phase_validate():
+    """Pre-commit validation. Exit 0 to allow, exit 1 to block."""
+    repo_root = find_gator_root()
+    if not repo_root:
+        # Not a gator repo — allow the commit silently
+        sys.exit(0)
+
+    gator_dir = repo_root / ".gator"
+    staged_files = get_staged_files(repo_root)
+
+    # Read enforcement level
+    enforcement = _read_enforcement_level(gator_dir)
+
+    # If enforcement is off, skip governance checks but clear stale artifacts
+    # so the repo doesn't misrepresent its posture. Trailers and cleanup
+    # still run in their own phases.
+    if enforcement == "off":
+        clear_commit_issues(gator_dir)
+        ci_file = gator_dir / "commit_issues.md"
+        if ci_file.exists():
+            stage_file(ci_file, repo_root)
+        wb = write_whiteboard(gator_dir, [], [], None, enforcement_level="off")
+        stage_file(wb, repo_root)
+        status = build_status(gator_dir, staged_files, {}, "", None)
+        sf = write_status_json(gator_dir, status)
+        stage_file(sf, repo_root)
+        print()
+        print("  gator pre-commit: enforcement OFF — governance checks skipped")
+        print()
+        sys.exit(0)
+
+    # Parse commit_draft
+    frontmatter, body, parse_error = parse_commit_draft(gator_dir)
+
+    # Check override — read once, pass everywhere, file deleted atomically
+    override = check_override(gator_dir)
+
+    # Validate governance rules
+    failures = validate_hard_rules(staged_files, frontmatter, body, parse_error, gator_dir, override)
+    warnings = validate_soft_rules(staged_files, frontmatter, body, gator_dir)
+
+    # Run Layer 1 mechanical lint on staged files (dangerous code patterns)
+    lint_findings = run_layer1_lint(staged_files, repo_root)
+    lint_failures = []
+    lint_warnings = []
+    for finding in lint_findings:
+        if finding["severity"] in ("CRITICAL", "HIGH"):
+            lint_failures.append(finding)
+            failures.append((
+                finding["rule"],
+                f"{finding['file']}:{finding['line']} — {finding['message']}"
+                + (f"\n       > {finding['match']}" if finding.get("match") else ""),
+            ))
+        else:
+            lint_warnings.append(finding)
+            warnings.append((
+                finding["rule"],
+                f"{finding['file']}:{finding['line']} — {finding['message']}",
+            ))
+
+    # Write lint findings to commit_issues.md (PI reviews these to approve)
+    if lint_failures or lint_warnings:
+        ci_file = write_commit_issues(gator_dir, lint_failures + lint_warnings)
+        stage_file(ci_file, repo_root)
+    else:
+        # Clear any stale commit_issues from a previous blocked attempt
+        clear_commit_issues(gator_dir)
+
+    # Warn mode: move failures to warnings (still report, but don't block)
+    if enforcement == "warn" and failures:
+        warnings.extend(failures)
+        failures = []
+
+    # Write status.json (even on failure — captures the state at attempt time)
+    status = build_status(gator_dir, staged_files, frontmatter, body, override)
+    status_file = write_status_json(gator_dir, status)
+    stage_file(status_file, repo_root)
+
+    # Write whiteboard (always — clears stale findings on clean pass)
+    wb_file = write_whiteboard(gator_dir, failures, warnings, override,
+                               enforcement_level=enforcement)
+    stage_file(wb_file, repo_root)
+
+    # Output
+    if failures:
+        print()
+        print("  gator pre-commit: BLOCKED")
+        print()
+        for rule, msg in failures:
+            print(f"  ✗ {rule}: {msg}")
+        if warnings:
+            print()
+            for rule, msg in warnings:
+                print(f"  ⚠ {rule}: {msg}")
+        print()
+        if lint_failures:
+            print("  Lint findings written to .gator/commit_issues.md")
+            print("  PI: review findings, approve with lint-allow.json, retry commit")
+        else:
+            print("  Findings written to .gator/whiteboard.md")
+
+        # Write override request for PI approval flow
+        charter_failures = [
+            r for r, _ in failures
+            if r in ("charter-alongside-code", "cross-cutting-missing", "charter-index-gap")
+        ]
+        if charter_failures:
+            _, has_charter, code_files, _ = classify_staged_files(staged_files)
+            request = _write_override_request(
+                gator_dir, charter_failures[0], code_files
+            )
+            block_id = request["block_id"]
+            print()
+            print("  ┌─────────────────────────────────────────────────────────┐")
+            print("  │ STOP. Do not override this yourself.                   │")
+            print("  │                                                        │")
+            print("  │ Present these findings to the PI. The PI decides:      │")
+            print("  │   1. Update the affected charters and retry the commit │")
+            print("  │   2. Approve override:                                 │")
+            print(f"  │      python .gator/scripts/gator-approve.py           │")
+            print("  │                                                        │")
+            print("  │ You may NOT create override files yourself.            │")
+            print("  │ You may NOT run gator-approve.py yourself.             │")
+            print("  │ Unauthorized self-approval is a governance violation.  │")
+            print("  └─────────────────────────────────────────────────────────┘")
+            print()
+            print(f"  Block ID: {block_id}")
+
+        print()
+        sys.exit(1)
+
+    # Commit is passing — consume and clear lint-allow.json (one-shot approvals)
+    clear_lint_allowlist(gator_dir, repo_root)
+
+    if warnings:
+        print()
+        if enforcement == "warn":
+            print("  gator pre-commit: PASS (enforcement: warn — findings are advisory)")
+        else:
+            print("  gator pre-commit: PASS (with warnings)")
+        print()
+        for rule, msg in warnings:
+            print(f"  ⚠ {rule}: {msg}")
+        print()
+
+    if override:
+        print()
+        print(f"  gator pre-commit: OVERRIDE ({override})")
+        print(f"  Override recorded in trailers and whiteboard.md")
+        print()
+
+    sys.exit(0)
+
+
+# ---------------------------------------------------------------------------
+# Phase 2: trailers (called from commit-msg hook)
+# ---------------------------------------------------------------------------
+
+def phase_trailers(msg_file_path):
+    """Append Gator-* trailers to the commit message file."""
+    repo_root = find_gator_root()
+    if not repo_root:
+        # Not a gator repo — leave message alone
+        sys.exit(0)
+
+    gator_dir = repo_root / ".gator"
+    staged_files = get_staged_files(repo_root)
+    frontmatter, body, _ = parse_commit_draft(gator_dir)
+
+    # Read override from status.json (written by validate phase, which
+    # already consumed and deleted the .override file)
+    override = None
+    status_file = gator_dir / "status.json"
+    if status_file.exists():
+        try:
+            status_data = json.loads(status_file.read_text(encoding="utf-8"))
+            charter_changed = status_data.get("charter_changed")
+            if charter_changed == "override-skip":
+                override = "charter-skip"
+        except (json.JSONDecodeError, OSError):
+            pass
+
+    # Build trailers
+    trailers = assemble_trailers(frontmatter, body, gator_dir, staged_files, override)
+
+    # Read current message (the -m message the agent provided, if any)
+    msg_path = Path(msg_file_path)
+    current_msg = msg_path.read_text(encoding="utf-8", errors="replace")
+
+    # --- Assemble message from commit_draft.md when it has real content ---
+    draft_message = (frontmatter.get("message") or "").strip()
+    # Strip only the exact stub heading — preserve all other #-prefixed
+    # lines (e.g. "#123 fix", "## Refactored auth", "#security follow-up").
+    _STUB_HEADING = "# Session Change Log"
+    draft_body_lines = []
+    for l in (body or "").splitlines():
+        if l.strip() == _STUB_HEADING:
+            continue
+        draft_body_lines.append(l)
+    # Strip leading/trailing blank lines
+    while draft_body_lines and not draft_body_lines[0].strip():
+        draft_body_lines.pop(0)
+    while draft_body_lines and not draft_body_lines[-1].strip():
+        draft_body_lines.pop()
+    draft_has_content = bool(draft_message or draft_body_lines)
+
+    if draft_has_content:
+        # commit_draft.md is the source of truth for the commit message
+        assembled_lines = []
+        if draft_message:
+            assembled_lines.append(draft_message)
+        elif draft_body_lines:
+            # Use first non-heading body line as summary if no message field
+            assembled_lines.append(draft_body_lines[0])
+            draft_body_lines = draft_body_lines[1:]
+        assembled_lines.append("")  # blank line after summary
+
+        if draft_body_lines:
+            assembled_lines.extend(draft_body_lines)
+            assembled_lines.append("")  # blank line after body
+
+        # Append trailers
+        final_lines = assembled_lines + trailers + [""]
+    else:
+        # Fallback: use whatever -m the agent provided (backward compatible)
+        # Strip any existing Gator-* trailers (in case of retry)
+        clean_lines = []
+        for line in current_msg.splitlines():
+            if not line.startswith("Gator-"):
+                clean_lines.append(line)
+        # Remove trailing blank lines
+        while clean_lines and not clean_lines[-1].strip():
+            clean_lines.pop()
+
+        # Assemble final message
+        final_lines = clean_lines + [""] + trailers + [""]
+
+    msg_path.write_text("\n".join(final_lines), encoding="utf-8")
+
+    sys.exit(0)
+
+
+def phase_cleanup():
+    """Reset commit_draft.md after a successful commit."""
+    repo_root = find_gator_root()
+    if not repo_root:
+        sys.exit(0)
+
+    gator_dir = repo_root / ".gator"
+    status_file = gator_dir / "status.json"
+    if status_file.exists():
+        try:
+            status = json.loads(status_file.read_text(encoding="utf-8"))
+            record_commit_and_emit_snippet(gator_dir, status)
+        except (json.JSONDecodeError, OSError):
+            pass
+    draft_file = gator_dir / "commit_draft.md"
+    draft_file.write_text(COMMIT_DRAFT_STUB, encoding="utf-8")
+    sys.exit(0)
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+def main():
+    if sys.stdout.encoding != "utf-8":
+        sys.stdout = io.TextIOWrapper(
+            sys.stdout.buffer, encoding="utf-8", errors="replace"
+        )
+
+    parser = argparse.ArgumentParser(
+        description="Gator pre-commit hook — deterministic governance gate."
+    )
+    parser.add_argument(
+        "--phase",
+        choices=["validate", "trailers", "cleanup"],
+        required=True,
+        help="Which hook phase to run",
+    )
+    parser.add_argument(
+        "msg_file",
+        nargs="?",
+        help="Path to commit message file (required for trailers phase)",
+    )
+    args = parser.parse_args()
+
+    if args.phase == "validate":
+        phase_validate()
+    elif args.phase == "trailers":
+        if not args.msg_file:
+            print("Error: trailers phase requires a message file path", file=sys.stderr)
+            sys.exit(1)
+        phase_trailers(args.msg_file)
+    elif args.phase == "cleanup":
+        phase_cleanup()
+
+
+if __name__ == "__main__":
+    main()