gator-command 1.0.0__py3-none-any.whl

gator_command/templates/gator-starter/reference-notes/failure-modes-and-self-correction.md

@@ -0,0 +1,72 @@
+---
+last-touched: 2026-05-17
+tags: [governance, charters, failure-modes, navigation-coding]
+---
+
+# Failure Modes and Self-Correction
+
+## Summary
+
+A common objection to charters is that a stale charter could become a confidently wrong map. In practice, that is not the dominant failure mode. The more typical pattern is that the charter gives the agent an expectation about the code, and the code immediately confirms or violates that expectation. When the map is even moderately viable, disagreement tends to surface as visible confusion rather than silent corruption.
+
+Put differently: the charter is not ground truth. It is a structured hypothesis about the codebase. Its value is twofold:
+
+- if the charter and code agree, orientation is faster
+- if the charter and code disagree, the discrepancy becomes visible early
+
+This makes charters useful not only as retained memory, but as cross-check surfaces.
+
+## Why This Does Not Behave Like Static Docs
+
+Static architecture docs mostly inform. A navigation-coded charter loop does two jobs:
+
+- it informs the next change
+- it exposes drift when the documented expectation no longer matches the code
+
+That is why the recursive maintenance loop matters so much. The system is not "documentation plus code." It is code, map, and discrepancy detection operating together.
+
+## Typical Failure Pattern
+
+The feared pattern is:
+
+1. Charter is stale
+2. Agent trusts it blindly
+3. Agent makes bad code changes
+4. Bad map causes more bad work
+
+The empirically more common pattern is:
+
+1. Charter is stale
+2. Agent reads it and forms an expectation
+3. The code does not match the expected structure
+4. The agent stops, asks, or updates the map
+
+An example shape is: "the charter says `write_file()` should exist here; where is it?" The mismatch becomes the signal.
+
+## What Makes This Work
+
+This self-correcting behavior depends on a few conditions:
+
+- the charter is close enough to reality to create useful expectations
+- the agent still reads the code rather than treating the charter as an oracle
+- disagreement is treated as a reason to inspect, not to push through
+
+If those conditions hold, both the charter and the code do not need to be perfect. They only need to be different enough that drift is detectable.
+
+## The Better Counterfactual
+
+This also answers part of the "why not just write `ARCHITECTURE.md` and module `README`s?" objection.
+
+The issue is not only that static docs go stale. It is that they usually do not participate in a loop where:
+
+- they are consulted before edits
+- they are updated as part of the same operation
+- their mismatch with code is operationally useful
+
+Navigation coding gets much of its value from that loop, not only from having written things down.
+
+## Connections
+
+→ [What Gator Requires From a Model](what-gator-requires-from-a-model.md) — assumes the agent reads before acting and checks repo artifacts against code
+→ [Why Navigation Coding Feels Different](why-navigation-coding-feels-different.md) — explains the friction of resolving ambiguity before coding
+→ [Supporting Research](supporting-research.md) — evidence for structured navigation, independent review, and compression

gator_command/templates/gator-starter/reference-notes/git-workflow.md

@@ -0,0 +1,60 @@
+# Git Workflow
+
+Suggested git process for projects using Gator. Not enforced — adapt to your team and comfort level.
+
+## Two Modes
+
+### Team / Careful Mode
+
+For teams, shared repos, or when changes carry risk.
+
+```
+main (stable, deployable)
+  └── dev (integration branch)
+        ├── feature/add-auth
+        ├── feature/refactor-store
+        └── fix/query-timeout
+```
+
+1. **Branch from dev** for each piece of work (`feature/`, `fix/`, `chore/`)
+2. **Work on the branch** — normal Gator loop (read charters, change code, update charters)
+3. **PR into dev** — review the diff, check that charters were updated, run enforcer if warranted
+4. **Test on dev** — integration, smoke tests, whatever the project needs
+5. **Merge dev to main** — when dev is stable and reviewed. This is the release gate.
+
+### Solo / Streamlined Mode
+
+For solo projects or when you're the only one touching the code.
+
+```
+main (stable)
+  └── dev (working branch)
+```
+
+1. **Work on dev** — normal Gator loop
+2. **When happy, commit to dev**
+3. **Merge dev to main** — when the work is complete and you're confident
+
+No feature branches needed. Dev is your working surface, main is your "known good" state.
+
+## Which Mode?
+
+| Situation | Use |
+|-----------|-----|
+| Solo project, one contributor | Streamlined |
+| Team, shared repo | Team mode |
+| Solo but high-stakes (production, public API) | Team mode — the branch discipline protects you |
+| Early prototyping, exploring | Streamlined — don't let process slow discovery |
+
+## How Gator Fits
+
+- **Charters update on the working branch**, not on main. They travel with the code.
+- **Enforcer reviews happen before PR or before merge** — the Architect decides when and at what level.
+- **commit_draft.md accumulates on the working branch until commit time** — use it to draft the next commit message or PR context, then clear it immediately after the commit so the next session starts fresh.
+- **Don't branch .gator/ separately from code.** The knowledge layer and the code must stay in sync. If you branch the code, the charters go with it.
+
+## What to Avoid
+
+- Don't commit directly to main during active development. Even in solo mode, use dev as a buffer.
+- Don't let feature branches live longer than a few days. Long-lived branches mean charter drift.
+- Don't merge without checking that charters reflect the current code state. The enforcer can catch this, but it's faster to just look.

