gator-command 1.0.0__py3-none-any.whl

gator_command/templates/gator-starter/reference-notes/dangerous-patterns.md

@@ -0,0 +1,91 @@
+# Dangerous Patterns Reference
+
+Patterns the agent must surface to the Architect before writing, running, or committing. This applies to all session activity — not just commits.
+
+The pre-commit hook catches these mechanically at commit time. This reference note governs agent behavior *during* the session: writing scripts, running commands, debugging, executing code.
+
+**Rule**: If the agent encounters any of these patterns in code it is about to write or execute, it stops and asks the Architect before proceeding. If the Architect approves, the agent logs the approval in `commit_draft.md`.
+
+## Credentials in the Conversation (Highest Priority)
+
+This is not a code pattern — it's a conversation-level security boundary.
+
+**If the Architect pastes a password, API key, token, private key, or any secret directly into a chat message, the agent must immediately stop and warn:**
+
+> **STOP — Credential Exposure**
+> The credential you just pasted has been transmitted to [provider] via the API request. It should be considered compromised regardless of what happens next. Rotate this credential immediately. I will not use, store, or repeat it.
+
+**Why this is the highest priority pattern**: Every other dangerous pattern in this catalog can be caught before damage occurs. A credential pasted into the conversation is compromised *the instant the message is sent* — before the agent even sees it. There is no undo. The credential is in the provider's request logs, potentially in training data pipelines, and must be treated as leaked.
+
+The agent cannot prevent the exposure (it happens before the agent responds), but it can:
+1. Warn immediately so the Architect rotates fast
+2. Refuse to use the credential (don't embed it in code, don't pass it to scripts)
+3. Not repeat the credential in its response (avoid amplifying the exposure)
+
+**Common scenarios**: Architect debugging auth failures pastes the raw token. Architect setting up a new service pastes the API key. Architect shares a `.env` file contents. Architect copies a database connection string with embedded password. All of these are compromised on paste.
+
+## Secrets & Credentials (in Code)
+
+| Pattern | Why it's dangerous |
+|---|---|
+| Hardcoded passwords (`password = "..."`) | Credentials in source code leak via git history, logs, and clones |
+| API keys/tokens in source (`api_key = "sk-..."`) | Same as passwords — once committed, consider them compromised |
+| Private key material (`-----BEGIN PRIVATE KEY-----`) | Cryptographic keys in source are permanent compromise vectors |
+| `.env` files in commits | Environment files contain secrets that should never enter version control |
+
+## Destructive Data Operations
+
+| Pattern | Why it's dangerous |
+|---|---|
+| `DROP TABLE` | Destroys table and all data. Irreversible without backup |
+| `DELETE FROM` without `WHERE` | Deletes all rows in a table. Usually a mistake |
+| `TRUNCATE TABLE` | Fast bulk deletion. Irreversible, not logged in transaction log on some DBs |
+| `ALTER TABLE ... DROP COLUMN` | Destroys column data. May break dependent queries silently |
+| `UPDATE` without `WHERE` | Overwrites all rows. Usually a mistake |
+
+## Code Execution Risks
+
+| Pattern | Why it's dangerous |
+|---|---|
+| `eval()` | Executes arbitrary code. If input is untrusted, this is remote code execution |
+| `exec()` | Same as eval but for statements. Same risk |
+| `subprocess` with `shell=True` | Shell injection — user input can escape into shell commands |
+| `os.system()` | Same as shell=True subprocess but harder to parameterize safely |
+| SQL string concatenation (`f"SELECT ... {user_input}"`) | SQL injection. Use parameterized queries |
+
+## Destructive System Operations
+
+| Pattern | Why it's dangerous |
+|---|---|
+| `rm -rf` / `shutil.rmtree()` | Recursive deletion. One wrong path = catastrophic data loss |
+| `git reset --hard` | Discards all uncommitted changes. Cannot be undone |
+| `git push --force` | Overwrites remote history. Can destroy other people's work |
+| `git clean -f` | Deletes untracked files. May include work not yet staged |
+| `chmod 777` / wide-open permissions | Security regression — makes files world-writable |
+| Disk formatting / partition operations | Catastrophic and irreversible |
+
+## Network & External Service Risks
+
+| Pattern | Why it's dangerous |
+|---|---|
+| Sending emails/messages programmatically | Can't unsend. May go to wrong recipients |
+| API calls that create/delete external resources | Cloud resources cost money and may be hard to recover |
+| Webhook registrations | May expose internal systems to external triggers |
+| DNS changes | Propagation delays make mistakes hard to reverse quickly |
+
+## What the Agent Does
+
+1. **Before writing**: If the agent is about to write code containing a dangerous pattern, it tells the Architect what it's about to write and why, and waits for confirmation.
+
+2. **Before executing**: If the agent is about to run a script, command, or test that contains a dangerous pattern (even if the code already exists), it surfaces the pattern and waits. This is especially important during debugging — "let me just run the migration script to see what happens" is exactly when accidents occur.
+
+3. **After Architect approval**: Log the approval in `commit_draft.md` with the pattern, the file, and the Architect's attribution. Example:
+   ```
+   - Architect approved DELETE FROM in tests/cleanup.py — test fixture teardown [#security] [#decision] — AG
+   ```
+
+4. **When in doubt**: Surface it. A false pause costs seconds. A missed destructive action costs hours, data, or reputation.
+
+## What This Is Not
+
+This is not a ban on dangerous patterns. Migrations need `DROP TABLE`. Tests need `eval()`. Deployment scripts need `rm -rf`. The rule is not "never use these" — it's "never use these without the Architect knowing and approving."

