taskledger

taskledger is a task-first durable state layer for staged coding work. New projects use Ledgercore's canonical .ledger/ledger.toml manifest and keep Taskledger configuration at .ledger/taskledger/config.toml. The manifest's [ledgers.taskledger] registration is authoritative; a config directory alone does not register the tool. Legacy taskledger.toml/.taskledger projects are supported only when no canonical manifest exists.

Canonical workflow

task -> plan -> approval -> implement -> validate -> done

The normal agent path is deliberately small:

actor whoami
task active | task show | task create | task activate | task follow-up
next-action | context | can
plan start -> plan guidance -> plan template -> plan check -> plan upsert -> plan lint -> plan accept
question add | question add-many | question answer | question answer-many | question status | question answers
todo next | todo show | todo done | todo status
implement start | implement resume | implement change | implement scan-changes | implement finish
validate start | validate status | validate command | validate check | validate finish
review record
handoff create | handoff show | handoff claim | handoff close

Everything else is support, human inspection, advanced transfer/storage work, repair/migration, or beta project search. Those commands remain public, but they are not part of the baseline lifecycle agents should reach for first.

The broader command surface is organized as:

Core workflow:

• task, plan, question, implement, validate, todo

Context and decision-making:

• intro, file, link, require, handoff, config

Operations and advanced overlays:

• context, pipeline, next-action, can, search, grep, symbols, deps, actor, view, usage, monitor, storage, sync, maintenance

Repair and inspection:

• lock, doctor, repair

For corrupted UUID identity or allocation state, take a backup of the canonical configuration and resolved data mount before applying a reviewed repair plan. See the backup-first recovery runbook; its Readio section is guidance only and does not imply access to that separate ledger.

Project lifecycle:

• init, status, export, import, snapshot, release

Non-goals

Taskledger is not a general project-management suite, issue tracker, CI system, release manager, or source-code intelligence platform. It is a local durable ledger for staged coding work. Optional reporting, sync, search, and worker pipeline features must not change the default task-first lifecycle unless a project explicitly opts in.

Opaque links and external artifacts

Taskledger stores task-local work state and opaque links. Cross-ledger semantics belong to an organizer such as ledgerdeck. Use taskledger link or taskledger file for references to external artifacts; taskledger does not interpret those references.

taskledger link add --url specs/behavior/features/checkout/payment.feature --label "behavior spec"
taskledger file link specs/behavior/features/checkout/payment.feature --kind doc --label "behavior spec"
taskledger validate check --criterion ac-0001 --status pass --evidence "pytest tests/test_checkout_payment.py::test_payment_flow"

Validation command failures must be classified before recording a criterion failure. A non-zero command is not automatically a failed acceptance criterion: distinguish a genuine target-behavior failure from a malformed probe or setup failure, repair the probe, and rerun it. Prefer taskledger validate command -- ... for durable command evidence, and normalize compared paths against the same explicit project root.

Which read command to use

Planning guidance profiles

Taskledger supports project-local advisory planning guidance under [prompt_profiles.planning] in the active project config file (.ledger/taskledger/config.toml). Legacy taskledger.toml and .taskledger.toml projects remain readable only for explicit migration.

[prompt_profiles.planning]
profile = "strict"
question_policy = "always_before_plan"
max_required_questions = 3
min_acceptance_criteria = 2
todo_granularity = "atomic"
require_files = true
require_test_commands = true
require_expected_outputs = true
require_validation_hints = true
plan_body_detail = "detailed"
required_question_topics = ["scope", "compatibility", "test strategy"]
extra_guidance = "Every plan must mention docs, tests, and rollback or repair behavior."

Inspect guidance for the active task:

taskledger plan guidance
taskledger --json plan guidance

This guidance is advisory and cannot override lifecycle gates, user approval, validation requirements, lock rules, or higher-priority harness instructions. See docs/usage.md for the full key reference and workflow details.

Quick config inspection/edit examples:

