task-ledger

# task-ledger

Turn long-running tasks into durable task objects with checkpoints, recovery verification, rollback metadata, task relations, readiness-aware scheduling, short-first reporting, and resumable execution instead of fragile chat context.

## Trigger

Use this skill when any of these are true:

- task runtime will likely exceed 5 minutes
- task has more than 3 stages
- task uses background `exec`
- task uses `sessions_spawn`
- task uses `cron`
- task has external side effects
- task involves restart / deploy / maintenance workflows with risky side effects
- task should be split into parent/child tasks or tracked with dependencies
- task readiness should be checked before starting downstream work
- task reporting should prefer short updates backed by long file-based reports
- the user wants the work to be recoverable / resumable / auditable

## What this skill provides

This package includes a task ledger toolkit with:

- task checkpoint JSON files in `tasks/`
- execution logs in `logs/`
- outputs/artifacts in `outputs/`
- lifecycle helpers for create/update/advance/close
- recovery helpers for verify/resume-summary
- binding helpers for process/subtask/cron references
- rollback metadata in the task schema
- parent/child task relations and dependency-aware tooling
- readiness-aware scheduling helpers
- specialized templates for restart and deployment workflows
- human-friendly export for reports, handoff, archival, and graph views
- short-first reporting with optional file-backed long reports

Bundled files live next to this skill under `toolkit/`.

## First-use bootstrap

If the current workspace does not already contain the toolkit, copy these bundled assets into the workspace root:

- `toolkit/scripts/*` → `<workspace>/scripts/`
- `toolkit/task-templates/*` → `<workspace>/task-templates/`
- `toolkit/tasks/README.md` → `<workspace>/tasks/README.md`

Always create the runtime directories if missing:

- `tasks/`
- `logs/`
- `outputs/`

Do **not** overwrite...

# Task Ledger

Persistent long-running task management, checkpoint, recovery, rollback-aware, relation-aware, scheduling-aware, and reporting-aware toolkit for OpenClaw.

## Why

OpenClaw gives you strong execution primitives (`exec`, `process`, `sessions_spawn`, `cron`), but long tasks still need a durable userland protocol:

- a task object
- explicit stages
- a log path
- an output directory
- execution references
- recovery rules
- rollback metadata
- final reporting rules

This skill packages that protocol.

## What changed in 0.2.3

- reporting schema support for `short-first`, `normal`, and `detailed` modes
- short-format task export for chat-friendly updates
- file-backed long report output to `outputs/<taskId>/report.md`
- exported long report path stored in task state
- published skill package synced to include reporting-aware workflow support

## Includes

- `SKILL.md` — agent-facing operating instructions
- `toolkit/scripts/` — helper scripts for task lifecycle, recovery, control-plane relations, scheduling, migration, export, and reporting
- `toolkit/task-templates/` — generic template, specialized examples, schema, and recovery notes
- `toolkit/tasks/README.md` — runtime directory guide
- `CHANGELOG.md` — tracked version history

## Runtime layout

When installed into a workspace, the toolkit expects:

- `tasks/`
- `logs/`
- `outputs/`
- `scripts/`
- `task-templates/`

## Typical flow

1. Confirm plan with the user
2. Create checkpoint skeleton first
3. Execute stage-by-stage
4. Update task state after each stage
5. Recover by reading resume summary and checking reality first
6. Correct stale checkpoint state if needed
7. Use parent/child relations and dependencies for larger task programs
8. Use readiness checks or start-if-ready automation before starting dependent tasks
9. Prefer short user-facing updates and keep long reports on file when appropriate
10. Report completion or recovery proactively

## Example use cases

- safe OpenClaw gateway restar...