# z3ed Agentic Workflow Implementation Plan _Last updated: 2025-10-01 (final update - Phase 6 + AW-02 complete)_ This plan decomposes the design additions (Sections 11–15 of `E6-z3ed-cli-design.md`) into actionable engineering tasks. Each workstream contains mi**Files Modified/Created** **Phase 6 (Resource Catalogue)**: 1. `src/cli/handlers/rom.cc` - Added `RomInfo::Run` implementation 2. `src/cli/z3ed.h` - Added `RomInfo` class declaration 3. `src/cli/modern_cli.cc` - Updated `HandleRomInfoCommand` routing 4. `src/cli/service/resource_catalog.cc` - Added `rom info` schema entry 5. `docs/api/z3ed-resources.yaml` - Generated comprehensive API catalog, owners (TBD), blocking dependencies, and expected deliverables. ## 1. Workstreams Overview | Workstream | Goal | Milestone Target | Notes | |------------|------|------------------|-------| | Resource Catalogue | Provide authoritative machine-readable specs for CLI resources. | Phase 6 | Schema now captures effects/returns metadata for palette/overworld/rom/patch/dungeon; automation pending. | | Acceptance Workflow | Enable human review/approval of agent proposals in ImGui. | Phase 7 | Sandbox manager prototype landed; UI work pending. | | ImGuiTest Bridge | Allow agents to drive ImGui via `ImGuiTestEngine`. | Phase 6 | Requires harness IPC transport. | | Verification Pipeline | Build layered testing + CI coverage. | Phase 6+ | Integrates with harness + CLI suites. | | Telemetry & Learning | Capture signals to improve prompts + heuristics. | Phase 8 | Optional/opt-in features. | ### Progress snapshot — 2025-10-01 (Phase 6 Complete, AW-03 Complete, IT-01 & AW-04 Active) **Resource Catalogue (RC)** ✅ COMPLETE: - CLI flag passthrough and resource catalog system operational - `agent describe` exports YAML/JSON command schemas for AI consumption - `docs/api/z3ed-resources.yaml` generated and maintained - Fixed `rom info` segfault with dedicated handler **Acceptance Workflow (AW-01, AW-02, AW-03)** ✅ COMPLETE: - `ProposalRegistry` tracks agent modifications with metadata/diffs/logs - Proposal persistence: LoadProposalsFromDiskLocked() enables cross-session tracking - `RomSandboxManager` handles isolated ROM copies - `agent list` and `agent diff` commands operational - **ProposalDrawer ImGui GUI** fully implemented: - List/detail split view with filtering and refresh - Accept/Reject/Delete actions with confirmation dialogs - **ROM merging complete**: AcceptProposal() loads sandbox ROM and merges into main ROM - Integrated into EditorManager (`Debug → Agent Proposals` menu) - Ready for end-to-end testing with live proposals **Graphics System** ✅ FIXED: - Fixed RAII shutdown crash in `PerformanceProfiler` (static destruction order issue) - Added shutdown flag and validity checks - application now exits cleanly - Enables stable testing and performance monitoring for AI workflow **Agent Run** ✅ FIXED: - Added automatic ROM loading from `--rom` flag when not already loaded - Proper error messages guide users to specify ROM path **Active Work (Oct 1-7, 2025)**: - **Priority 1**: ImGuiTestHarness (IT-01) - Design spike for IPC architecture - **Priority 2**: Policy Evaluation (AW-04) - YAML-based constraint system ## 2. Task Backlog | ID | Task | Workstream | Type | Status | Dependencies | |----|------|------------|------|--------|--------------| | RC-01 | Define schema for `ResourceCatalog` entries and implement serialization helpers. | Resource Catalogue | Code | Done | Schema system complete with all resource types documented | | RC-02 | Auto-generate `docs/api/z3ed-resources.yaml` from command annotations. | Resource Catalogue | Tooling | Done | Generated and committed to docs/api/ | | RC-03 | Implement `z3ed agent describe` CLI surface returning JSON schemas. | Resource Catalogue | Code | Done | Both YAML and JSON output formats working | | RC-04 | Integrate schema export with TUI command palette + help overlays. | Resource Catalogue | UX | Planned | RC-03 | | RC-05 | Harden CLI command routing/flag parsing to unblock agent automation. | Resource Catalogue | Code | Done | Fixed rom info handler to use FLAGS_rom | | AW-01 | Implement sandbox ROM cloning and tracking (`RomSandboxManager`). | Acceptance Workflow | Code | Done | ROM sandbox manager operational with lifecycle management | | AW-02 | Build proposal registry service storing diffs, logs, screenshots. | Acceptance Workflow | Code | Done | ProposalRegistry implemented with disk persistence | | AW-03 | Add ImGui drawer for proposals with accept/reject controls. | Acceptance Workflow | UX | Done | ProposalDrawer GUI complete with ROM merging | | AW-04 | Implement policy evaluation for gating accept buttons. | Acceptance Workflow | Code | In Progress | AW-03, Priority 2 - YAML policies + PolicyEvaluator | | AW-05 | Draft `.z3ed-diff` hybrid schema (binary deltas + JSON metadata). | Acceptance Workflow | Design | Planned | AW-01 | | IT-01 | Create `ImGuiTestHarness` IPC service embedded in `yaze_test`. | ImGuiTest Bridge | Code | In Progress | Priority 1 - Design spike + IPC transport | | IT-02 | Implement CLI agent step translation (`imgui_action` → harness call). | ImGuiTest Bridge | Code | Planned | IT-01 | | IT-03 | Provide synchronization primitives (`WaitForIdle`, etc.). | ImGuiTest Bridge | Code | Planned | IT-01 | | VP-01 | Expand CLI unit tests for new commands and sandbox flow. | Verification Pipeline | Test | Planned | RC/AW tasks | | VP-02 | Add harness integration tests with replay scripts. | Verification Pipeline | Test | Planned | IT tasks | | VP-03 | Create CI job running agent smoke tests with `YAZE_WITH_JSON`. | Verification Pipeline | Infra | Planned | VP-01, VP-02 | | TL-01 | Capture accept/reject metadata and push to telemetry log. | Telemetry & Learning | Code | Planned | AW tasks | | TL-02 | Build anonymized metrics exporter + opt-in toggle. | Telemetry & Learning | Infra | Planned | TL-01 | _Status Legend: Prototype · In Progress · Planned · Blocked · Done_ ## 3. Immediate Next Steps (Week of Oct 1-7, 2025) ### Priority 0: Testing & Validation (Active) 1. **TEST**: Complete end-to-end proposal workflow - Launch YAZE and verify ProposalDrawer displays live proposals - Test Accept action → verify ROM merge and save prompt - Test Reject and Delete actions - Validate filtering and refresh functionality ### Priority 1: ImGuiTestHarness Foundation (IT-01, 6-8 hours) 🔥 NEW PRIORITY **Rationale**: Required for automated GUI testing and remote control of YAZE for AI workflows 2. **DESIGN SPIKE**: ImGuiTestHarness Architecture - Evaluate IPC transport options: - **Socket/Unix Domain Socket**: Low overhead, platform-specific - **HTTP/REST**: Universal, easier debugging, more overhead - **Shared Memory**: Fastest, most complex - **stdin/stdout pipe**: Simplest, limited to synchronous calls - Decision criteria: cross-platform support, latency, debugging ease - Prototype preferred approach with simple "click button" test 3. **IMPLEMENT**: Basic IPC Service - Embed IPC listener in `yaze_test` or main `yaze` binary (conditional compile) - Protocol: JSON-RPC style commands (click, type, wait, assert) - Security: localhost-only, optional shared secret - Example commands: ```json {"cmd": "click", "target": "button:Open ROM"} {"cmd": "type", "target": "input:filename", "value": "zelda3.sfc"} {"cmd": "wait", "condition": "window_visible:Overworld Editor"} {"cmd": "assert", "condition": "color_at:100,200", "value": "#FF0000"} ``` 4. **INTEGRATE**: CLI Agent Translation Layer - `z3ed agent test` generates ImGui action sequences - Translates natural language → test commands → IPC calls - Example: "open overworld editor" → `click(menu:Editors→Overworld)` - Capture screenshots for LLM feedback loop ### Priority 2: Policy Evaluation Framework (AW-04, 4-6 hours) 5. **DESIGN**: YAML-based Policy Configuration ```yaml # .yaze/policies/agent.yaml version: 1.0 policies: - name: require_tests type: test_requirement enabled: true rules: - test_suite: "overworld_rendering" min_pass_rate: 0.95 - test_suite: "palette_integrity" min_pass_rate: 1.0 - name: limit_change_scope type: change_constraint enabled: true rules: - max_bytes_changed: 10240 # 10KB - allowed_banks: [0x00, 0x01, 0x0E] # Graphics banks only - forbidden_ranges: - start: 0xFFB0 # ROM header end: 0xFFFF - name: human_review_required type: review_requirement enabled: true rules: - if: bytes_changed > 1024 then: require_diff_review: true - if: commands_executed > 10 then: require_log_review: true ``` 6. **IMPLEMENT**: PolicyEvaluator Service - `src/cli/service/policy_evaluator.{h,cc}` - Singleton service loads policies from `.yaze/policies/` - `EvaluateProposal(proposal_id) -> PolicyResult` - Returns: pass/fail + list of violations with severity - Hook into ProposalRegistry lifecycle 7. **INTEGRATE**: Policy UI in ProposalDrawer - Add "Policy Status" section in detail view - Display violations with icons: ⛔ Critical, ⚠️ Warning, ℹ️ Info - Gate Accept button: disabled if critical violations exist - Show helpful messages: "Accept blocked: Test pass rate 0.85 < 0.95" - Allow policy overrides with confirmation: "Override policy? This action will be logged." ### Priority 3: Documentation & Consolidation (2-3 hours) 8. **CONSOLIDATE**: Merge standalone docs into main plan - ✅ AW-03 summary → already in main plan, delete standalone doc - Check for other AW-* or task-specific docs to merge - Update main plan with architecture diagrams 9. **CREATE**: Architecture Flow Diagram - Visual representation of proposal lifecycle - Component interaction diagram - Add to implementation plan ### Later: Advanced Features - VP-01: Expand CLI unit tests - VP-02: Integration tests with replay scripts - TL-01: Telemetry capture for learning ## 4. Current Issues & Blockers ### Active Issues None - all blocking issues resolved as of Oct 1, 2025 ### Known Limitations (Non-Blocking) 1. ProposalDrawer lacks keyboard navigation 2. Large diffs/logs truncated at 1000 lines (consider pagination) 3. Proposals don't persist full metadata to disk (prompt, description, sandbox_id reconstructed) 4. No policy evaluation yet (AW-04) ## 5. Architecture Overview ### 5.1. Proposal Lifecycle Flow ``` ┌─────────────────────────────────────────────────────────────────┐ │ 1. CREATION (CLI: z3ed agent run) │ ├─────────────────────────────────────────────────────────────────┤ │ User Prompt │ │ ↓ │ │ MockAIService / GeminiAIService │ │ ↓ (generates commands) │ │ ["palette export ...", "overworld set-tile ..."] │ │ ↓ │ │ RomSandboxManager::CreateSandbox(rom) │ │ ↓ (creates isolated copy) │ │ /tmp/yaze/sandboxes//zelda3.sfc │ │ ↓ │ │ Execute commands on sandbox ROM │ │ ↓ (logs each command) │ │ ProposalRegistry::CreateProposal(sandbox_id, prompt, desc) │ │ ↓ (creates proposal directory) │ │ /tmp/yaze/proposals/proposal--/ │ │ ├─ execution.log (command outputs) │ │ ├─ diff.txt (if generated) │ │ └─ screenshots/ (if any) │ └─────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────┐ │ 2. DISCOVERY (CLI: z3ed agent list) │ ├─────────────────────────────────────────────────────────────────┤ │ ProposalRegistry::ListProposals() │ │ ↓ (lazy loads from disk) │ │ LoadProposalsFromDiskLocked() │ │ ↓ (scans /tmp/yaze/proposals/) │ │ Reconstructs metadata from filesystem │ │ ↓ (parses timestamps, reads logs) │ │ Returns vector │ │ ↓ │ │ Display table: ID | Status | Created | Prompt | Stats │ └─────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────┐ │ 3. REVIEW (GUI: Debug → Agent Proposals) │ ├─────────────────────────────────────────────────────────────────┤ │ ProposalDrawer::Draw() │ │ ↓ (called every frame from EditorManager) │ │ ProposalDrawer::RefreshProposals() │ │ ↓ (calls ProposalRegistry::ListProposals) │ │ Display proposal list (selectable table) │ │ ↓ (user clicks proposal) │ │ ProposalDrawer::SelectProposal(id) │ │ ↓ (loads detail content) │ │ Read execution.log and diff.txt from proposal directory │ │ ↓ │ │ Display detail view: │ │ ├─ Metadata (sandbox_id, timestamp, stats) │ │ ├─ Diff (syntax highlighted) │ │ └─ Log (command execution trace) │ │ ↓ │ │ User decides: [Accept] [Reject] [Delete] │ └─────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────┐ │ 4. ACCEPTANCE (GUI: Click "Accept" button) │ ├─────────────────────────────────────────────────────────────────┤ │ ProposalDrawer::AcceptProposal(proposal_id) │ │ ↓ │ │ Get proposal metadata (includes sandbox_id) │ │ ↓ │ │ RomSandboxManager::ListSandboxes() │ │ ↓ (find sandbox by ID) │ │ sandbox_rom_path = sandbox.rom_path │ │ ↓ │ │ Load sandbox ROM from disk │ │ ↓ │ │ rom_->WriteVector(0, sandbox_rom.vector()) │ │ ↓ (copies entire sandbox ROM → main ROM) │ │ ROM marked dirty (save prompt appears) │ │ ↓ │ │ ProposalRegistry::UpdateStatus(id, kAccepted) │ │ ↓ │ │ User: File → Save ROM │ │ ↓ │ │ Changes committed ✅ │ └─────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────┐ │ 5. REJECTION (GUI: Click "Reject" button) │ ├─────────────────────────────────────────────────────────────────┤ │ ProposalDrawer::RejectProposal(proposal_id) │ │ ↓ │ │ ProposalRegistry::UpdateStatus(id, kRejected) │ │ ↓ │ │ Proposal preserved for audit trail │ │ Sandbox ROM left untouched (can be cleaned up later) │ └─────────────────────────────────────────────────────────────────┘ ``` ### 5.2. Component Interaction Diagram ``` ┌────────────────────┐ │ CLI Layer │ │ (z3ed commands) │ └────────┬───────────┘ │ ├──► agent run ──────────┐ ├──► agent list ─────────┤ └──► agent diff ─────────┤ │ ┌────────────────────────▼──────────────────────┐ │ CLI Service Layer │ ├───────────────────────────────────────────────┤ │ ┌─────────────────────────────────────────┐ │ │ │ ProposalRegistry (Singleton) │ │ │ │ • CreateProposal() │ │ │ │ • ListProposals() │ │ │ │ • GetProposal() │ │ │ │ • UpdateStatus() │ │ │ │ • RemoveProposal() │ │ │ │ • LoadProposalsFromDiskLocked() │ │ │ └────────────┬────────────────────────────┘ │ │ │ │ │ ┌────────────▼────────────────────────────┐ │ │ │ RomSandboxManager (Singleton) │ │ │ │ • CreateSandbox() │ │ │ │ • ActiveSandbox() │ │ │ │ • ListSandboxes() │ │ │ │ • RemoveSandbox() │ │ │ └────────────┬────────────────────────────┘ │ └───────────────┼────────────────────────────────┘ │ ┌───────────────▼────────────────────────────────┐ │ Filesystem Layer │ ├────────────────────────────────────────────────┤ │ /tmp/yaze/proposals/ │ │ └─ proposal--/ │ │ ├─ execution.log │ │ ├─ diff.txt │ │ └─ screenshots/ │ │ │ │ /tmp/yaze/sandboxes/ │ │ └─ -/ │ │ └─ zelda3.sfc (isolated ROM copy) │ └────────────────────────────────────────────────┘ ▲ │ ┌───────────────┴────────────────────────────────┐ │ GUI Layer │ ├────────────────────────────────────────────────┤ │ ┌─────────────────────────────────────────┐ │ │ │ EditorManager │ │ │ │ • current_rom_ │ │ │ │ • proposal_drawer_ │ │ │ │ • Update() { proposal_drawer_.Draw() } │ │ │ └────────────┬────────────────────────────┘ │ │ │ │ │ ┌────────────▼────────────────────────────┐ │ │ │ ProposalDrawer │ │ │ │ • rom_ (ptr to EditorManager's ROM) │ │ │ │ • Draw() │ │ │ │ • DrawProposalList() │ │ │ │ • DrawProposalDetail() │ │ │ │ • AcceptProposal() ← ROM MERGE │ │ │ │ • RejectProposal() │ │ │ │ • DeleteProposal() │ │ │ └─────────────────────────────────────────┘ │ └────────────────────────────────────────────────┘ ``` ### 5.3. Data Flow: Agent Run to ROM Merge ``` User: "Make soldiers wear red armor" │ ▼ ┌────────────────────────┐ │ MockAIService │ Generates: ["palette export sprites_aux1 4 soldier.col"] └────────┬───────────────┘ │ ▼ ┌────────────────────────┐ │ RomSandboxManager │ Creates: /tmp/.../sandboxes/20251001T200215-1/zelda3.sfc └────────┬───────────────┘ │ ▼ ┌────────────────────────┐ │ Command Executor │ Runs: palette export on sandbox ROM └────────┬───────────────┘ │ ▼ ┌────────────────────────┐ │ ProposalRegistry │ Creates: proposal-20251001T200215-1/ │ │ • execution.log: "[timestamp] palette export succeeded" └────────┬───────────────┘ • diff.txt: (if diff generated) │ │ Time passes... user launches GUI ▼ ┌────────────────────────┐ │ ProposalDrawer loads │ Reads: /tmp/.../proposals/proposal-*/ │ │ Displays: List of proposals └────────┬───────────────┘ │ │ User clicks "Accept" ▼ ┌────────────────────────┐ │ AcceptProposal() │ 1. Find sandbox ROM: /tmp/.../sandboxes/.../zelda3.sfc │ │ 2. Load sandbox ROM │ │ 3. rom_->WriteVector(0, sandbox_rom.vector()) │ │ 4. Main ROM now contains all sandbox changes │ │ 5. ROM marked dirty └────────┬───────────────┘ │ ▼ ┌────────────────────────┐ │ User: File → Save │ Changes persisted to disk ✅ └────────────────────────┘ ``` ## 5. Open Questions - What serialization format should the proposal registry adopt for diff payloads (binary vs. textual vs. hybrid)? \ ➤ Decision: pursue a hybrid package (`.z3ed-diff`) that wraps binary tile/object deltas alongside a JSON metadata envelope (identifiers, texture descriptors, preview palette info). Capture format draft under RC/AW backlog. - How should the harness authenticate escalation requests for mutation actions? \ ➤ Still open—evaluate shared-secret vs. interactive user prompt in the harness spike (IT-01). - Can we reuse existing regression test infrastructure for nightly ImGui runs or should we spin up a dedicated binary? \ ➤ Investigate during the ImGuiTestHarness spike; compare extending `yaze_test` jobs versus introducing a lightweight automation runner. ## 5. Completed Work Summary ### Resource Catalogue Workstream (RC) - ✅ COMPLETE The Resource Catalogue workstream has been successfully completed, providing a foundation for AI-driven automation: **Implementation Details**: - Created comprehensive schema system in `src/cli/service/resource_catalog.{h,cc}` - Implemented resource catalog for: ROM, Patch, Palette, Overworld, Dungeon, and Agent commands - Each resource includes: name, description, actions, arguments, effects, and return values - Built dual-format serialization: JSON (compact) and YAML (human-readable) **Key Fixes**: - Fixed `rom info` segfault by creating dedicated `RomInfo` handler using `FLAGS_rom` - Added `rom info` action to resource schema with proper metadata - Ensured all ROM commands consistently use flag-based dispatch **Generated Artifacts**: - `docs/api/z3ed-resources.yaml` - Authoritative machine-readable API reference - Both JSON and YAML output formats validated and working - Resource filtering capability (`--resource `) operational **Command Examples**: ```bash # View all resources in YAML z3ed agent describe --format yaml # Get specific resource as JSON z3ed agent describe --format json --resource rom # Generate documentation file z3ed agent describe --format yaml --output docs/api/z3ed-resources.yaml ``` **Testing Results**: All commands tested and verified working: - ✅ `z3ed rom info --rom=zelda3.sfc` - displays title, size, filename - ✅ `z3ed rom validate --rom=zelda3.sfc` - verifies checksum and header - ✅ `z3ed agent describe --format yaml` - outputs complete catalog - ✅ `z3ed agent describe --format json --resource rom` - filters by resource ### Acceptance Workflow (AW-01, AW-02) - ✅ CORE COMPLETE The foundational infrastructure for proposal tracking and review is now operational: **RomSandboxManager Implementation** (AW-01): - Singleton service managing isolated ROM copies for agent proposals - Sandboxes created in `YAZE_SANDBOX_ROOT` (env var) or system temp directory - Automatic directory creation and ROM file cloning - Active sandbox tracking for current agent session - Cleanup utilities for removing old sandboxes **ProposalRegistry Implementation** (AW-02): - Comprehensive tracking of agent-generated ROM modifications - Stores proposal metadata: ID, sandbox ID, prompt, description, timestamps - Records execution diffs in `diff.txt` within proposal directory - Appends command execution logs to `execution.log` with timestamps - Support for screenshot attachments (path tracking) - Proposal lifecycle: Pending → Accepted/Rejected - Query capabilities: get by ID, list all, filter by status, find latest pending **Agent Run Integration**: - `agent run` now creates sandbox + proposal automatically - All command executions logged with timestamps and status - Success/failure outcomes captured in proposal logs - User feedback includes proposal ID and sandbox path for review - Foundation ready for `agent diff`, `agent commit`, `agent revert` enhancements **Agent Diff Enhancement** (Completed Oct 1, 2025): - Reads proposal diffs from ProposalRegistry automatically - Displays detailed metadata: proposal ID, status, timestamps, command count - Shows diff content from proposal directory - Displays execution log (first 50 lines, with truncation for long logs) - Provides next-step guidance (commit/revert/GUI review) - Supports `--proposal-id` flag to view specific proposals - Fallback to legacy diff behavior if no proposals found **Agent List Command** (New - Oct 1, 2025): - Enumerates all proposals in the registry - Shows proposal ID, status, creation time, prompt, and stats - Indicates pending/accepted/rejected status for each proposal - Provides guidance on using `agent diff` to view details - Empty state message guides users to create proposals with `agent run` **Resource Catalog Updates**: - Added `agent list` action with returns schema - Added `agent diff` action with arguments (`--proposal-id`) and returns schema - Updated agent resource description to include listing and diffing capabilities - Regenerated `docs/api/z3ed-resources.yaml` with new agent actions **ProposalDrawer GUI Component** (Completed Oct 1, 2025): - ImGui right-side drawer for proposal review (AW-03) - Split view: proposal list (top) + detail view (bottom) - List view: table with ID, status, prompt columns; colored status indicators - Detail view: collapsible sections for metadata/diff/log; syntax-aware display - Action buttons: Accept, Reject, Delete with confirmation dialogs - Status filtering (All/Pending/Accepted/Rejected) - Integrated into EditorManager with Debug → Agent Proposals menu - Accept/Reject updates ProposalRegistry status - Delete removes proposal from registry and filesystem - TODO: Implement actual ROM merging in AcceptProposal method **Proposal Persistence Fix** (Completed Oct 1, 2025): - Fixed ProposalRegistry to load proposals from disk on first access - Added `LoadProposalsFromDiskLocked()` method scanning proposal root directory - Lazy loading implementation in `ListProposals()` for automatic registry population - Reconstructs metadata from filesystem: ID, timestamps, log/diff paths, screenshots - Parses creation time from proposal ID format (`proposal-20251001T200215-1`) - Enables cross-session proposal tracking - `agent list` now finds all proposals - ProposalDrawer can now display proposals created via CLI `agent run` **CMake Build Integration**: - Added `cli/service/proposal_registry.cc` and `cli/service/rom_sandbox_manager.cc` to all app targets - Fixed linker errors by including CLI service sources in: - `yaze` (main GUI app) - `yaze_emu` (emulator standalone) - `yaze_core` (testing library) - `yaze_c` (C API library) - All targets now build successfully with ProposalDrawer dependencies **Architecture Benefits**: - Clean separation: RomSandboxManager (file ops) ↔ ProposalRegistry (metadata) - Thread-safe with mutex protection for concurrent access - Extensible design ready for ImGui review UI (AW-03) - Proposal persistence enables post-session review and auditing - Proposal-centric workflow enables human-in-the-loop review - GUI and CLI both have full access to proposal system **Next Steps for AW Workstream**: - Test ProposalDrawer in running application - Complete ROM merging in AcceptProposal method - AW-04: Policy evaluation for gating mutations - AW-05: `.z3ed-diff` hybrid format design ### Files Modified/Created **Phase 6 (Resource Catalogue)**: 1. `src/cli/handlers/rom.cc` - Added `RomInfo::Run` implementation 2. `src/cli/z3ed.h` - Added `RomInfo` class declaration 3. `src/cli/modern_cli.cc` - Updated `HandleRomInfoCommand` routing 4. `src/cli/service/resource_catalog.cc` - Added `rom info` schema entry 5. `docs/api/z3ed-resources.yaml` - Generated comprehensive API catalog **AW-01 & AW-02 (Proposal Tracking)**: 6. `src/cli/service/proposal_registry.h` - New proposal tracking service interface 7. `src/cli/service/proposal_registry.cc` - Implementation with full lifecycle management 8. `src/cli/handlers/agent.cc` - Integrated ProposalRegistry into agent run workflow **Agent Diff & List Enhancement**: 9. `src/cli/handlers/agent.cc` - Enhanced HandleDiffCommand with proposal reading, added HandleListCommand 10. `src/cli/service/resource_catalog.cc` - Added agent list/diff actions with schemas 11. `docs/api/z3ed-resources.yaml` - Regenerated with new agent commands 12. `docs/E6-z3ed-cli-design.md` - Updated Section 8.1 with list/diff documentation **AW-03 (ProposalDrawer GUI)**: 13. `src/app/editor/system/proposal_drawer.h` - Complete drawer interface with Draw/Accept/Reject/Delete 14. `src/app/editor/system/proposal_drawer.cc` - Full implementation (~350 lines) with list/detail views 15. `src/app/editor/editor_manager.h` - Added ProposalDrawer member and include 16. `src/app/editor/editor_manager.cc` - Added menu item and Draw() call in Update loop 17. `src/CMakeLists.txt` - Added proposal_drawer files to System Editor source group 18. `src/app/app.cmake` - Added CLI service sources to yaze target (both Apple and non-Apple builds) 19. `src/app/emu/emu.cmake` - Added CLI service sources to yaze_emu target 20. `src/CMakeLists.txt` - Added CLI service sources to yaze_core library sources 9. `src/cli/z3ed.cmake` - Added proposal_registry.cc to build 10. `docs/E6-z3ed-implementation-plan.md` - Updated progress and task statuses **Agent Diff & List (Oct 1, 2025)**: 21. `src/cli/handlers/agent.cc` - Enhanced `HandleDiffCommand` with proposal reading, added `HandleListCommand` 22. `src/cli/service/resource_catalog.cc` - Added agent list and diff actions to schema 23. `docs/api/z3ed-resources.yaml` - Regenerated with new agent commands **Proposal Persistence Fix (Oct 1, 2025)**: 24. `src/cli/service/proposal_registry.h` - Added `LoadProposalsFromDiskLocked()` declaration 25. `src/cli/service/proposal_registry.cc` - Implemented disk loading with timestamp parsing and metadata reconstruction 26. `src/cli/service/proposal_registry.cc` - Modified `ListProposals()` to lazy-load proposals from disk **ROM Merging Implementation (Oct 1, 2025)**: 27. `src/app/editor/system/proposal_drawer.h` - Added `SetRom()` method and `Rom*` member for merge operations 28. `src/app/editor/system/proposal_drawer.cc` - Implemented full ROM merging in `AcceptProposal()` with sandbox loading 29. `src/app/editor/editor_manager.cc` - Added `SetRom(current_rom_)` call before drawing ProposalDrawer 30. `src/app/editor/system/proposal_drawer.cc` - Added RomSandboxManager include for sandbox path resolution ## 6. References - `docs/E6-z3ed-cli-design.md` - Overall CLI design and architecture - `docs/api/z3ed-resources.yaml` - Machine-readable API reference (generated) - `src/cli/service/resource_catalog.h` - Resource catalog implementation - `src/cli/service/resource_catalog.cc` - Schema definitions and serialization