gator-command 1.0.0__py3-none-any.whl

gator_command/templates/gator-starter/procedures/charter-alignment.md

@@ -0,0 +1,83 @@
+# Charter Alignment Procedure
+
+**When to use**: Periodically during a session, and immediately when the code appears to deviate from what a charter describes.
+
+## Why This Exists
+
+Charters are only useful if they reflect reality. The constitution requires updating charters with every code change, but drift still happens -- changes made outside a Gator session, changes where the charter update was incomplete, or charters that were never fully accurate to begin with.
+
+This procedure gives the primary agent a way to detect and resolve drift before it causes problems.
+
+## When to Check Alignment
+
+### Periodic checks (proactive)
+
+The agent should periodically verify alignment during a session:
+
+- **At session open**: After reading the relevant charters, do a quick sanity check -- do the function names in the charter still exist in the code? Does the "Owns" section still match what the module actually does?
+- **Before a significant change**: If about to modify a module, check that the charter's description of that module matches the current code state. If it doesn't, resolve the discrepancy first.
+- **Before commit**: As part of the pre-commit checklist, confirm that charter updates in this session's commits correspond to the code changes in those same commits.
+
+### Reactive checks (when something seems off)
+
+If the agent notices any of these, **stop and check alignment before proceeding**:
+
+- A function name referenced in a charter doesn't exist in the code
+- A charter says a module "Does Not Own" something, but the code contains that logic
+- A TRIPWIRE pattern described in the cross-cutting charter no longer matches the code
+- The callers (`<-`) or callees (`->`) listed in a charter don't match what grep shows
+- The code does something the charter doesn't mention at all
+- The agent's plan conflicts with what the charter describes
+
+## How to Check
+
+### Quick check (30 seconds)
+
+```
+1. Read the relevant charter
+2. Grep for the function names it lists -- do they still exist?
+3. Scan the "Owns" and "Does Not Own" -- does the code still respect these boundaries?
+4. Check any TRIPWIREs -- are the described patterns still present?
+```
+
+### Git history check (when drift source is unclear)
+
+```
+1. git log --oneline -- <module-path>          # recent code changes
+2. git log --oneline -- .gator/charters/<charter>.md   # recent charter changes
+3. Compare: do code changes have corresponding charter updates?
+4. If not, identify which commits changed code without updating the charter
+```
+
+If code was changed without charter updates, the charter is stale. If the charter was updated but the code doesn't match, the code may have regressed or the charter update was wrong.
+
+### Full alignment audit (when drift is significant)
+
+For deeper misalignment, ask the Architect to run the enforcer review script or a CLI enforcer focused on charter accuracy:
+
+```bash
+# Enforcer review script (uses configured model, diff-based)
+python .gator/scripts/enforcer-review.py
+
+# CLI enforcer (separate model, full repo-wide audit, no diff needed)
+codex review "Read all charters in .gator/charters/. Read the code they cover. Report any places where the code has drifted from what the charters describe -- missing functions, stale entries, boundary violations, and broken cross-references."
+```
+
+## How to Resolve
+
+When a discrepancy is found:
+
+1. **Present the discrepancy to the Architect**: "The charter says X, but the code does Y. Which is correct?"
+2. **Don't assume the code is right**: Sometimes the charter is the intent and the code has drifted. The Architect decides.
+3. **Fix whichever is out of date**:
+   - If the charter is stale: update the charter to match the code
+   - If the code is wrong: fix the code to match the charter (the charter represents the intended design)
+   - If both need updating: work with the Architect to establish what the intent should be, then update both
+4. **Log the alignment fix**: Add a bullet to `commit_draft.md` noting the drift and how it was resolved
+
+## What the Agent Should NOT Do
+
+- Don't silently "fix" a charter to match code that might be wrong
+- Don't ignore a discrepancy and proceed with the change anyway
+- Don't treat alignment as a one-time bootstrap activity -- it's ongoing
+- Don't assume recent code is more correct than the charter -- the Architect decides

gator_command/templates/gator-starter/procedures/enforcer-review.md

