---
engine: devin
cwd: /Users/sd9235/code/mygh/learning_ai_common_plat
yolo: true
lock: common-plat-tracker
timeout: 4h
---

ROLE: Senior backend engineer. Implement the PHASE 2 DIRECT TRACKER -> MODULE WIRING
(§10) for the fleet coordinator: a service-side bridge that turns a tracker Item into
a fleet job (submitted through the coordinator, so it is routed by the §7 scheduler),
and echoes the job's lifecycle back onto the Item — the full task<->job ROUND-TRIP,
in-process, with no shell hop. This closes the §10 "direct tracker->module calls" box.

PARALLEL-SAFETY: One other Devin is running in a DIFFERENT repo (learning_ai_devops_tools,
the two-factory demo). There is NO other Devin in this repo, so you may edit any fleet
file you need. Do NOT edit the agent-queue repo.

READ FIRST (understand the contracts before writing):
- services/platform-service/src/modules/fleet/coordinator.ts
    - submitJob(productId, SubmitJobInput) -> { job, outcome } : idempotent submit; the
      job already has a `trackerItemId` field (types.ts) — reuse it, do NOT add a new one.
    - claimNextJob(ctx) already routes candidates through the §7 scheduler (selectJob).
      You do NOT change claim/scheduler — tracker jobs flow through the SAME path.
    - patchJobFenced / stage transitions — the lifecycle you will mirror to the tracker.
- services/platform-service/src/modules/fleet/types.ts — FleetJobDoc.stage values,
  SubmitJobSchema (trackerItemId, idempotencyKey, priority, capabilities, budget, kind).
- services/platform-service/src/modules/fleet/routes.ts — existing fleet route patterns
  (auth, getRequestProductId(req), Zod parse, productId enforcement). Add new routes here
  in the SAME style.
- services/platform-service/src/modules/items/{types,routes,repository}.ts — the Item
  API contract you mirror to: Item fields (id, productId, title/description, status,
  labels[]), the status vocabulary, and the comment/note mechanism. Call the items
  repository DIRECTLY in-process (no HTTP/curl) — this is the whole point of "direct wiring".
- ../learning_ai_devops_tools/agent-queue/docs/GIGAFACTORY_ROADMAP.md §10 (tracker
  integration), §24.5 (echo rule), §14 Phase-2 checklist (the §10 box you will tick).

PREREQUISITE / BRANCHING: branch off CURRENT main -> feat/gigafactory-p2-tracker-wiring.
Push + open a PR. DO NOT merge.

DELIVERABLES

1. tracker-bridge.ts (NEW) — pure-ish service module (it may call the items + fleet
   repositories, but no HTTP, no Fastify types inside it):
   - `ingestItemAsJob(productId, itemId, opts?) -> { job, outcome }`:
       * read the Item via the items repository (404 -> NotFoundError).
       * map Item -> SubmitJobInput: title/description -> bodyMd (verbatim instruction);
         labels carry manifest hints where present (engine-class:*, profile:*,
         priority:*, cap:* -> capabilities[]); otherwise sane defaults.
       * set trackerItemId = itemId and a STABLE idempotency-key (e.g. `tracker-<itemId>`),
         then call coordinator.submitJob — so re-ingest of the same Item dedupes (no
         duplicate job) and the job is scheduled by the §7 router like any other.
   - `echoJobToItem(productId, jobId) -> { echoed: status | null }`:
       * load the job; if it has no trackerItemId -> no-op (return null).
       * map stage -> Item status (FULL round-trip, both directions of the lifecycle):
           queued/assigned/building/review/testing -> in_progress
           shipped                                 -> done
           failed                                  -> blocked (+ note)
       * append a comment/note with metrics ONLY (attempts, duration, cost/tokens if
         present) — NEVER the prompt body / secrets.
       * IDEMPOTENT: persist the last-echoed status (on the job doc or a small bridge
         record) and make a re-echo of an unchanged outcome a no-op.
   - Echo is BEST-EFFORT and downstream: an items-write failure NEVER fails the job —
     surface it as a logged error / a `{ echoed: null, error }` shape, never throw into
     the job lifecycle.

2. Wire echo into stage transitions (server-side, opt-in, additive):
   - When the coordinator/route performs a stage transition for a job that has a
     trackerItemId, call echoJobToItem (guarded by a config flag, default OFF, e.g.
     FLEET_TRACKER_ECHO; OFF => behavior byte-for-byte unchanged). Do not block or fail
     the transition on echo error.

3. Routes (routes.ts, additive — match existing auth/productId style):
   - POST /fleet/tracker/ingest        { itemId }            -> ingestItemAsJob
   - POST /fleet/tracker/echo          { jobId }             -> echoJobToItem (manual echo)
   - All productId-scoped via getRequestProductId(req); a foreign productId cannot ingest
     or echo another product's Item/job.

TESTS (tracker-bridge.test.ts + route additions — tests are sacred; use @bytelyst/testing
+ the in-memory providers; NO live HTTP):
- ingest creates exactly one job: Item -> job with trackerItemId set, bodyMd = description,
  idempotency-key = tracker-<id>; the job is claimable via the normal claimNextJob path.
- ingest label mapping: labels [engine-class:agentic-coder, priority:high, cap:os:mac]
  -> job priority/capabilities reflect them.
- ingest idempotent: ingesting the same Item twice -> one job (dedupe), outcome reflects it.
- echo round-trip: a job advancing queued->building->shipped drives the Item
  in_progress -> done, and a metrics-only comment is written (assert NO bodyMd/secret leaks).
- echo failed -> Item blocked (+ note).
- echo idempotent: re-echo of an unchanged stage -> no duplicate Item write.
- echo non-fatal: items-write throws -> echoJobToItem returns { echoed:null,error }, the
  job state is untouched, the transition still succeeds.
- echo OFF (default flag): a stage transition performs ZERO items writes.
- productId isolation: ingest/echo for a foreign productId -> not found / rejected.
- REGRESSION: every existing fleet + items test stays green.

VERIFY GATE:
- pnpm --filter @lysnrai/platform-service exec vitest run src/modules/fleet src/modules/items
- pnpm --filter @lysnrai/platform-service build
- pnpm build && pnpm test   (no consumer regression)

CONSTRAINTS: ESM `.js` import specifiers; no `any` (Zod inference / explicit types); no
console.log (use app.log / req.log); every Cosmos doc keeps `productId`; reuse the
existing `trackerItemId` field and items contract — do NOT fork a parallel schema;
do NOT change claimNextJob or the scheduler; conventional commits
(feat(platform-service): ...); do not edit the agent-queue repo.

DOCS: tick §10 "direct tracker->module calls" in
../learning_ai_devops_tools/agent-queue/docs/GIGAFACTORY_ROADMAP.md §14 Phase-2 (note the
flag name + that it is the in-process round-trip; the agent-queue shell adapter remains the
single-host path).

FINAL OUTPUT — report in EXACTLY this format:
## Implementation Report — Phase 2 Direct Tracker -> Module Wiring (§10)
### Branch & commits / PR
### Files changed
### What was implemented (ingest mapping, round-trip status map, echo idempotency + flag)
### Tests added (+ pnpm test summary)
### Verify gate results
### Deviations / assumptions (Item status vocabulary matched, flag name, where last-echoed is stored)
### Suggested next slice (Phase 3 tracker-web fleet control plane)