How to Implement the Recovery System for Automatic Failure Handling in aios-core

The Recovery System in aios-core provides automatic failure handling through the RecoveryTracker class, which records every sub-task execution to JSON-backed attempt files, supports programmatic retries and rollbacks, and exposes a CLI for agent integration.

The Recovery System (Epic 5 of the Autonomous Development Engine) is a critical infrastructure component in the SynkraAI/aios-core repository. It enables autonomous agents to track execution attempts, handle failures gracefully, and maintain auditable histories of every sub-task. This guide explains how to implement the Recovery System using the RecoveryTracker class and its associated CLI tools.

Understanding the aios-core Recovery System Architecture

The Recovery System is built around three core pillars: a programmatic API, strict schema validation, and a command-line interface for agent interaction.

Core Components

The RecoveryTracker class, defined in .aios-core/infrastructure/scripts/recovery-tracker.js, serves as the primary API. It handles loading attempt histories, validating data against the ATTEMPTS_SCHEMA (lines 83-116), and persisting updates to disk. The schema enforces required fields including attemptNumber, status, startTime, and approach.

The CLI entry point (lines 442-629) parses commands such as start, complete, abandon, history, and summary, forwarding them to the appropriate RecoveryTracker methods.

File Structure and Storage

Each story receives isolated storage under docs/stories/<story-id>/recovery/. The tracker auto-creates this directory on first use. Individual sub-tasks maintain separate JSON files named subtask-<id>.json (AC6), ensuring that concurrent work on different sub-tasks does not create write conflicts.

Implementing the RecoveryTracker Class

To integrate automatic failure handling into your application, instantiate the tracker and invoke its lifecycle methods at appropriate execution points.

Initializing the Tracker

Create a tracker instance by specifying the story identifier. The constructor automatically resolves paths based on the centralized CONFIG object (lines 50-58).

const { RecoveryTracker } = require('./.aios-core/infrastructure/scripts/recovery-tracker');

// Initialize for a specific story
const tracker = new RecoveryTracker({ storyId: 'STORY-42' });

Starting and Completing Attempts

Use startAttempt() to record the beginning of a sub-task execution. This method auto-increments attempt numbers (AC7) and timestamps the entry.

// Start tracking sub-task 2.1
const attempt = tracker.startAttempt('2.1', {
  approach: 'Refactor state handling with zustand middleware',
  changes: ['src/store.ts', 'src/components/Widget.ts'],
  notes: 'First try with immer middleware',
});

console.log('Started attempt #: ', attempt.number);

When execution finishes, call completeAttempt() with the outcome. For failures, include error details to support downstream analysis.

// Record a failed attempt
tracker.completeAttempt('2.1', {
  success: false,
  error: 'TypeError: persist is not a function',
  notes: 'Missing export from zustand-persist',
});

// Record a successful attempt
tracker.completeAttempt('2.1', {
  success: true,
  notes: 'All tests passing',
});

Handling Failures and Rollbacks

For unrecoverable errors, invoke abandonAttempt() to mark the sub-task as abandoned. This status triggers rollback procedures in the ADE pipeline and prevents further automatic retries.

// Abandon the current approach
tracker.abandonAttempt('2.1', {
  reason: 'Architecture incompatible with existing state shape',
  rollbackTarget: '2.0',
});

Using the Recovery System CLI

Agents and automation scripts interact with the Recovery System through the CLI wrapper, enabling *track-attempt and *rollback commands.

Starting a New Attempt

Execute the start command with the story ID, sub-task ID, and metadata flags.

node .aios-core/infrastructure/scripts/recovery-tracker.js start STORY-42 2.1 \
  --approach "Add optimistic UI updates" \
  --changes "src/ui.jsx,src/api.js" \
  --notes "Will need to add loading flag"

Recording Success or Failure

Update the attempt status using the complete command with either --success or --fail.

# Mark as successful

node .aios-core/infrastructure/scripts/recovery-tracker.js complete STORY-42 2.1 --success

# Mark as failed with error details

