Tasks

The task ledger (.openloop/tasks.json in each repo) is the single source of truth for what work exists and what happened to it. Everything the daemon does starts and ends with a ledger entry.

Anatomy

{
  "id": "harden-webhook-retries",
  "title": "Harden webhook retries",
  "kind": "bugfix",
  "status": "ready",
  "risk": "low-risk",
  "scope": { "paths": ["src/webhooks/", "tests/webhooks/"] },
  "source": { "type": "human", "ref": "openloop task add" },
  "dependsOn": ["fix-flaky-checkout-tests"],
  "acceptanceCriteria": ["To be defined during planning."],
  "attempts": 0,
  "promotion": "pull-request",
  "createdAt": "2026-07-01T09:00:00.000Z"
}

• id: slug of the title (lowercase, --separated, max 64 chars).
• kind: feature · bugfix · test · refactor · docs · lint-fix · type-fix · localized-test-fix · ci-heal · discovery · scope-proposal.
• risk: low-risk · medium-risk (default) · high-risk. Drives the promotion decision.
• scope: optional relative path constraints; validated on creation (no absolute paths, no ..) and enforced by policy.
• dependsOn: other task ids that must finish first.
• promotion: the default promotion mode for the task (pull-request).

Statuses

proposed → planned → ready → in_progress → done
                ↑                     ↓
        awaiting-approval          blocked / failed
                                      ↓
                              cancelled / promoted

Status	Meaning
proposed	Exists, not yet planned. Entry point for task add.
planned	A spec exists (.openloop/specs/).
ready	Eligible for scheduling.
awaiting-approval	Needs explicit human sign-off before running (see below).
in_progress	An agent run is active.
blocked	Attempt ceiling hit, policy denial, or failed validations, needs attention.
done / failed / cancelled	Terminal states for a run cycle.
promoted	A promotion was applied.

Creating and managing tasks

# from a title
openloop task add -p api --title "Harden webhook retries" --kind bugfix --risk low

# from an issue reference (URL or key)
openloop task add -p api --from-ref "https://github.com/org/repo/issues/42"

# list / inspect
openloop task list -p api --status ready
openloop task show -p api --task harden-webhook-retries

# edit
openloop task update -p api --task harden-webhook-retries --risk medium-risk

# recover stuck runs (in_progress → ready)
openloop task recover -p api

The daemon also creates tasks itself: self-healing failures become lint-fix / type-fix / localized-test-fix tasks, and idle-time continuous improvement proposes discovery and scope-proposal tasks.

Approvals

Tasks moved to awaiting-approval (by policy, by hooks, or by hand) will not run until approved:

openloop approval list -p api
openloop approval show -p api --task migrate-auth-lib
openloop task approve -p api --task migrate-auth-lib

The approval packet gathers what a human needs to decide: risk class, attempts, measured cost, and the branch the change sits on.