/ledger-tasks-yylo

name: ledger-tasks-yylo
description: Retrieve any YYLO Ledger Record by ID, discover PDRs and artifacts, and manage tasks and dependencies. Use for unknown record types, universal get/search, task operations, and source-of-truth boundaries.
argument-hint: "[command or workflow question]"
enable-shell-directives: true

YYLO Ledger CLI Reference

Use `yy ledger` from the controller, or `yylo-ledger` standalone. Ledger exposes compatible flat task commands and native ID-first `record|task|wiki|pdr|workflow|artifact` groups, subject to installed help. `yy kanban` is a labelled compatibility alias for the same controller-routed runtime.

Retrieve any Record first

Preflight `yy ledger get --help`. When it advertises universal retrieval, use `yy ledger get RECORD_ID -f json` for tasks, documents, PDRs and artifacts without knowing the type. If installed get is task-only, use `yy ledger record get RECORD_ID -f json` after checking native help; if absent, stop for an upgrade. Do not try each type until one works.

New generated IDs use `task_`, `doc_`, or `artifact_` for storage kind only; existing IDs remain unchanged. New PDRs are artifact/report, while historical document/pdr Records remain readable through the same command. Exact reads include hot and archived Records in the selected project. When no ID is known, start with `yy ledger record search --projection summary --limit 20 -f json`; use explicit `--scope archive|all` for cold discovery.

Read [references/retrieval.md](references/retrieval.md) for bounded content, `--content` byte retrieval, PDR examples, compatibility and refusal handling. Small readable non-task payloads are included by default; Record metadata alone is not proof that payload bytes were retrieved. Typed commands remain for mutation and specialized rendering/validation.

Supported task contract

• Preflight installed `yy ledger --version` and `yy ledger --help`; command help is authoritative for the selected runtime.
• Use universal get for reads, flat task commands for task bookkeeping, and the controller's `yy task` lifecycle for managed delivery. Use dedicated wiki, workflow, and artifact skills for typed mutations rather than guessing arguments.
• New operational PDRs, contracts, plans, reports, receipts, and evidence belong in typed Artifact Records, not product documentation, task bodies/responses, or new `.juno_task/specs` files.
• If a required native group is absent, fail closed and request a Ledger upgrade. Never invoke mutable source directly or write Ledger store files by hand.
• Read current task state before mutation, preserve mutation receipts where offered, and never bypass controller routing or lifecycle state with direct file edits.
• Normal discovery is hot-only unless an explicit cold-archive command is used.

Opt-in cross-project routing

Cross-project access is disabled by default. The source `.juno_task/config.json` must set `kanbanRegistry.enabled: true` and explicitly list `allowedProjects`; environment overrides are `YYLO_LEDGER_REGISTRY_ENABLED` and `YYLO_LEDGER_REGISTRY_ALLOWED_PROJECTS`. Register with `yy ledger project add ALIAS --path /absolute/project`, then route any command with `--project ALIAS`. The destination wrapper/runtime remains authoritative, and routing failures never fall back to the source board.

Legacy Task compatibility commands

**CREATE** — Add a new task

yy ledger create "Task description here" --status backlog --tags feature,backend

Options: `--status` (backlog|todo|in_progress|done), `--tags` (comma/space-separated), `--blocked-by` (task IDs), `--related-tasks` (task IDs)

**LIST** — Browse tasks with summary stats

yy ledger list --limit 5 --sort asc
yy ledger list --status todo --sort asc
yy ledger list --status todo,in_progress --limit 10

**SEARCH** — Find tasks by criteria

yy ledger search --status todo --tag backend --limit 10
yy ledger search --body "OAuth" --open
yy ledger search --commit abc123

Filters: `--status`, `--tag`, `--body`, `--response`, `--commit`, `--open` (no agent_response), `--recent`, `--exclude` (exclude tags)

**GET** — Universal Record read; task details retain dependency and related-task compatibility

yy ledger get TASK_ID

**MARK** — Update status with required response message

yy ledger mark in_progress --id TASK_ID --response "Starting work on this"
yy ledger mark done --id TASK_ID --response "Completed: implemented X, tested Y" --commit abc123def
yy ledger mark todo --id TASK_ID --response "Reopening: found regression"

Required: `--id` and `--response`. Optional: `--commit` (recommended for done).

**UPDATE** — Modify task fields

yy ledger update TASK_ID --status todo --tags backend,urgent
yy ledger update TASK_ID --commit abc123def
yy ledger update TASK_ID --response "Additional context"

**ARCHIVE** — Soft delete (preserves data, sets status to archive)

yy ledger archive TASK_ID

Immutable cold archive packs

Normal `list`, `search`, `ready`, and `order` are deliberately hot-only. Exact `get TASK_ID` transparently resolves a hot task or a read-only archived task; use `history TASK_ID` explicitly for its ledger. Discover cold tasks only with bounded, projected `archive-search` output:

yy ledger archive-search --tag backend --before 2026-01-01 --limit 20 --projection metadata

Before archive maintenance, preflight the installed version/help and obtain explicit owner authorization. The repository and index must be clean, and reports must be durable new paths outside the repository:

yy ledger --version
yy ledger archive-pack plan --status done,archive --older-than 90d --max-tasks 1000 --target-bytes 26214400 --hard-max-bytes 47185920 --report /external/receipts/archive-plan.json
# Independently inspect selected IDs, revisions, source HEAD, policy, and plan hash.
yy ledger archive-pack create --plan /external/receipts/archive-plan.json --report /extern