attempt-ledger

# Attempt Ledger Pattern

## Purpose

The attempt ledger tracks execution attempts for tasks, enabling:

- **Retry with context:** Each attempt includes previous failure information
- **Gating:** Prevents infinite retry loops when tasks consistently fail
- **Progress persistence:** Resume execution after interruption
- **Receipt tracking:** Structured summaries instead of full transcripts

## Epic Schema

```yaml
# .agents-os/relay/epic.yml
version: 2
id: "20260111-feature-name"
source: "docs/plans/xxx.md"
created_at: "2026-01-11T17:30:00Z"

title: "Feature Name"
description: |
  Brief description of the epic.

tasks:
  T1:
    title: "Create users migration"
    priority: p1
    points: 2
    files:
      - db/migrate/xxx_create_users.rb
    depends_on: []
    acceptance_criteria:  # Generated by relay:init if missing
      - "Migration creates users table with email and password_digest"
      - "Migration is reversible"
      - "Email column has unique index"
```

## Ledger Schema

```yaml
# .agents-os/relay/attempt-ledger.yml
version: 1
epic_id: "20260111-feature-name"
started_at: "2026-01-11T17:30:00Z"

settings:
  max_attempts_per_task: 3
  timeout_minutes: 15

task_status:
  T1: completed
  T2: in_progress
  T3: pending
  T4: blocked

attempts:
  T1:
    - id: 1
      started_at: "..."
      ended_at: "..."
      result: success
      receipt:
        summary: "Created migration and model"
        files_changed: [file1.rb, file2.rb]

  T2:
    - id: 1
      result: failure
      receipt:
        error_category: missing_dependency
        error_summary: "Database not migrated"
        suggestion: "Run db:migrate first"

gated_tasks:
  T5:
    reason: "max_attempts_exceeded"
    gated_at: "..."
```

## Gating Rules

Tasks are gated (blocked from retry) when:

| Condition | Gating Action |
|-----------|---------------|
| `attempts >= max_attempts` | Gate with `max_attempts_exceeded` |
| Same error repeated 2+ times | Gate with `repeated_failure` |
| Quality gate