manual_slop/AGENTS.md

# AGENTS.md

## What This Is

Manual Slop is a local GUI orchestrator for LLM-driven coding sessions. It bridges high-latency AI reasoning with a low-latency ImGui render loop via a thread-safe async pipeline; every AI-generated payload passes through a human-auditable gate before execution.

## The Conductor Convention

All AI agents consuming this project must read `./conductor/workflow.md` and treat `./conductor/tracks.md` as the task registry. Track implementation follows the TDD protocol documented in `conductor/workflow.md` with per-file atomic commits and git notes.

## Guidance for AI Agents

Detailed agent guidance lives in the following locations — read these directly, do not duplicate content here:

- **MUST READ TO - CORRECT EDIT WORKFLOW** `conductor/edit_workflow.md`
- **Operational workflow:** `conductor/workflow.md`
- **Code style and process:** `conductor/product-guidelines.md`
- **Tech stack and constraints:** `conductor/tech-stack.md`
- **Product context:** `conductor/product.md`
- **MMA orchestrator role:** `mma-orchestrator/SKILL.md`
- **Tier 1 (Orchestrator):** `.agents/skills/mma-tier1-orchestrator/SKILL.md`
- **Tier 2 (Tech Lead):** `.agents/skills/mma-tier2-tech-lead/SKILL.md`
- **Tier 3 (Worker):** `.agents/skills/mma-tier3-worker/SKILL.md`
- **Tier 4 (QA):** `.agents/skills/mma-tier4-qa/SKILL.md`

## Canonical Operating Rules

@conductor/code_styleguides/data_oriented_design.md
This is the canonical DOD reference. The same file is injected into the Application's RAG / context assembly via `[agent].context_files` in `manual_slop.toml` — one source of truth for both harnesses. Edit it there; do not duplicate rules into this file.

## Code Styleguides (the convention catalog)

Per-domain rules live in `conductor/code_styleguides/`. The full list is in `./docs/AGENTS.md` §2 (the canonical 6-styleguide catalog with one-line summaries + when-to-read). This section is a pointer.

**The short version (the 6 styleguides):**

- `data_oriented_design.md` — The canonical DOD reference (Tier 0/1/2; 3 defaults to reject; 7-question simplification pass)
- `agent_memory_dimensions.md` — The 4 memory dimensions (curation / discussion / RAG / knowledge) and when to use each
- `rag_integration_discipline.md` — The conservative-RAG rule: opt-in, complement, provenance, no mutation
- `cache_friendly_context.md` — Stable-to-volatile context ordering; the cache TTL GUI contract; the byte-comparison test
- `knowledge_artifacts.md` — The knowledge harvest pattern: category files, provenance, sha256 ledger, digest regeneration
- `feature_flags.md` — Codifies "delete to turn off" (file presence) + config flags; when to use each
## Human-Facing Documentation

For understanding, using, and maintaining the tool, see `docs/Readme.md` (the canonical teaching document) and `./docs/AGENTS.md` (the agent-facing mirror of `docs/Readme.md`).

The 14 deep-dive guides under `docs/` (`guide_architecture.md`, `guide_ai_client.md`, etc.) are referenced from `docs/Readme.md`; an agent reading for a feature scope should read `./docs/AGENTS.md` first, then the relevant `guide_*.md`.

## Critical Anti-Patterns

This is a thin index. For the full lists, see the canonical styleguides:
- `conductor/code_styleguides/python.md` §"AI-Agent Specific Conventions" + §"Anti-Patterns (LLM Default Anti-Patterns)" — the full LLM anti-pattern list (navigation, no comments, no diagnostic noise, TDD, decorator-orphan, ast.parse, set_file_slice, etc.)
- `conductor/code_styleguides/data_oriented_design.md` §8.5 — the Python Type Promotion Mandate (technical canonical for opaque types)
- `conductor/edit_workflow.md` — the edit tool contract
- `conductor/workflow.md` §"Known Pitfalls" + §"Skip-Marker Policy" — operational pitfalls

### The 4 canonical HARD BANs (in this file because they're project-wide)

