bob task¶

Vault-wide task maintenance: archive, move, reconcile, reroll

Every `bob task` command rewrites task lines across the whole vault.

Usage: bob task <COMMAND>

Commands:
  archive    Move done and canceled tasks into done/ archives and repair links
  move       Move open tasks between notes and repair vault links
  reconcile  Reconcile task statuses from the Pomodoro ledger and dependencies
  reroll     Re-roll due prioritized tasks within their priority windows

Options:
  -h, --help  Print help

Examples:
  bob task archive               Archive done and canceled tasks
  bob task move --dry-run        Preview moving tasks and repairing links
  bob task reconcile --dry-run   Preview task status reconciliation
  bob task reroll --dry-run      Preview re-rolling due prioritized tasks

See also: bob plan, bob ready, bob freshness, bob projects, bob query
Run 'bob task <command> --help' for more information on a command.

usage: bob task archive [-t|--threshold N]

Move done and canceled Bob task blocks into archive notes, link sources,
repair archive metadata, and repair Obsidian links to moved block ids.

example:
  bob task archive --threshold 10

options:
  -h, --help       show this help message and exit
  -t, --threshold N
                   minimum completed/canceled task count per source note (default: 10)

Move selected open task blocks to another eligible note, preserving task state while repairing block links and dependency identities throughout the vault.

A live run holds the shared maintenance lock, syncs before and after the move, and commits exactly the changed Markdown files. Use --dry-run to inspect the same plan without locking, syncing, probing Git, or writing. Use --offline to skip both sync cycles while keeping the lock and scoped local commit.

Usage: bob task move [OPTIONS] <--block <ID>|--match <TEXT>> <SOURCE> <DEST>

Arguments:
  <SOURCE>
          Source note stem or vault-relative path

  <DEST>
          Destination note stem or vault-relative path

Options:
  -b, --block <ID>
          Select a task by trailing block id without ^; repeatable

  -d, --dry-run
          Plan and print only; do not lock, sync, probe Git, or write

  -f, --format <FORMAT>
          Output format: human or json

          [default: human]
          [possible values: human, json]

  -h, --help
          Show help

  -m, --match <TEXT>
          Select the task whose line contains this literal text; repeatable

  -o, --offline
          Skip both sync cycles; commit locally without pushing

  -r, --retry-timeout <SECONDS>
          Lock wait and re-plan budget after concurrent edits; 0 fails fast

          [default: 60]

Examples:
  bob task move --dry-run old-note new-note -b work-item
                                 Preview a move selected by block id
  bob task move old-note new-note -m 'Prepare release'
                                 Move a task selected by literal line text
  bob task move -d -f json old-note new-note -b work-item
                                 Print a machine-readable preview

Run 'bob task reconcile' after a move when the report says
reconciliation is pending.

Make the current Pomodoro ledger the source of truth for active task statuses and use the latest existing earlier daily note as a read-only recent-activity source.

Tasks block-linked from child bullets of open Pomodoro entries have a minimum desired status of Next [*]; tasks already In Progress [/] keep that stronger status. Dependency tasks are discovered recursively from Depends-On line links plus R8 legacy dependency children (see docs/task-dependencies.md) and inherit the strongest effective parent status, promoting Ready [ ] tasks to Next or In Progress and Next tasks to In Progress. Depends-On lines are reconciled into [dependsOn::] / [id::] fields first (R1-R10: project, adopt, heal, canonicalize, warn), and human and JSON reports include the dependency projection counts. Status propagation never lowers a task, and removing a link never changes a lane: unlinked Next [*] and In Progress [/] tasks stay as they are. Only a daily-note Next task still clears: a [*] that lives in a canonical daily note or the selected current ledger and is not reachable from an open entry is reset to [ ], unless it is directly referenced by recent activity, in which case it is kept. Historical links supply recovery-only rank for Blocked tasks without promoting Ready tasks; a recovered directly referenced Next task stays Next while it remains recent, and the historical note is never modified. Tasks whose Dataview [dependsOn:: ...] metadata names an open vault-wide [id:: ...] task, or whose task-level [scheduled:: YYYY-MM-DD] date is later than the effective daily anchor, are marked Blocked [?], overriding Ready, Next, and In Progress. A schedule on the anchor date or earlier is not future. When every derived blocking reason clears, Blocked tasks recover to Next when directly recent, In Progress only through a stronger eligible transclusion path, or Ready when unreachable. No pre-Blocked status is stored. Blocking starts from an open project's `^prj` Depends-On line and inline schedule, and cascades through project `parent:` links. Descendant `^prj` tasks inherit ancestor reasons and carry `#prj_is_blocked`; every open resident of a blocked project carries the same tag, and every automatic Blocked-to-Ready recovery writes `[unblocked::]` (see docs/task-dependencies.md §13). Completed linked-task references are retired as struck, non-embedded links. References found under open Pomodoros keep the existing policy of moving their containing bullets beneath the current timed Pomodoro, or the last completed Pomodoro when there is no current one. A link to an unambiguously cancelled Tasks task removes its complete Markdown list-item subtree from an open Pomodoro, including for custom single-character statuses whose Tasks type is CANCELLED; the cancelled task status itself is left unchanged. A live Task Link to an effectively Blocked task under today's open Pomodoros is consumed: it seeds promotion along the task's dependency edges, then the link is removed (a link-only bullet with its subtree; otherwise only the token). After duplicate, canceled, blocked-link consumption, completed-reference, and marker repairs are composed, childless open or completed Pomodoro entries in the current daily ledger are removed with their full entry blocks. Done, cancelled, non-task, and unknown task statuses are never transitioned.

