bytelyst-devops-tools/agent-queue/docs/jobs/phase1-slice1.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 1 of the Agent Gigafactory roadmap.

SOURCE OF TRUTH: agent-queue/docs/GIGAFACTORY/GIGAFACTORY_ROADMAP.md (read §4, §5, §6, §7, §14 Phase 1 first). This slice implements ONLY the items listed below.

STRICT SCOPE:

• Edit ONLY files under agent-queue/ (primarily agent-queue.sh, selftest.sh, README.md, docs/GIGAFACTORY/GIGAFACTORY_ROADMAP.md). DO NOT touch any other repo.
• DO NOT modify, move, or delete anything under agent-queue/queue/ — there are LIVE jobs running there. DO NOT run agent-queue.sh run. selftest.sh uses its own temp queue (AGENT_QUEUE_ROOT) — that is the only execution allowed.
• This is bash (single host). No service/Cosmos/Zod work in this slice (that is Phase 2).

DELIVERABLES (in agent-queue.sh, backward-compatible — legacy .md files with only engine/cwd/yolo MUST behave exactly as today):

1. MANIFEST PARSING: recognize these new frontmatter keys with safe defaults via the existing fm_get pattern: profile, engine-class, capabilities, prefers, priority, budget, deps, deps-mode, idempotency-key, retry, review-policy, artifacts, tracker-item. In THIS slice only items 2–5 are functional; the rest must be parsed + stored in the job .meta and shown in status, but otherwise inert (document as "reserved, no-op until later phase").

2. PRIORITY ORDERING: replace pure-FIFO inbox selection with priority-then-age. priority in {critical,high,medium,low} (default medium). Higher priority picked first; ties broken by oldest timestamp. Must not break per-lock serialization.

3. CAPABILITY GRAMMAR + MATCH (single-host):

   • detect_capabilities(): emit tokens for this host — os:<mac|linux>, engine:<devin|claude|codex|copilot present>, node>=, has: for a small probe set (git, pnpm, docker if present).
   • caps_match(required[], available[]) honoring §5 grammar: bare key = presence; key:value exact; key<op>version with op in {>=,>,=,<=,<} (numeric/semver-major compare); os:any = wildcard match-all. A job matches iff EVERY required token is satisfied.
   • At run time, if a job declares capabilities the host does not satisfy, move the job to failed/ with result=capability_mismatch and a clear log line (do NOT launch the agent).

4. ENGINE-CLASS RESOLUTION: if engine is unset but engine-class is set, pick a concrete engine from a documented class map honoring prefers-engine then availability: agentic-coder -> [devin, claude, codex]; chat-coder -> [copilot]. Explicit engine always wins. If neither yields an available binary, fail the job with result=no_engine.

5. IDEMPOTENCY-KEY DEDUPE (on add): compute a content hash of the stripped body. If an existing job in ANY stage (inbox/building/review/testing/shipped) has the same idempotency-key AND same hash -> no-op (log "duplicate, skipped"). Same key + DIFFERENT hash -> reject with a clear error UNLESS the prior job is still in inbox/ (then replace it).

TESTS (selftest.sh — tests are sacred; only ADD, never weaken existing ones). Add cases:

• backward-compat: a legacy engine/cwd/yolo-only .md still completes and lands in review/.
• priority: with max=1, a critical job queued after a low job runs first.
• capability mismatch: a job requiring has:definitely-not-installed -> failed/ result=capability_mismatch (agent never launched; use the existing no-op engine stub).
• engine-class: a job with engine-class: agentic-coder and no engine, DEVIN_BIN stubbed, runs and lands in review/.
• idempotency: adding the same key+body twice yields exactly one inbox file; same key + different body is rejected.

DOCS:

• README.md frontmatter table: add the new fields, clearly marking ACTIVE (Phase 1) vs RESERVED.
• docs/GIGAFACTORY/GIGAFACTORY_ROADMAP.md: tick ONLY the Phase 1 checklist boxes you fully completed and update the §0 progress % for Phase 1 (do not tick incomplete items).

CONSTRAINTS:

• bash style consistent with the existing script; no new runtime dependencies; macOS + Linux safe (no GNU-only flags without fallback). No emojis in code. No leftover debug echo noise.
• Work on a NEW branch: feat/gigafactory-p1-slice1. Commit in logical steps with conventional commit messages. Push the branch and open a PR. DO NOT merge to main (human gate).

VERIFY GATE (must pass before finishing):

• bash agent-queue/selftest.sh -> MUST be fully green (existing + new cases).
• bash -n agent-queue/agent-queue.sh and node --check agent-queue/dashboard.mjs.

FINAL OUTPUT — print an implementation report in EXACTLY this format:

Implementation Report — Phase 1 Slice 1

Branch & commits

• branch:
• commits: (one per line)
• PR: <url or "opened, not merged">

Files changed

• :

What was implemented (per deliverable 1-5)

• : <how, key functions added/changed>

Tests added

• : (plus selftest.sh PASS/FAIL summary)

Verify gate results

• selftest.sh: <PASS/FAIL + counts>
• bash -n / node --check:

Deviations / assumptions

Reserved (parsed-but-inert) fields

Suggested next slice