Module backlog 

Module: backlog

Pure functions for parsing and mutating the agent:backlog component body.

Each pending item carries:

• a GFM task-list checkbox (- [ ] / 1. [ ] or - [x] / 1. [x])
• an id prefix rendered as [#xxxx] (generated hash or caller-provided custom id)
• free-form text

Canonical unordered form: - [ ] [#a3f2] refactor preflight commit path Canonical ordered form: 1. [ ] [#a3f2] refactor preflight commit path

This module is I/O-free. Callers (backlog_cmd.rs, preflight.rs, write.rs) handle reading/writing files, locking, and git commits.

Spec

• Parser accepts legacy forms and normalizes via backfill.
• IDs are stable across edits/reorders; generated once (or supplied on insert), preserved thereafter.
• reap removes - [x] items. detect_reorder diffs id order between snapshot/current.
• Mutation ops (op_add/done/edit/clear/reorder) return a new body string, never mutate in place.

Structs

DroppedBacklogItem

DroppedBacklogReport

ExecutionContext

Machine-readable execution-context attributes parsed from a backlog item’s text (#goqueuestall).

ExplicitIdCollision

MalformedPendingItemLine

MalformedTrackedItemRef

PendingAddBatchItemOutcome

PendingAddBatchOutcome

PendingAddOutcome

PendingItem

A parsed pending list item.

ShadowPendingItem

ShadowPendingReport

SymptomDedupeKey

TrackedComponentItemDrop

Enums

AddPosition

Insert a new item at the beginning of the body. Binary assigns hash and [ ] (or [/] if gated). Returns (new_body, assigned_id). #ah0s: explicit insertion position for a newly added pending item. The backlog is a priority-ordered pool with id-based consumption (not a stack or queue), so position encodes author intent and is set explicitly when it matters. First is the cheap default used by --pending-add.

PendingListMarker

PendingOp

Mutating operation on a pending item — used by the state-transition matrix.

PendingState

Lifecycle state for a pending item, encoded by its GFM checkbox.

TrackedWorkList

TransitionResult

Outcome of validate_transition. NoOp means “already in target state, do nothing”.

Constants

CLEAN_SESSION_TAG

Author-controlled execution-context tag literals on a backlog item (#goqueuestall). They live as bracketed tokens in the item text alongside markers like [recommended] / [TOP], and gate whether a go-mode queue may auto-drain the item in the current session type.

FOCUSED_CYCLE_TAG

IN_PROGRESS_MARKER

OPERATOR_VERIFY_TAG

PRIORITY_RANK_UNSET

Rank an item’s priority from a priority=<1..9> token anywhere in its text (#backlog-priority-attribute). 1 is the highest priority and sorts first; 9 is the lowest numbered priority. An item with no valid priority= token ranks 10 — below every numbered item — so unprioritized items sort last while preserving their authored relative order under a stable sort.

Functions

active_enqueue_item_ids

Active open backlog item ids marked for one-shot queue insertion.

active_item_after_deps

Active (open) backlog item ids paired with their after=#id dependency ids, in document order. Feeds the auto-dag queue ordering (#queue-auto-dag-priority).

active_item_execution_contexts

Active (open) backlog item ids paired with their parsed execution context, in document order (#goqueuestall). Feeds the go-mode backlog→queue sync skip and the queue-continuation drainable-head computation.

active_item_ids

Active (open [ ], not gated, not done) backlog item ids in document order.

active_item_priorities

Active (open) backlog item ids paired with their priority rank, in document order. Used to priority-order a synced agent:queue (#backlog-priority-attribute).

backfill

Lazy backfill: ensure every item has a hash id and a checkbox.

canonicalize_preserving_non_item_lines

canonicalize_tracked_work_body

Render a tracked-work component body in canonical form, assigning any missing ids against an otherwise empty active-id registry.

completed_items

completed_tracked_items_in_components

completed_tracked_items_in_content

component_matches_tracked_surface

content_has_resolved_tracked_work_id

detect_dropped_from_history

Compare current document against a baseline to find open backlog items that existed in the baseline but are completely absent from the current document.

detect_dropped_from_history_with_extra_current_ids

detect_identity_collisions

Collect identities that resolve under more than one active source.

detect_malformed_item_lines

Find lines that look like tracked checklist items but are not parseable as live pending items. These lines are dangerous during closeout because guards that operate on parsed items would otherwise treat the matching id as absent.

detect_reorder

Detect reorder: returns Some(current_order) when id-sets match but order differs. Returns None when id-sets differ or order is identical.

detect_shadow_open_items

document_active_identities

Build the active document identity registry for tracked-work lookup.

dropped_tracked_component_items

Return non-exchange components whose tracked checklist item count decreased.

ensure_new_item_explicit_id_available

Enforce that an explicit new tracked-work id has exactly one active meaning in the document after insertion.

ensure_no_completed_tracked_items

ensure_no_new_leading_custom_id_prefix

explicit_custom_id

Return the explicit, caller-provided custom id from a --pending-add item string (id=<id> <text> or [#<id>] <text>), normalized (lowercase, no #). Returns None for auto-id items (no explicit prefix) and for malformed prefixes — callers that need the strict parse error use the add path itself. Used by mutation-time collision enforcement (#preset-item-id-collision-enforce) so an explicit id that collides with a prompt preset or active item id is rejected before the add is written.

explicit_new_item_id_collision

Return existing active sources that a new explicit item id would collide with. Auto-id adds (no id=<custom> / [#custom] prefix) never collide.

extract_done_item_own_ids

Extract only each done/archive item’s own #id — the FIRST [#id] on a list-item line (- <date> [#id] … / - [x] [#id] …) — and ignore any other [#id] cited in that item’s prose.

extract_items_by_id

Remove specific tracked items by id while preserving surrounding non-item structure in the source body. Returns (remaining_body, moved_body, matched_ids).

extract_pending_hash_ids

Ordered unique bare #id references in free text.

extract_pending_ids_from_text

find_open_tracked_work_component_in_content

find_tracked_work_component_in_content

format_dropped_refs

format_shadow_refs

generate_hash_n

Generate a stable variable-width base32 hash. width is clamped to [4, 8] — the spec §1 ceiling on collision extension.

identity_collision_for_new_id

Return existing active sources that a new explicit id would collide with.

is_valid_pending_id

item_after_deps

Parse after=#id dependency tokens from an item’s text (#queue-auto-dag-priority). Declares that this item must be ordered after each named id. Accepts repeated tokens and comma lists: after=#a, after=#a,#b, after=#a after=#b. Ids are normalized lowercase with #/[/] stripped; only valid pending ids are kept. The after= token must start at a word boundary so prose like hereafter= does not match.

item_clean_session_required

True when the item text carries a [clean-session] tag token (#goqueuestall). Matched case-insensitively as a whitespace-delimited bracketed token so prose mentions of the word do not trip it.

item_execution_context

Parse all execution-context tags from an item’s text (#goqueuestall / #qstallguard).

item_focused_cycle_required

True when the item text carries a [focused-cycle] tag token (#qstallguard Layer A).

item_not_before_day

Parse a not-before=YYYY-MM-DD scheduling precondition from an item’s text (#backlog-not-before). Returns the threshold as a day number (days since 1970-01-01) so callers can compare it against today_civil_day. The token must start at a word boundary so prose does not match, and only a strict zero-or-more-digit YYYY-MM-DD is accepted; a malformed value is ignored (the item is then treated as having no precondition rather than silently held).

item_operator_verify_required

True when the item text carries an [operator-verify] tag token (#goqueuestall).

item_precondition_unmet

True when an item’s not-before= scheduling precondition is still in the future relative to today (so it must be held out of the backlog→queue sync). An item with no not-before= token, or with a threshold on/<= today, is eligible (#backlog-not-before).

item_priority_rank

maintenance_surface_label

malformed_tracked_item_interruption_message

malformed_tracked_item_refs

malformed_tracked_item_refs_in_components

merge_partial_backlog_prefix

normalize_pending_id

op_add

op_add_at

Position-aware variant of op_add (#ah0s). Assigns/validates the id and dedups exactly like op_add, then inserts the new item at position. After/Before error if the anchor id is absent.

op_add_at_with_outcome

Add a pending item and report whether it inserted a new item or attached evidence to an existing symptom with the same de-duplication key.

op_add_with_outcome

op_append_items

Append existing tracked items after the current item list, preserving order.

op_clear

Clear all items from the body. Non-item lines, including headers, are preserved.

op_dedupe_identical_items

Collapse runs of identical same-id entries to a single representative, preserving first-seen order. Two items are “identical” when their id, state, gate type, text, and continuation all match — this targets the exact-dup shape an interleaved finalize produces, never distinct items that merely share an id (those remain so an ambiguity warning still surfaces). Returns the rewritten body and the ids that had duplicates removed.

op_done

Mark an item [x] by id. Phase 1: state-machine validation lives in the upcoming backlog_cmd layer; this primitive forces Done unconditionally.

op_edit

Edit an item’s text, preserving its hash id.

op_edit_many

Apply multiple text edits in order to one tracked-work body.

op_gate

Transition an item to Gated ([/]) by id.

op_insert_item_first

Insert an existing tracked item at the first item slot of a component body.

op_prepend_many_with_outcomes

Prepend multiple new tracked-work items while preserving caller order.

op_remove_matching_tracked_line

op_reorder

Reorder items by id. Listed ids come first (in the given order); unlisted ids keep their relative order and follow.

op_resolve_gate

Resolve all gated items matching a typed gate. Finds items with [/<gate_type>] and flips them to [x]. Returns (new_body, resolved_ids).

op_set_gate_type

Set a typed gate on a gated item. The item must already be in [/] state. Transitions [/] → [/<gate_type>]. Errors if the item is not gated.

op_set_gate_verify

Set (or replace) a typed proof/disproof verify predicate on a gated item (#optverify / #optv1). The item must already be in [/] state. The predicate is stored as an inline <!-- gate-verify ... --> annotation in the item text (see crate::gate_verify); set_at stamps the gate-set time so the later ops.log scan only counts markers emitted at/after it.

op_take_active_items_by_ids

Extract non-done items with ids in ids, returning the updated body and removed items.

op_take_all_by_id

Remove every item whose id matches id, returning the rewritten body and the removed items. Unlike op_take_item (which keeps a single representative and errors on a miss), this collapses duplicate-id entries in one pass and returns them all — used by --review-remove so a duplicated review id (e.g. an interleaved finalize that wrote the same #id twice) can be cleared without an ambiguous edit-by-id.

op_take_item

Remove a tracked item by id and return the updated body plus the removed item.

op_take_items_by_state

Extract all items matching state, returning the updated body and removed items.

op_ungate

Transition an item to Open ([ ]) by id.

open_backlog_ids_in_content

open_tracked_work_component_name_in_content

open_tracked_work_ids_in_content

parse_items

Parse the pending component body into (prelude, items, postlude).

preserves_non_item_structure

printable_tracked_work_lines

Non-empty tracked-work body lines as rendered by the CLI list command.

reap

Reap [x] items. [/] (gated) items are never reaped. Returns (new_body, removed_ids).

reap_with_items

Reap [x] items and return the removed items (with text), not just ids. Used by preflight to archive reaped items to an agent:done component.

render_items

Serialize items back to a body string.

review_counts

set_in_progress_item_ids

Set the ephemeral in-progress marker on exactly the requested tracked item ids, clearing stale markers from every other parsed item in the body.

should_reap_already_done_mirrors

should_reap_ops_proof_completions

sort_by_priority

Stable-sort the item lines of a pending body by per-item priority (#backlog-priority-attribute), preserving every non-item segment (blank lines, prose, ordered-list separators) at its original position. Returns Some(new_body) when the order changes, None otherwise (idempotent).

strip_execution_context_tags

Remove the [clean-session] / [operator-verify] execution-context tags from display text (#goqueuestall), collapsing the whitespace they leave behind. Mirrors how machine-only markers are kept out of rendered prose.

symptom_dedupe_key_from_text

today_civil_day

Today as a day number (days since 1970-01-01, UTC) from the system clock, for evaluating not-before= scheduling preconditions. Best-effort: a clock before the epoch clamps to day 0.

tracked_body_for_reorder

tracked_component_item_counts

Count tracked checklist items in every non-exchange component.

tracked_item_ref

tracked_item_refs

tracked_work_ids_for_target

tracked_work_ids_from_component_body

trim_tracked_parent_prefix

validate_transition

Apply the state-machine matrix from specs/pending-system.md §4.