gator_command/templates/gator-starter/reference-notes/identity-and-ownership.md

@@ -0,0 +1,37 @@
+# Identity and Ownership Context
+
+## The Problem
+
+When you bootstrap a fresh project, you don't know who you're talking to or how many people share this repo. Getting this wrong early creates friction that compounds:
+
+- In a **solo repo**, one person is the Architect. Identity and mission are tightly coupled. You can learn their preferences, role, and context — it all belongs in the same place.
+- In a **team repo**, multiple people share the `.gator/` folder. The project is the stable identity, not any individual. Writing the knowledge layer around one person's perspective alienates everyone else.
+
+## The Rule
+
+**Don't assume. Ask.**
+
+Before populating `mission.md` or forming a mental model of "who you're working with," establish:
+
+1. **Is this a solo or team repo?** ("Is this your project, or does a team share this repo?")
+2. **Who is the Architect?** In solo repos, it's obvious. In team repos, there may be one Architect, rotating Architects, or a shared-ownership model.
+3. **Where does individual context belong?** In solo repos, the `.gator/` folder can hold user-specific notes freely. In team repos, individual preferences and context should stay outside the shared knowledge layer (e.g., in personal config, not in `mission.md`).
+
+## What This Means in Practice
+
+**Solo repo**: `mission.md` can reflect the person's goals, style, and priorities directly. Threads and inbox can be informal. The whole `.gator/` folder is theirs.
+
+**Team repo**: `mission.md` describes the *project's* goals, not any individual's. Keep it neutral and factual. Individual preferences, roles, and context should not be baked into shared files. If team members need individual context, that lives outside `.gator/` (e.g., in their own editor config or personal notes).
+
+## The Cost of Getting It Wrong
+
+If you pin identity to a person in a team repo:
+- Other contributors feel like guests in their own project
+- `mission.md` reads like one person's vision, not the team's
+- Threads and decisions carry implicit bias toward one perspective
+
+If you treat a solo repo as a team repo:
+- The knowledge layer feels impersonal and bureaucratic
+- You miss opportunities to tailor the experience to the one person who uses it
+
+Neither error is fatal, but both create drag. One question at bootstrap prevents it.

gator_command/templates/gator-starter/reference-notes/refactor-approach.md

