apra-labs/apra-fleet/auto-sprint-args

auto-sprint argument contract

Auto-sprint hard-fails on malformed args (validateSprintArgs runs first, before any work). Get the shape right before launching.

Fields

Do not invent other fields -- these seven are the whole contract.

Args must be a JSON OBJECT, not a JSON-encoded string

RIGHT -- pass the object itself as the args value:

{ "issues": ["APM-12"], "branch": "feat/x" }

Full example:

{
  "issues": ["BD-1", "BD-2"],
  "branch": "feat/auth",
  "goal": "P1/P2",
  "max_cycles": 5,
  "base_branch": "main",
  "requirementsFile": "docs/auth-requirements.md",
  "skip_dolt_push": false
}

WRONG -- a JSON string containing escaped JSON:

"{\"issues\":[\"APM-12\"],\"branch\":\"feat/x\"}"

Also wrong: { "issues": "APM-12" } (issues must be an array), { "issue": [...] } (field is issues), { "goal": "P2" } (not an accepted goal value).

Tolerant fallback forms (accepted, but don't rely on them)

The parser normalizes these to { issues: [...] }:

• BD-1 -- bare issue ID
• BD-1 BD-2 or BD-1,BD-2 -- space/comma-separated IDs
• ["BD-1","BD-2"] -- JSON array

In these forms branch falls back to the current git branch -- an easy way to accidentally sprint on the wrong branch. Always use the full object form with an explicit branch.

Pre-launch checklist (mirrors the preflight gate)

1. Issues exist and are open -- bd show <id> for each root; a missing root hard-fails preflight.
2. Ready leaf work exists -- at least some leaves under the roots are unblocked (bd ready); an all-blocked backlog deadlocks and aborts.
3. Branch name chosen -- explicit branch, created if absent.
4. `base_branch` is the intended PR target (default main) and must differ from branch -- an equal pair is rejected at launch.
5. Branching off latest main -- the workflow fetches and cuts new branches from origin/<base_branch>; if fetch fails, launch fails. Make sure the remote is reachable.

Common failures and the exact error you'll see