diff --git a/AGENTS.md b/AGENTS.md index a458ca96..3693a5ee 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,6 +21,27 @@ reserved for Claude Code sessions where the user has direct control. --- +## Required Reading (all agents that write or review NASM) + +Every agent that generates, reviews, or integrates NASM code **must** read these +before doing any work. They are not optional background — violations will cause +silent runtime bugs or corrupt glitch behaviour. + +| Document | Why it matters | +|---|---| +| `CLAUDE.md` | Register map, memory model, DPMI gotchas, build conventions | +| `docs/register_map.md` | Canonical SM83→x86 register assignments | +| `docs/386_optimization_strategy.md` | Instruction selection rules for 386 targets | +| `docs/bugs_and_glitches.md` | Which SM83 bugs to preserve and at what fix level | +| `docs/glitch_safety.md` | Which glitches are safe to emulate vs. dangerous under DPMI | + +Dispatch_Manager must read all five before writing any ticket. +Code Workers must read all five before translating any function. +Integration_Agent must read `CLAUDE.md` and `docs/register_map.md` before placing files. +Docs_Commit_Agent must read `CLAUDE.md` for commit conventions. + +--- + ## Role: Dispatch_Manager - **Model**: `gemini-3.1-pro` - **Settings**: `effort: high` @@ -201,14 +222,19 @@ if it genuinely does not apply — the parser ignores unfilled placeholders. ### Mandatory checklist 1. Read the exact pret source label from the ticket. Read surrounding context. -2. Run `dos_port/tools/work_queue manifest --id ` and write the header to +2. Check `docs/bugs_and_glitches.md` for any entry matching this function. + If found, apply the appropriate `; BUG(level):` block at the affected site. +3. Check `docs/glitch_safety.md` — if the function is involved in a known + glitch, verify the glitch is safe to emulate under DPMI before translating. + Emit `; GLITCH: — Safety: ` at the relevant site. +4. Run `dos_port/tools/work_queue manifest --id ` and write the header to `dos_port/scratch/__