@@ -0,0 +1,155 @@
+# Refactor Approach
+
+This note describes how an AI agent should approach significant refactors under Gator.
+
+The core idea: **do not "rewrite and hope."** Create a safe track, preserve behavior, extract behind stable seams, verify continuously, and keep the Architect involved in intent and boundary decisions.
+
+## The Default Shape
+
+For a non-trivial refactor, the agent should prefer this sequence:
+
+1. Create a dedicated refactor branch from `dev`
+2. Read the relevant charters and cross-cutting notes first
+3. Confirm refactor intent and boundaries with the Architect
+4. Identify stable seams where new modules can be introduced without changing public behavior
+5. Extract new modules behind the existing call surface
+6. Add or extend tests while behavior is still stable
+7. Switch callers over only after the new path works
+8. Remove old code only after parity is verified
+9. Update charters to reflect the new ownership map
+
+This is a **parallel-track refactor**, not a big-bang rewrite.
+
+## Branch Discipline
+
+Significant refactors should happen on a dedicated branch, not directly on `dev`.
+
+Suggested names:
+
+- `refactor/<area>`
+- `feature/refactor-<area>`
+
+Why:
+
+- the refactor may take several commits before the code is clearer than it was
+- the Architect needs a visible diff and a reversible checkpoint
+- charter changes during a refactor can be substantial and should be reviewable as a set
+
+If the work is high-risk, keep `main` as the known-good state, `dev` as the normal working branch, and the refactor branch as the isolated mutation surface.
+
+## Charter-First Navigation
+
+Before changing code, the agent should:
+
+- read the module charters for the touched files
+- read `cross-cutting.md` for repo-wide invariants and tripwires
+- identify which functions are stable external surfaces versus internal implementation details
+- identify what the Architect believes the module *should* own after the refactor
+
+During refactors, charters serve four jobs:
+
+- dependency map
+- invariant checklist
+- cutover checklist
+- final ownership map
+
+If the charters are missing or obviously stale, the right move is often to repair the map first, then refactor.
+
+## Architect Checkpoints
+
+Refactors need more Architect interaction than ordinary feature work.
+
+The agent should explicitly confirm:
+
+- the goal of the refactor
+- what behavior must not change
+- whether this is extraction, simplification, decomposition, or redesign
+- whether naming and ownership should change
+- whether compatibility shims are acceptable during transition
+
+The agent should not silently reinterpret a refactor as a redesign.
+
+Good checkpoint questions:
+
+- "Is the goal better structure with behavior preserved, or are we also changing behavior?"
+- "Should this module become thinner and delegate, or still own orchestration?"
+- "Do you want a temporary adapter layer during migration?"
+
+## Preferred Refactor Pattern
+
+When possible, prefer:
+
+1. leave the existing entry points in place
+2. extract new logic into a new module
+3. call the new module from the old path
+4. verify behavior with tests
+5. migrate callers gradually
+6. delete the old implementation only after parity is established
+
+This reduces blast radius and keeps rollback simple.
+
+Examples:
+
+- extract parsing logic out of a giant CLI script into `*_core.py`
+- move file-system traversal into a helper module while keeping the old command entry point
+- split a mixed "read + transform + render" function into separable pieces behind the same public API
+
+## What To Avoid
+
+Avoid these failure modes:
+
+- rewriting large files wholesale without stable checkpoints
+- changing public behavior and structure at the same time without Architect signoff
+- moving ownership boundaries without updating charters
+- deleting old code before the new path is tested
+- introducing new abstractions that are not yet called by the existing program
+- mixing refactor work with unrelated feature additions
+
+The smell is: **the diff is large, the behavior changed, the ownership moved, and there is no parity proof.**
+
+## Tests During Refactor
+
+Tests are part of the extraction path, not a cleanup step afterward.
+
+Preferred order:
+
+1. identify current behavior
+2. capture it with tests where practical
+3. extract new module
+4. route old entry point through new module
+5. extend tests for the new boundary
+6. remove legacy path only after green verification
+
+Where full automated coverage is not available, use:
+
+- targeted script invocations
+- golden-file comparisons
+- fixture-based behavior checks
+- before/after command output comparison
+
+For AI-assisted refactors, "works on inspection" is not enough.
+
+## Charter Updates During Refactor
+
+Refactors often create temporary asymmetry between code and charters. The agent should keep the map usable throughout the transition.
+
+Preferred approach:
+
+- update charters incrementally as ownership moves
+- note temporary adapters explicitly
+- update `Covers`, caller/callee arrows, and tripwires as soon as they change
+- remove obsolete charter entries when the old code is actually gone
+
+If a temporary shim exists, the charter should say so plainly.
+
+## A Good Refactor Outcome
+
+A good Gator refactor leaves:
+
+- smaller modules with clearer ownership
+- stable entry points or an explicit migration path
+- tests that prove parity or intended change
+- charters that match the new structure
+- a branch diff the Architect can review coherently
+
+The refactor is not complete when the code "looks cleaner." It is complete when the **structure, tests, and charters agree**.

gator_command/templates/gator-starter/reference-notes/what-gator-requires-from-a-model.md