gator_command/templates/gator-starter/reference-notes/dashboard-operations.md

@@ -0,0 +1,22 @@
+# Dashboard Operations
+
+Notes on launching and operating the Gator Dashboard from an agent session.
+
+## Launching
+
+```
+python .gator/scripts/gator-dashboard.py
+```
+
+The script starts an HTTP server on port 8420, opens the browser, and enters `serve_forever()`. It works on the first invocation. Do not retry or attempt to verify the launch -- the server process stays alive but agent tooling may incorrectly report it as "completed" because only the startup banner is captured before the event loop takes over.
+
+**Known false signal**: background task tracking (Claude Code, Codex, other agent harnesses) can show the dashboard process as "completed" immediately after launch. This is a monitoring artifact, not a failure. The dashboard is running.
+
+## Flags
+
+| Flag | Effect |
+|------|--------|
+| `--no-open` | Start server without opening browser |
+| `--port N` | Use a specific port (default 8420, tries 8421-8429 on conflict) |
+| `--snapshot` | Write self-contained HTML to stdout and exit (no server) |
+| `--repo NAME` | Pre-load a specific repo view on open |

gator_command/templates/gator-starter/reference-notes/enforcer-configuration.md

@@ -0,0 +1,232 @@
+# Enforcer Configuration Guide
+
+This reference note helps a primary agent configure an enforcer for the Architect. When the Architect asks "how do I set up an enforcer?" or hits step 5 for the first time, use this to figure out what they have available and walk them through it.
+
+## The Conversation to Have
+
+Ask the Architect three things:
+
+1. **What's your primary agent?** (Claude, GPT/Codex, Gemini, etc.)
+2. **What API keys or CLI tools do you have?** (Anthropic, OpenAI, Google, or none)
+3. **How much do you care about cost?** (Determines model choice)
+
+Then match to a config below.
+
+## Decision Tree
+
+```
+Do you have any API key or CLI tool?
+├─ No → Mechanical lint only (Layer 1). Free, instant, no setup.
+│       Consider ollama for free local charter-grounded review.
+│
+├─ Yes → Is it the same vendor as your primary agent?
+│   ├─ Yes → It works, but cross-vendor is stronger.
+│   │         Same-vendor review is still better than nothing.
+│   └─ No → Ideal. Different training = different blind spots.
+│
+└─ Multiple → Pick the one that's different from your primary agent.
+```
+
+## Configs by Enforcer
+
+### Sonnet (Anthropic)
+
+**Best for**: Primary agent is GPT, Gemini, or any non-Anthropic model. Also fine as same-vendor enforcer when primary is Claude Opus — Sonnet is a different model with different trade-offs.
+
+**What the Architect needs**: `ANTHROPIC_API_KEY` from [console.anthropic.com](https://console.anthropic.com)
+
+**Cost**: Low. Sonnet is one of the cheapest capable models.
+
+**Config** (`enforcer-config.json`) — this is the default, no changes needed:
+```json
+{
+  "layer2_3": {
+    "provider": "anthropic",
+    "model": "claude-sonnet-4-6",
+    "api_key_env": "ANTHROPIC_API_KEY"
+  }
+}
+```
+
+**Setup steps**:
+```bash
+pip install anthropic
+export ANTHROPIC_API_KEY=sk-ant-...          # macOS/Linux
+# $env:ANTHROPIC_API_KEY = "sk-ant-..."      # Windows PowerShell
+```
+
+**Run**: `python .gator/scripts/enforcer-review.py`
+
+**If the primary agent is Codex**: this is the cleanest way to use Anthropic as enforcer. The Python script applies the enforcer role directly and avoids any ambiguity from Claude CLI also seeing the repo's `CLAUDE.md`.
+
+### GPT (OpenAI) via Python script
+
+**Best for**: Primary agent is Claude or Gemini.
+
+**What the Architect needs**: `OPENAI_API_KEY` from [platform.openai.com](https://platform.openai.com)
+
+**Cost**: `gpt-4o-mini` is very cheap. `gpt-4o` is moderate.
+
+**Config**:
+```json
+{
+  "layer2_3": {
+    "provider": "openai",
+    "model": "gpt-4o-mini",
+    "api_key_env": "OPENAI_API_KEY"
+  }
+}
+```
+
+**Setup steps**:
+```bash
+pip install openai
+export OPENAI_API_KEY=sk-...
+```
+
+**Run**: `python .gator/scripts/enforcer-review.py`
+
+### Codex CLI (OpenAI)
+
+**Best for**: Primary agent is Claude or Gemini. Architect wants to run the enforcer independently (no intermediary).
+
+**What the Architect needs**: Codex CLI installed, OpenAI account
+
+**Cost**: Depends on model (configured in `~/.codex/config.toml`)
+
+**No config file changes needed** — but give Codex the dedicated enforcer prompt explicitly, because `AGENTS.md` is the primary-agent entrypoint.
+
+**Setup steps**:
+```bash
+npm install -g @openai/codex
+codex login
+```
+
+**Run**: `codex review "Read .gator/scripts/enforcer-prompt.md for full instructions. Review the uncommitted changes against the charters."`
+
+**Note**: Codex review runs in a read-only sandbox by default. The Architect can run this in a separate terminal for fully independent review (no primary agent involved).
+
+### Gemini (Google)
+
+**Best for**: Primary agent is Claude or GPT.
+
+**What the Architect needs**: `GOOGLE_API_KEY` from [aistudio.google.com](https://aistudio.google.com)
+
+**Cost**: `gemini-2.0-flash` is very cheap. `gemini-2.5-pro` is moderate.
+
+**Config**:
+```json
+{
+  "layer2_3": {
+    "provider": "google",
+    "model": "gemini-2.0-flash",
+    "api_key_env": "GOOGLE_API_KEY"
+  }
+}
+```
+
+**Setup steps**:
+```bash
+pip install google-generativeai
+export GOOGLE_API_KEY=...
+```
+
+**Run**: `python .gator/scripts/enforcer-review.py`
+
+### Claude Code CLI (Anthropic)
+
+**Best for**: Architect wants a separate Claude terminal/session as the reviewer, rather than using the Python API path.
+
+**What the Architect needs**: Claude Code installed, Anthropic access configured
+
+**Run**:
+```bash
+claude --print "$(cat .gator/scripts/enforcer-prompt.md)"
+```
+
+**Trade-off**: workable, but less clean than the Python Anthropic path when `CLAUDE.md` in the same repo defines Claude as the primary agent. The explicit enforcer prompt should steer the session correctly, but the role boundary is cleaner through `enforcer-review.py`.
+
+### Local model via ollama (free, offline)
+
+**Best for**: No API keys, cost-sensitive, privacy-sensitive, or offline use.
+
+**What the Architect needs**: [ollama](https://ollama.com) installed
+
+**Cost**: Free. Runs locally.
+
+**Config**:
+```json
+{
+  "layer2_3": {
+    "provider": "ollama",
+    "model": "llama3"
+  }
+}
+```
+
+**Setup steps**:
+```bash
+# Install ollama from https://ollama.com
+ollama pull llama3
+```
+
+**Run**: `python .gator/scripts/enforcer-review.py`
+
+**Trade-off**: Free and private, but slower and less capable than cloud models. Good enough for catching obvious charter violations. Won't match Sonnet/GPT on nuanced boundary analysis.
+
+### Mechanical lint only (no model)
+
+**Best for**: Zero setup, no API keys, no local model. Quick hygiene check.
+
+**What the Architect needs**: Python 3. That's it.
+
+**No config changes needed.**
+
+**Run**: `python .gator/scripts/enforcer-review.py --layer 1`
+
+**Limitation**: Only catches secrets, SQL dangers, injection risks, TODO markers. Does **not** read charters, check TRIPWIREs, or verify boundary compliance. This is hygiene, not architectural review.
+
+## How the Config File Works
+
+The enforcer config lives at `.gator/scripts/enforcer-config.json`. The primary agent edits this file when configuring the enforcer for the Architect.
+
+```json
+{
+  "layer1": {
+    "enabled": true
+  },
+  "layer2_3": {
+    "provider": "anthropic",
+    "model": "claude-sonnet-4-6",
+    "api_key_env": "ANTHROPIC_API_KEY"
+  }
+}
+```
+
+- `layer1.enabled` — mechanical lint. Leave this `true`. No reason to disable it.
+- `layer2_3.provider` — which API to call: `anthropic`, `openai`, `google`, `ollama`, or `none`
+- `layer2_3.model` — the specific model identifier
+- `layer2_3.api_key_env` — the environment variable name holding the API key (not the key itself — never put secrets in this file)
+
+Setting `provider` to `"none"` disables charter-grounded review entirely. Layer 1 still runs.
+
+## Cross-Vendor Principle
+
+The enforcer should ideally be a **different vendor** than the primary agent. Different training data, different RLHF, different blind spots. This isn't dogma — same-vendor is still better than nothing — but cross-vendor review is where the real value of independent verification comes from.
+
+| Primary agent | Recommended enforcer |
+|---------------|---------------------|
+| Claude (Opus) | Sonnet (same vendor, different model), GPT, or Gemini |
+| GPT / Codex | Sonnet via `enforcer-review.py`, GPT/Codex via CLI, or Gemini |
+| Gemini | Sonnet or GPT |
+
+## What the Agent Should Do
+
+When an Architect asks to set up an enforcer:
+
+1. Ask the three questions above (primary agent, available keys/tools, cost sensitivity)
+2. Pick the matching config from this guide
+3. Edit `enforcer-config.json` with the right provider/model
+4. Help the Architect set the environment variable (show the exact export command)
+5. Run a test review to confirm it works
+6. Show the Architect where `whiteboard.md` is so they can verify findings independently

gator_command/templates/gator-starter/reference-notes/example-project.md

@@ -0,0 +1,289 @@
+# Worked Example: taskflow (a simple Python CLI task manager)
+
+This is a complete reference showing what a populated Gator knowledge layer looks like for a small Python project. Study this before bootstrapping your own project. The format, density, and style shown here is what you're aiming for.
+
+---
+
+## The Project
+
+`taskflow` — a CLI task manager in Python. ~800 lines across 5 files:
+```
+taskflow/
+  __main__.py      # CLI entry point (click)
+  store.py         # SQLite persistence
+  models.py        # Task, Project dataclasses
+  filters.py       # Query builder for task lists
+  export.py        # Markdown/JSON export
+```
+
+---
+
+## Example: mission.md
+
+```markdown
+# Mission
+
+## What We're Building
+
+A command-line task manager that stores tasks in SQLite and exports to Markdown.
+Designed for solo developers who want something between a text file and Jira.
+
+## Why It Exists
+
+Every task manager either requires a browser or locks data in a proprietary format.
+taskflow is local-first, file-friendly, and scriptable.
+
+## What Success Looks Like
+
+- `task add "fix login bug" --project api` works in under 50ms
+- Tasks survive across machines via git (SQLite file in repo)
+- Weekly review exports to Markdown that reads well in any viewer
+```
+
+---
+
+## Example: roadmap.md
+
+```markdown
+# Roadmap
+
+| # | Feature | Status | Next step |
+|---|---------|--------|-----------|
+| 1 | Core CRUD (add/done/delete/list) | Done | — |
+| 2 | Project grouping | Done | — |
+| 3 | Priority sorting | Building | Wire into `list` output |
+| 4 | Markdown export | Designed | Template in export.py |
+| 5 | Recurring tasks | Considering | Need cron-like syntax |
+| 6 | Due dates with reminders | Deferred | After recurring tasks |
+```
+
+---
+
+## Example: charters/INDEX.md
+
+```markdown
+# Charter Index
+
+**Always read first:** [Cross-Cutting](cross-cutting.md)
+
+| If you're changing... | Read these charters |
+|---|---|
+| `taskflow/__main__.py` | [CLI](cli.md) + [Cross-Cutting](cross-cutting.md) |
+| `taskflow/store.py` | [Store](store.md) + [Cross-Cutting](cross-cutting.md) |
+| `taskflow/models.py` | [Models](models.md) |
+| `taskflow/filters.py` | [Store](store.md) + [Cross-Cutting](cross-cutting.md) |
+| `taskflow/export.py` | [Export](export.md) |
+```
+
+---
+
+## Example: charters/cross-cutting.md
+
+```markdown
+# Charter: Cross-Cutting Patterns
+
+### TRIPWIRE: SQLite file locking
+
+The store opens a single connection at CLI entry and closes on exit.
+Concurrent access (two terminals) will hit SQLite's write lock.
+This is intentional — taskflow is single-user. Do NOT add connection
+pooling or WAL mode unless the mission changes to multi-user.
+
+### TRIPWIRE: Task ID stability
+
+Task IDs are SQLite rowids. They are permanent — deletion does not
+reassign IDs. Export files reference IDs. If you ever compact/reindex,
+every exported Markdown file breaks.
+
+### Data flow: add command
+
+__main__.py (parse args)
+  → models.py (Task dataclass construction)
+    → store.py (INSERT, returns ID)
+      → __main__.py (prints confirmation with ID)
+
+### Data flow: export command
+
+__main__.py (parse args, date range)
+  → filters.py (build WHERE clause)
+    → store.py (SELECT with filter)
+      → export.py (format as Markdown or JSON)
+        → __main__.py (write to stdout or file)
+```
+
+---
+
+## Example: charters/store.md
+
+```markdown
+# Charter: Store
+
+**Covers**: `taskflow/store.py`
+
+## Owns
+
+SQLite connection lifecycle, all INSERT/UPDATE/DELETE/SELECT operations,
+schema migration, file path resolution.
+
+## Does Not Own
+
+Task validation (models.py owns that).
+Query building for complex filters (filters.py owns that).
+Formatting output (export.py owns that).
+
+---
+
+### init_db(path)
+File: taskflow/store.py
+Creates SQLite DB at path if absent. Runs migrations.
+← __main__.py (called once at startup)
+→ sqlite3.connect()
+! Path defaults to ./tasks.db relative to CWD, not the package.
+  This is intentional — the DB lives in the project, not globally.
+
+### add_task(task: Task) -> int
+File: taskflow/store.py
+Inserts Task, returns rowid.
+Models: Task(R), sqlite(W)
+← __main__.py add command
+! Returns the rowid, not a Task object. Caller must use this ID.
+
+### get_tasks(filter: Filter) -> list[Task]
+File: taskflow/store.py
+Runs SELECT with filter's WHERE clause, returns Task list.
+Models: Task(R), sqlite(R)
+← __main__.py list command, export.py
+→ filters.py build_where()
+! Returns empty list (not None) when no matches. Callers rely on this.
+
+### mark_done(task_id: int) -> bool
+File: taskflow/store.py
+Sets done=True, done_at=now(). Returns False if ID not found.
+Models: sqlite(RW)
+← __main__.py done command
+! Does NOT delete the task. "Done" is a state, not removal.
+
+### delete_task(task_id: int) -> bool
+File: taskflow/store.py
+Hard deletes by rowid. Returns False if ID not found.
+Models: sqlite(W)
+← __main__.py delete command
+! See cross-cutting TRIPWIRE on ID stability.
+
+---
+
+## Before Changing This Module
+
+- Schema changes require a migration function (see bottom of file)
+- The connection is opened once and passed around — not per-query
+- All timestamps are UTC ISO-8601 strings, not datetime objects
+
+## Connections
+
+→ [Models](models.md) — Task dataclass definition
+→ [Cross-Cutting](cross-cutting.md) — SQLite locking, ID stability
+```
+
+---
+
+## Example: charters/cli.md
+
+```markdown
+# Charter: CLI
+
+**Covers**: `taskflow/__main__.py`
+
+## Owns
+
+Argument parsing (click), command routing, DB initialization,
+user-facing output formatting, exit codes.
+
+## Does Not Own
+
+Business logic (store.py). Data shapes (models.py).
+Export formatting (export.py).
+
+---
+
+### main()
+File: taskflow/__main__.py
+Click group entry point. Initializes DB connection.
+→ init_db() in store.py
+! Exit code 0 on success, 1 on error. Scripts depend on this.
+
+### add(name, project, priority)
+File: taskflow/__main__.py
+Parses add-command args, creates Task, calls store.
+→ Task() in models.py, add_task() in store.py
+← CLI: `task add "name" --project X --priority N`
+
+### list(project, status, sort)
+File: taskflow/__main__.py
+Builds filter from flags, fetches tasks, prints table.
+→ Filter() in filters.py, get_tasks() in store.py
+! --sort=priority is descending (high first). Not alphabetical.
+
+---
+
+## Before Changing This Module
+
+- Every command prints to stdout. Errors go to stderr.
+- Click handles --help automatically. Don't duplicate.
+- The DB path comes from --db flag or TASKFLOW_DB env var.
+
+## Connections
+
+→ [Store](store.md) — all persistence
+→ [Cross-Cutting](cross-cutting.md) — data flows start here
+```
+
+---
+
+## Example: threads/sqlite-vs-postgres.md
+
+```markdown
+---
+last-touched: 2026-05-10
+tags: [architecture, database, decision]
+---
+
+# SQLite vs Postgres
+
+## Summary
+
+Evaluated Postgres for multi-user support. Decision: stay on SQLite.
+The project is single-user by mission. Postgres adds deployment complexity
+(managed service, connection strings, migrations) for zero benefit at
+current scope. Revisit only if mission changes to multi-user.
+
+## Connections
+
+→ [Store charter](../charters/store.md) — the module this decision constrains
+```
+
+---
+
+## Example: commit_draft.md
+
+```markdown
+# Session Change Log
+
+- Added priority field to Task model and store schema [#feature] [#models] -agent
+- Updated store charter: add_task now accepts priority param [#charter-update] -agent
+- Architect decision: priority is 1-5 integer, not string label [#decision] [#models] -architect
+- Updated cross-cutting: added note about priority sort direction [#charter-update] -agent
+```
+
+---
+
+## Key Observations
+
+1. **Charters are short.** Each function entry is 3-5 lines. The whole store charter is maybe 60 lines for a real module. This is a small, compressed map — not a rewrite of the code.
+
+2. **Cross-cutting is the star.** The TRIPWIREs prevent the two most common agent mistakes: adding connection pooling to a single-user app, and reindexing IDs that exported files depend on.
+
+3. **"Does not own" is load-bearing.** It prevents the agent from putting export logic in the store, or validation logic in the CLI. Scope boundaries are the first thing that erodes without governance.
+
+4. **Threads are tiny.** The SQLite-vs-Postgres thread is 8 lines. It exists so the decision doesn't have to be re-explained every session.
+
+5. **The loop is visible in commit_draft.** Charter updates appear alongside code changes. They're the same operation.