taskledger config list
taskledger config get prompt_profiles.planning.max_required_questions
taskledger config set prompt_profiles.planning.max_required_questions 3
taskledger config set prompt_profiles.planning.question_policy always_before_plan

Optional worker pipelines

Projects may optionally configure worker pipelines in .ledger/taskledger/config.toml to guide fresh-context handoffs. Worker pipelines are advisory overlays on the existing planning, implementation, and validation lifecycle. They can be three steps, four steps, five steps, or custom. When no worker pipeline is configured, the default taskledger behavior is unchanged.

[worker_pipeline]
enabled = true
name = "tdd-four-context"
mode = "guided"

[[worker_pipeline.steps]]
id = "planner"
lifecycle_stage = "planning"
base_context = "planner"

[[worker_pipeline.steps]]
id = "tester"
label = "Test Writer"
lifecycle_stage = "implementation"
base_context = "implementer"
actor_role = "implementer"
kind = "check"
description = "Add or update failing tests before code changes."
required_output = ["New or updated failing tests with a short summary."]
must_not = ["Do not change production code in this step."]
todo_tag = "tests"
test_command_policy = "may_fail"

[[worker_pipeline.steps]]
id = "coder"
lifecycle_stage = "implementation"
base_context = "implementer"
kind = "todo"
description = "Implement the approved change and make the tests pass."
required_output = ["Code changes plus passing targeted checks."]
must_not = ["Do not skip required validation evidence."]
todo_tag = "implementation"
test_command_policy = "must_pass"

[[worker_pipeline.steps]]
id = "reviewer"
lifecycle_stage = "review"
base_context = "code-reviewer"
kind = "review"

Supported top-level keys are enabled, name, mode, and steps. Supported step keys are id, label, lifecycle_stage, base_context, actor_role, kind, description, required_output, must_not, todo_tag, and test_command_policy. mode = "guided" does not add lifecycle gates; it adds worker-step hints to taskledger next-action, including the pending step id plus ready-to-run worker context and handoff commands.

taskledger pipeline show
taskledger pipeline next
taskledger next-action
taskledger context --worker tester
taskledger pipeline context tester
taskledger handoff create --worker tester --summary "Add failing tests only."
taskledger plan template --with-worker-pipeline --file ./plan.md

Install

python -m pip install -e .
python -m pip install -e ".[dev]"

Behavior specifications

The retained behavior corpus uses SpecMason for Gherkin identities, pytest mappings, bidirectional coverage, and reports. Install SpecMason from its project distribution, then run:

specmason check --config specmason.toml --requirements requirements/manifest.json --json
specmason discover-pytest --config specmason.toml --json
specmason coverage --config specmason.toml --requirements requirements/manifest.json --view both --show gaps --json
specmason review --config specmason.toml --requirements requirements/manifest.json --json

Taskledger does not package or import SpecMason. See specs/behavior/README.md for the mapping and intentional-waiver policy.

Shell completion

After installing taskledger, install completion for your current shell:

taskledger --install-completion

To inspect the generated completion script instead of installing it:

taskledger --show-completion

Restart your shell session after installation.

Quick start

Initialize durable state in the current workspace:

taskledger init
taskledger storage where
taskledger --root /path/to/repo init

init writes a schema-3 .ledger/ledger.toml manifest and .ledger/taskledger/config.toml. Default data is external at ../ledger; indexes are cache storage. Use storage set data user-data --scope local for a local override.

Canonical discovery is fail-closed. Once .ledger/ledger.toml is found, Taskledger never falls back to a root taskledger.toml, .taskledger.toml, or .taskledger/, including when the Taskledger registration, config, binding, or storage is missing or invalid. Read commands never initialize storage. In a canonical-unregistered project, status, usage, and doctor identify the manifest boundary and taskledger init is the next step; mutations stop before writing. If both canonical and legacy roots contain tasks, doctor reports a split-brain condition. Back up and inspect both histories before any explicit recovery; Taskledger never auto-deletes or merges them.

Create and activate a task, ask required planning questions, regenerate the plan from answers, approve it, implement todos with evidence, and validate it:

taskledger task create "Rewrite V2" --slug rewrite-v2 --description "Migrate to the task-first design."
taskledger task activate rewrite-v2 --reason "Start planning"
taskledger plan start
taskledger question add-many --required-for-plan --text $'Should exports include the new state?\nShould snapshots include implementation artifacts?'
taskledger question answer-many --text $'q-0001: Yes.\nq-0002: No.'
taskledger question status
taskledger plan template --from-answers --file ./plan.md
taskledger plan upsert --from-answers --file ./plan.md
taskledger plan review --version 1
taskledger plan lint --version 1
taskledger plan accept --version 1 --note "Ready."

taskledger next-action
taskledger --json next-action

taskledger context --for implementer --format markdown
taskledger implement start
taskledger implement checklist
taskledger implement change --path taskledger/storage/task_store.py --kind edit --summary "Normalized v2 markdown storage."
taskledger todo done todo-0001 --evidence "Updated taskledger/storage/task_store.py"
taskledger implement finish --summary "Implemented the approved plan."
taskledger review record --result pass --summary "No blocking code-quality issues."

taskledger context --for validator --format markdown
taskledger validate start
taskledger validate status
taskledger validate check --criterion ac-0001 --status pass --evidence "pytest -q tests/test_taskledger_v2_cli.py"
taskledger validate finish --result passed --summary "Validated the rewrite."

Review evidence may also be recorded after validation has moved a task to done; this appends a review record without reopening the completed task.

When a user explicitly asks an agent for a review, the agent should persist the final review with taskledger review record before answering. A chat-only review is not durable task evidence. Post-completion review records are append-only and do not reopen the task.

To revise a proposed plan, prepare and check the editable draft before submitting it. Never edit .taskledger/ files directly. Export to a distinct workspace file so an existing plan.md and local edits are preserved:

taskledger plan export --version latest --file ./plan.revision.md
# edit ./plan.revision.md
taskledger plan check --file ./plan.revision.md
taskledger plan upsert --auto-revise --file ./plan.revision.md
taskledger plan diff --from 1 --to 2
taskledger plan review --version 2

If you already have an edited ./plan.md, check and submit it directly:

taskledger plan check --file ./plan.md
taskledger plan upsert --auto-revise --file ./plan.md

Auto-revision proposes a new version; it does not approve it. Continue only after explicit user approval.

For manually completed work (e.g., manual testing, operations tasks, or work completed outside the task-first lifecycle), use task record to create a done task directly without acquiring lifecycle locks. Note: task record does not replace the normal task lifecycle; it is for recording work already completed, not as a shortcut for active task management.

taskledger task record "Deploy to production" --summary "Deployed v0.4.1 to prod" --change "infra/deploy.sh:run:Updated prod config" --evidence "Monitoring shows no errors"
taskledger task record "Manual API testing" --summary "Tested new endpoints" --allow-empty-record --reason "Exploratory testing, no formal changes tracked"

Archive is a visibility operation: it hides tasks from default list/tree/dashboard views without deleting history. Task ids stay monotonic and are never reused. Slugs can be reused after archive.

taskledger task archive task-0030 --reason "Hide historical task"
taskledger task list --archived
taskledger task unarchive task-0030 --reason "Need to continue work" --slug task-0030-reopened
taskledger tree --include-archived

If validation finds an implementation bug, keep the accepted plan and restart implementation explicitly:

taskledger validate finish --result failed --summary "Parser edge case still fails."
taskledger next-action
taskledger context --for implementer --format markdown
taskledger implement restart --summary "Fix failed validation findings."

Release boundary tags

Release commands are advanced human/project operations, not part of the normal task -> plan -> approval -> implement -> validate -> done agent path.

Use taskledger only to record the task boundary for a release:

taskledger release tag 0.4.1 --at-task task-0030 --note "0.4.1 released"
taskledger release list
taskledger release show 0.4.1