node .aios-core/infrastructure/scripts/recovery-tracker.js complete STORY-42 2.1 \
  --fail \
  --error "ReferenceError: apiClient is undefined"

Generating Reports

Retrieve human-readable history or story-wide summaries using the history and summary commands.

# View sub-task specific history

node .aios-core/infrastructure/scripts/recovery-tracker.js history STORY-42 2.1

# View story-wide recovery summary

node .aios-core/infrastructure/scripts/recovery-tracker.js summary STORY-42

The generateReport() method (lines 778-834) produces markdown-styled output suitable for agent consumption and documentation.

Validating Recovery Data with JSON Schema

The Recovery System enforces data integrity through the ATTEMPTS_SCHEMA constant. To export the schema for external validation tools or documentation:

node .aios-core/infrastructure/scripts/recovery-tracker.js schema > attempts-schema.json

The schema defines required properties including attemptNumber, status (enum: ['in-progress', 'completed', 'abandoned']), startTime, endTime, and nested approach objects. Runtime validation occurs in RecoveryTracker.validateData() (lines 232-267), ensuring corrupted attempt files cannot propagate through the ADE pipeline.

Integrating Recovery Tracking into the ADE Pipeline

The Recovery System serves as the failure-handling backbone of the Autonomous Development Engine (ADE). According to the ADE Guide, agents invoke recovery commands through standardized terminal protocols:

• *track-attempt – Maps to the CLI start and complete commands.
• *rollback – Maps to the CLI abandon command, triggering the rollback procedure.

The Execution Engine can programmatically instantiate RecoveryTracker to record attempts without shelling out to the CLI, reducing overhead for high-frequency operations. Recovery data feeds into Epic 6 (QA Evolution) for test result correlation and Epic 7 (Memory Layer) for long-term pattern analysis.

Summary

• The Recovery System in aios-core provides automatic failure handling through JSON-backed attempt tracking, implemented in .aios-core/infrastructure/scripts/recovery-tracker.js.
• Use the RecoveryTracker class programmatically with startAttempt(), completeAttempt(), and abandonAttempt() to manage sub-task lifecycles.
• Invoke the CLI for agent integration using commands like start, complete, history, and summary.
• All attempt data is stored under docs/stories/<story-id>/recovery/subtask-<id>.json with strict schema validation via ATTEMPTS_SCHEMA.
• The system integrates with the ADE pipeline through standardized commands (*track-attempt, *rollback) and supports downstream analysis for QA Evolution and Memory Layer epics.

Frequently Asked Questions

Where is the RecoveryTracker class defined in aios-core?

The RecoveryTracker class is defined in .aios-core/infrastructure/scripts/recovery-tracker.js (lines 118-230). This file also exports the ATTEMPTS_SCHEMA constant and provides the CLI entry point, making it the single source of truth for recovery functionality in the framework.

How does the Recovery System handle automatic retries?

The Recovery System tracks each execution as a distinct attempt with an auto-incremented attemptNumber (AC7). While the core tracker does not automatically re-execute failed code, it maintains the complete history of failures under docs/stories/<story-id>/recovery/. Agents or the Execution Engine can query this history via tracker.getAttemptHistory() to decide whether to retry based on failure patterns, ensuring intelligent retry logic rather than blind repetition.

Can I use the Recovery System outside of the ADE pipeline?

Yes. While designed for the Autonomous Development Engine, the RecoveryTracker class is a standalone module with no hard dependencies on other ADE components. You can require it in any Node.js application to track arbitrary task attempts by instantiating it with a custom storyId. The CLI also functions independently, allowing integration into non-ADE automation scripts or manual developer workflows.

What file format does the Recovery System use for attempt history?

The Recovery System uses JSON files with a strict schema defined by ATTEMPTS_SCHEMA. Each sub-task receives its own file named subtask-<id>.json stored under docs/stories/<story-id>/recovery/. These files contain an array of attempt objects with properties including attemptNumber, status (enum: in-progress, completed, abandoned), startTime, endTime, approach, changes, and optional error messages.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}