- **HARD BAN: `git restore` / `git checkout -- <file>` / `git reset`** are FORBIDDEN without explicit user permission in the same message. They destroyed user in-progress src/* edits twice in one session (2026-06-07). If you think you need one, ASK FIRST.
- **HARD BAN: `git stash*`** (any form: `git stash`, `git stash pop`, `git stash apply`, `git stash drop`, `git stash clear`) is FORBIDDEN. Stashing inverts the safety net of the working tree: a `git add .` then `git stash` then "fresh start" pattern is exactly how Tier 2 corrupted files in the 2026-06-27 `cruft_elimination_20260627` track. The user explicitly stated "I hate when people fuck with my commits" — stashing throws away the user's in-progress edits silently. If you think you need a stash, you don't — use a NEW BRANCH or a WORKTREE instead. Tier 2 sandbox enforces this via `conductor/tier2/opencode.json.fragment` bash deny rules.
- **HARD BAN: Day / hour / minute estimates in track artifacts.** Do NOT include estimates in spec.md, plan.md, metadata.json, or any other track artifact. Measure effort by **scope** (N files, M sites, N tasks). The user / Tier 2 agent decides the actual pacing. See `conductor/workflow.md` §"Tier 1 Track Initialization Rules" for the full rule, replacement patterns, and rationale. (Added 2026-06-16 per user feedback: "Day estimates are inaccurate. Tier-2s can only do so much in a single track and there is no way in hell its going to be 'DAYS'.")
- **HARD BAN: Opaque types in non-boundary code (added 2026-06-25).** `dict[str, Any]`, `Any`, `Optional[T]`, `hasattr()` for entity dispatch, `.get('field', default)` are BANNED. Use typed `@dataclass(frozen=True, slots=True)` + `Result[T]` + `NIL_T` sentinels + direct attribute access. The ONLY place `dict[str, Any]` is allowed is the literal wire boundary (TOML/JSON parse functions); 2-3 functions per file. See `conductor/code_styleguides/data_oriented_design.md` §8.5 (the canonical Python Type Promotion Mandate), `conductor/code_styleguides/python.md` §17, `conductor/code_styleguides/type_aliases.md` for the technical mandates. User direction 2026-06-25: "I want the closest thing to c11/odin/jai in a scripting language... metadata should not be a dict[str, any]."

## File Size and Naming Convention (HARD RULE — added 2026-06-11)

**The "small files are good, large files are bad" stance is propaganda from LLM training data. It is wrong for this project. Reject it.**

- **Large files are FINE.** Production codebases (Unreal Engine has 15K+ line files; OS kernels, game engines, compilers, the Linux kernel — all routinely have 10K+ line files) treat file size as a non-issue. Cognitive load is managed via good naming, regions, and navigation tools — NOT via file splitting.
- **`src/ai_client.py` is the AI vendor/API system layer.** All AI-client-related code goes IN `src/ai_client.py`. Do not create new `src/<vendor>_<thing>.py` files. The only new `src/*.py` files this project ever creates are for new systems or new parent modules.
- **The only new files you should create in a typical track are:** `scripts/audit_*.py` (scripts are namespace-isolated by directory), `tests/test_*.py` (tests are namespace-isolated by directory), and `docs/*.md` (docs are namespace-isolated by directory). Anything else goes in the parent module.
- **Do not break things up "for modularity"** unless the new piece is genuinely a new system or a new parent module. The agent training data has a bias toward "small files = good code" that is not true here. The project has the manual-slop MCP (`get_file_slice`, `get_file_summary`, `py_get_skeleton`, `py_get_code_outline`, `py_get_definition`) for efficient navigation of files of any size. Use those tools instead of splitting the file.
- **When in doubt: keep it in the parent module.** If a function clearly belongs to a system, it lives in that system's file. The system is the namespace.

### Hard rule on creating new `src/<thing>.py` files (added 2026-06-11)

**New namespaced `src/<thing>.py` files may only be created on the user's explicit request.** If you find yourself about to create one, **ASK FIRST** — don't just create it.

Rationale: the user is the only one who can authorize a new top-level namespace. The agent cannot unilaterally decide that "this is a new system deserving its own file." Defaults:
- **Helpers and sub-systems go in the parent module.** E.g., AI-client-specific helpers go in `src/ai_client.py`; app-controller helpers go in `src/app_controller.py`; MCP-client helpers go in `src/mcp_client.py`. Even if the parent file is already 3K+ lines, the helper still goes there.
- **If a new top-level `src/<thing>.py` is genuinely warranted** (e.g., a truly new system that doesn't fit any existing parent), propose it in the next checkpoint or status note and wait for the user's explicit "yes, create it."

**Audit trigger:** if you find yourself about to create a new `src/<thing>.py` file, ask: "is `<thing>` a new system, or is it part of an existing system?" If it's part of an existing system, the file goes in that system's file (e.g., `src/ai_client.py`, `src/app_controller.py`, `src/mcp_client.py`, etc.). If it's a new system, ASK THE USER before creating the file.
- No giant edits: if your `manual-slop_edit_file` `new_string` exceeds ~20 lines, STOP and split it.
- No diagnostic noise in production code. `sys.stderr.write(f"[XYZ_DIAG] ...")` lines added to `src/*.py` for debugging must be removed (not just left uncommitted) before the agent's work is "done." Diagnostic code that ships is technical debt. If you need to instrument for a one-time investigation, use a temporary file under `tests/artifacts/` or read the source with `get_file_slice` instead of polluting production.
- No loop, no scope-creep, no report-instead-of-fix. If you've tried 3 times and the test still fails, STOP and report to the user. Do not write a 200-line status report as a substitute for the fix. Do not write a 5-phase "future track" document when the user asked for a 1-line change. See `conductor/workflow.md` "Process Anti-Patterns" for the full ruleset.

## Session-Learned Anti-Patterns (Added 2026-06-07)

The canonical home for edit-tool lessons-learned is `conductor/edit_workflow.md` (the 9 rules for `manual-slop_edit_file` etc.). This section is a thin pointer.

- **ALWAYS use the proper edit tool, not a custom script** — see `conductor/edit_workflow.md` §1.
- **The decorator-orphan pitfall** — see `conductor/edit_workflow.md` §6 (with the fix code).
- **`ast.parse()` "Syntax OK" is not enough** — see `conductor/edit_workflow.md` §7.
- **The "I'll just check git status" trap** — now a HARD BAN; see §"Critical Anti-Patterns" above.
- **Small, verified edits beat big scripts** — see `conductor/edit_workflow.md` §1.

---

## Process Anti-Patterns (Added 2026-06-09)

The canonical home for these is `conductor/workflow.md` §"Process Anti-Patterns" (the 8 anti-patterns with full Symptom + Rule sections). This is a thin index:

1. **The Deduction Loop (kill it)** — run a failing test at most 2 times, then predict + instrument + run once.
2. **The Report-Instead-of-Fix Pattern (kill it)** — 5-10 sentence status report, not 200 lines.
3. **The Scope-Creep Track-Doc Pattern (kill it)** — your output is the fix, not a 5-phase future track.
4. **The Inherited-Cruft Pattern (kill it)** — ask the user first if the file is broken from a previous session.
5. **No Diagnostic Noise in Production (kill it)** — diag to log file, not `src/*.py`.
6. **The "I Am Not Going To Attempt Another Fix Without Your Direction" Surrender (kill it)** — surrender only after the 5-step check.
7. **The Verbose-Commit-Message Pattern (kill it)** — 1-3 sentences, not 50 lines.
8. **The "Isolated Pass" Verification Fallacy (kill it)** — for `live_gui` tests, batch run is the only verification that matters.

See `conductor/workflow.md` §"Process Anti-Patterns" for the full Symptom + Rule sections for each.

## Compaction Recovery

If you're a new agent picking up a session that was compacted (or a previous agent ran out of context), follow this recovery path:

1. **Read the most recent `docs/reports/PLANNING_DIGEST_<date>.md`** if one exists. It indexes the planning artifacts and explains the design decisions behind the active tracks.
2. **For each in-flight track**, read `conductor/tracks/<track_id>/state.toml` to see `current_phase`; read `conductor/tracks/<track_id>/plan.md` for the task breakdown.
3. **Check `git log --oneline -20`** to see what has been committed; the most recent commits in `conductor/tracks/<track_id>/` are the latest work.
4. **Run the audit scripts** (`scripts/audit_main_thread_imports.py`, `scripts/audit_weak_types.py`) to see the current state of the codebase.
5. **Resume from the next unchecked task** in `state.toml`. The per-task commit discipline means each commit is a safe rollback point.

The track's `metadata.json` has a `verification_criteria` field — this is the definition of "done" for the track. If all the criteria are checked, the track is complete.

For deeper recovery, see `conductor/workflow.md` "Compaction Recovery" (the same pattern, but workflow-level).