Repairledger

Structured, versioned repair observations for agent-discovered tool failures.

Repairledger is a Python CLI that lets coding agents log durable repair observations during primary tasks, then hand off an aggregate Markdown report to a human maintainer.

Product contract

• Repairledger stores repair observations only.
• Each observation is a structured record with modular Markdown components, version snapshots, and rendered artifacts.
• Observations are stored locally, versioned after every mutation, and exportable as standalone Markdown files or an aggregate report.
• Repairledger does not replace issue trackers, test runners, task ledgers, or source code fixes.

Installation

pip install repairledger

Or from source:

git clone https://github.com/holgern/repairledger.git
cd repairledger
pip install -e .

Quick start for agents

# Check workspace status
repairledger --json status

# Initialize a workspace
repairledger init

# Log an observation
repairledger log \
  --title "Tool rejects valid input" \
  --target-tool mytool \
  --kind validation_false_positive \
  --severity high \
  --summary "Mytool rejected a valid config file." \
  --context "The agent was configuring mytool." \
  --tool-call "mytool validate config.yaml" \
  --expected "Config should pass validation." \
  --actual "Config was rejected with a confusing error." \
  --reproduction "1. Run mytool validate on config.yaml. 2. Observe rejection." \
  --impact "Blocks agent workflow." \
  --suggested-fix "Make the validation field-aware." \
  --status observed

# Build rendered artifacts
repairledger repair build

# Export aggregate report
repairledger report export

Example: Taskledger lint false positive

repairledger --json status
repairledger init

repairledger log \
  --title "Taskledger plan lint rejects 'later' in quoted context" \
  --target-tool taskledger \
  --kind validation_false_positive \
  --severity high \
  --summary "Taskledger rejected a plan because it contained the word 'later' in contextual prose." \
  --context "The agent was entering a plan via the Taskledger skill." \
  --tool-call "taskledger plan set --stdin" \
  --expected "The lint should reject vague scheduling terms only in actionable timing fields." \
  --actual "The lint rejected the full plan because 'later' appeared in unrelated context." \
  --reproduction "1. Submit a plan containing 'later' in a quoted example.\n2. Run plan lint.\n3. Observe rejection." \
  --impact "The agent could not store a valid implementation plan without rewriting harmless context." \
  --suggested-fix "Make the banned-term lint field-aware or ignore quoted/context sections." \
  --status observed

repairledger repair build
repairledger report export

CLI command surface

repairledger [--root PATH] [--cwd PATH] [--json] [--version] COMMAND

  init                          Initialize a workspace
  status                        Show workspace status
  info                          Show workspace or repair info
  doctor                        Run workspace diagnostics
  next-action [REPAIR_ID]       Show next recommended action
  log                           Convenience repair logging

  repair activate REPAIR_ID     Set active repair
  repair list                   List repairs
  repair show [REPAIR_ID]       Show a repair
  repair status [REPAIR_ID]     Change repair status
  repair archive [REPAIR_ID]    Archive a repair
  repair build [REPAIR_ID]      Build rendered artifacts
  repair export [REPAIR_ID]     Export repair Markdown
  repair validate [REPAIR_ID]   Validate a repair
  repair versions [REPAIR_ID]   List versions
  repair diff [REPAIR_ID]       Diff two versions
  repair apply --file PATH      Apply structured JSON bundle

  repair component list         List components
  repair component show KEY     Show a component
  repair component set KEY      Set a component
  repair component append KEY   Append to a component

  report build                  Build aggregate report (to storage)
  report export                 Export aggregate report (to workspace root)

Structured bundle examples

Create a repair with a JSON bundle:

cat <<'JSON' | repairledger repair apply --file -
{
  "schema": "repairledger.structured_repair.v1",
  "operation": "create",
  "repair": {
    "title": "Example tool failure",
    "target_tool": "example",
    "kind": "tool_failure",
    "severity": "medium",
    "status": "observed",
    "components": {
      "summary": "Example summary.",
      "context": "Example context.",
      "tool_call": "example command",
      "expected_behavior": "Expected result.",
      "actual_behavior": "Actual result.",
      "reproduction": "1. Step one.\n2. Step two.",
      "impact": "This matters because...",
      "suggested_fix": "Add validation."
    }
  }
}
JSON

Update a repair:

cat <<'JSON' | repairledger repair apply --file -
{
  "schema": "repairledger.structured_repair.v1",
  "operation": "update",
  "repair_id": "rl:repair-0001",
  "reason": "Added diagnosis",
  "components": {
    "diagnosis": "Root cause hypothesis."
  }
}
JSON

Report export workflow

repairledger report export
# Writes WORKSPACE_ROOT/repairledger-report.md

repairledger report export --target-tool taskledger
# Filters by tool

Storage layout

<workspace root>/
  repairledger.toml
  .repairledger/
    storage.yaml
    repairs/
      repair-0001/
        repair.yaml
        components/
          00-summary.md
          10-context.md
          ...
        rendered/
          latest.md
          repair-0001-v0003.md
        versions/
          v0001/
          v0002/
          ...
    reports/
      repairledger-report.md

Dynamic versioning

Version is derived from Git tags via setuptools_scm. The _version.py file is auto-generated.

• Tag a commit: git tag v0.1.0
• Build: python -m build --sdist --wheel

Repository layout

repairledger/
  repairledger/        Python package (shipped in wheel)
  tests/               Test suite
  skills/              Agent skill files (repository-only, not in wheel)
  docs/                Documentation
  examples/            Usage examples

The skills/repairledger/ directory contains coding-agent skill documentation. These files are available from the Git repository but are not included in PyPI wheel distributions. CLIs and editors that consume agent skills should source them from the repository.

Development commands

python -m pytest -q
python -m ruff check .
python -m mypy repairledger
python -m build --sdist --wheel
python -m twine check dist/*

License

Apache 2.0