Task Clock: 20260511-T001 - Asset Extraction Readiness

Team: d3-tui-triad
Lead: lead
Stage: T1 Review/Research
Status: IN PROGRESS (Waiting for team acknowledgment)

Task Summary

Prepare D3-TUI asset extraction pipeline for title-menu target by improving documentation, error handling, and creating clear guidance for when private D2 assets become available. The current build works with pre-extracted decoder-evidence assets (NLOGO.PVM + 0GDTEX.PVR), but title-menu asset extraction is blocked by missing source files and unclear workflow. This task ensures the repo is ready to extract title-menu assets without requiring the actual licensed content.

Rationale

The current build status shows that title-menu asset extraction is blocked by: 1. Missing private D2 assets at expected paths 2. Speculative placeholder names in title_menu_manifest.json 3. No clear documentation on how to resolve asset paths when they become available

This task addresses the documentation and tooling readiness without requiring the actual licensed content.

Stages

T0: Intake (COMPLETE)

• ✅ Reviewed repo state, docs, and build status
• ✅ Identified asset extraction as current blocker
• ✅ Confirmed no active claims on claim board

T1: Review/Research (IN PROGRESS)

• [x] Research exact asset paths and naming conventions from historical evidence
• [x] Review extraction tool error handling and user experience
• [x] Identify documentation gaps around asset workflow
• [x] Verify current build works with existing pre-extracted assets
• [x] Analyze gap between current code and title menu target
• [x] Review existing manifest format and tool capabilities

Output: Comprehensive research findings in /workcell/llm-wiki/runs/20260511-t1-research-findings.md

Status: Researcher has completed T1 work. Waiting for builder-reviewer acknowledgment per protocol requirement: "No implementation begins until lead writes the T0-T3 plan and all agents acknowledge it."

Blocker: Python toolchain missing from environment (discovered by team-lead). Extraction tool improvements cannot be validated without Python installation.

T2: Design (BLOCKED)

• [ ] Draft improved asset extraction workflow documentation
• [ ] Design better error messages and discovery guidance
• [ ] Plan manifest validation improvements
• [ ] Create comprehensive design document
• [ ] Incorporate researcher feedback and suggestions

Status: BLOCKED waiting for: 1. Builder-reviewer acknowledgment of task clock 2. Resolution of Python toolchain blocker 3. Team agreement on how to proceed given environmental constraints

T3: Implementation

• [ ] Update tools/extract_d2_menu_assets.py with better error handling
• [ ] Add --dry-run mode to validate manifest without requiring files
• [ ] Improve discovery output formatting and guidance
• [ ] Update title_menu_manifest.json with clearer placeholders

T4: Documentation

• [ ] Write docs/ASSET_EXTRACTION_WORKFLOW.md with step-by-step guide
• [ ] Update README.md with asset requirements section
• [ ] Add troubleshooting section to BUILD.md
• [ ] Update tools/README.md with extraction tool usage

T5: Testing

• [ ] Test extraction tool with --discover flag on empty directory
• [ ] Test --dry-run mode with current manifest
• [ ] Verify error messages are clear and actionable
• [ ] Test that existing decoder-evidence build still works

T6: Review

• [ ] Peer review of documentation changes
• [ ] Reviewer tests extraction workflow with mock data
• [ ] Builder-reviewer verifies no source file changes affect existing build

T7: Synthesis

• [ ] Merge documentation improvements
• [ ] Update claim board and log
• [ ] Write summary of asset extraction readiness
• [ ] Identify next task (likely actual asset extraction when files available)

Scope

IN SCOPE: - Documentation improvements for asset extraction workflow - Tooling improvements for better error handling and guidance - Manifest validation and placeholder clarity - Workflow documentation for when assets become available

OUT OF SCOPE: - Actual extraction of licensed D2 assets - Modifying source PVM/PVR files - Changing the visual target (still D2 title menu) - KOS/Flycast build system changes

Expected Output

1. Updated docs/ASSET_EXTRACTION_WORKFLOW.md with clear step-by-step guide
2. Improved tools/extract_d2_menu_assets.py with better error handling
3. Enhanced title_menu_manifest.json with validated placeholders
4. Updated README.md and BUILD.md with asset requirements
5. Tested extraction workflow that fails gracefully without assets

Success Criteria

• Extraction tool provides clear, actionable error messages
• Documentation explains exactly what's needed and where to place assets
• Manifest placeholders are clearly marked as speculative
• Existing decoder-evidence build continues to work
• No changes require actual D2 licensed content

Current Blockers

1. Protocol Blocker: Waiting for builder-reviewer acknowledgment of task clock per AGENT_PROTOCOL.md requirement
2. Environmental Blocker: Python toolchain missing from environment - extraction tool improvements cannot be validated
3. Decision Blocker: Need team agreement on how to proceed given environmental constraints

Next Task Candidate

Once blockers are resolved and assets are available at the expected paths, the next task will be: - Run python3 tools/extract_d2_menu_assets.py --discover to resolve exact PVM entry names - Update manifest with confirmed names - Extract title-menu assets with make d2-assets - Update d3tui_main.c to render title menu instead of decoder evidence screen

Protocol Compliance Note

Per team-lead feedback: "No implementation begins until lead writes the T0-T3 plan and all agents acknowledge it." Current status: - ✅ Researcher has acknowledged and provided detailed feedback - ⏳ Builder-reviewer has read messages but not yet responded - ✅ Wiki outputs are substantial and useful

Task clock will remain in IN PROGRESS state until builder-reviewer acknowledgment is received.