8.6 KiB
8.6 KiB
History and Attribution
Who an entry is attributed to, and what the log does and does not record.
Who Wrote an Entry
- Identity is supplied, not detected. Every option that needs no cooperation fails: a harness variable such as
CLAUDECODEnames the tool rather than the instance and breaks across versions, walking the parent process is platform specific and also only names the harness, and a terminal check separates interactive from not, which a human piping output is too. So the actor isWORKLANE_ACTOR, set once per session, with--actoras the per-call override - Precedence: flag, then
WORKLANE_ACTOR, thenget_git_user(), thenunknown. With--actor-from-gitand no explicit value the git user is lifted above the variable rather than added beneath it — the flag says attribute this to the human, and a machine with no git user configured readsunknowninstead of quietly attributing back to the agent. An explicit--actorwins outright either way.resolve_actoris the only caller ofget_git_userfor an entry's author, and every entry the CLI writes goes through it. The halves are separate pure functions,session_actor(the variable alone now) andentry_actor, tested without touching the process environment for the reasoncolors_wantedis split that way - The variable half is cached in a
OnceLockand the git user in another, the wayshould_use_colorsis: neither input can change mid-run, and the git user costs a subprocess. Two caches rather than one is the whole point: baking the git user into the session's answer would make--actor-from-gitread whatever the run's first call produced, since with the variable set that call never fetched git at all.entry_actortakes the git user as a closure so the subprocess is not run when something ahead of it already answered - The two flags are refused together at parse time, clap
conflicts_with: both answer who the entry is attributed to, and last-wins would be a silent answer to a contradictory call.every_actor_command_takes_actor_from_gitwalks the clap definition so the pair travels together onto any command that grows an--actor - An empty
WORKLANE_ACTORcounts as unset, the conventioncolors_wantedfollows forNO_COLOR, so a wrapper script can clear an inherited one. Whitespace counts the same, since a shell quoting a missing value writes one - The actor is free text, checked against nothing, like the
chownuser: there is no registry of actors, and the same reasonls --tagrefuses to validate a tag - It was
comment --owner, renamed with no alias. Owner is the ticket's assignee and has one writer,chown; this names the writer of the entry, which is a different field. Pre-1.0, and two names for one thing is what splittingsetandchownavoided.the_owner_flag_is_gonepins the refusal, since an alias kept "for now" is what makes the wrong name permanent add --ownerandcampaign add --ownerstill default to the git user, deliberately. Those write the assignee, and a ticket an agent files is work for the person whose board it is; attributing it to the agent would put its name in the Owner column of everything it reported- An entry does not record whether the call had a terminal. It is the one agent signal that needs no cooperation, so it was worth considering, and it was rejected: it cannot name an actor, a human piping output produces the same value, and once the actor is explicit the extra field answers no question anybody asks
- Set it in the agent's configuration, not per call.
envin~/.claude/settings.jsonreaches every command Claude Code runs. opencode has no equivalent: its config is JSON with noenvblock for the tools it spawns, so it inherits the environment it was started with, which means a wrapper or a shell function aroundopencode. Both are documented inassets/SKILL.mdrather than assumed
The History Log
- The log is the comments directory with the kind named in it. It was already an append-only log with one event kind: one file per entry under
.worklane/history/<uuid>/, stamped to the microsecond and written withcreate_new. Addingstatus,ownerandtagsbesidecommentneeded no new mechanism, which is why there is no separate journal file and no database - What is not logged, deliberately: ticking or unticking a criterion, and edits to the title, description, plan, priority or due. Those change often and a log of them is noise. When one of them matters, whoever made it adds a comment saying why. Do not add a kind for a field on the grounds that it is cheap to record: the cost is that the log stops being worth reading
--clearis logged, since it is the same field going somewhere.chown --clearandset --clear tagswrite an entry whose after-value is the sentinel the ticket now holds,_Not set_or_None_. The values are recorded verbatim rather than translated into words this module invented, so an entry reads the way the field it came from does- The kind is read from the file and only counted from the filename.
parse_entrymatches the leading marker;kind_from_stemsplits the stem for the card's counter, which must not read four hundred files to draw a board. A name says what a file is for a listing, and the file says what it is for a reader - A file with no marker is a comment, which is what every entry written before the kinds existed is. That is the whole of the compatibility, and it is why there is no migration command:
entry_content(Kind::Comment, ..)is byte for byte whatcmd_commentwrote before this module, so nothing is rewritten and either version can read the other's board - The old directory is adopted, not migrated.
adopt_commentsrenamescommentstohistoryon the first access, and the reader, the writer and the counter all call it, so no caller has to remember it and no path reaches the log without it. A board holding both is refused, naming both paths: only worklane writes there, so it cannot reach that state on its own, and picking which of two entries with one name survives is not a decision to make silently. The counter swallows that error, because a count is drawn per card and a board that cannot be adopted must not take the TUI down; the next write reports it - An entry is written after the edit it describes, never before. A refused move, a refused chown and a failed save log nothing, which is what
a_refused_move_writes_nothinganda_failed_edit_writes_nothingpin. The cost of that order is that a failed entry write leaves the edit in place and reports the failure, which is the right way round: the ticket is the record and the log is the story of it - A no-op edit writes nothing either, and
applyis what decides that forset: a field it did not record as changed was already what the call asked for.cmd_mvandcmd_chownhave their own early returns and sit behind them - The stamp leads the filename and the kind follows it, so the lexicographic sort in
read_historystays chronological however many kinds there are. The collision suffix goes last, after the kind, and is a number, so it matches no slug and the counter skips it - A mechanical entry renders as one line and a comment as it always did. A field change is one fact, and a paragraph for it would bury the comments it sits between. The labels are padded to
Kind::LABEL_WIDTH,campaignbeing the longest of the four, so the bodies line up under each other - A campaign entry records
Campaign::name, the codename or failing that the title, never the uuid the field holds. Settled when the entry is written, not left to the renderer: a log is a record, and resolving at read time would let an entry change meaning when a campaign is renamed. Abeforeuuid the board no longer has reads_missing_, the way the Campaign field itself renders a dangling one, and a ticket never assigned starts from_Not set_(f774a33) --actoris on every command that writes an entry, spelled from oneACTOR_HELPincommand.rs: a flag documented differently on each command reads as four flags.--actor-from-gitrides beside it from its own one string, the same way. Onchownit sits besideuser, which is the ticket's new assignee — the two are different questions and that command answers bothset --actorreaches only the entry--tagswrites, since tags are the one field of that command's that is logged. Documented on the flag rather than left for a reader to notice from the absence of entries.append --actoris the same flag for the same reason:append --tagsmoves the same field, so it writes the sameKind::Tagsentry, and a tag added without replacing the rest would otherwise be the one tag change the log missed