Taskledger does not manage changelog entries or edit docs/changelog.md. When you need release notes, changelog entries, or docs/changelog.md updates, use the separate releaseledger tool, which owns changelog entries, changelog context rendering, and docs/changelog.md builds. The ledgers stay isolated; load both skills when cross-ledger release notes are needed.

taskledger next-action is the preferred fresh-context entrypoint. It stays read-only and points at the next concrete question, todo, criterion, or repair step.

Human output example:

todo-work: Implementation is in progress; 1 todos remain.
Next todo: todo-0001 -- Update next-action JSON payload.
Command: taskledger todo show todo-0001
Mark todo done after evidence exists: taskledger todo done todo-0001 --evidence "..."
Progress: 0/1 todos done

JSON result example:

{
  "kind": "task_next_action",
  "action": "todo-work",
  "next_command": "taskledger todo show todo-0001",
  "next_item": {
    "kind": "todo",
    "id": "todo-0001",
    "text": "Update next-action JSON payload.",
    "validation_hint": "Run: pytest tests/test_todo_implementation_gate.py -q; Expected: pass",
    "done_command_hint": "taskledger todo done todo-0001 --evidence \"...\""
  },
  "commands": [
    {
      "kind": "inspect",
      "label": "Show next todo",
      "command": "taskledger todo show todo-0001",
      "primary": true
    },
    {
      "kind": "complete",
      "label": "Mark todo done after evidence exists",
      "command": "taskledger todo done todo-0001 --evidence \"...\"",
      "primary": false
    }
  ],
  "progress": {
    "todos": {
      "total": 1,
      "done": 0,
      "open": 1,
      "open_ids": ["todo-0001"]
    }
  },
  "blocking": []
}

Compact implementation loop

For routine same-session implementation, prefer next-action and the single next todo over broad generated context:

taskledger --json next-action
taskledger --json todo next
taskledger todo show todo-0003
# implement only that todo
pytest tests/...
taskledger todo done todo-0003 --evidence "pytest tests/... passed"
taskledger --json next-action

Rules for agents:

• Prefer next-action and todo next over generated context during normal work.
• Use the todo validation_hint before marking a todo done.
• Record concise evidence with todo done.
• Do not create handoffs or context bundles unless the user asked to switch harness or session.

Fresh-session startup and human monitoring

Use taskledger usage as the compact fresh-session startup command for agents and taskledger monitor as the lightweight human terminal dashboard.

taskledger usage
taskledger --json usage
taskledger usage -q
taskledger usage --task task-0040

taskledger monitor --once
taskledger monitor --refresh-seconds 2
taskledger monitor --task task-0040

monitor is dependency-free, read-only, and suitable for narrow terminals such as Termux. Agents should keep using next-action, todo next, and --json for routine automation; monitor is the human observation surface.

File links can now capture a baseline snapshot and later report drift:

taskledger file link task-0040 src/foo.py --kind code --snapshot
taskledger file status task-0040
taskledger file refresh task-0040 src/foo.py --reason "Rebaseline after accepted implementation"

Agents should keep using taskledger next-action, taskledger todo next, and --json commands as the canonical automation interface for routine same-session work. Reach for context or handoffs when the task actually needs a broader fresh-context transfer.

Legacy storage layout

Legacy branch-scoped layout (migration only)

The following layout applies only to legacy projects without a canonical .ledger/ledger.toml manifest. New projects use the canonical Ledgercore layout described below. In legacy projects, checked-in taskledger.toml stores project identity plus the current branch-scoped ledger pointer and next task number. Operational task state remains ignored under .taskledger/ledgers/<ledger_ref>/:

taskledger.toml
.taskledger/
  storage.yaml
  ledgers/
    main/
      intros/
      releases/
      tasks/
      events/
      indexes/   # optional derived caches and registries

For canonical projects, use taskledger storage where to inspect the resolved Ledgercore data and index mounts. The canonical config path is always .ledger/taskledger/config.toml; it is inactive until the manifest registers Taskledger.

