Metadata-Version: 2.4
Name: repairledger
Version: 0.1.0
Summary: Durable repair-observation ledger and CLI for agent-discovered tool failures
Author: Repairledger Contributors
Maintainer: Holger Nahrstaedt
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/holgern/repairledger
Project-URL: Repository, https://github.com/holgern/repairledger
Project-URL: Issues, https://github.com/holgern/repairledger/issues
Project-URL: Changelog, https://github.com/holgern/repairledger/releases
Keywords: cli,developer-tools,llm-agents,repair,observability,workflows
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer
Requires-Dist: ledgercore>=0.2.0
Requires-Dist: PyYAML
Requires-Dist: tomli; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-xdist; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: types-PyYAML; extra == "dev"
Requires-Dist: sphinx; extra == "dev"
Requires-Dist: myst-parser; extra == "dev"
Requires-Dist: sphinx-rtd-theme; extra == "dev"
Dynamic: license-file

# 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

```bash
pip install repairledger
```

Or from source:

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

## Quick start for agents

```bash
# 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

```bash
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:

```bash
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:

```bash
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

```bash
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

```bash
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