When the same resolved task is linked beneath multiple open Pomodoros, the first open Pomodoro in file order keeps ownership and every conflicting physical line beneath later open Pomodoros is removed in full. Aliases, embeds, same-note links, and alternate note spellings compare by resolved vault-relative path plus block ID. Repeats within one owning Pomodoro are preserved, as are unresolved links and links beneath completed or cancelled Pomodoros. If a block ID matches multiple task lines, canceled-reference list-item removal requires every match to have a recognized CANCELLED status.

After final checkbox and daily structural changes are composed, eligible area/project Tasks sections are grouped into generated child headings: Next & In Progress, Blocked, and Done & Canceled. Ready [ ] tasks and introductory prose stay in the unheaded intake where ordinary capture adds new tasks. Decorated containers carry a linked status-count badge row, authored topic headings keep their local context, generated groups exist only while they hold a task, and unsupported containers are warned and left unchanged. Grouping excludes daily notes, the selected previous daily, ordinary notes, archives, generated notes, and templates.

Only Markdown checkbox lines allowed by the Obsidian Tasks globalFilter are considered. The scan skips hidden directories, templates, generated notes, and done archives. Blocked writes require exactly one compatible Tasks status named Blocked with symbol [?], type ON_HOLD, and next status Ready. Missing current daily notes and current daily notes without a Pomodoros section, as well as current notes with multiple non-empty open timed Pomodoros, fail before any file is changed. No earlier daily note is valid; an earlier note without a Pomodoros section contributes no historical references. Live writes use guarded snapshots, recovery copies, and a bounded quiet-period check for structural regrouping. Dry-run computes the same grouping preview without locking, waiting, staging, writing notes, or creating recovery records.

Usage: bob task reconcile [OPTIONS]

Options:
  -b, --bob-dir <DIR>
          Bob vault root; defaults to BOB_DIR or ~/bob

  -d, --dry-run
          Compute and report the sync without writing notes

  -f, --format <FORMAT>
          Output format: human or json

          [default: human]
          [possible values: human, json]

  -h, --help
          Show help

  -r, --retry-timeout <SECONDS>
          Retry recoverable failures (lock contention, a changed vault, an unstable read) for up to this many seconds with jittered backoff; 0 attempts once and fails fast

          [default: 120]

Examples:
  bob task reconcile
  bob task reconcile --dry-run
  bob task reconcile --format json
  bob task reconcile --bob-dir /tmp/bob-vault
  bob task reconcile --retry-timeout 0
  bob task reconcile --retry-timeout 300

Environment:
  BOB_DAY_FILE  exact current daily ledger; its dated filename anchors earlier-note lookup and future schedules
  BOB_DIR       Bob vault root when --bob-dir is omitted
  BOB_NOW       current date/time fallback for current and earlier-note selection

Re-schedule every due prioritized task to an independent random date inside that task's own priority window from the Bob config.

A task qualifies when it is an open Ready or Blocked task with exactly one `priority` field naming a configured level and exactly one strict `YYYY-MM-DD` `scheduled` date on or before the cutoff. Each re-roll replaces the scheduled date, flips a future-dated Ready task to Blocked, and writes a 🎲 Schedule Log entry; eligible project notes are regrouped in the same write.

P0 tasks, Next and In Progress tasks, tasks linked from today's open Pomodoros, and tasks with `due` or `repeat` dates are always left alone, as are tasks owned by `bob projects sync` (`^prj`).

A live run holds the shared vault-maintenance lock while it syncs, plans, writes, commits exactly the rewritten notes as one `bob task reroll` commit, and syncs again. Undo a run with `git -C ~/bob revert <sha> && bob vault-sync`; re-running with the printed seed replays the same dates.

Usage: bob task reroll [OPTIONS]

Options:
  -d, --dry-run
          Preview the full plan without locking, syncing, or writing

  -f, --format <FORMAT>
          Output format: human or json

          [default: human]
          [possible values: human, json]

  -h, --help
          Show help

  -l, --level <LABEL>
          Only re-roll these configured labels; repeatable

  -o, --offline
          Skip both vault-sync cycles; commit locally without pushing

  -r, --retry-timeout <SECONDS>
          Budget for waiting on the maintenance lock and for re-planning after concurrent-edit races; 0 fails fast

          [default: 60]

  -s, --seed <SEED>
          Base seed, decimal or 0x-hex; a dry run prints the seed that reproduces its dates

  -u, --until <DATE|+N>
          Treat tasks scheduled through DATE (or N days from today) as due and roll their windows from that date

Examples:
  bob task reroll --dry-run
                                 Preview what would move and where
  bob task reroll --seed 0x7f3a91c2
                                 Apply the dates a dry run showed
  bob task reroll --level P2 --level P3
                                 Leave P1 tasks for hand triage
  bob task reroll --until +7
                                 Clear a week for P0 work
  bob task reroll --dry-run --format json
                                 Machine-readable preview

Environment:
  BOB_CONFIG_FILE  priority-window config; defaults to ~/.config/bob/config.yml
  BOB_DAY_FILE  exact current daily ledger; its dated filename anchors the effective day
  BOB_DIR       Bob vault root
  BOB_NOW       current date/time override for the effective day
  BOB_PRIORITY_ROLL_SEED  default base seed when --seed is omitted
  BOB_VAULT_SYNC_LOCK_FILE  shared vault-maintenance lock file
  BOB_VAULT_SYNC_STATE_FILE  vault-sync status record
  NO_COLOR      disable colored output
  XDG_CONFIG_HOME  config root when BOB_CONFIG_FILE is unset
  XDG_STATE_HOME  recovery-record root