# 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: e15d8b7f51bea6b56558c981964082a4e76e523c
- 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.