ready_context

Category: tasks
Access: read
Audience: ordinary (an ordinary user normally calls this directly)

Purpose

Returns deterministic ready/prime context: live tasks scored into ready states with reasons, urgency, blockers, and provenance. The cross-project answer to what should be worked next, meant to be consulted before broad memory search.

Arguments

Optional: include_readings, limit, mode.

include_readings. Note: Threaded into record building; off by default.
limit. Note: Clamped to 1..100 (default 12).
mode. Note: ready (scored records), suggested (task-shaped candidates), or prime (compact session boot pack). Anything else returns an error naming the valid modes.

Result

Versioned under contract_version ready_context.v1. ready returns mode, count, truncated, and items; suggested returns mode, count, and task-shaped items; prime returns the mandate, guidance, today_used, items_empty, top_ready_items, blocked_or_waiting, cleanup_candidates, explicit_exclusions, risk_or_escalation_items, evidence_refs, and mode. An invalid mode returns error plus valid_modes.

Boundaries

Only live content inside the caller's project grants is scored; finished content appears solely as review-only candidates or explicit exclusions. No visible scope reads as the empty shape for the requested mode, never a denial.

Lifecycle / side effects

Pure read; scoring, sorting, and sort_position stamping leave the underlying tasks untouched.

Errors

Unknown arguments and bad types are rejected (strict validator). An unknown mode is rejected with an error plus the valid mode list.

Example

{
  "limit": 12,
  "mode": "ready"
}

Result shape:

{
  "contract_version": "ready_context.v1",
  "count": 2,
  "items": [],
  "mode": "ready",
  "truncated": false
}