Archive & Cleanup

As a project progresses, completed tasks accumulate. Backlog.md provides archiving and cleanup mechanisms to help keep the task list tidy.

Archiving Tasks

Archiving moves inactive tasks into the backlog/archive/tasks/ directory. It is a soft delete:

backlog task archive back-10

After archiving:

• The task file is moved from backlog/tasks/ to backlog/archive/tasks/.
• The task no longer appears in default task lists, boards, or search results.
• The original task ID is released and may be reused by newly created tasks.

Archiving Drafts

Drafts can also be archived individually:

backlog draft archive draft-2

Reusing Archived Task IDs

Backlog.md's ID allocator automatically skips IDs that are already in use. After a task is archived, its original ID is reclaimed and may be assigned again by a future backlog task create.

Reference Cleanup When an ID Is Freed

Archiving (task archive) and demoting (task demote) automatically clean up references to the freed ID in other tasks:

• Dependencies and references pointing to that ID are removed or corrected in active tasks and in the completed corpus, preventing old references from silently binding to new tasks after ID reuse.
• The IDs of affected tasks are listed in CLI output, MCP results, and Web responses (cleanedTaskIds) and are included in the commit scope when auto-commit is enabled.
• Demoted drafts keep their own dependency and parent fields, but references from other tasks to the draft are removed rather than rewritten to the new draft ID.
• Completing (complete / cleanup) does not clean up references—completed records are the completion evidence needed by readiness determination.
• Archive and demote operations are resolved against the local working copy (local-first) and will not accidentally modify other branches.

Files affected by cleanup are also covered by file locking and auto-commit; no manual follow-up is needed.

The Cleanup Command

The cleanup command batch-moves old completed tasks out of the active directory into the backlog/completed/ folder:

backlog cleanup

Running it starts an interactive wizard that guides you through:

1. Scanning all tasks in a terminal status (usually Done).
2. Choosing a time threshold: 1 day, 1 week, 2 weeks, 3 weeks, 1 month, 3 months, or 1 year.
3. Listing all tasks that meet the threshold.
4. Confirming before batch-moving them to the backlog/completed/ directory.

Found 12 tasks marked as Done.

Move tasks to completed folder if they are older than:
> 1 month

Found 8 tasks older than 1 month:
  - back-3: Design database tables (2026-04-01)
  - back-4: Implement user registration (2026-04-02)
  ... and 6 more

Move 8 tasks to completed folder? (y/N)

Completing a Single Task

cleanup is for batch cleanup. To move a single terminal-status task out of the active board, use task complete:

backlog task complete back-10

Unlike cleanup, task complete only performs the completion move: it validates that the task is in a terminal status (determined by the categories/exits in config.statuses, not simply "the last status is terminal"), then moves the task file from backlog/tasks/ to backlog/completed/ without touching references in other tasks—the completed corpus is exactly the completion evidence other tasks need for readiness determination. If the task is not in a terminal status, the command fails and suggests first advancing the status with backlog task edit <id> -s "<terminal-status>".

The corresponding MCP tool is task_complete (parameter id), with the same semantics: it accepts only local tasks and returns VALIDATION_ERROR when terminal-status validation fails. Note the difference from task_archive—task_archive rejects terminal-status tasks and prompts you to use task_complete instead.

Archive vs. Complete / Cleanup

Maintenance Recommendations

Keeping the active task list lean improves board load speed, enhances the search experience, and keeps the team focused on work in progress.