Skip to content

Commit abbabb6

Browse files
scawfulscawful
committed
docs: add oracle integration section and minecart regression tracker
- AGENTS.md: add Section 5a for Oracle of Secrets integration (ROM naming, z3ed targets) - docs/internal/oracle/: new directory for Oracle-specific tracking - Goron Mines regression tracker: GM-001 through GM-007 with implementation status - Coordination board snapshot refresh
1 parent a5641d9 commit abbabb6

5 files changed

Lines changed: 280 additions & 20 deletions

File tree

‎AGENTS.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,10 +44,17 @@ Use tool classes intentionally:
4444

4545
### 5) Essential Repo Facts (non-discoverable defaults)
4646
- Build presets commonly used for agent work: `build_ai`.
47+
- Build command: `cmake --preset mac-ai && cmake --build --preset mac-ai`
48+
- Unit tests: `ctest --preset mac-ai-unit`
4749
- Coordination source of truth: `~/.context/agent-universe/{events.jsonl,state.json}`.
4850
- Generated human snapshot: `docs/internal/agents/coordination-board.generated.md`.
4951
- Legacy board file is history-only: `docs/internal/agents/coordination-board.md`.
5052

53+
### 5a) Oracle of Secrets Integration
54+
- `oos<VERSION>.sfc` = edit target, `oos<VERSION>x.sfc` = patched/emulator only
55+
- `z3ed --write` targets the base ROM (`oos168.sfc`), never `oos168x.sfc`
56+
- Oracle context: `../oracle-of-secrets/.context/scratchpad/agent_handoff.md`
57+
5158
### 6) Dependency Graph
5259
`Task Class` -> `Primary Persona` -> `Focused Context Files` -> `Tools/Scripts` -> `Validation`.
5360

‎docs/internal/README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# YAZE Internal Documentation
22

3-
**Last Updated**: 2026-02-24
3+
**Last Updated**: 2026-02-26
44

55
Internal documentation for architecture, AI agent coordination, and development planning.
66

@@ -12,6 +12,7 @@ Internal documentation for architecture, AI agent coordination, and development
1212
| Refactoring plan | [agents/refactoring-plan-0.7.md](agents/refactoring-plan-0.7.md) |
1313
| Latest handoff | [agents/refactoring-handoff-2026-02-24.md](agents/refactoring-handoff-2026-02-24.md) |
1414
| Release test checklist | [agents/oracle-morning-test-checklist.org](agents/oracle-morning-test-checklist.org) |
15+
| Goron Mines regression tracker | [oracle/goron-mines-minecart-regression-tracker-2026-02-26.md](oracle/goron-mines-minecart-regression-tracker-2026-02-26.md) |
1516
| Doc hygiene rules | [agents/doc-hygiene.md](agents/doc-hygiene.md) |
1617
| Agent scripts | [scripts/agents/README.md](../../scripts/agents/README.md) |
1718

@@ -23,6 +24,7 @@ Internal documentation for architecture, AI agent coordination, and development
2324
| `agents/archive/` | Retired initiatives, handoffs, and drafts (do not edit) |
2425
| `architecture/` | System design docs (editor, dungeon, overworld, ROM, graphics, etc.) |
2526
| `archive/` | Completed features, closed investigations, old plans |
27+
| `oracle/` | Oracle-of-Secrets dungeon/collision runtime docs and regression tracking |
2628
| `zelda3/` | ALTTP-specific data format documentation |
2729
| `gui/` | Canvas system and widget layer reference |
2830
| `wasm/` | Web/WASM port documentation |

‎docs/internal/agents/coordination-board.generated.md‎

Lines changed: 30 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,13 @@
11
# Coordination Snapshot (Generated)
22

3-
- Generated: `2026-02-24T10:54:38Z`
3+
- Generated: `2026-02-26T04:39:16Z`
44
- Source: `~/.context/agent-universe/state.json`
5+
- Project Key: `Users:scawful:src:hobby:yaze`
56