Markdown files are canonical. Task, plan, and run listings scan only the current ledger by default. JSON files under the current ledger's indexes/ directory are optional derived caches or registries and are not required for task correctness.

Branch-scoped ledgers

.taskledger/ stays ignored and local. taskledger.toml is safe to commit and contains the current ledger_ref, optional parent ref, and the next logical task number for the checked-out source branch.

When starting long-lived branch-local work, fork the ledger pointer after creating the Git branch:

git checkout -b feature-a
taskledger ledger fork feature-a
git add taskledger.toml

Returning to a branch whose taskledger.toml points back to main hides the feature branch's active task and task list. Two ledgers may both contain a logical task-0030; this is expected because task IDs are scoped by ledger_ref. Use taskledger ledger adopt --from REF TASK_REF when branch-local task history should be copied into the current ledger.

Canonical Taskledger storage uses the schema-3 Ledgercore mounts:

taskledger init
taskledger storage where
taskledger storage path data
taskledger storage path indexes

For a project UUID `PROJECT_UUID`, default data is stored at:

```text
../ledger/taskledger/PROJECT_UUID/data

The cache path is checkout-specific and ends in /indexes. Legacy projects are migrated explicitly with taskledger migrate status, taskledger migrate plan, and taskledger migrate apply.

Migration discovery is independent of the current manifest registrations. When a canonical .ledger/ledger.toml already contains another ledger, Taskledger adopts its project UUID and records the legacy UUID as the source identity. Use the same options for inspection and apply when recovery needs an explicit source:

taskledger migrate plan --sibling-ledger-root ../ledger
taskledger migrate plan --sibling-ledger-root ../ledger --source-data-root ../ledger/taskledger/LEGACY_UUID/data
taskledger migrate apply --sibling-ledger-root ../ledger

The migration creates automatic backups, preserves other ledger registrations, and leaves the legacy source in place. It refuses split-brain or foreign-bound targets. Do not manually create bindings or copy task directories. --create-sibling-store only initializes the sibling root marker.

Keep one active writer at a time. Before starting on a PC, inspect the shared
store with `taskledger doctor` and `taskledger next-action`.

Helpful local commands:

```bash
taskledger storage where
taskledger sync preflight
taskledger sync status
taskledger sync commit --message "Sync project-a taskledger state"
taskledger export --output ./taskledger-transfer.tar.gz
taskledger import ./taskledger-transfer.tar.gz --dry-run
taskledger sync git init --repo ../taskledger-state --project-path project-a
taskledger sync git status
taskledger sync git pull
taskledger sync git push
taskledger sync git push --message "Sync project-a taskledger state"

See docs/sync.md for the full second-PC bootstrap, daily sync protocol, and Syncthing/rclone caveats.

JSON output

Use --json for machine-readable payloads:

taskledger --json info
taskledger --json task active
taskledger --json task show
taskledger --json task show task-0001
taskledger --json context --for validator --format json

Example status payload:

{
  "ok": true,
  "command": "info",
  "result": {
    "kind": "taskledger_status",
    "workspace_root": "/home/me/src/project-a",
    "config_path": "/home/me/src/project-a/.ledger/taskledger/config.toml",
    "taskledger_dir": "/home/me/src/project-a/.ledger/taskledger",
    "project_dir": "/home/me/src/project-a/.ledger/taskledger",
    "counts": {
      "tasks": 1,
      "introductions": 0,
      "plans": 1,
      "questions": 1,
      "runs": 2,
      "changes": 1,
      "locks": 0
    },
    "active_task": null,
    "healthy": true
  },
  "events": []
}

Action/event logging

Action/event logging is enabled by default. Taskledger writes immutable TaskEvent records for lifecycle mutations (task create, implementation start, todo completion, validation checks, etc.) so taskledger monitor shows recent activity without extra configuration.

To disable new action events, set in .ledger/taskledger/config.toml:

[event_logging]
enabled = false

Existing event files remain readable regardless of the setting. taskledger task events continues to work when logging is disabled.

Action/event logging is separate from agent command transcript logging, which remains disabled by default (see [agent_logging]).

