gator-command 1.0.0__py3-none-any.whl

gator_command/templates/gator-starter/charterignore

@@ -0,0 +1,53 @@
+# .charterignore — files and directories excluded from charter work.
+# Uses gitignore-style glob patterns. Lines starting with # are comments.
+# This file lives at .gator/.charterignore
+
+# Tests
+tests/
+test/
+__tests__/
+*_test.py
+*_test.go
+*_test.js
+**/*_spec.rb
+**/conftest.py
+
+# Build and vendor
+dist/
+build/
+node_modules/
+vendor/
+__pycache__/
+*.pyc
+
+# Generated / minified
+**/*.min.js
+**/*.min.css
+**/*.generated.*
+
+# Config and metadata (not production logic)
+setup.py
+setup.cfg
+pyproject.toml
+package.json
+package-lock.json
+tsconfig.json
+Makefile
+Dockerfile
+docker-compose.yml
+*.toml
+*.ini
+*.cfg
+
+# Documentation (charters cover code, not docs)
+docs/
+*.md
+
+# IDE and environment
+.vscode/
+.idea/
+.env
+.env.*
+
+# Gator internals
+.gator/

gator_command/templates/gator-starter/charters/README.md

@@ -0,0 +1,178 @@
+# Charters
+
+Charters are the comprehension layer for AI-assisted software development. They solve a specific problem: when AI generates code faster than a human can review it, the human loses architectural control — unless there's a structural layer that preserves comprehension at the speed code is now produced.
+
+This folder contains both the philosophy (this document) and the working charters for this project. Point an LLM here and it gets everything: *why* charters exist, *how* they work, the notation system, and real examples it can study and replicate.
+
+**Source**: "Constitutional Architecture for AI-Assisted Software Development" (Cumberland Laboratories, 2026)
+
+---
+
+## The Problem
+
+The bottleneck in AI-assisted development is not code generation. Models are good at writing code. The bottleneck is *comprehension* — the human's ability to understand, evaluate, and direct the system they're nominally in charge of.
+
+Before LLMs, code and comprehension scaled together: you wrote it, so you understood it. AI breaks that coupling. Code volume grows without a corresponding growth in human understanding. The developer becomes a reviewer of output they didn't write, in a codebase that's growing faster than they can read.
+
+This is not a tooling problem. It's a governance problem. The same problem organizations faced when they grew beyond the size where everyone could know everything: you need institutional structures — constitutions, charters, separation of powers — not smarter individuals.
+
+## The Inversion
+
+Traditional documentation describes code. You write the code first, then document it. The documentation is secondary, the code is primary.
+
+Charters invert this relationship.
+
+The charter network — function signatures, access patterns, cross-references, tripwires — is the primary artifact the human works with. It's the layer where architectural decisions are legible, where you can reason about the system without reading every file. The code is the *implementation* of what the charters describe. AI reads the code; humans read the charters; the charters keep them synchronized.
+
+## Session Zero
+
+Every reader — human or LLM — arrives at a codebase with zero history. They don't know why a function exists, what invariants it assumes, or which design decisions look wrong but are intentional.
+
+Code alone doesn't fix this. Code tells you *what* the system does. It doesn't tell you *why* it's shaped this way, *what state it reads and writes*, or *what the system deliberately doesn't do*. These are the things that matter most when you're about to make a change, and they're invisible in the source.
+
+Charters surface what cannot be inferred from reading code:
+
+- **Access patterns**: what a function reads and writes — models, session state, caches, external APIs — so you can predict side effects without reading the body
+- **Dependency direction**: what calls this function (`←`) and what it calls (`→`) — so you know what breaks when you change it
+- **Tripwires**: the non-obvious patterns that *must* be preserved — rendering dualities, race conditions, intentional workarounds that look like bugs
+- **Negative space**: what the system deliberately lacks, stated explicitly to prevent false assumptions
+
+That last point matters especially for LLMs. A model's training data creates priors about what systems "should" have. If your system intentionally omits error retry, or deliberately uses a naive algorithm, the model will "fix" it unless the charter says otherwise. Negative space documentation corrects false priors before they become false code.
+
+---
+
+## The Notation
+
+Each charter covers a code module. Each *function* within that module gets its own block:
+
+```
+### apply_grade(submission, raw_score, grader)
+File: core/utils/grading.py
+Creates Grade record with penalty-adjusted score.
+Models: Submission(R), Grade(W), Enrollment(RW)
+Session R: current_grader_id, active_rubric
+Session W: last_graded_at
+← grade_submission() in views_assignments
+→ see cross_cutting.md "Late Penalty Timing"
+! The instructor sees raw_score, but Grade.score
+  is penalty-adjusted. These are different numbers.
+```
+
+| Symbol | Meaning | Why it exists |
+|--------|---------|---------------|
+| `function_name()` | Function heading | Greppable identifier — the agent finds the current location via `grep -rn "def function_name"`. Survives code churn without maintenance. |
+| `(R)/(W)/(RW)` | Access pattern | Predicts side effects without reading code — `(R)` is safe to call, `(RW)` requires checking downstream effects |
+| `!` | Tripwire | Inverts the reader's assumption — contradiction spikes LLM attention at the point of maximum relevance |
+| `→` | Outbound cross-reference | "This function depends on..." — follow to understand downstream effects |
+| `←` | Inbound cross-reference | "This function is called by..." — follow to understand blast radius |
+| `Session R:` / `Session W:` | State access | Tracks untyped state (session dicts, Redis keys) that code analysis alone can't reveal |
+| `TRIPWIRE` | Section-level danger label | Flags architectural patterns that span multiple functions and must be preserved as a unit |
+
+**Why function names, not line numbers:** An earlier version of this notation used `[Lnnn]` line anchors. These break on every edit above them, creating combinatorial maintenance overhead. Function names are structurally stable — they survive code churn, they're self-verifying via grep, and they match how LLM agents actually navigate code. The staleness signal is cleaner too: a function name either resolves or visibly fails. A stale line number silently points to the wrong code.
+
+## The Cross-Cutting Charter
+
+The most important charter in any set. It doesn't map to a single code module — it maps to *patterns that span modules*.
+
+Every codebase has behaviors that emerge from the interaction of multiple modules: a data flow that traverses four files, an implicit contract between a prompt and the code that parses its output, an invariant that must be preserved across every exit path. These patterns are invisible in any individual module's charter. They're the things that break during refactors — not because any single module was changed incorrectly, but because the *relationship* between modules was violated.
+
+The cross-cutting charter documents these patterns with `TRIPWIRE` labels. In graph terms, it's a hub node — it connects tightly-clustered domain charters and dramatically improves navigability.
+
+**What goes in the cross-cutting charter:**
+- Multi-module data flows where changing one link breaks the chain
+- Implicit contracts not encoded in any function signature
+- Invariants that must be preserved across all code paths (e.g., "session must be saved on every exit")
+- Patterns where two parallel implementations must stay synchronized (rendering dualities, cache/DB consistency)
+- Stub inventories — scattered stubs connected by design decisions not yet finalized
+
+**When to read it:** Always. Read the cross-cutting charter first, before the module-specific one.
+
+## How Charters Were Used: A Validated Example
+
+These charters were battle-tested on a 97K-line production Django codebase (20 charter files). They were created *before* a major refactor and served four roles:
+
+1. **Navigation map**: every function, its access patterns, and its cross-module dependencies — so the agent could trace call chains without reading every file
+2. **Dependency graph**: the `←` and `→` annotations show what calls what, so you know what will break when moving code
+3. **Tripwire documentation**: the `!` annotations flag dangerous patterns that must be preserved during refactoring
+4. **Invariant checking**: after moving code, verify that all charter-documented call paths still work
+
+Three god-function decompositions were completed without regressions. A cross-module CSRF bug was identified via charter cross-references. The enforcer caught 4 stale charters in a single audit run.
+
+## The Three-Layer Documentation Architecture
+
+In a mature codebase, charters are one layer of a three-layer structure:
+
+1. **Charters** — per-module API references. Every public function, what it reads/writes, what models it touches, session keys, cross-references, and tripwires. Organized by code structure. The machine-readable map.
+2. **Designs** — flow-oriented user journey documents. Each one describes a complete business flow (checkout, authentication, quiz-taking) from the user's perspective, referencing charters for technical detail. Organized by what the user does.
+3. **Systems** — infrastructure and subsystem documentation. How specific subsystems work (CI/CD, caching, rendering pipeline). Technical reference.
+
+Charters are the ground truth. Designs are generated *from* charters as a more human-readable layer. Systems docs cover the infrastructure charters don't reach.
+
+---
+
+## When to Write Charters
+
+- **At project start**: write skeleton charters alongside skeleton code. They force you to articulate module boundaries before writing implementations.
+- **Before onboarding**: when someone new (human or LLM) will parachute into the codebase.
+- **Before a refactor**: charters created before a refactor serve as navigation map, dependency graph, and invariant checklist during the work.
+- **After a refactor**: module boundaries shift. Update charters to match the new reality, or they become misleading.
+- **When an LLM will modify the code**: the charter is the most efficient way to give an LLM the "what goes where" knowledge it needs. It's cheaper than loading every source file into context.
+
+## The Maintenance Obligation
+
+Charters that fall out of sync with code are worse than no charters — a wrong map is more dangerous than no map. This is a structural obligation, not a suggestion.
+
+The update chain: **code change → charter update → design doc update**. If you change a function's signature, access patterns, or cross-references, the charter must be updated in the same operation. Not "later." The charter is part of the change, the same way a migration is part of a schema change.
+
+Because charters use function names (not line numbers), routine code edits that don't change function signatures or behavior don't require charter updates. The maintenance obligation triggers on: renamed functions, changed access patterns, new cross-module dependencies, or new tripwire-worthy behavior. This keeps the overhead proportional to architectural change, not code churn.
+
+## Why Charters Are Especially Effective for LLMs
+
+**Token efficiency.** A charter set compresses a 97K-line codebase into ~20 files of structured notation. The LLM gets the map without paying for the territory.
+
+**Access pattern prediction.** `Models: Submission(R), Grade(W), Enrollment(RW)` tells the LLM exactly what a function mutates without reading a single line of the body. For session state — often an untyped dictionary with hundreds of references across dozens of files — `Session R:` / `Session W:` annotations are the *only* way to track state flow without loading every file.
+
+**Tripwire attention.** The `!` notation exploits how models process text: contradiction spikes attention. When a charter says `! The instructor sees raw_score, but Grade.score is penalty-adjusted — these are different numbers`, the model's prediction is immediately corrected at the point of maximum relevance.
+
+**Negative space correction.** Training-data priors are strong and often wrong for your specific system. A single line saying "no retry logic; failures are intentional signals" prevents the model from "improving" your design. The `TRIPWIRE` label on cross-cutting patterns tells the model "this looks wrong but it's not — preserve it."
+
+## Sizing
+
+Charters are a **small, intelligent map** — not a mirror of the code, but a compressed navigation layer. The goal is to fit the cross-cutting charter plus 1–2 module charters into context alongside the code being changed.
+
+| Metric | Target | Warning sign |
+|--------|--------|-------------|
+| Lines per function entry | 3–5 | >8 lines means you're writing docs, not a map |
+| Lines per charter | 30–80 | >100 lines means split into two domains |
+| Total charter set | 3–6% of codebase | >10% means over-documenting; <1% means under-documenting |
+| Charters per project | 3–8 typical | >12 means boundaries are too fine-grained |
+
+**Measured ratios**: A 75K-line production Django app = 6% across 20 charter files. Smaller projects trend higher (a 700-line project might be 30%+ because the charters carry design intent that outweighs the code). The ratio is a calibration guide, not a hard rule. The real test: can the agent load the relevant charters alongside the code being changed?
+
+## Anti-Patterns
+
+- **Charter as API docs**: charters are about ownership, access patterns, and boundaries, not method signatures. If it reads like a docstring, it's too low-level.
+- **Bloated charters**: if a charter exceeds 100 lines, it's trying to cover too much. Split by domain. If your charters approach 10% of codebase size, you're writing documentation, not a map.
+- **Charter without negative space**: the boundaries and "does not own" / tripwire entries are the most valuable parts. Without them, the charter is just a description.
+- **Stale charters**: worse than no charters. If you refactor, update or delete the charter. A wrong map is more dangerous than no map.
+- **No cross-cutting charter**: if your project has more than 3 module charters and no cross-cutting charter, you're missing the most important one.
+
+## How to Implement Charters in Another Repo
+
+1. **Start with the cross-cutting charter.** Identify multi-module patterns, implicit contracts, and invariants. These are the things that will break first during changes.
+
+2. **Write one charter per code domain.** Not one per file — one per logical domain (e.g., `views_quiz`, `models_core`, `frontend_js`). Each function gets a block with the notation above.
+
+3. **Add an INDEX.md** to your charters folder. The index maps code paths to charter files: "if you're changing X, read Y." See [INDEX.md](INDEX.md) for the format.
+
+4. **Make it mandatory.** Add a rule: "before modifying code, consult the relevant charters." Without governance, charters become optional documentation that decays.
+
+5. **Update charters with code changes.** Embed this in your workflow — same commit, same PR, same operation. The charter is part of the change.
+
+For a working example of the full setup, see the [worked example](../reference-notes/example-project.md) and the charter files in this folder.
+
+---
+
+## Charters in This Project
+
+See [INDEX.md](INDEX.md) for the current charter map. The index is the authoritative list — it maps code paths to charter files and is updated with every code change.

gator_command/templates/gator-starter/charters/_template.md

@@ -0,0 +1,31 @@
+# Charter: [Module Name]
+
+**Covers**: `path/to/module/`
+
+## Owns
+
+[What this module is responsible for]
+
+## Does Not Own
+
+[What belongs elsewhere — prevents scope creep]
+
+---
+
+### function_name(args)
+File: path/to/file.py
+[One line: what it does]
+Models: [what it reads/writes — e.g., User(R), Order(RW)]
+← [callers — what calls this]
+→ [callees — what this calls]
+! [tripwire — non-obvious behavior to preserve]
+
+---
+
+## Before Changing This Module
+
+[Institutional knowledge: implicit contracts, stubs, intentional decisions]
+
+## Connections
+
+→ [Other Charter](other-module.md) — why the link exists

gator_command/templates/gator-starter/commands/commit.md

@@ -0,0 +1,33 @@
+Commit the current session's work.
+
+Before committing, ensure `commit_draft.md` has structured YAML frontmatter:
+
+```yaml
+---
+message: "One-line commit message describing the change"
+change-type: feature|fix|refactor|policy|security|docs
+significance: routine|notable|high
+decision-tags: [tag1, tag2]
+agent: claude|codex|gemini
+architect: AG
+---
+```
+
+The body of `commit_draft.md` remains the free-form session change log.
+
+**Steps:**
+1. Verify `commit_draft.md` frontmatter is populated (write it if not — you have the context)
+2. Stage all changed files (including `.gator/` files)
+3. Read the `message` field from `commit_draft.md` frontmatter
+4. Run `git commit -m "<message>"` — the pre-commit hook handles the rest:
+   - Validates charter-alongside-code (blocks if code changed but no charter updated)
+   - Validates commit_draft is populated
+   - Assembles Gator-* trailers and appends them to the commit
+   - Writes `.gator/status.json` snapshot
+   - Writes any warnings to `.gator/whiteboard.md`
+5. If the hook blocks the commit, read `.gator/whiteboard.md` and present the findings to the Architect
+6. Clear `commit_draft.md` after successful commit (reset to header only)
+
+**Do not run git commit automatically.** The constitution requires Architect confirmation before committing. Present the proposed message and wait for the Architect to approve, adjust, or decline.
+
+**Override** (emergency only): write `charter-skip` to `.gator/.override` before committing: `echo charter-skip > .gator/.override && git commit -m "msg"`. The hook reads and deletes the file — one file, one commit, no sticky state. The override is audited in trailers and whiteboard.md — it cannot be hidden.

gator_command/templates/gator-starter/commands/init.md

@@ -0,0 +1,11 @@
+Run the Gator boot sequence by executing: `python .gator/scripts/gator-init.py`
+
+Display the output exactly as printed — do not summarize, reformat, or interpret it. This is the standardized Gator orientation display.
+
+After displaying the output, read the session-opening files as the constitution directs:
+1. `mission.md`
+2. `roadmap.md`
+3. `inbox.md`
+4. `commit_draft.md`
+
+Then greet the Architect and surface the most relevant next step, as described in the constitution's session-opening procedure.

gator_command/templates/gator-starter/commands/update.md

@@ -0,0 +1,5 @@
+Run the Gator template update by executing: `python .gator/scripts/gator-update.py`
+
+This refreshes template-derived files (constitution, procedures, scripts, reference-notes, charter templates, slash commands) from the command post without touching any user content (charters, threads, artifacts, mission, roadmap, etc.).
+
+Display the output showing what was added, updated, or unchanged. If the Architect wants to preview first, use `--dry-run`.

gator_command/templates/gator-starter/constitution.md

@@ -0,0 +1,165 @@
+# Constitution
+
+This document governs how you work in this project. Read it at session start. Follow it exactly.
+
+## Roles
+
+| Role | What it does |
+|------|-------------|
+| **Architect** | Human. Holds mission, taste, architectural coherence. All decisions. |
+| **Agent** | Reads and writes the .gator/ knowledge layer in-session. Updates charters, captures ideas, maintains the knowledge layer. |
+| **Enforcer** | Different model. Read-only audit. Produces reports, does not edit. |
+
+## The Loop
+
+This is a closed-loop system. The agent's workflow on every code change:
+
+1. **Before changing code**: read the relevant charters (use `charters/INDEX.md` to find them)
+2. **Propose the plan**: explain what you're about to do, grounded in charter context
+3. *(optional)* **Pre-code enforcer review**: the Architect may request an enforcer check of the plan against charters before any code is written
+4. **Make the change**: write code grounded in what the charters say about invariants, access patterns, and neighbors
+5. **Immediately after editing each code file, update the affected charter** — before editing the next file, before running tests, before moving on. This is part of the edit, not part of the commit. Update: new functions, changed access patterns, new cross-references, removed entries. If you touched code and haven't touched a charter, you are not done with the edit.
+6. **Log the change**: append a bullet to the body of `commit_draft.md` and update the YAML frontmatter (`message`, `change-type`, `significance`, `decision-tags`, `agent`, `architect`)
+7. **Significance check**: if the change touches public API, cross-module invariants, TRIPWIREs, or security-relevant code, generate a steelman argument against the change and flag compatibility implications. Surface to the Architect before committing. See [`procedures/significance-check.md`](procedures/significance-check.md). Skip for routine edits.
+8. **Commit**: stage files and run `git commit`. Two deterministic hooks fire automatically:
+   - **Pre-commit** (`gator-pre-commit.py --phase validate`): validates charter-alongside-code (blocks if code changed but no charter updated), checks commit_draft is populated, writes `.gator/status.json`. Findings go to `whiteboard.md`.
+   - **Commit-msg** (`gator-pre-commit.py --phase trailers`): assembles the full commit message from `commit_draft.md` (`message` field becomes the summary line, session change log entries become the body) and appends Gator-* metadata trailers. Falls back to the agent's `-m` message if the draft is empty.
+   - **Post-commit** (`gator-pre-commit.py --phase cleanup`): records the commit to the session ledger and emits a **session snippet** to `.gator/session-snippets/`. Then resets `commit_draft.md`.
+   The agent does not run these scripts directly — git runs them. If the pre-commit hook blocks, read `whiteboard.md` for the reason and present it to the Architect.
+   **Session snippets appear as untracked files after a commit. This is normal.** A snippet contains the commit hash that produced it, so it cannot be part of that same commit. Snippets are staged and committed with the *next* commit. Do not retroactively amend or create a separate "add snippet" commit — just let them flow forward naturally.
+9. *(optional)* **Post-code enforcer review**: the Architect may request a full charter-grounded enforcer review of the diff before committing
+
+Steps 1, 2, 4, 5, 6 are the default workflow. A code change without a charter update is incomplete — and the pre-commit hook enforces this structurally. Step 7 (significance check) runs automatically when triggered — the agent does not need Architect prompting for this; it's the agent's responsibility to notice when a change is significant. Step 8 (commit with hooks) runs by default. Steps 3 and 9 are Architect-driven — the agent does **not** run charter-grounded reviews unprompted. The Architect controls the cadence and weight of model-based review.
+
+The right level of review depends on the project and the change. See [`reference-notes/workflow-profiles.md`](reference-notes/workflow-profiles.md) for suggested profiles from Light (no review) to Rigorous (multiple reviews, cross-vendor). The Architect picks the profile — or mixes and matches per change.
+
+## Charter Rules
+
+- **Always read the cross-cutting charter first** (`charters/cross-cutting.md`, when it exists). It documents multi-module invariants — the patterns that break during refactors because the *relationship* between modules was violated. Then read the module-specific charter via `charters/INDEX.md`.
+- Charters use **function names** as identifiers (not line numbers). Grep-verifiable, survives code churn.
+- Every charter entry includes: what the function does, what it reads/writes, what calls it (`←`), what it calls (`→`), and tripwires (`!`) for non-obvious behavior.
+- The `charters/INDEX.md` maps code paths → charter files. The agent maintains it.
+- If the code appears to deviate from what a charter describes, **stop and resolve the discrepancy before proceeding**. Check git history to determine whether the charter or the code drifted. Present the discrepancy to the Architect. See [`procedures/charter-alignment.md`](procedures/charter-alignment.md).
+- Format reference: [`charters/README.md`](charters/README.md)
+
+## Session Opening
+
+At the start of every session:
+1. Read this constitution
+2. If `.gator/command-post.md` exists, read org policy from the command post: follow the path in that file, then read `gator-command/org-policy.md`. If no command-post.md exists, skip this step (standalone mode)
+3. Read `mission.md` (what we're building)
+4. Read `roadmap.md` (current priorities)
+5. Check `inbox.md` (anything captured since last session)
+6. Check `commit_draft.md` (what happened last session)
+7. Check charter health: if `charters/` is empty or has no real charters, follow the Charter Bootstrap Procedure → [`procedures/charter-bootstrap.md`](procedures/charter-bootstrap.md) before beginning substantial coding work
+
+Make the human feel like the conversation never ended. For common Architect questions — "what's the process?", "catch me up", "is this safe to change?" — see [`reference-notes/concierge-responses.md`](reference-notes/concierge-responses.md).
+
+## File Purposes
+
+| File | Purpose | When to update |
+|------|---------|---------------|
+| `mission.md` | What we're building and why | When the project direction changes |
+| `roadmap.md` | Priority-ordered feature list | When priorities shift |
+| `inbox.md` | Zero-friction idea capture | Anytime — append freely |
+| `commit_draft.md` | Source of truth for commit messages: `message` field becomes the summary line, session change log becomes the body. Also drives Gator-* trailers. | Every code change, every decision; cleared to stub after commit |
+| `patterns.md` | Recurring rhythms, obligations, schedules | When patterns emerge |
+| `charters/` | The intelligent map of the codebase (3–6% by line count) | Every code change (mandatory) |
+| `blueprints/` | Per-feature flow maps — how features work, referencing charters and modules | When the Architect wants system-level comprehension |
+| `threads/` | Lightweight reference notes on topics | When a topic has momentum |
+| `pulse.md` | Strategic operations brief — generated by `gator-pulse.py` | Run `python .gator/scripts/gator-pulse.py` to regenerate |
+| `artifacts/` | Deep records, design docs, research | When depth is needed |
+| `procedures/` | Repeatable workflows | When a process stabilizes |
+| `field-guides/` | Language-specific pattern sheets + Architect tutorials | Manual regeneration when patterns drift |
+| `reference-notes/` | Cognitive aids, vocabulary, examples | When reference material helps |
+| `whiteboard.md` | Ephemeral working surface (enforcer findings) | During review, cleared after |
+| `vault/` | Sensitive material and large files (gitignored, never committed) | When handling credentials, keys, PDFs, datasets |
+| `scripts/enforcer-review.py` | Charter-grounded linter (3 layers) | Architect-requested, agent-invoked |
+
+## Threads
+
+Threads are lightweight (5–20 lines). They carry:
+- `## Summary` (2–4 sentences, self-contained)
+- `## Connections` (annotated cross-references — why the link exists)
+
+Threads don't need to be long. They exist to give a topic a name and a place.
+
+## Compression
+
+The .gator/ folder should stay lean. If a thread exceeds 60 lines, consider splitting or moving detail to an artifact. If an artifact grows, that's fine — artifacts are deep storage.
+
+## Terminology
+
+| Term | Meaning |
+|------|---------|
+| **Enforcer** | The *role* — a different AI model that audits the primary agent's work. Read-only. |
+| **Enforcer review script** | `enforcer-review.py` — the automated tool that sends diffs + charters to a model and writes findings to `whiteboard.md`. Architect-triggered, not automatic. |
+| **Charter alignment procedure** | The process for detecting and resolving code-charter drift. Three levels: quick check (agent grep), model review (enforcer review script), full audit (CLI enforcer). See [`procedures/charter-alignment.md`](procedures/charter-alignment.md). |
+| **Pre-commit hook** | The mechanical gate (`gator-pre-commit.py`) — runs automatically on every `git commit`. No model. Deterministic. |
+| **Gatorize** | Install or upgrade Gator in a repo. Run `python gatorize.py <target-directory>`. This is the canonical installer. (`gatorize.sh` is the legacy bash wrapper — same function, use `.py` for cross-platform.) |
+| **Session snippet** | A durable commit-linked artifact in `.gator/session-snippets/`. Emitted automatically by the post-commit hook. **Must be committed** — snippets are the traceability bridge between session history and git history. |
+
+## Enforcer Findings Are for the Architect
+
+When enforcer findings arrive, the agent **presents them to the Architect and asks for direction**. The agent does not silently fix findings, dismiss them, or start acting on them unprompted.
+
+**How to run enforcers** (trust boundary):
+- **Enforcer review script**: `python .gator/scripts/enforcer-review.py` — sends diff + relevant charters to the configured model, writes findings to `whiteboard.md`
+- **CLI enforcers** (Codex, Gemini, Claude): `.gator/scripts/enforcer-run.sh <command>` — wrapper routes output to `whiteboard.md`, agent sees only "review complete"
+- **Never** run a CLI enforcer directly (e.g., `codex review --uncommitted`) from the primary agent session — the agent intercepts the findings via stdout, bypassing the trust boundary
+
+The correct behavior:
+1. Run the enforcer via the enforcer review script or CLI wrapper
+2. Read `whiteboard.md` for findings
+3. Summarize the findings clearly to the Architect
+4. Offer context: what the finding means, what charter or TRIPWIRE is involved, what the options are
+5. **Ask the Architect what to do next**
+
+This is deliberate. Enforcer findings are a forcing function for the Architect to think deeply about what's happening in the code. The value isn't just the fix — it's the Architect's understanding that comes from deciding *whether* and *how* to fix it.
+
+## Project Assessment
+
+When the Architect asks for a project assessment, write a 2-paragraph expert evaluation to `.gator/artifacts/YYYY-MM-DD-project-assessment.md`. Write as an expert consultant advising an engineering manager — direct, evidence-based, actionable.
+
+**Format:**
+```
+---
+date: YYYY-MM-DD
+type: project-assessment
+model: <your model name>
+---
+
+## Project Assessment
+
+[Paragraph 1: current state — what's working, what's built, where the project stands]
+
+[Paragraph 2: what's needed — priorities, risks, recommendations for the path forward]
+
+— <model name>, YYYY-MM-DD
+```
+
+The next `gator pulse` run will include the latest assessment automatically.
+
+## Knowledge Lives in the Repo
+
+Many AI models maintain per-user memory systems (Claude's `MEMORY.md`, Gemini's memory, etc.). These are external to the repo and invisible to other users and other models. **Repo knowledge belongs in `.gator/`, not in model-specific memory.**
+
+The `.gator/` folder is the shared knowledge layer — it works across users, across models, across sessions. If you learn something about this codebase that would help the next person (or the next model) work here, it goes in the repo:
+
+- Decisions, invariants, patterns → charters, threads, or `inbox.md`
+- Project context and priorities → `mission.md`, `roadmap.md`
+- Ideas and observations → `inbox.md`
+
+See [`procedures/knowledge-capture.md`](procedures/knowledge-capture.md) for the full decision guide.
+
+## Field Guides
+
+Field guides are optional language-specific pattern references in `field-guides/`. Consult when writing new code in a language that has a guide — same cadence as reference-notes (situational, not always-loaded). If no guide exists for a language, that's normal. Generation procedure: → [`procedures/field-guide-generation.md`](procedures/field-guide-generation.md)
+
+## What You Don't Do
+
+- Don't create documentation for code that the charters already cover
+- Don't defer the charter update to commit time — update it immediately after each file edit, as part of the same mental operation
+- Don't treat this folder as optional context — it's the primary working surface
+- Don't save repo knowledge to model-specific memory instead of `.gator/`
+- Don't act on enforcer findings without Architect direction — present, suggest, ask

gator_command/templates/gator-starter/field-guides/README.md

@@ -0,0 +1,25 @@
+# Field Guides
+
+Condensed pattern references organized by language. Each guide has two sections: an **agent pattern sheet** (concise dispatch table for the agent) and an **Architect tutorial** (real code snippets with rationale for the human).
+
+Field guides are the third layer: constitution ("how to behave"), charters ("what exists"), field guides ("how to work here").
+
+## When to Generate
+
+Field guides are optional. The system never flags their absence, never detects staleness, never prompts for regeneration. Generate one when:
+
+- The Architect wants to restore sharpness on patterns used in this repo
+- The agent keeps reinventing patterns that already have established idioms
+- A language is covered by ≥2 charters with ≥4 source files
+
+## How to Generate
+
+Follow the procedure: → [field-guide-generation.md](../procedures/field-guide-generation.md)
+
+## File Format
+
+Two files per language:
+- `{slug}-patterns.md` — agent pattern sheet (concise, under 80 lines, loaded by the agent)
+- `{slug}-tutorial.md` — Architect tutorial (real snippets with rationale, read by the human)
+
+YAML frontmatter tracks generation date, source charters, and cross-references between the pair. Regenerate manually when patterns drift — the `generated` date is the staleness signal.

gator_command/templates/gator-starter/gator-start-up.md

@@ -0,0 +1,119 @@
+# Gator Start-Up — Bootstrap Procedure
+
+**When to use**: First session on a fresh project, OR when `charters/` is empty or contains only templates.
+
+This procedure creates the initial knowledge layer. After this, the normal loop takes over (constitution.md governs ongoing work).
+
+## Before You Start
+
+Read the worked example in [`reference-notes/example-project.md`](reference-notes/example-project.md). It shows what a fully populated Gator looks like for a simple Python project — mission, roadmap, charters, threads, the whole thing. Study the charter format and density. That's what you're building toward.
+
+## Step 1: Establish Ownership Context
+
+Before anything else, read [`reference-notes/identity-and-ownership.md`](reference-notes/identity-and-ownership.md). Then determine: is this a solo repo or a team repo? This shapes how you write `mission.md` and everything downstream. Don't skip this — getting identity wrong early creates drag that compounds.
+
+## Step 2: Scan for Existing Knowledge
+
+Before building the knowledge layer from scratch, look for existing documentation or structure in the repo that could be migrated into `.gator/`. Many repos already have some form of architectural knowledge — just not in Gator's format.
+
+**Scan for:**
+- `ARCHITECTURE.md`, `DESIGN.md`, `CONTRIBUTING.md`, or similar top-level docs
+- `docs/` folders with architecture, decisions, or design documents
+- ADR (Architecture Decision Records) directories (`docs/decisions/`, `docs/adr/`, `adr/`)
+- Existing charter-like files (`docs/charters/`, `docs/modules/`)
+- Homegrown knowledge folders (`memex/`, `.memex/`, `docs/knowledge/`)
+- Inline module documentation (`README.md` files inside package directories)
+- `.cursorrules`, `.github/copilot-instructions.md`, or other AI instruction files
+
+**If you find existing knowledge**, tell the Architect what you found and offer to migrate:
+
+- Architecture docs → seed `mission.md`, charters, and cross-cutting charter
+- ADRs → convert to threads (one thread per decision, preserving rationale)
+- Module READMEs → seed the charter for that module's "Owns" and boundaries
+- Existing AI instructions → review for content that should move into the constitution or reference notes (and keep the original for model-specific config)
+
+Don't migrate silently. Show the Architect what you found, suggest where it maps, and ask before copying. Some of it may be outdated or intentionally separate.
+
+## Step 3: Understand the Project
+
+Ask the Architect (or read existing docs, including anything found in Step 2):
+- What is this project? (→ `mission.md`)
+- What are the current priorities? (→ `roadmap.md`)
+- What's the tech stack?
+- How is the code organized? (top-level packages, major modules)
+
+Populate `mission.md` and `roadmap.md` from the answers.
+
+## Step 4: Identify Module Boundaries
+
+Walk the directory structure. Identify the natural charter boundaries — one charter per logical domain, not one per file.
+
+Good boundaries:
+- A top-level package or directory with a clear responsibility
+- A group of files that change together
+- A subsystem with its own data model or external dependencies
+
+For a typical project, expect 3–8 charters.
+
+## Step 5: Generate Skeleton Charters
+
+For each module boundary, create a charter file in `charters/`. Use `_template.md` for structure and study the [worked example](reference-notes/example-project.md) for density and tone.
+
+For each charter:
+- Start with **Owns** (what this module is responsible for) and **Does Not Own** (what belongs elsewhere). "Does Not Own" is load-bearing — it prevents scope creep and tells the agent where boundaries are. Every charter needs both.
+- For each public function or class:
+  - Read the actual code
+  - Document: what it does (one line), what it reads/writes, callers (←), callees (→)
+  - Flag any tripwires (!) — non-obvious behavior, intentional workarounds, things that look wrong but aren't
+- Each function entry should be 3–5 lines. If it's longer, you're over-documenting. If it's one line, you're probably missing access patterns or cross-references.
+
+Don't invent. Extract from the code. If you're unsure about intent, ask the Architect or mark it with `?`.
+
+**Sizing**: Charters are a small map, not a mirror. A single charter should typically be 30–80 lines. If it exceeds ~100 lines, split it into two domains. The total charter set is typically 3–6% of the codebase by line count (a 75K-line codebase → ~4,500 lines of charters across 20 files). Smaller projects trend higher — that's normal, because charters carry design intent that outweighs the code. Oversized charters defeat the purpose — they consume the context window they're supposed to save. The real test: can the agent load the cross-cutting charter plus 1–2 module charters alongside the code being changed?
+
+## Step 6: Build the Index
+
+Populate `charters/INDEX.md` mapping code paths → charter files:
+
+```
+| If you're changing... | Read these charters |
+|---|---|
+| `src/auth/` | [Auth](auth.md) + [Cross-Cutting](cross-cutting.md) |
+| `src/api/` | [API](api.md) + [Cross-Cutting](cross-cutting.md) |
+```
+
+## Step 7: Write the Cross-Cutting Charter
+
+This is the most important charter. Read the [cross-cutting section in charters/README.md](charters/README.md#the-cross-cutting-charter) for the full rationale and study the [worked example](reference-notes/example-project.md) for format.
+
+It documents patterns that span modules:
+- Multi-module data flows (show the full chain, not just one hop)
+- Implicit contracts between modules (things not encoded in function signatures)
+- Invariants that must hold across all code paths
+- Synchronized implementations (if you change one, you must change the other)
+
+Label dangerous patterns with `TRIPWIRE`. Every cross-cutting charter should have at least one. If you can't find any tripwires, you haven't looked hard enough — ask the Architect what keeps them up at night.
+
+## Step 8: Verify
+
+After bootstrap, check:
+- [ ] Every major module has a charter
+- [ ] INDEX.md maps code paths to charters
+- [ ] Cross-cutting charter exists with at least one TRIPWIRE
+- [ ] `mission.md` and `roadmap.md` are populated
+- [ ] The Architect has reviewed and corrected anything off
+
+## What "Done" Looks Like
+
+The system is bootstrapped when the next code change can follow the normal loop:
+1. Agent reads relevant charters before changing code
+2. Agent makes the change grounded in charter context
+3. Agent updates charters after the change
+4. The cycle improves from here — monotonically
+
+## Reference
+
+→ [Identity and Ownership](reference-notes/identity-and-ownership.md) — solo vs. team repo context (read before Step 1)
+→ [Worked Example](reference-notes/example-project.md) — a complete populated Gator for a simple Python project
+→ [Charter Format](charters/README.md) — notation, philosophy, anti-patterns
+→ [Constitution](constitution.md) — the rules that govern ongoing work after bootstrap