makelore/.project-docs/30-worklog/tasks/20260826-ml04-pi-data-tools-8d3c91a7.md

Task: Implement ML-04 purpose-specific Pi product tools

Identity

• Task ID: 20260826-ml04-pi-data-tools-8d3c91a7
• Mode: Feature
• Branch: codex/20260826-ml04-pi-data-tools-8d3c91a7-ml04-pi-data-tools
• Worktree: D:\Datas\OthersProjects\makelore-ml04-pi-data-tools-8d3c91a7
• Base commit: e15d8b7f51
• Owner: ml04-pi-tools
• Status: Ready for integration

Scope

• Implement ML-04 in the MakeLore Electron Main/Pi boundary: ten purpose-specific Data Service Pi tools, strict protocol schemas, safe result details, destructive confirmation handling, and one-to-one in-process dispatch through the existing ML-03 DataServiceOperations seam.
• Primary owned paths are electron/coding-runtime/pi/product-tools.ts, electron/coding-runtime/pi/extensions/makelore-runtime.ts, electron/api/coding-composition.ts, and focused Pi product-tool/extension tests. Only directly required shared contracts/projectors and the Data Service trusted-project-path seam may change.
• Explicitly out of scope: ML-05 preview, ML-06 browser work, unrelated Renderer work, any OpenCode compatibility or generic multiplexer, loopback HTTP, credentials or arbitrary project/owner/path inputs, and root-main/push/PR operations. The only Renderer touch is the type-required conversation detail summary for the new safe data-service.v1 contract.

Intent And Constraints

• Preserve Pi 0.84.2 as the sole runtime and preserve both parent-only controls: bundled extension registration and the extension-host bridge 403 for child workers.
• Tool identifiers are the exact ten underscore names from spec 9.4. Every input is closed (additionalProperties: false), validated at the product-tool seam, and derives authority from PiProductToolContext.projectPath; no tool input may contain owner, project, path, token, endpoint, URL, or local handles.
• Reuse the single Main DataServiceOperations instance created by composition. Pass trusted Pi context projectPath at the deep operation boundary so active project identity is checked by the existing ML-03 service rather than by a second adapter or network hop.
• Destructive operations require literal confirmed: true and return the safe Data Service envelope/detail without leaking credentials, local paths, or arbitrary upstream data.

Project Context Loaded

• Task identity: 20260826-ml04-pi-data-tools-8d3c91a7; mode feature; owner ml04-pi-tools; branch codex/20260826-ml04-pi-data-tools-8d3c91a7-ml04-pi-data-tools; isolated worktree D:\Datas\OthersProjects\makelore-ml04-pi-data-tools-8d3c91a7; base e15d8b7f51bea6b56558c981964082a4e76e523c.
• Concurrent-task findings: the ML-00..ML-09 coordinator owns integration sequencing but not these implementation paths; existing Pi product-tools, extension-host, child-worker, and core-host-api work is already in the base. Other active planning records are placeholders or unrelated E2E/media work; no semantic ownership conflict was found for this scope.
• Read before planning: repository AGENTS.md; .project-docs entry, memory-index, current-state, decision index, ADR-006, system overview, module-map, data-flow, business-rules, glossary, evidence/reflection/ commitments/stale-item indexes; all relevant active/ready peer task records; the server-side ML plan and Data Service integration specification sections 8.5, 9.1–9.4.
• Relevant understanding: Main composition already creates one DataServiceOperations; CodingProjectService exposes requireActiveRealProjectWithIdentity; Pi product tools currently dispatch existing product operations in-process; the extension bundle forwards parent invocations to the extension-host bridge; the bridge already rejects child product invocation with 403.
• Known documentation uncertainty: project positioning and success-criteria documents remain mostly placeholders; this task therefore treats the accepted ML plan/spec and existing code/contracts as authoritative.

Plan

1. Extend shared Data Service result/detail contracts and product-tool projectors only as needed to represent a safe, versioned result envelope.
2. Add strict ten-tool validation and one-to-one dispatch in Pi product-tools, passing trusted context projectPath to the single Data Service operations object; wire that object from composition.
3. Add all ten parent-only registrations and closed parameter schemas to the bundled Makelore Pi extension while retaining existing registration behavior and bridge child-worker rejection.
4. Add focused contract, Pi product-tool, bundle, and bridge tests proving exact IDs/schemas, dispatch/authority, safe details, confirmations, and absence of forbidden input fields.
5. Run focused tests, typecheck, lint, diff/doc-drift checks; update this task record and complete the task-context gate.

Outcome

• Added the ten exact parent-only Pi Data Service tools with closed, bounded protocol schemas and matching Main-side input validation. Each operation dispatches directly to the one composition-owned DataServiceOperations instance; active-project operations receive the trusted Pi projectPath and owner-wide listing does not.
• Added versioned data-service.v1 safe result details with bounded envelope projection, wired them through the existing conversation projector, and kept destructive operations behind literal confirmed: true.
• Preserved the bundled parent-role registration gate and extension-host child bridge 403; added tests for all ten registrations, dispatch routing, trusted path authority, forbidden input fields, and confirmation rejection.
• Follow-up correction tightened the bundled document and revision schemas to match Main-side validation: document_id rejects ./.., and if_revision is capped at Number.MAX_SAFE_INTEGER; focused assertions cover both rules.
• No canonical project memory was changed. The only non-Main contract touch is the minimal conversation timeline summary required for the new discriminated safe-detail type to remain type-safe and visible.

Verification

• pnpm exec vitest run tests/unit/pi-product-tools.test.ts tests/unit/pi-extension-bundle.test.ts tests/unit/pi-extension-host.test.ts --maxWorkers=1 — 23 passed.
• Schema-hardening rerun of the focused Pi suite — 23 passed, including the document_id and if_revision bundled-schema assertions.
• Data Service/projector plus Pi focused suites — 62 passed.
• Full unit suite excluding the separately serialized pressure test — 186 files, 1,574 passed, 2 skipped.
• pnpm typecheck — passed.
• pnpm lint:check — passed with the five pre-existing repository warnings in src/pages/Home/index.tsx and src/pages/Makelore/index.tsx.
• git diff --check — passed.
• Final task-aware doc-drift check and task-context completion are run before handoff.

Follow-ups

• The coordinator advanced after this task's required base with ML-03 commit 0ecceef15d2e43190f835fd71a7a1478222f1ba8 / coordinator frontier 44bcdf52...; when integrating, retain its Data Service error-code/status consistency correction while applying this task's trusted-project-path method-signature hunk.

Promotion Candidates

• None. The accepted ML-04 plan/spec and existing architecture remain the authority; no canonical ADR or project-memory update is proposed.