makelore/.project-docs/30-worklog/tasks/20260823-pi-product-tools-a9c4e7d2.md

Task: Implement PI-090 product tools and change tracker

Identity

• Task ID: 20260823-pi-product-tools-a9c4e7d2
• Mode: Feature
• Branch: codex/20260823-pi-product-tools-a9c4e7d2-pi-product-tools
• Worktree: D:\Datas\OthersProjects\makelore-pi-product-tools-a9c4e7d2
• Base commit: 77cdee7e73
• Owner: codex
• Status: Ready for Integration

Scope

• Implement PI-090 — Product tools and Conversation change tracker from the 【架构】opencode2pi Spec/ticket graph on cumulative PI-080 baseline 77cdee7e73feff8f3941afcfd280e6dedd83b73b.
• Own the product-side Pi tools for browser, game-asset browse/review, versioned task state, relative changed-file reporting, selected skills and command catalog, plus a Main-owned Git/status/diff Conversation tracker.
• Reuse the existing Main Agent Browser seam and migrate retained game-asset and skill semantics out of OpenCode-specific ownership without wiring the PI-105 Host routes or PI-130 Renderer UI.

Intent And Constraints

• Browser commands must call the existing Main-owned browser module directly; they must not launch @playwright/mcp, discover MCP servers, or introduce a second browser protocol. Screenshot results use bounded attachment identity, never repeated base64 projection to Renderer.
• Product tool details are versioned and strictly normalized. task_state is not an old todo endpoint, changed_file accepts only project-relative paths, and changes never come from parsing Pi message text.
• Record run-start Git head/status/diff baselines, refresh precise touched paths after write/edit, and perform one project-level refresh after bash/settle. Untracked preview is bounded and contains no absolute path. Do not add file hashes, checkpoints, rollback semantics, or a generic VCS framework.
• Selected skills and commands come only from the explicit bundled registry and project Agent selection; project/user .pi discovery and OpenCode plugin types remain excluded.
• Keep the extension/bridge Main-private and authenticated by the existing worker token + conversation/generation/run identity. Child tool exposure must stay within PI-080's explicit role/tool policy.
• Real external Provider validation remains Explicitly Waived / Accepted Risk with realTurnVerified=false; macOS x64/arm64 remains deferred to mandatory PI-150 validation. Neither is a Pass.
• Do not create subagents. Keep all writes in this isolated worktree and leave canonical project memory to the later integration ticket.

Plan

1. Inspect and lock the smallest interfaces across the Pi extension bridge, existing Agent Browser module, retained game-asset logic, explicit skill resources, and Git/project seams.
2. Add the versioned product tools and bridge adapters, reuse the Main browser module, and rehome retained game-asset behavior without MCP or OpenCode plugin dependencies.
3. Add the selected skill/command registry and Conversation change tracker with relative paths, bounded previews, touched-path refresh and bash/project refresh semantics.
4. Add focused real/fake bundle, bridge, browser/game, registry and git/no-git/dirty/untracked/bash tracker tests plus the applicable packaged smoke.
5. Run focused Pi tests, typecheck, lint, full unit, Vite build and project-doc gates; commit the exact owned scope and request planner review.

Outcome

• Added the versioned makelore-runtime-v3.mjs parent extension surface for agent_browser, game_asset_browser, game_asset_review, task_state, changed_file, and runtime_context. Product calls cross the existing loopback worker-token bridge with conversation/generation/run validation; child workers do not register or invoke these parent product tools.
• Added PiProductTools and direct Main-domain adapters. Agent Browser calls AgentBrowserModule without MCP and converts Page.captureScreenshot results into product attachment IDs. Game asset browse/review behavior now lives under vendor-neutral electron/coding-projects ownership while the current OpenCode Host route temporarily consumes the same module.
• Added strict v1 typed details for browser, game assets, task state, changed files, and runtime context. Live projection and cold session hydration accept only normalized known versions and replace unknown raw details with bounded generic text.
• Added ConversationChangeTracker: each run captures Git HEAD plus dirty status/diff/untracked baseline; write/edit reports refresh exact relative paths, bash requests a settled project-wide refresh, and no-Git projects use only explicitly touched paths. Diffs and untracked previews are bounded, absolute paths are rejected, and no hashes/checkpoints/rollback mechanism were introduced.
• Added an explicit bundled Skill registry and Makelore/Pi/selected-Skill command catalog projection. Only packaged Skill IDs and safe metadata are exposed; project/user auto-discovery remains disabled.
• Extended the real Pi and staged production-closure smoke to require all parent product tools while retaining the exact read-only child tool set.
• No Renderer or /api/coding route was added; PI-105/PI-130 remain the owners of Host API and UI consumption. README.md therefore still describes the unchanged current product cutover state and did not require an update here.

Verification

• corepack pnpm run typecheck: passed.
• corepack pnpm run lint:check: passed with the same six repository warnings and no errors (ExecutionGraphCard.tsx, Home/index.tsx, and Makelore/index.tsx; none are in this task's changed scope).
• Focused PI-090/Pi projection/bridge/game suite: 10 files, 61 tests passed before the final boundary additions; subsequent focused runs covered 27 and 9 tests respectively and passed.
• corepack pnpm test: 203 files passed; 2224 tests passed, 2 skipped.
• corepack pnpm run build:vite: passed for Renderer, Electron Main, Preload, and release utility outputs; existing chunk-size/dynamic-import warnings remain non-blocking.
• corepack pnpm run test:electron:windows: 1 file, 3 tests passed.
• corepack pnpm run test:pi-subagent:packaged: 1 file, 4 tests passed, including staged parent product-tool registration and the unchanged staged read-only child boundary.
• Real external Provider turns remain Explicitly Waived / Accepted Risk; realTurnVerified=false. macOS x64/arm64 validation remains deferred to the mandatory PI-150 gate. Neither item is recorded as passed.

Follow-ups

• PI-100/PI-105 must construct/configure PiProductTools in the production Main composition, expose Conversation changes, attachment reads, Skills and command DTOs through /api/coding, and keep the new attachment store behind Main-owned routes.
• PI-130 must consume typed product-tool details and Conversation change snapshots without inferring changes from message text; fork copy must not imply filesystem rollback.
• PI-140 may delete the remaining OpenCode-specific consumer/MCP artifacts only after cutover; the vendor-neutral game asset and Skill sources remain.
• PI-150 must run mandatory macOS x64/arm64 validation. Real external Provider concurrency, credential isolation and protocol compatibility remain the explicitly accepted unverified risk until a separately authorized test.

Promotion Candidates

• Target canonical documents: .project-docs/30-worklog/current-state.md and the accepted PI cutover implementation status maintained by the planner. Proposal: after the implementation commit is reviewed and integrated, mark PI-090 complete and make PI-105/PI-130 eligible on the cumulative chain. Evidence: the implementation commit from this task plus the verification matrix above. Future impact: Host API/UI tickets may consume the typed product-tool, Skill-command and Conversation-change contracts instead of OpenCode Session diff/todo/MCP behavior. Semantic conflicts: none known. Human confirmation required: no for recording the merged implementation fact; normal planner review and integration ownership still apply.