Backlog Manager

BacklogManager is a public file-backed task utility. It keeps active tasks in a .backlog JSON file and completed tasks in the matching .history file.

Backlog example

For a base path such as planning/specs, the utility reads planning/specs.backlog and planning/specs.history. An active backlog may contain:

{
  "tasks": [
    {
      "description": "Document MainAgent request routing",
      "options": [
        "Add a sequence diagram",
        "Add a flowchart"
      ],
      "resolution": ""
    },
    {
      "description": "Reduce documentation page padding",
      "options": [],
      "resolution": "Use one rem on desktop and half a rem on mobile."
    }
  ]
}

Calling markDone(basePath, 2) removes the second task from the active array and appends it to the history file with its resolution. Task identifiers accepted by the API are one-based.

Operational API

Operation	Result
`createBacklog()` / `loadBacklog()`	Create the pair of files or load tasks, history, and backlog file metadata.
`addTask()` / `addTasksFromText()`	Append one task or numbered task descriptions.
`getTask()`, `getApprovedTasks()`, `getNewTasks()`	Read one task or selected task sets.
`addOptionsFromText()` / `approveTask()`	Add numbered alternatives or store a resolution and clear alternatives.
`updateTask()`	Change only supported description, options, and resolution fields.
`markDone()`	Move the selected task into history, using `Executed.` when no resolution exists.
`saveBacklog()` / `flush()`	Persist supplied data or force queued writes to complete.

Persistence boundary

The utility serializes task objects and coordinates writes through backlogIO.mjs. It does not schedule work, choose an option, or execute a task; the caller owns those decisions.