Files
worklane/docs/campaigns.md
T

12 KiB

Campaigns

The container that groups tickets across the flow, and why its state is derived.

  • A campaign's state is derived, never stored. Open until every member is done, computed by Standing from the members. A Status field on the campaign would be the same state in two places, and the two would disagree the moment a member moved. It is also why there is no campaign mv and no forward-only ruleset beside mv's
  • A campaign with no members is neither open nor done. Standing::state() returns None there, and both callers print no members. Calling it done would make a container nothing has been filed against the most complete thing on the board; calling it open would claim work that does not exist
  • Membership is one field on the member, Campaign in the ticket Metadata, written only by assign. The member list is deliberately not on the campaign: that would put membership in two places, and would make one file that every assignment edits, which is contended the moment two agents share a board. So add has no --campaign and set has no --campaign, the same rule as Owner and Status
  • The full uuid is stored and the title is resolved for display, as the Relations section already does. reference_cells is shared between the two, so a dangling campaign and a dangling relation target are both spelled _missing_ rather than each inventing a spelling
  • add does not write the field. Every ticket written before campaigns existed has none, so the insertion path has to exist regardless; leaving it out of add means one path that is always exercised rather than two. Same reasoning as the Relations section
  • set_or_insert_metadata_field() is the upsert, and METADATA_ORDER is its anchor list, the way SECTION_ORDER is ensure_section's. Campaign is placed before Status, so Status stays last where every file already keeps it. A file with no ## Metadata heading is an error, not an insertion: per 641e3d5 such a file has no fields at all, and writing one above the prose would invent a shape nothing reads
  • The four tiers are resolve_in(), shared by tickets and campaigns. A campaign is addressed exactly the way a ticket is, and a second resolver would be a second copy of the precedence rules to keep in step. Found.dir is the status for a ticket and empty for a campaign, which is what makes the ambiguity listing drop the bracket for one
  • An exact Codename is the top tier, and it lives in the shared resolver rather than in a campaign-only path. Only campaigns carry the field, so parse_codename returns None for every ticket and the tier is always empty for one: ticket resolution is unchanged, which a_ticket_search_is_unaffected_by_the_codename_tier pins. It goes above the uuid prefix because it is an exact match on a field written for the purpose, where a substring can be a coincidence, and because a codename like v1 is below MIN_ID_SEARCH and would never be tried as an id at all. A codename that a title also contains, v2 against v2 release, has to win outright rather than be reported ambiguous against it
  • resolve_ticket explains a search that names a campaign, rather than each command doing it. One place, so mv, show, chown and everything else that takes a ticket give the same reason instead of a bare "no ticket found". Checked only on the zero-match path, so it costs nothing normally, and only when exactly one campaign matches: an ambiguous ticket error must not be replaced by a complaint about a directory the caller never mentioned
  • Resolved carries what content_trim cannot render from the file. The relations block and the campaign cell both come from elsewhere on the board. A struct rather than two more parameters, so the next such field is one entry here instead of an edit at every call site
  • campaign show lists done members, unlike ls, which leaves the done column out of its listing. What is finished against what is left is the whole question a campaign asks, so hiding half the answer is not an option. ls --campaign is the other way round: it is the ordinary board filtered, and keeps every rule ls already has
  • campaign ls scans the status directories once per campaign to count members. That is a scan per row rather than one walk reused, and it is deliberate: the map-from-uuid version is worth writing when a board has enough campaigns to notice
  • The TUI got a card label and a frame, not a campaign tab. 61879a4 decided it. A tab would have had to answer what its columns are, and a campaign groups across the flow rather than within one status, so the honest answer is the four statuses filtered — which is a filter on the board it already has rather than a fifth tab. So: a label on the card, a frame above the columns while one is selected, and c for the picker. The cost the earlier decision balked at, a campaigns read per reload, is paid once per project in columns_of and is what names the label; see The Board View
  • A campaign is named by its codename on the board, and by its short id when it has none. The uuid does not fit on a card and the title is a sentence, which is the gap Codename fills. campaign_label builds it in one place, as a Cell, so the CLI paints it and the board makes a span of it; the mark is CAMPAIGN_MARK, ~, beside # for a tag
  • campaign set and campaign append are the only writers of a filed campaign's fields. d637288 decided the command: a set rather than a flag on something narrower, because the file has more than one editable thing and the moment somebody wants to fix a typo in a title there would be a second command to design. set carries --title, which renames the file the way set --title does, --description and --codename; append carries --description alone. campaign add writing a field at creation is not a second writer, exactly as add --title and set --title coexist
  • Replacing a codename the campaign already has needs --force. Once a campaign has one it is referred to by it: it is on every card in the campaign, it is what resolves the campaign at the command line, and it is in somebody's shell history. Changing it silently is the mistake install-skill --force exists to prevent, so it is refused and the refusal names both words and the flag rather than leaving it to be found. Checked before any edit is applied, like SetArgs::contested, so a call also carrying --title writes neither field. Setting the codename a campaign already carries stays a no-op, not a refusal — --force is about overwriting a different word, which is the same division install::Outcome draws between Unchanged and Refused. --force guards the codename alone: a campaign always has a title, so guarding that would mean the flag was always required
  • The description arrived as a pair, set --description and campaign append, 32e98ab. Never one without the other: for a prose section set replaces and append adds, and a way to replace a description with no way to add a paragraph is the half that is easy to reach for and wrong, since replacing a description to add a sentence to it is how the rest of it gets lost. The two scalars have no append form at all, which is the same line append already draws for a ticket, and campaign_append_offers_only_the_description pins that. Neither flag takes --force: a description is prose written to be revised, the same reason tags set --annotation has none
  • append is a campaign's own subcommand, not the top-level append. That one resolves a ticket, and one positional naming either object is the ambiguity resolve_in makes real: its tiers are the same over both directories, so a search can resolve in each and nothing but a flag could say which was meant. It would also make a liar of resolve_ticket, which explains a ticket search that names a campaign. Under campaign the object is settled by the command, as it is for set, show and ls
  • Still no --owner and still no --clear. No --owner, because nothing writes a campaign's Owner today and giving set one would settle by accident whether chown grows a campaign. No --clear, which 32e98ab settled rather than deferred: a codename is replaced rather than emptied, and emptying the description of a container six tickets are filed against is not a thing anybody has asked for, so the only spellings left would be Clearable on a campaign, whose variants are a ticket's fields, or a second enum with one variant in it. campaign_set_offers_no_owner_and_no_clear pins both
  • An empty --description "" is a paragraph break here too, and the refusal for an all-blank value names no flag. Every prose argument in the tool reads a blank value that way, add, set and tags --annotation alike, so a campaign reading it as empty the section would be the one exception. With no --clear to point at, the refusal says a campaign's description has no cleared form instead of naming a flag that does not exist. replaced_items is where the check lives, shared with set, and the way out is the caller's argument for exactly that reason
  • SECTION_ORDER needs no campaign variant, and that is what the one-section file proves. A campaign holds Description and Metadata where a ticket holds four sections and Metadata. Every consumer of the list looks for the headings that follow, filtered by what is actually in the file, so a campaign's description anchors against ## Metadata — which is where campaign_body writes it. the_description_is_edited_in_place_in_a_file_with_one_section pins that no section a campaign does not have gets inserted to anchor against
  • A campaign whose Description heading is gone is refused, not given the section back. No ensure_section on this path: every campaign the tool has ever filed carries the heading, so an insertion here would be reachable only from a hand-edited file, which is the opposite of the Relations case, where add writes nothing and the insertion is the only path there is. The refusal therefore names the section and not the object — "There is no description section to write to" — because both a ticket and a campaign reach replace_section_body now. write_then_replace still carries the noun, where the message is about a file
  • The codename is written through set_or_insert_metadata_field, not set_metadata_field. Every campaign filed before the field existed has no such line, and those are exactly the campaigns the command is for, which is the same reasoning that puts assign on the upsert. Codename is therefore in METADATA_ORDER, directly after ID, so an inserted one lands where campaign_body writes it and a campaign given a codename later is the same file as one filed with it. Nothing upserts it on a ticket, so its place in a ticket's order costs nothing
  • One write path for tickets and campaigns. save_entry is the body, save_ticket and save_campaign are the named wrappers, and write_then_replace and find_entry_file take the noun as a &str so a failure says "campaign" where it is one. A campaign file is a ticket file in every way that matters here, <uuid>_<slug>.md in a directory, and the rename happens only after the write has landed. Every message puts the noun mid-sentence so there is no capital to case
  • campaign_body() builds the file from DESCRIPTION and METADATA_HEADING rather than its own string literals, so the two file formats cannot drift apart on the spelling of a heading. A campaign has no acceptance criteria (its definition of done is derived), no implementation plan and no Status
  • The campaigns directory is created by init and on demand by campaign add, since every board made before campaigns existed has none and a worklane init over a live board to get one would be a strange thing to have to do