bytelyst-devops-tools/agent-queue/docs/jobs/phase1-slice4.md

engine	cwd	yolo	lock	timeout
devin	/Users/sd9235/code/mygh/learning_ai_devops_tools	true	devops-tools	3h

ROLE: Senior engineer. Implement Phase 1 — Slice 4: TRACKER ADAPTER (single host). This CLOSES Phase 1: a task in the tracker can become a job, and job outcomes echo back to the tracker — the task<->job round-trip (§10, the last Phase-1 §14 item).

SOURCE OF TRUTH: agent-queue/docs/gigafactory/GIGAFACTORY_ROADMAP.md (read §10 tracker integration, §5 manifest incl. tracker-item + idempotency-key, §24.5 one-way echo).

PREREQUISITE / BRANCHING:

• Slice 1, Slice 3, AND Slice 2 (profiles/deps) are merged into main. Branch off the CURRENT main. This slice MUST run AFTER Slice 2 is merged (it shares agent-queue.sh) — do not start it until then.
• New branch: feat/gigafactory-p1-slice4. Push + open a PR. DO NOT merge.
• Keep ALL existing selftest checks green (regression).

STRICT SCOPE:

• Edit ONLY under agent-queue/ (agent-queue.sh, selftest.sh, README.md, docs/gigafactory/GIGAFACTORY_ROADMAP.md). No other repo is modified.
• You MAY READ (not edit) ../learning_ai_common_plat/services/platform-service/ src/modules/items/{types,routes}.ts to match the real Item API contract (paths, fields, auth header). Do not change that repo.
• bash, single host, mac+linux safe, zero new runtime deps (curl only).

CONFIG (all via env; document in README; never hardcode URLs/tokens/secrets):

• AQ_TRACKER_API : base URL of the items API (default http://localhost:4003).
• AQ_TRACKER_TOKEN : bearer token for auth (required for real calls).
• AQ_PRODUCT_ID : productId to stamp/filter (every tracker Item has productId).
• A single tracker_api <method> <path> [json] wrapper does ALL HTTP via curl (bearer header, content-type, base URL). It MUST be overridable for tests via AQ_TRACKER_API_CMD (a stub script path) so selftest needs NO live service.

DELIVERABLES

1. aq from-tracker <ITEM_ID> — pull a tracker Item and materialize a job in inbox/:

   • GET the item via tracker_api; map fields → job frontmatter: title/description -> job body (the instruction markdown, verbatim) item type/labels -> engine-class/profile/capabilities/priority where labels carry them (e.g. label engine-class:agentic-coder, profile:backend-engineer, priority:high, cap:os:mac); otherwise sane defaults. item id -> tracker-item: <ITEM_ID> and idempotency-key: tracker-<ITEM_ID> (stable).
   • IDEMPOTENT: if a job for this tracker-item already exists in any stage (reuse Slice 1 idempotency on the derived key) → no duplicate enqueue.
   • On success print the created inbox filename; on missing item → clear error, nonzero.

2. aq to-tracker <job> — push a job's CURRENT outcome to its tracker Item (one-way echo, child -> tracker; §24.5). Only if the job meta has tracker-item.

   • Map stage/result -> item status PATCH: building/review/testing -> in_progress shipped -> done failed -> blocked (or the API's failure status) + note
   • Post a comment/note with result, attempts, and insights summary (duration, tokens/cost if present) — reuse Slice 3 metrics. Metrics only, NEVER prompt content or secrets.
   • IDEMPOTENT: re-running to-tracker for an unchanged outcome is a no-op (track last-echoed state in meta, e.g. tracker_echoed=<status>).

3. Auto-echo hook (opt-in, default OFF): an env flag (e.g. AQ_TRACKER_AUTO=1) makes the worker call to-tracker automatically on each stage transition it already performs (enqueue→building→review/testing/failed/shipped). When OFF, echo is manual via the command. Never block/fail a job because an echo failed — log the echo error and continue (the tracker is downstream, not authoritative for execution).

4. status / aq insights: show the tracker-item id and last echoed status where present (you already surface tracker-item in status from Slice 1 — extend it).

TESTS (selftest.sh — only ADD; NO live service — use AQ_TRACKER_API_CMD stub that returns canned JSON and records the calls it received):

• from-tracker creates an inbox job: stub returns an item JSON → aq from-tracker T-1 creates one inbox/*.md whose frontmatter has tracker-item: T-1 and idempotency-key: tracker-T-1, body = item description.
• from-tracker label mapping: item with labels [engine-class:agentic-coder, priority:high] → frontmatter reflects them.
• from-tracker idempotent: calling it twice for T-1 → exactly one job (dedupe).
• to-tracker status echo: a shipped job → stub receives a PATCH to status=done and a comment with the insights summary; assert no prompt body is sent.
• to-tracker idempotent: second call with unchanged outcome → no duplicate PATCH/comment (tracker_echoed honored).
• echo failure is non-fatal: stub returns HTTP 500 → to-tracker logs the error, exits without corrupting job state; the job's stage is unchanged.
• REGRESSION: all existing checks (Slice 0/1/2/3) still green.

DOCS:

• README: "Tracker integration" section — from-tracker/to-tracker, the env config, label→manifest mapping table, the one-way-echo rule, AQ_TRACKER_AUTO, and a note that real use needs platform-service running + a token.
• docs/gigafactory/GIGAFACTORY_ROADMAP.md: tick the §10 single-host items + the §14 Phase-1 "tracker adapter" item; set §0 Phase 1 → complete (or note the exact remaining %).

CONSTRAINTS: bash style consistent with the script; curl-only HTTP through the one wrapper; mac+linux safe; no emojis; conventional commits; tests sacred.

VERIFY GATE: bash agent-queue/selftest.sh fully green; bash -n agent-queue.sh; node --check dashboard.mjs; shellcheck --severity=error clean.

FINAL OUTPUT — print the report in EXACTLY this format:

Implementation Report — Phase 1 Slice 4

Branch & commits

• branch / based-on:
• commits:
• PR: <url or "opened, not merged">

Files changed

• :

What was implemented (1-4)

• : <how, key functions; the Item API contract you matched>

Tests added

• : (+ selftest PASS/FAIL summary)

Verify gate results

• selftest / bash -n / node --check / shellcheck:

Deviations / assumptions

• <API path/field/status mapping choices; anything stubbed>

Phase 1 status

• <which §14 items now complete; what (if anything) remains>

Suggested next slice

• Phase 2 Slice 1 (fleet data model + repositories in platform-service)