Handoff-driven work

Fresh-context handoff is a primary feature:

taskledger context --for planner --format markdown
taskledger context --for implementer --format markdown
taskledger context --for validator --format json
taskledger task report --task task-0030 -o task30.md
taskledger task export task-0030 -o task-0030.llm.md
taskledger usage --task task-0030
taskledger handoff create --mode implementation --intended-actor agent --intended-harness codex
taskledger handoff claim handoff-0001
taskledger handoff close handoff-0001 --reason "Implementation started."

task dossier and root view remain advanced read surfaces. Prefer context --for planner|implementer|validator and handoff show for agent continuation.

Independent cross-harness review handoffs

Use a review handoff when another harness should inspect an implementation without taking its lock:

taskledger handoff review --run run-0002 --kind code --intended-harness pi --summary "Independent review before implementation continues."
taskledger handoff claim handoff-0004
taskledger handoff show handoff-0004 --format markdown
taskledger review record --handoff handoff-0004 --result pass --summary-file REVIEW.md
taskledger handoff close handoff-0004 --reason "Review recorded."

Review handoffs are run-scoped and read-only with respect to implementation. The implementation lock remains with its owner; reviewers must not run implement resume, mark implementation todos done, or transfer/break that lock merely to review. If a reviewer is interrupted, the claiming session can release the handoff for another reviewer:

taskledger handoff release handoff-0004 --reason "Reviewer session interrupted."
taskledger handoff retarget handoff-0004 --intended-harness codex --reason "Reviewer harness changed."

Persisted actor/harness identity is used by handoff boundaries. Pi sessions are auto-detected when PI_VERSION/PI_SESSION_ID are available, while incompatible stale stored harness state does not override a detectable live harness.

Fresh-worker contexts

Use focused contexts when handing one todo or one review run to a fresh worker:

taskledger context --for implementer --todo todo-0003
taskledger context --for spec-reviewer --run run-0008
taskledger context --for code-reviewer --run run-0008
taskledger handoff create --mode implementation --todo todo-0003
taskledger handoff show handoff-0001 --format markdown

handoff create now stores the generated Markdown context snapshot in the handoff record so another harness can continue from the exact same input.

Multi-Actor Handoff Protocol

The handoff protocol enables safe work transitions between human and agent actors across different harnesses:

Features

• Actor Identity: Track WHO performs each stage (human, agent, system)
• Harness Tracking: Record FROM WHERE each stage ran (manual, Codex, OpenCode, etc.)
• Handoff Records: Explicitly hand off work with context and intent
• Claim Protocol: New actors claim handoffs before starting work
• Lock Management: Transfer or release locks during handoffs
• Event Trail: Full audit trail recording all state changes
• Durable Records: Markdown-first storage with YAML metadata

Quick Start

# See your current identity
$ taskledger actor whoami

# Create a handoff
$ taskledger handoff create --task task-0001 --mode implementation --todo todo-0003

# Claim it
$ taskledger handoff claim handoff-0001 --task task-0001

# Show details
$ taskledger handoff show handoff-0001 --task task-0001 --format text

# Close when done
$ taskledger handoff close handoff-0001 --task task-0001 --reason "Continued."

See docs/usage.md and skills/taskledger/SKILL.md for task-first handoff guidance.

Export, import, and snapshots

taskledger init --project-name "Taskledger"
taskledger export
taskledger export --task task-0040
taskledger export task-0040
taskledger import ./taskledger-transfer.tar.gz --dry-run
taskledger import ./taskledger-task-planledger-main-task-0040-20260509T101500Z.tar.gz
taskledger import ./taskledger-transfer.tar.gz --replace
taskledger snapshot ./artifacts

When no explicit output path is passed, default export archives are written inside the resolved workspace root with this filename policy:

taskledger-export-{project_slug}-{ledger_ref}-{timestamp}.tar.gz
taskledger-task-{project_slug}-{ledger_ref}-{task_id}-{timestamp}.tar.gz