67
## Active
8+
- `task_20260225T032329Z_28215` [A] AFS+z3dk model infra phase1-2 bootstrap (asar eval, z3dk refs, dataset builder) (assignee: `ai-infra-architect`, updated: `2026-02-25T03:23:33Z`)
9+
- `task_20260225T031729Z_382` [A] AI provider matrix + training/integration plan for Claude/OpenAI/Gemini/custom (assignee: `ai-infra-architect`, updated: `2026-02-25T03:17:33Z`)
10+
- `task_20260224T210424Z_17502` [B] Create refactoring handoff document (assignee: `ai-infra-architect`, updated: `2026-02-24T22:26:22Z`)
711
- `import_20260214_0023_gui_editor_simplification_automation_reliability` [B] GUI Editor Simplification + Automation Reliability (assignee: `backend-infra-engineer`, updated: `2026-02-14T00:00:00Z`)
812
- `import_20260214_0022_0_6_0_ci_stabilization_linux_windows_quality` [B] 0.6.0 CI Stabilization (Linux/Windows/Quality) (assignee: `backend-infra-engineer`, updated: `2026-02-14T00:00:00Z`)
913
- `import_20260211_0046_ceiling_pit_transparency_follow_up` [B] Ceiling/Pit Transparency Follow-up (assignee: `CODEX`, updated: `2026-02-11T00:00:00Z`)
@@ -24,6 +28,13 @@
2428
- `import_20251123_0133_v0_3_9_release_rerun` [B] v0.3.9 release rerun (assignee: `CODEX`, updated: `2025-11-23T00:00:00Z`)
2529

2630
## Open
31+
- `task_20260226T043912Z_9206` [B] GM-004: Enforce savestate freshness/scenario validation for Goron Mines live smoke (assignee: `ai-infra-architect`, updated: `2026-02-26T04:39:12Z`)
32+
- `task_20260226T043912Z_5419` [A] GM-001: Fix minecart track-collision footprint undercount in CLI (assignee: `ai-infra-architect`, updated: `2026-02-26T04:39:12Z`)
33+
- `task_20260226T043912Z_25422` [C] GM-007: Add object-level room inspection output for minecart debug in CLI (assignee: `ai-infra-architect`, updated: `2026-02-26T04:39:12Z`)
34+
- `task_20260226T043912Z_22848` [A] GM-002: Add CLI/project feature-flag parity for custom-object-dependent generation (assignee: `ai-infra-architect`, updated: `2026-02-26T04:39:12Z`)
35+
- `task_20260226T043912Z_21048` [B] GM-005: Guardrail ROM edit workflow (oos168_test2 vs derived ROM targets) (assignee: `docs-janitor`, updated: `2026-02-26T04:39:12Z`)
36+
- `task_20260226T043912Z_1757` [A] GM-003: Add regression tests/gates for Goron Mines track footprint stability (assignee: `test-infrastructure-expert`, updated: `2026-02-26T04:39:12Z`)
37+
- `task_20260226T043912Z_17567` [B] GM-006: Preserve stop tiles during dungeon-generate-track-collision writes (assignee: `zelda3-hacking-expert`, updated: `2026-02-26T04:39:12Z`)
2738
- `import_20260207_0057_dungeon_workbench_panel_scopes` [B] Dungeon Workbench + Panel Scopes (assignee: `imgui-frontend-engineer`, updated: `2026-02-07T00:00:00Z`)
2839
- `import_20260207_0055_hackmanifest_guardrails` [B] HackManifest Guardrails (assignee: `ai-infra-architect`, updated: `2026-02-07T00:00:00Z`)
2940
- `import_20260206_0059_room_mode_validation_skill` [B] Room-mode validation + skill (assignee: `docs-janitor`, updated: `2026-02-06T00:00:00Z`)
@@ -38,23 +49,23 @@
3849
- `import_20251126_0123_menu_bar_right_panel_ui_ux_overhaul` [B] Menu Bar & Right Panel UI/UX Overhaul (assignee: `ui-architect`, updated: `2025-11-26T00:00:00Z`)
3950

