Initial commit: pygenium as git submodule

tasks/05-infrastructure-utils.md

@@ -0,0 +1,46 @@
+# 05. Scheduler, retry, and command-target parsing
+
+meta:
+  id: pygienium-05
+  feature: pygienium
+  priority: P1
+  depends_on: [pygienium-01]
+  tags: [infrastructure, utilities, no-model]
+
+objective:
+
+- Build three small infra modules the check runner needs: a concurrency-bounding scheduler, a retry-with-backoff helper, and a command argument parser.
+
+deliverables:
+
+- `src/scheduler.ts`: `Scheduler` with `enqueue({id, run})`, burst cap from env `PYGIENIUM_MAX_AGENTS` (default 3), `dispose()`
+- `src/retry.ts`: `runWithRetry`, `readPositiveIntEnv`, `readNonNegativeIntEnv`, `errorMessage`, `yieldToEventLoop`
+- `src/command-target.ts`: `parseCommandArgs(args, cwd, opts)` → `{ cwd, tokens, args, error? }` supporting `[path]`, `--fresh`, `--fix`, `--check=<name>`, `--scope=<path>`
+
+steps:
+
+- Port piolium's `Scheduler` (Promise.allSettled under a semaphore-like cap) and `retry.ts` env helpers
+- Implement `runWithRetry(fn, { maxRetries, backoffBaseMs, backoffMaxMs, onRetry, signal })`
+- Implement `parseCommandArgs`: first non-flag token = optional target path (default cwd); collect `--flag` and `--opt=val` tokens into a tokens array + option lookup; return error string for malformed input
+
+tests:
+
+- Unit: scheduler caps concurrent runs at the configured value (spawn N no-op tasks, assert max in-flight)
+- Unit: retry exhausting throws the last error; onRetry invoked with backoff between attempts
+- Unit: parser handles `--fresh /repo --check=comments` → cwd=/repo, tokens=[--fresh, --check=comments], check=comments
+
+acceptance_criteria:
+
+- Scheduler never exceeds the burst cap
+- retry respects maxRetries and aborts on signal
+- parser returns structured tokens with no ambiguity for the supported flags
+
+validation:
+
+- `grep -n "PYGIENIUM_MAX_AGENTS" src/scheduler.ts` present
+- Unit test suite for the three modules passes (if a test runner is configured)
+
+notes:
+
+- These are pure utilities; keep them dependency-free beyond node builtins
+- Grouped into one task because each is small and they're mutually independent