project_slug is derived from project_name in .ledger/taskledger/config.toml. If project_name is missing, taskledger falls back to the workspace directory name. Import safety still relies on project_uuid, not the name/slug.

--include-bodies and --include-run-artifacts now change archive content:

• --no-include-bodies strips record body text (body / context_body) from exported payloads.
• --include-run-artifacts embeds task and agent-log artifact files under artifacts/ in the archive.

Artifact file-size policy

Taskledger-owned artifact files are bounded to prevent command output from creating very large ledger blobs. The default and hard ceiling is 20,000,000 bytes per artifact; configure a lower artifact_max_bytes value when needed. Oversized command evidence keeps a UTF-8-safe head and tail with an explicit truncation marker, while command execution and exit-code semantics remain unchanged.

Archive import/export applies the same policy, and taskledger doctor reports legacy oversized artifacts without reading their contents. taskledger sync git push performs a preflight before committing or pushing. Taskledger does not use Git LFS or rewrite Git history; repair existing blobs separately.

Cross-machine imports preserve durable task/run data, but imported runtime locks are quarantined by default. After importing an in-progress implementation, run:

taskledger next-action
taskledger implement resume --reason "Continue imported implementation."

Use --lock-policy keep only for diagnostic full-fidelity lock restoration.

Single-task transfer from a config-only checkout:

# fresh checkout on another PC
taskledger init
taskledger task create "Fix import edge case" --slug fix-import-edge-case --description "..."
# ... normal plan / implementation / validation lifecycle ...
taskledger export task-0040

# main dev repo
taskledger import ./taskledger-task-planledger-main-task-0040-20260509T101500Z.tar.gz
taskledger task list
taskledger task show task-0040

Skill packaging

Agent workflows work best when the taskledger skill is installed in the coding harness. The CLI has a task-first lifecycle with explicit planning, approval, implementation, validation, locks, and handoff gates; without the skill, an agent may not know the intended command sequence or gate semantics.

The canonical skill file lives at:

skills/taskledger/SKILL.md

Keep this skill outside the Python package. No additional skills/taskledger/examples/ directory is required.

Development

python -m pytest -m "not slow"
python -m pytest -m "not slow" -n auto
python -m pytest -n auto
python -m pytest
ruff check .

Full release-readiness sweep:

make release-check

Task-centered traceability

Taskledger owns temporal work truth: tasks, plans, acceptance criteria, implementation changes, validation checks, reviews, locks, and handoffs. Cross-ledger links are opaque file or ID references.

Local IDs remain the stored identity. Global refs are derived as <ledger.code>:<local_id>.

Examples:

• task-0001 -> tl:task-0001
• todo-0001 -> tl:todo-0001
• ac-0001 -> tl:ac-0001

File-safe aliases:

• tl-task-0001
• tl-todo-0001
• tl-ac-0001

Do not store global_id in task records. Uppercase/file-safe forms may be accepted as aliases, but canonical output is lowercase colon refs.

Run taskledger trace TASK --format json for a read-only taskledger.trace.v1 bundle that links task history, accepted AC IDs, opaque link refs, source refs, evidence refs, reviews, and handoffs.

Canonical Ledger layout

New projects use a schema-3 Ledgercore manifest. Taskledger configuration is stored at .ledger/taskledger/config.toml. The mounts are durable data (external ../ledger by default), checkout-local runtime (user-data), diagnostic logs (user-data), and rebuildable indexes (cache). A machine-local .ledger/ledger.local.toml may select user-data for data; use taskledger storage where, taskledger storage set, and taskledger storage clear-override for storage operations. Legacy .taskledger/ projects remain readable only for explicit migration. Canonical task bundles live under <data-root>/ledgers/<ledger_ref>/tasks/<uuidv7>/; UUIDv7 is the stable storage and relationship identity, while task-#### remains the derived CLI/display alias and is not a directory name. Layout-5 bundles migrate deterministically and recoverably to layout 6 before the first mutation; read-only commands do not migrate.