4051
## Recently Completed
52+
- `task_20260225T211943Z_29730` [A] Integrate pending dungeon graph command edits (assignee: `zelda3-hacking-expert`, updated: `2026-02-25T21:24:55Z`)
53+
- `task_20260224T220223Z_29884` [B] Document yaze capability assessment + competitor parity matrix (assignee: `docs-janitor`, updated: `2026-02-24T22:04:38Z`)
54+
- `task_20260224T210824Z_28339` [B] Docs cleanup: remove outdated docs, simplify navigation (assignee: `docs-janitor`, updated: `2026-02-24T21:18:17Z`)
55+
- `task_20260224T210022Z_13029` [B] Delete src/lib, fix DISABLED dungeon tests, homebrew cmake, proto converter tests (assignee: `ai-infra-architect`, updated: `2026-02-24T21:07:08Z`)
56+
- `task_20260224T203624Z_24516` [B] Fix emulator service input validation + error propagation + CPU arg + toast draw guard (assignee: `ai-infra-architect`, updated: `2026-02-24T20:49:45Z`)
57+
- `task_20260224T190022Z_12668` [B] Remove src/lib include paths + create emulator domain types (assignee: `ai-infra-architect`, updated: `2026-02-24T20:19:22Z`)
58+
- `task_20260224T185135Z_22761` [B] Phase 1/2 prep: src/lib audit, Homebrew dedup analysis, IEmulator proto inventory (assignee: `ai-infra-architect`, updated: `2026-02-24T18:53:17Z`)
59+
- `task_20260224T180545Z_30443` [B] Refactoring plan review + phase 0 quick wins (assignee: `ai-infra-architect`, updated: `2026-02-24T18:10:30Z`)
60+
- `task_20260224T172621Z_16327` [B] Tier 1 ImGui Test Engine tests for dungeon editor panels (assignee: `ai-infra-architect`, updated: `2026-02-24T17:36:53Z`)
61+
- `task_20260224T162803Z_32644` [B] Cross-platform SHA1 + dry-run structural checks + hash normalize (assignee: `ai-infra-architect`, updated: `2026-02-24T16:35:51Z`)
62+
- `task_20260224T155920Z_17654` [B] Bundle verify --check-rom-hash + unpack --dry-run (assignee: `ai-infra-architect`, updated: `2026-02-24T16:12:28Z`)
63+
- `task_20260224T160119Z_31494` [B] UI/UX polish: door placement clarity + tile filter feedback (assignee: `imgui-frontend-engineer`, updated: `2026-02-24T16:09:34Z`)
64+
- `task_20260224T134231Z_20647` [B] 0.6.1 release gate: safety fix + CI checks + evidence automation (assignee: `ai-infra-architect`, updated: `2026-02-24T13:53:47Z`)
65+
- `task_20260224T132551Z_5707` [B] Unpack safe cleanup + --keep-partial-output flag (assignee: `ai-infra-architect`, updated: `2026-02-24T13:29:54Z`)
66+
- `task_20260224T125636Z_26840` [B] 0.6.1 follow-ups: limits tests, enum cleanup, Oracle header extraction (assignee: `ai-infra-architect`, updated: `2026-02-24T13:04:26Z`)
67+
- `task_20260224T121324Z_30554` [B] 0.6.1 refactor: unify project format, harden bundle archive, dedup backup, centralize limits (assignee: `ai-infra-architect`, updated: `2026-02-24T12:27:24Z`)
68+
- `task_20260224T120307Z_8807` [B] Add semantic protocol checks to protocol-audit.sh (assignee: `ai-infra-architect`, updated: `2026-02-24T12:04:13Z`)
69+
- `task_20260224T111726Z_29333` [B] Protocol compliance verification run (assignee: `ai-infra-architect`, updated: `2026-02-24T11:17:49Z`)
4170
- `import_20260224_0007_ci_infra_hardening_pass` [B] CI/Infra Hardening Pass (assignee: `ai-infra-architect`, updated: `2026-02-24T00:00:00Z`)
4271
- `import_20260224_0006_p1_03_project_bundle_pack_unpack_cli_commands` [B] P1-03: project-bundle-pack/unpack CLI Commands (assignee: `ai-infra-architect`, updated: `2026-02-24T00:00:00Z`)
43-
- `import_20260224_0005_ghost_preview_warning_states_filter_feedback_roo` [B] Ghost Preview Warning States + Filter Feedback + Room Copy (assignee: `imgui-frontend-engineer`, updated: `2026-02-24T00:00:00Z`)
44-
- `import_20260224_0004_dungeon_ux_validation_pass_qa_checklist` [B] Dungeon UX Validation Pass (QA Checklist) (assignee: `zelda3-hacking-expert`, updated: `2026-02-24T00:00:00Z`)
45-
- `import_20260224_0003_ux_pass_validation_infra_toast_dedup` [B] UX Pass Validation Infra + Toast Dedup (assignee: `ai-infra-architect`, updated: `2026-02-24T00:00:00Z`)
46-
- `import_20260224_0002_door_ghost_parity_placement_toast_room_dungeon_c` [B] Door Ghost Parity + Placement Toast + Room Dungeon Context (assignee: `imgui-frontend-engineer`, updated: `2026-02-24T00:00:00Z`)
47-
- `import_20260224_0001_follow_up_oracle_labels_toast_visibility_snap_ca` [B] Follow-up: Oracle Labels + Toast Visibility + Snap Capacity Colors (assignee: `imgui-frontend-engineer`, updated: `2026-02-24T00:00:00Z`)
48-
- `import_20260224_0000_universe_coordination_system_mvp` [B] Universe Coordination System MVP (assignee: `ai-infra-architect`, updated: `2026-02-24T00:00:00Z`)
49-
- `import_20260223_0013_oracle_regression_smoke_workflow` [B] Oracle Regression Smoke Workflow (assignee: `test-infrastructure-expert`, updated: `2026-02-23T00:00:00Z`)
50-
- `import_20260223_0012_oracle_smoke_check_c_command` [B] oracle-smoke-check C++ Command (assignee: `test-infrastructure-expert`, updated: `2026-02-23T00:00:00Z`)
51-
- `import_20260223_0011_dungeon_tile16_object_editor_ux_pass` [B] Dungeon/Tile16/Object Editor UX Pass (assignee: `imgui-frontend-engineer`, updated: `2026-02-23T00:00:00Z`)
52-
- `import_20260223_0010_placement_guardrails_tile16_filter_recent_rooms` [B] Placement Guardrails + Tile16 Filter + Recent Rooms (assignee: `imgui-frontend-engineer`, updated: `2026-02-23T00:00:00Z`)
53-
- `import_20260223_0009_sprite_door_placement_error_feedback` [B] Sprite/Door Placement Error Feedback (assignee: `imgui-frontend-engineer`, updated: `2026-02-23T00:00:00Z`)
54-
- `import_20260223_0008_p1_02_project_bundle_verify_cli_command` [B] P1-02: project-bundle-verify CLI Command (assignee: `ai-infra-architect`, updated: `2026-02-23T00:00:00Z`)
55-
- `import_20260222_0016_oracle_workflow_validation_tests` [B] Oracle Workflow Validation Tests (assignee: `test-infrastructure-expert`, updated: `2026-02-22T00:00:00Z`)
56-
- `import_20260222_0015_dungeon_oracle_preflight_minecart_integration_te` [B] dungeon-oracle-preflight + Minecart Integration Test (assignee: `test-infrastructure-expert`, updated: `2026-02-22T00:00:00Z`)
57-
- `import_20260222_0014_oracle_cli_preflight_follow_up_hardening` [B] Oracle CLI/Preflight Follow-up Hardening (assignee: `test-infrastructure-expert`, updated: `2026-02-22T00:00:00Z`)
58-
- `import_20260216_0017_dungeon_water_face_parity_custom_object_ux` [B] Dungeon Water-Face Parity + Custom Object UX (assignee: `imgui-frontend-engineer`, updated: `2026-02-16T00:00:00Z`)
59-
- `import_20260214_0030_z3ed_help_ux_ninja_stability` [B] z3ed Help UX + Ninja Stability (assignee: `backend-infra-engineer`, updated: `2026-02-14T00:00:00Z`)
60-
- `import_20260214_0029_0_6_0_gui_claim_verification` [B] 0.6.0 GUI Claim Verification (assignee: `imgui-frontend-engineer`, updated: `2026-02-14T00:00:00Z`)

‎docs/internal/oracle/README.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Oracle Internal Docs
2+
3+
Internal Oracle-of-Secrets runtime and collision documentation.
4+
5+
## Contents
6+
- [custom_collision_mapping.md](custom_collision_mapping.md)
7+
- Tile IDs, behavior, and RAM layout for Oracle custom collision (including minecart tracks).
8+
- [goron-mines-minecart-regression-tracker-2026-02-26.md](goron-mines-minecart-regression-tracker-2026-02-26.md)
9+
- Active issue tracker for current Goron Mines minecart regressions, fix plans, and validation gates.
10+
11+
## Coordination Linkage
12+
- Actionable tasks are tracked via universe coordination and surfaced in:
13+
- `docs/internal/agents/coordination-board.generated.md`

0 commit comments

Comments
 (0)