@@ -0,0 +1,108 @@
+# What Gator Requires From a Model
+
+Gator is not magic. It is a harness. It improves results when the model behaves in ways the harness can work with.
+
+This note explains the minimum behavioral assumptions behind Gator, why some models benefit more than others, and why short structured instructions outperform one giant prompt file.
+
+## The Core Requirement
+
+Gator works best when the model is willing to:
+
+- read before acting
+- treat repo artifacts as authoritative
+- follow workflow instructions across multiple steps
+- update the knowledge layer after changing code
+- distinguish project facts from general priors
+
+In practice, this means Gator is a multiplier on **model discipline**. A strong explorer with poor instruction-following will still miss value that a more disciplined model captures.
+
+## Minimum Behavioral Assumptions
+
+For Gator to work at all, the model does not need to be perfect. It does need a few baseline traits:
+
+### 1. Instruction-following
+
+The model must reliably honor the entry point and the constitution. If it ignores `AGENTS.md`, skips `constitution.md`, or treats the loop as optional, the governance layer collapses into passive documentation.
+
+### 2. Willingness to read structured context
+
+The model must be able to use `mission.md`, `roadmap.md`, charters, and reference notes as working context rather than treating them as decorative docs. Gator assumes the model can navigate from a small map to a relevant local subset.
+
+### 3. Multi-step persistence
+
+The loop is not one instruction. It is a sequence: read, plan, change, update charters, log, lint, optionally review. Gator depends on the model being able to hold that sequence together across a session.
+
+### 4. Respect for repo state over prior assumptions
+
+The model must be willing to replace its generic idea of how software "usually" works with what this repo says is true. This is especially important for `Does Not Own` boundaries and `TRIPWIRE` patterns.
+
+## What Gator Gives a Strong Model
+
+When the model already has good tool use and repo traversal, Gator improves performance in three ways:
+
+### 1. Better orientation
+
+The model starts with a map instead of discovering everything from raw exploration. This reduces cold-start ambiguity and helps the model find the right files faster.
+
+### 2. Better behavioral discipline
+
+The constitution, charters, and reference notes turn good practice into explicit local rules. A model that follows instructions gets a tighter behavioral rail than raw code alone provides.
+
+### 3. Better continuity
+
+The model does not need to reconstruct project intent from scratch each session. Decisions, boundaries, and recurring Architect questions are already captured in repo artifacts.
+
+## Failure Modes
+
+Gator degrades when the model behaves like an undisciplined fast local optimizer.
+
+Common failure modes:
+
+- **Skips the map**: reads code directly, ignores charters, and answers from priors
+- **Treats docs as advisory**: follows the code but not the governance
+- **Optimizes for immediate completion**: makes the code change but skips charter updates and session logging
+- **Hallucinates continuity**: claims knowledge of prior decisions without grounding in repo artifacts
+- **Overloads context**: reads too much at once instead of navigating to the relevant subset
+
+These are not failures of the idea. They are failures of harness compliance.
+
+## Why Short Structured Instructions Beat One Giant Prompt
+
+Gator assumes that shorter top-level instructions plus structured repo artifacts outperform a single monolithic instruction file.
+
+Why:
+
+- A short entry point is easier for the model to obey consistently
+- The constitution separates global rules from local code knowledge
+- Charters localize understanding to the module being changed
+- Reference notes answer recurring process questions without bloating the main instruction surface
+- The model loads what is relevant instead of dragging every rule into every task
+
+This is why Gator uses a layered structure:
+
+- `AGENTS.md` / `CLAUDE.md` / `GEMINI.md` -- entry point
+- `constitution.md` -- global workflow and governance
+- `charters/` -- code-local map
+- `reference-notes/` -- cognitive aids and repeated explanations
+- `threads/` / `artifacts/` -- retained project memory
+
+The goal is not "more instructions." The goal is **better instruction topology**.
+
+## Codex, Claude, and Similar Agents
+
+Agents with strong tool use already perform well through live exploration. Gator helps them by converting some repeated exploration into maintained structure. The better the model is at reading, navigating, and complying with local instructions, the more value Gator adds.
+
+This is why Gator often helps disciplined models more than rogue ones:
+
+- disciplined model + Gator = navigation with accumulation
+- rogue model + Gator = some orientation benefit, but much less continuity and governance benefit
+
+Even with a less disciplined model, the structure still creates gravity. A visible constitution, explicit charter index, and dedicated mission/roadmap files make correct orientation easier than in a repo with only raw code and a giant prompt file.
+
+## Practical Test
+
+The practical question is simple:
+
+> Does the model behave as if the repo has a memory and a workflow, or as if every task starts from zero?
+
+If the answer is the first, Gator compounds. If the answer is the second, Gator still helps, but only partially.