@@ -0,0 +1,317 @@
+# Procedure: Enforcer Review
+
+**Enforcer review is optional and Architect-driven.** The Architect decides when to run one, and at what level. Not every change needs a full charter-grounded review — routine edits might need nothing, or just a quick lint. Critical changes to invariants or cross-cutting patterns might warrant a full model review. The Architect picks the weight.
+
+## Ad Hoc Invocation
+
+The Architect can request a review at any point during a session. The primary agent translates intent to action:
+
+| Architect says | Agent does |
+|---------|-----------|
+| "run a quick lint" / "check for secrets" | `python .gator/scripts/enforcer-review.py --layer 1` |
+| "get a review on this" / "run the enforcer" | `python .gator/scripts/enforcer-review.py` |
+| "have Sonnet check this" | Same script — default config uses Sonnet |
+| "run Codex on this" | `.gator/scripts/enforcer-run.sh codex review "Read .gator/scripts/enforcer-prompt.md for full instructions. Review the uncommitted changes against the charters."` |
+| "just the mechanical checks" | `python .gator/scripts/enforcer-review.py --layer 1` |
+| "full review before we commit" | `python .gator/scripts/enforcer-review.py` (all layers) |
+
+**Important**: For CLI-based enforcers (Codex, Claude, Gemini), always use the `enforcer-run.sh` wrapper — never run the CLI command directly. The wrapper routes output to `whiteboard.md` so the primary agent cannot intercept or filter findings. See the Trust Model section below.
+
+The agent should **not** run enforcer reviews unprompted. The Architect controls the cadence.
+
+## Common Setups
+
+Pick your enforcer. Follow the steps. Running in under 5 minutes.
+
+### Sonnet as enforcer
+
+The default config. Cheap, fast, charter-grounded. Works with any primary agent.
+
+```bash
+pip install anthropic
+```
+
+Set your API key (if not already set):
+```bash
+# macOS/Linux
+export ANTHROPIC_API_KEY=sk-ant-...
+
+# Windows (PowerShell)
+$env:ANTHROPIC_API_KEY = "sk-ant-..."
+```
+
+Run the enforcer:
+```bash
+python .gator/scripts/enforcer-review.py
+```
+
+That's it. Sonnet reads the charters, reviews the diff, writes findings to `whiteboard.md`. The primary agent presents findings and asks the Architect what to do.
+
+**If the primary agent is Codex**: this is the cleanest Anthropic-based enforcer path. The Python script sends the enforcer prompt directly and does not depend on `CLAUDE.md` role interpretation.
+
+**No API key?** Go to [console.anthropic.com](https://console.anthropic.com) to create one. Sonnet calls are cheap. Or fall back to mechanical lint (see below).
+
+### Codex / GPT as enforcer
+
+Best cross-vendor option when your primary agent is Claude.
+
+**When the primary agent runs it** (output goes to whiteboard, agent doesn't see findings):
+```bash
+.gator/scripts/enforcer-run.sh codex review "Read .gator/scripts/enforcer-prompt.md for full instructions. Review the uncommitted changes against the charters."
+```
+
+**When the Architect runs it independently** (separate terminal, no intermediary at all):
+```bash
+codex review "Read .gator/scripts/enforcer-prompt.md for full instructions. Review the uncommitted changes against the charters."
+```
+
+Setup: Install [Codex CLI](https://github.com/openai/codex), run `codex login`. `AGENTS.md` is the primary-agent entrypoint, so Codex should be given the dedicated enforcer prompt explicitly for review work. Review mode runs in a read-only sandbox.
+
+### Gemini as enforcer
+
+```bash
+pip install google-generativeai
+```
+
+Edit `.gator/scripts/enforcer-config.json`:
+```json
+{
+  "layer2_3": {
+    "provider": "google",
+    "model": "gemini-2.0-flash",
+    "api_key_env": "GOOGLE_API_KEY"
+  }
+}
+```
+
+```bash
+export GOOGLE_API_KEY=...
+python .gator/scripts/enforcer-review.py
+```
+
+### Claude Code CLI as enforcer
+
+Possible, but less clean than the Python Anthropic path when the repo's `CLAUDE.md` defines Claude as the primary agent.
+
+**When the primary agent runs it**:
+```bash
+.gator/scripts/enforcer-run.sh claude --print "$(cat .gator/scripts/enforcer-prompt.md)"
+```
+
+**When the Architect runs it independently**:
+```bash
+claude --print "$(cat .gator/scripts/enforcer-prompt.md)"
+```
+
+**Why this is a bit awkward**: `CLAUDE.md` is the repo entrypoint for the primary-agent role, while `.gator/scripts/enforcer-prompt.md` defines the read-only enforcer role. In practice the explicit enforcer prompt should dominate, but the role separation is cleaner through `enforcer-review.py` with Anthropic configured directly.
+
+**Recommendation**: if the primary agent is Codex and the Architect wants Anthropic as enforcer, prefer `python .gator/scripts/enforcer-review.py` with `provider: anthropic`. Use Claude Code CLI only when the Architect specifically wants a separate Claude terminal/session as the reviewer.
+
+### Mechanical lint only (no model, no API key)
+
+Zero setup. Catches secrets, SQL dangers, injection risks — but does not read charters.
+
+```bash
+python .gator/scripts/enforcer-review.py --layer 1
+```
+
+For charter-grounded review without an API key, see the `ollama` option under Option D below (free, local).
+
+### Local model as enforcer (free, offline)
+
+Install [ollama](https://ollama.com), pull a model, no API key needed:
+
+```bash
+ollama pull llama3
+```
+
+Edit `.gator/scripts/enforcer-config.json`:
+```json
+{
+  "layer2_3": {
+    "provider": "ollama",
+    "model": "llama3"
+  }
+}
+```
+
+```bash
+python .gator/scripts/enforcer-review.py
+```
+
+Free and private, but slower and less capable than cloud models.
+
+---
+
+## Configuration Reference
+
+For the full guide on configuring enforcers — decision tree, config file format, cross-vendor principle, and step-by-step setup for each provider — see [`reference-notes/enforcer-configuration.md`](../reference-notes/enforcer-configuration.md). That's what the agent should read when an Architect asks "how do I set this up?"
+
+## All Options (Reference)
+
+The common setups above cover most cases. Below is the full menu for advanced use or when you want to customize.
+
+### Option A: Mechanical lint only (no model, no API key, instant)
+
+```bash
+python .gator/scripts/enforcer-review.py --layer 1
+```
+
+Checks for hardcoded secrets, SQL dangers, injection risks, TODO markers, `.env` files. No API key needed. Zero setup.
+
+**Limitation**: This only runs hygiene checks. It does **not** read charters, check TRIPWIREs, or verify boundary compliance. For charter-grounded review, use Options B–E.
+
+### Option B: Codex CLI (OpenAI)
+
+```bash
+# Explicit enforcer prompt
+codex review "Read .gator/scripts/enforcer-prompt.md for full instructions. Review the uncommitted changes against the charters."
+
+# With explicit charter-grounded prompt
+codex review "Read .gator/scripts/enforcer-prompt.md for full instructions. Read all charters in .gator/charters/ and .gator/constitution.md. Review the git diff against the charters."
+
+# Review changes since branching from main
+codex review --base main
+
+# Review a specific commit
+codex review --commit HEAD
+```
+
+**Setup**: Install [Codex CLI](https://github.com/openai/codex), run `codex login`. That's it.
+
+Codex reads `AGENTS.md` automatically for its role instructions. Review mode runs in a read-only sandbox by default — the "no edits" rule is enforced at the system level.
+
+### Option C: Claude Code (Anthropic)
+
+```bash
+# From a separate terminal (not your primary agent session)
+claude --print "$(cat .gator/scripts/enforcer-prompt.md)"
+```
+
+Or start an interactive session and paste the enforcer prompt. Claude reads `CLAUDE.md` by default — the enforcer prompt overrides with the read-only audit role.
+
+**Note**: this works, but if `CLAUDE.md` defines Claude as the primary agent for the repo, the cleaner Anthropic enforcer path is still Option D (`enforcer-review.py` with `provider: anthropic`) because it avoids entrypoint-role overlap.
+
+**Setup**: Install [Claude Code](https://docs.anthropic.com/en/docs/claude-code), set `ANTHROPIC_API_KEY`.
+
+### Option D: Python script with API call (any provider)
+
+```bash
+# Uses enforcer-config.json to pick provider and model
+python .gator/scripts/enforcer-review.py
+
+# Review specific files
+python .gator/scripts/enforcer-review.py --files "src/auth.py,src/store.py"
+
+# Review staged changes only
+python .gator/scripts/enforcer-review.py --staged
+```
+
+**Setup**: Edit `.gator/scripts/enforcer-config.json`:
+
+| Provider | Install | API key env | Recommended model |
+|----------|---------|-------------|------------------|
+| `anthropic` | `pip install anthropic` | `ANTHROPIC_API_KEY` | `claude-sonnet-4-20250514` |
+| `openai` | `pip install openai` | `OPENAI_API_KEY` | `gpt-4o-mini` |
+| `google` | `pip install google-generativeai` | `GOOGLE_API_KEY` | `gemini-2.0-flash` |
+| `ollama` | Install ollama, pull a model | None (local) | `llama3` |
+| `none` | — | — | Layer 1 only |
+
+### Option E: Gemini CLI (Google)
+
+```bash
+# Run the enforcer prompt through Gemini
+gemini < .gator/scripts/enforcer-prompt.md
+```
+
+**Setup**: Install [Gemini CLI](https://github.com/google-gemini/gemini-cli), authenticate with Google.
+
+## Which Should I Pick?
+
+| Situation | Use |
+|-----------|-----|
+| Just getting started, no API keys | **Option A** — mechanical lint |
+| Primary agent is Claude | **Option B** (Codex) or **Option D** (Gemini/GPT) |
+| Primary agent is GPT/Codex | **Option C** (Claude) or **Option D** (Gemini) |
+| Primary agent is Gemini | **Option B** (Codex) or **Option C** (Claude) |
+| Want the cheapest API option | **Option D** with `gpt-4o-mini` or `gemini-2.0-flash` |
+| Want free/local | **Option D** with `ollama` |
+| CI/CD pipeline | **Option D** with `--format json` |
+
+**The principle**: different model than your primary agent. Different training = different blind spots = independent verification. Same-model is still better than nothing.
+
+## Prerequisites
+
+Options B–E (charter-grounded review) require **populated charters**. If `.gator/charters/` contains only templates, the enforcer has nothing to check against and will return a clean report — which is misleading. Run the bootstrap procedure first (see `.gator/gator-start-up.md`).
+
+Option A (mechanical lint) works regardless — it doesn't read charters.
+
+## What the Enforcer Checks
+
+### Layer 1 — Mechanical Lint (instant, no model)
+- Hardcoded passwords and API keys
+- Private key material in source
+- `DROP TABLE`, `DELETE FROM` without WHERE, `TRUNCATE`
+- SQL string concatenation (injection risk)
+- `eval()`, `os.system()`, `subprocess` with `shell=True`
+- `TODO`/`FIXME`/`HACK` markers introduced
+- `.env` files staged for commit
+
+### Layer 2 — Charter-Grounded Review (model required)
+- Code change respects charter "Does not own" boundaries
+- TRIPWIRE patterns preserved
+- Charter updates reflect actual code changes
+- New cross-module dependencies captured in `←`/`→`
+
+### Layer 3 — Blast Radius (model required)
+- Changes touching TRIPWIRE patterns in cross-cutting charter
+- Synchronized implementations still synchronized
+- Data flow changes reflected in cross-cutting docs
+
+## Trust Model
+
+The enforcer exists because the primary agent shouldn't be the sole judge of its own work. But if the primary agent runs the enforcer and controls what the Architect sees, that independence is compromised — even without intentional deception (unconscious filtering, self-serving summarization, or simply not running the review at all).
+
+**The rule: enforcer output must reach `whiteboard.md` without passing through the primary agent.**
+
+Two mechanisms enforce this:
+
+1. **Python script** (`enforcer-review.py`): Writes directly to `whiteboard.md` by default. The agent sees the output in stdout too, but the whiteboard is the authoritative record the Architect checks.
+
+2. **CLI wrapper** (`enforcer-run.sh`): For CLI-based enforcers (Codex, Gemini, Claude), the primary agent **must** use this wrapper instead of running the CLI command directly. The wrapper captures the enforcer's output, writes it to `whiteboard.md`, and returns only "Review complete" to the agent. The agent never sees the findings.
+   ```bash
+   # Correct — agent doesn't see findings
+   .gator/scripts/enforcer-run.sh codex review "Read .gator/scripts/enforcer-prompt.md for full instructions. Review the uncommitted changes against the charters."
+
+   # Wrong — agent intercepts findings via stdout
+   codex review "Read .gator/scripts/enforcer-prompt.md for full instructions. Review the uncommitted changes against the charters."
+   ```
+
+3. **Architect runs independently**: The Architect can always run the enforcer in a separate terminal. No wrapper needed — the output goes straight to their eyes.
+   ```bash
+   codex review "Read .gator/scripts/enforcer-prompt.md for full instructions. Review the uncommitted changes against the charters."
+   ```
+
+4. **Spot-check the whiteboard**: After the primary agent says "review is clean," open `whiteboard.md` in your editor and verify. This takes 10 seconds and catches filtering.
+
+For routine changes, trusting the agent's summary is fine. For critical changes — anything touching TRIPWIREs, cross-cutting patterns, or security boundaries — the Architect should see enforcer output directly.
+
+## After Review
+
+1. Findings go to `whiteboard.md` automatically (script default) with a timestamp and review type header:
+   ```
+   ## Review — 2026-05-15 18:30 — Codex CLI (GPT-5.4)
+   ```
+2. **Agent presents findings to the Architect with context and suggestions — then asks for direction.** The agent does not start fixing things on its own. The Architect decides what to act on, what to defer, and what to dismiss. This is constitutional (see "Enforcer Findings Are for the Architect").
+3. Architect directs next steps:
+   - Fix now → agent makes the change, updates charters
+   - Defer → capture in `inbox.md` with the finding reference
+   - Dismiss → Architect explains why (agent notes it for context)
+4. Resolved findings stay on the whiteboard as the review record
+
+## Whiteboard Size Policy
+
+`whiteboard.md` is the review log but it can't grow forever. When it exceeds **100 lines**:
+- Archive the oldest reviews to `artifacts/review-log.md` (append, don't overwrite)
+- Keep only the most recent 2–3 reviews on the whiteboard
+- The whiteboard header and separator stay; only review entries rotate out

gator_command/templates/gator-starter/procedures/field-guide-generation.md

@@ -0,0 +1,176 @@
+# Field Guide Generation
+
+**When to use**: When ≥2 charters reference the same language and the Architect wants condensed pattern reference material. Field guides are optional — the system never prompts for them.
+
+A field guide has two audiences in two files per language: a **pattern sheet** (`{slug}-patterns.md`, concise dispatch table for the agent) and a **tutorial** (`{slug}-tutorial.md`, real snippets with rationale for the Architect). Separate files so the agent loads only the condensed sheet; the Architect reads the tutorial at their own pace.
+
+## Step 0 — Maturity Gate
+
+Count charters in `charters/` (skip `_template.md`, `README.md`, `INDEX.md`). For each charter, read the `Covers` line and `File:` lines. Map file extensions to language slugs:
+
+| Extension | Slug |
+|-----------|------|
+| `.py` | python |
+| `.sh` | bash |
+| `.js` | javascript |
+| `.ts` | typescript |
+| `.go` | go |
+| `.rs` | rust |
+| `.gd` | gdscript |
+
+A language qualifies when **all three** conditions are met:
+- ≥2 charters reference files with that extension
+- ≥4 source files with that extension across those charters
+- ≥8 extractable patterns (estimated — confirm after Step 3)
+
+If no language qualifies, stop. Tell the Architect: "This repo doesn't have enough chartered code to generate a useful field guide yet. Field guides work best when charters cover multiple modules in the same language."
+
+## Step 1 — Inventory Languages from Charters
+
+Read all charter files. For each, extract:
+- The `Covers:` line (lists primary files)
+- Lines starting with `File:` inside function entries
+- `@reads:` and `@writes:` paths that reference source files
+
+Build a map: `{language_slug: [{charter_name, [files]}]}`
+
+Example:
+```
+python:
+  - boot-version: [gator-init.py, gator-update.py, gator-version.py]
+  - fleet-intelligence: [gator-fleet-report.py, gator-drift.py, gator-audit.py]
+  - gator-core: [gator_core.py]
+bash:
+  - installer: [gatorize.sh, gatorize-lib.sh, gatorize-actions.sh, gatorize-post.sh]
+```
+
+## Step 2 — Extract Patterns from Charters
+
+For each qualifying language, scan its charters for:
+
+| Charter element | Pattern type |
+|----------------|--------------|
+| `TRIPWIRE` sections | Constraint (highest priority) |
+| `!` lines in function entries | Gotcha / non-obvious behavior |
+| `@reads:` / `@writes:` tags | Data flow pattern |
+| `←` / `→` cross-references | Dependency pattern |
+| "Before Changing" invariants | Guard / pre-condition |
+| "Does Not Own" boundaries | Scope boundary |
+
+Record each pattern with: name, source charter, affected files, 1-sentence description.
+
+## Step 3 — Extract Patterns from Code
+
+Read the actual source files identified in Step 1. Look for:
+
+- **Recurring idioms** (3+ uses): Same code shape appearing in multiple functions or files. Name the shape.
+- **Structural conventions**: How files are organized (section headers, function ordering, import structure).
+- **Guard patterns**: How errors, missing files, and edge cases are handled. Note the common try/except or if/return shapes.
+- **Naming conventions**: Variable naming, function naming, constant naming patterns.
+- **Error handling**: What gets caught, what gets returned on failure, how errors propagate.
+
+For each pattern, note: which files use it, approximate frequency, whether it connects to a charter pattern from Step 2.
+
+## Step 4 — Merge and Rank
+
+Combine charter patterns (Step 2) and code patterns (Step 3). Deduplicate — if the same pattern appears in both, merge into one entry with richer context.
+
+Rank by: `frequency × importance`
+
+- TRIPWIRE patterns get 3× boost (breaking these has fleet-wide consequences)
+- `!` gotcha patterns get 2× boost (these cause subtle bugs)
+- Patterns appearing in 3+ files get 1.5× boost
+- Patterns unique to one file get 0.5× weight (may be local, not language-wide)
+
+Cut to **8–20 patterns**. If you have more than 20, you're documenting implementation details, not patterns. If fewer than 8, the language may not qualify after all — revisit the maturity gate.
+
+## Step 5 — Write Agent Pattern Sheet
+
+A separate file: `.gator/field-guides/{slug}-patterns.md`. Target: **under 80 lines**. The agent loads only this file alongside charters — it must be self-contained and concise.
+
+Format for each entry:
+
+```markdown
+### Pattern Name
+Files: file1.py, file2.py
+1–3 line description of when and how to apply this pattern.
+! Optional tripwire note — only if violating this pattern has non-obvious consequences.
+```
+
+Rules:
+- No code snippets in the pattern sheet (those go in the tutorial)
+- Every file reference must be a real file in the repo
+- Description answers: "When I encounter [situation], I should [action]"
+- Group related patterns (e.g., all error-handling patterns together)
+- Describe observed reality, not aspirational norms. If a pattern is followed by most scripts but not all, say which scripts follow it.
+
+## Step 6 — Write Architect Tutorial
+
+A separate file: `.gator/field-guides/{slug}-tutorial.md`. Target: **under 300 lines** (~5 pages). Cross-references the pattern sheet via frontmatter `patterns:` field.
+
+For each pattern from the pattern sheet (or a curated subset of the most important):
+
+```markdown
+### Pattern Name
+
+**Charter connection**: [charter name] — [specific section or tripwire]
+
+[Real code snippet from the repo, 3–10 lines, showing the pattern in use]
+
+**Why it matters**: 1 paragraph explaining what goes wrong if you violate this pattern
+or don't recognize it when reading code.
+
+**What to watch for**: 1 sentence — the signal that this pattern is relevant to
+what you're currently reading or writing.
+```
+
+Rules:
+- Every snippet must be copied from actual repo code (not invented)
+- Cite the source file for each snippet
+- Keep "why it matters" grounded in this repo's specific history or architecture, not generic advice
+- The tutorial reads like a colleague walking you through the codebase
+
+## Step 7 — Assemble and Validate
+
+Write two files per language in `.gator/field-guides/`:
+
+**Pattern sheet** (`{slug}-patterns.md`) frontmatter:
+```yaml
+---
+generated: YYYY-MM-DD
+generator: field-guide-gen-v1
+type: agent-patterns
+language: {slug}
+source-charters: [{charter1}, {charter2}, ...]
+source-file-count: {N}
+pattern-count: {N}
+tutorial: {slug}-tutorial.md
+---
+```
+
+**Tutorial** (`{slug}-tutorial.md`) frontmatter:
+```yaml
+---
+generated: YYYY-MM-DD
+generator: field-guide-gen-v1
+type: architect-tutorial
+language: {slug}
+source-charters: [{charter1}, {charter2}, ...]
+patterns: {slug}-patterns.md
+---
+```
+
+**Validation checklist**:
+- [ ] Every file reference in "Files:" lines resolves to a real file
+- [ ] Every charter reference in "Charter connection:" resolves to a real charter
+- [ ] Pattern count in frontmatter matches actual pattern count
+- [ ] Pattern sheet is under 80 lines
+- [ ] Tutorial is under 300 lines
+- [ ] No invented code snippets — every snippet traces to a source file
+- [ ] Pattern sheet and tutorial cross-reference each other in frontmatter
+
+## Reference
+
+→ [Constitution](../constitution.md) — field-guides/ in the file purposes table
+→ [Charter Format](../charters/README.md) — the notation these patterns reference
+→ [Concierge Responses](../reference-notes/concierge-responses.md) — when to surface field guides to the Architect

gator_command/templates/gator-starter/procedures/knowledge-capture.md

@@ -0,0 +1,57 @@
+# Procedure: Knowledge Capture — Where Things Go
+
+## Context
+
+AI models have built-in memory systems (Claude's `MEMORY.md`, Gemini's memory, Copilot's context, etc.). These systems are designed to persist information across sessions for a single user on a single model. They are **invisible** to other users and other models working in the same repo.
+
+Gator repos are designed to work across multiple users and multiple AI models. The `.gator/` folder is the shared knowledge layer. If repo knowledge ends up in a model's personal memory instead, it creates information silos that defeat the purpose of the system.
+
+## The Decision Rule
+
+When you learn something worth remembering, ask: **"Is this about the project or about the person?"**
+
+### Goes in `.gator/` (shared, visible to all)
+
+- Architectural decisions and their rationale
+- Code invariants, constraints, tripwires
+- Module boundaries and ownership
+- Data flows and access patterns
+- Bug context, incident notes, post-mortems
+- Project priorities, milestones, deadlines
+- Patterns that span modules
+- Anything a different user or model would need to work here effectively
+
+**Where in `.gator/`:**
+
+| What you learned | Where it goes |
+|---|---|
+| Something about a function or module | Charter update |
+| A decision with rationale | Thread |
+| A pattern or invariant spanning modules | Cross-cutting charter |
+| An idea or observation (unstructured) | `inbox.md` |
+| A priority shift | `roadmap.md` |
+| A project direction change | `mission.md` |
+| A recurring obligation or rhythm | `patterns.md` |
+
+### Goes in model memory (personal, per-user)
+
+- The user's communication preferences (terse vs. verbose, etc.)
+- The user's role and expertise level
+- Workflow habits specific to one person
+- Editor or tooling preferences
+
+### When in doubt
+
+Put it in `.gator/`. A redundant note in `inbox.md` costs nothing. Knowledge trapped in one model's memory is invisible and eventually lost.
+
+## Common Mistakes
+
+**Saving an Architect decision to memory instead of a thread.** The next model won't know about it. The next user won't know about it. The decision will be relitigated.
+
+**Saving a tripwire to memory instead of a charter.** The whole point of tripwires is that they protect everyone. A tripwire only one model knows about protects no one.
+
+**Saving project context to memory instead of `mission.md` or `roadmap.md`.** This creates drift — different models and users develop different understandings of what the project is and where it's going.
+
+## For Model-Specific Entry Points
+
+If you maintain a model-specific entry point file (e.g., `CLAUDE.md`, `GEMINI.md`, `AGENTS.md`), it should point the model to the constitution and `.gator/` as the primary knowledge source. Model-specific instructions in these files should be limited to behavioral configuration (how to invoke tools, formatting preferences), not project knowledge.