Module model 

Entries (tasks, notes and decisions), their links, status history, time-tracking sessions and comments.

• [markdown]: reading and writing the task file format.
• [text]: tags, file-name slugs and heading rules for user text.
• [time]: timestamps, ages and durations.

Structs

Comment

A timestamped comment on a task, like on a GitHub/GitLab issue.

RepoLink

An entry in another repository of the same project, written shop-api#3: ids repeat across repositories, so the repository’s name goes with it.

Session

One continuous stretch of tracked work on a task.

StatusChange

One status change, as kept in the task’s history.

Task

An entry: a task, note or decision. What it is, how it’s tagged and linked, and for tasks, where it stands and how it got there.

Unknown

Fields, link forms and sections a newer version wrote, kept as written: otherwise an older kb or app saving the entry, for a comment or a status change, would drop them from the file.

Enums

Asked

Where a question an agent asked on a task stands, while the task is parked waiting on it.

Author

Who made a change: the user, or a coding agent working through kb. Comments and status changes record it, so the board tells them apart, and so a question an agent asked waits for a person.

DecisionState

Where a decision stands. An agent records the decisions within its task as accepted, and proposes those it shouldn’t take alone (architecture, dependencies, storage) for a person to accept or reject.

Kind

What an entry is. Only tasks have a status, history and sessions; notes and decisions are documents that tasks and each other link to. Declared in the order tab cycles the list.

Status

Where a task stands. Declared in the order the task list shows them, so position() is the sort key; the names are what task files contain.

Functions

counted

1 session, 3 sessions: n with its noun, one for one and many otherwise (0 sessions).

covered

The time spans (start, end) cover, counting once what several cover at the same moment: two tasks worked on in parallel for an hour took an hour of the day, not two. Empty or reversed spans count nothing.

fmt_age

How long ago, rounded down: <1m, 5m, 3h, 2d, 6w.

fmt_clock

01:02:03 for a live clock.

fmt_dur

45m, 1h 05m; rounded down to whole minutes, but <1m for less than one: a report row or a total that took seconds isn’t one that took none.

fmt_ts

A timestamp in the stored format.

not_a_link

The first word of value that isn’t a link (an id, #12, or REPO#ID): typed on the command line, it’s a mistake to say, where a file’s - links: line keeps such words as they are.

now

Current local time truncated to whole seconds, so files round-trip exactly.

one_line

A title on one line, as its file’s # line holds it: line breaks typed into it (kb add $'Plan\nSteps') become spaces, rather than lines the file would read as something else, and the ends are trimmed.

parse_links

5, 9 or #5 #9: ids of linked entries in this brain; shop-api#3: an entry of another repository. Without repeats; anything else is skipped.

parse_tags

Splits on commas/whitespace, drops a leading #, lowercases and dedupes.

sanitize_comment

See sanitize_description.

sanitize_description

In a task file ## starts a section and, inside Comments, ### starts a comment. Headings typed into a description or comment are pushed below those levels so they can’t break the file. Returns the text and whether anything was changed.

slugify

Fix: prod login! → fix-prod-login; ASCII only so the name works on every file system.

worked

Time worked on any of tasks inside [from, to): time two of them ran at once counts once (see covered), so agents’ tasks running in parallel don’t make a day longer than it was.