WORKLANE_ACTOR is set once in the environment an agent runs in, which is
right for an agent and wrong for the board: a person who exports it where
their own shell picks it up, the obvious way to configure it for the agents
on that machine, then moved a ticket with ':' and the board recorded the
move as the agent's.
Nothing but the reader can type that line, so the prompt asks for
--actor-from-git's precedence without the flag. An explicit --actor still
wins, which is how the reader puts somebody else's name on their own
keystrokes, and a machine with no git user configured reads unknown rather
than falling back to the variable, for the reason the flag does.
The attribution is a parameter of dispatch rather than a field the prompt
writes into what clap parsed: rewriting the arguments would need an arm per
entry-writing command, and the command added after it would be attributed
to the agent until somebody noticed. no_handler_decides_its_own_attribution
reads src for a handler naming an Attribution of its own, which the
compiler cannot catch because it compiles.
The same command typed in a shell is unchanged, which is what keeps a board
several agents write to saying which of them wrote what.
Also closes a code fence in the skill that e26e589 left open, duplicating
the mv --actor example under it.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
34 lines
10 KiB
Markdown
34 lines
10 KiB
Markdown
# 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 `CLAUDECODE` names 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 is `WORKLANE_ACTOR`, set once per session, with `--actor` as the per-call override
|
|
- **Precedence: flag, then `WORKLANE_ACTOR`, then `get_git_user()`, then `unknown`.** With `--actor-from-git` and 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 reads `unknown` instead of quietly attributing back to the agent. An explicit `--actor` wins outright either way. `resolve_actor` is the only caller of `get_git_user` for 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) and `entry_actor`, tested without touching the process environment for the reason `colors_wanted` is split that way
|
|
- **A command typed at the board is the person's, not the session's.** `dispatch` takes an `Attribution`, `Session` from `main` and `Person` from the command prompt, and `Person` asks for `--actor-from-git`'s lift without the flag: nothing but the reader can type that line, and a person who exported `WORKLANE_ACTOR` where their own shell picks it up — the obvious way to configure it for the agents on that machine — would otherwise watch their own `mv` recorded as the agent's. An explicit `--actor` still wins there, which is how the reader puts somebody else's name on their own keystrokes, and with no git user configured the entry reads `unknown` rather than falling back to the variable, for the reason the flag does. `entry_actor` takes it beside `from_git` and the two are one branch, since `--actor-from-git` typed at the prompt asks for what the prompt does anyway
|
|
- **The attribution is a parameter of `dispatch`, not a field the prompt writes into the parsed arguments.** Rewriting what clap produced would need an arm per entry-writing command, and the command added after it would be attributed to the agent until somebody noticed. A parameter is one edit for both callers, and `no_handler_decides_its_own_attribution` reads `src` for a handler naming an `Attribution` of its own, which the compiler cannot catch because it compiles
|
|
- **The variable half is cached in a `OnceLock` and the git user in another**, the way `should_use_colors` is: 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-git` read whatever the run's *first* call produced, since with the variable set that call never fetched git at all. `entry_actor` takes 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_git` walks the clap definition so the pair travels together onto any command that grows an `--actor`
|
|
- An **empty `WORKLANE_ACTOR` counts as unset**, the convention `colors_wanted` follows for `NO_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 `chown` user: there is no registry of actors, and the same reason `ls --tag` refuses 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 splitting `set` and `chown` avoided. `the_owner_flag_is_gone` pins the refusal, since an alias kept "for now" is what makes the wrong name permanent
|
|
- **`add --owner` and `campaign add --owner` still 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.** `env` in `~/.claude/settings.json` reaches every command Claude Code runs. opencode has no equivalent: its config is JSON with no `env` block for the tools it spawns, so it inherits the environment it was started with, which means a wrapper or a shell function around `opencode`. Both are documented in `assets/SKILL.md` rather 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 with `create_new`. Adding `status`, `owner` and `tags` beside `comment` needed 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
|
|
- **`--clear` is logged, since it is the same field going somewhere.** `chown --clear` and `set --clear tags` write 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_entry` matches the leading marker; `kind_from_stem` splits 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 what `cmd_comment` wrote before this module, so nothing is rewritten and either version can read the other's board
|
|
- **The old directory is adopted, not migrated.** `adopt_comments` renames `comments` to `history` on 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_nothing` and `a_failed_edit_writes_nothing` pin. 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 `apply` is what decides that** for `set`: a field it did not record as changed was already what the call asked for. `cmd_mv` and `cmd_chown` have their own early returns and sit behind them
|
|
- **The stamp leads the filename and the kind follows it**, so the lexicographic sort in `read_history` stays 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`, `campaign` being 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. A `before` uuid 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)
|
|
- **`--actor` is on every command that writes an entry**, spelled from one `ACTOR_HELP` in `command.rs`: a flag documented differently on each command reads as four flags. `--actor-from-git` rides beside it from its own one string, the same way. On `chown` it sits beside `user`, which is the ticket's new assignee — the two are different questions and that command answers both
|
|
- **`set --actor` reaches only the entry `--tags` writes**, 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 --actor` is the same flag for the same reason: `append --tags` moves the same field, so it writes the same `Kind::Tags` entry, and a tag added without replacing the rest would otherwise be the one tag change the log missed
|
|
|