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

# .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

# .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:

attempts >= max_attempts

max_attempts_exceeded

repeated_failure

quality_gate_blocked

user_blocked

Receipt Structure

Success Receipt

receipt:
  summary: "Brief description of what was done"
  files_changed: [list, of, files]
  quality_gate_verdict: APPROVED
  learning: "Reusable insight from this task"  # Compound learning
  pattern_tags: [yq, shell, quoting]           # For aggregation

Failure Receipt

receipt:
  error_category: missing_dependency | code_error | test_failure | quality_gate | cli_error
  error_summary: "What went wrong"
  quality_gate_verdict: NEEDS CHANGES | BLOCKED  # If quality gate failed
  quality_gate_findings: |  # Structured findings for retry context
    ## Finding 1: Missing test coverage
    **Severity:** HIGH
    **File:** app/models/user.rb:15
    **Fix:** Add unit tests for validation
  suggestion: "What to try differently"
  learning: "What was learned from the failure"  # Compound learning
  pattern_tags: [migration, database]            # For aggregation

Compound Learning

Learnings are extracted after each task attempt, aggregated at epic completion, then cleared.

Per-Task Extraction

After each attempt (success or failure), a lightweight prompt extracts:

• learning: One-sentence reusable insight
• pattern_tags: Comma-separated tags for grouping

Epic Completion Flow

When epic completes, the

learning-processor

1. Reads all learnings from ledger
2. Consolidates similar patterns by semantic meaning
3. Applies frequency thresholds:
   • 1x = Skip (noise)
   • 2x = Emerging (watch)
   • 3x = Recommend
   • 4+ = Strong signal
4. Promotes to AGENTS.md Key Learnings (primary destination)
5. Clears learnings from ledger after promotion

Why Clear After Promotion?

• Learnings are temporary working memory
• AGENTS.md is the permanent store (always loaded by Claude)
• Prevents accumulation across epics
• Keeps ledger lean for next epic

Task Status Flow

pending → in_progress → completed
                ↓
            failure → pending (retry)
                ↓
            max_attempts → gated

Integration with Re-anchoring

Each fresh Claude instance receives:

1. Git state: Current branch, last commit, uncommitted changes
2. Epic context: Title, description, overall progress
3. Task details: Files, acceptance criteria, dependencies
4. Previous receipts: What was tried, what failed, why

This prevents context drift and ensures each attempt builds on prior learnings.

Commands

/relay:init

/relay:status

/relay:work

Defaults

Settings are stored in

attempt-ledger.yml

• max_attempts_per_task: 3

  - Retry limit before gating

• timeout_minutes: 15

  - Max execution time per task

Override at runtime with

--max-attempts N