gator_command/templates/gator-starter/reference-notes/why-navigation-coding-feels-different.md

@@ -0,0 +1,99 @@
+# Why Navigation Coding Feels Different
+
+One of the first things PIs notice in Gator is that the interaction does not feel like ordinary prompting.
+
+Instead of "tell the model what to build and wait," the Architect gets pulled into a sequence of specific questions:
+
+- what exactly should this module own?
+- is this behavior intentional or accidental?
+- what must stay synchronized if this changes?
+- what is the real next step here?
+- is this a local edit or a boundary decision?
+
+That difference is not incidental. It is part of the architecture.
+
+## Prompting vs. Navigation
+
+In prompt-driven workflows, the human often operates as a requester:
+
+- describe the task
+- wait for output
+- inspect the result
+- correct it if needed
+
+In navigation coding, the human operates more like an Architect under active questioning:
+
+- clarify intent before code is written
+- answer boundary questions while the plan is still cheap to change
+- resolve ambiguities the repo cannot infer on its own
+- make the judgment calls only the human can make
+
+The model is not just generating code. It is repeatedly trying to align the next change with the repo's existing structure and the Architect's intent.
+
+## Why the Questions Get So Specific
+
+When Gator is working properly, the agent starts from charters, mission, roadmap, recent session history, and cross-cutting patterns. That gives it enough structure to ask better questions than a generic prompt loop would.
+
+The questions become more specific because the map is more specific.
+
+This is similar to what happens when a capable new engineer pair-programs with a senior engineer on a real codebase. The new engineer does not just ask "what should I build?" They ask:
+
+- which subsystem should own this?
+- do we already have a pattern for this case?
+- what is safe to defer?
+- what looks local but is actually cross-cutting?
+
+Navigation coding reproduces that dynamic in a repo-native way.
+
+## Why This Is Naturally Allergic to Vibe Coding
+
+Vibe coding works best when ambiguity is tolerated and fast output is rewarded.
+
+Navigation coding does the opposite:
+
+- it pulls ambiguity forward
+- it asks the Architect to resolve it explicitly
+- it records the answer in the repo
+- it treats unresolved architectural questions as real work, not as noise around the work
+
+That makes the workflow less comfortable for people who want the feeling of progress without sustained attention. It also makes it much harder to glide past load-bearing uncertainty with a plausible-looking answer.
+
+The friction is not a bug. It is a defensive mechanism.
+
+## The Attention Trade
+
+Navigation coding demands more attention from the Architect at the moments where judgment matters most.
+
+That is the trade:
+
+- more attention upstream
+- less cleanup downstream
+
+The process does not remove human judgment. It relocates that judgment earlier, where it is cheaper, more precise, and easier to preserve.
+
+This is why Gator can feel more intense than simple prompt-and-walk-away workflows. The system keeps asking for specificity until the map, the code, and the Architect's intent are aligned enough to proceed safely.
+
+## Why Some People Will Bounce Off It
+
+Not every user wants this mode.
+
+Some people want:
+
+- immediate output
+- low interruption
+- minimal architectural discussion
+- a workflow that feels lightweight even if it accumulates confusion
+
+Navigation coding is not optimized for that experience. It is optimized for long-lived repo comprehension.
+
+That means it will feel natural to some engineers and exhausting to others. The ones who value architectural control, continuity, and grounded collaboration tend to see the questions as the point. The ones who want a looser relationship with the code often experience the same questions as friction.
+
+## The Deeper Difference
+
+The deepest difference is not just that Gator stores better project memory.
+
+It changes the human-model contract.
+
+The Architect is no longer a person issuing isolated prompts into an amnesic system. The Architect becomes a participant in a governed loop that keeps extracting, testing, and preserving project knowledge while the code changes.
+
+That is why navigation coding feels more like engineering collaboration than prompting.