@rse/ase 1.0.7 → 2.0.1

package/dst/man/ase-task-board.1

@@ -0,0 +1,384 @@
+.TH "ASE-TASK-BOARD" "1" "October 2026" "2.0.1" "Agentic Software Engineering (ASE)"
+.SH "NAME"
+\fBase-task-board\fR - Show the interactive task board of the project
+.SH "SYNOPSIS"
+.P
+\fBase task board\fR \[lB]\fB-h\fR|\fB--help\fR\[rB] \[lB]\fB-w\fR|\fB--web\fR\[rB] \[lB]\fB-t\fR|\fB--text\fR\[rB] \[lB]\fB--agent-relay\fR \fIurl\fR\[rB]
+.SH "DESCRIPTION"
+.P
+\fBase task board\fR shows the \fItask board\fR of the current project: all persisted task plans of the task store of the project (see \fBase-task\fR(1)) as \fIcards\fR in the \fIlanes\fR of the effective task lifecycle model (see \fBase task lifecycle\fR), following all changes of the task plans live. It comes in three variants:
+.RS 0
+.IP \(bu 4
+the interactive \fIterminal board\fR (the default, on a terminal),
+.IP \(bu 4
+the \fIweb board\fR in the browser (with \fB--web\fR), and
+.IP \(bu 4
+the plain \fItext overview\fR (with \fB--text\fR, or without an interactive terminal on standard input or output).
+.RE 0
+.P
+The lanes are grouped by the phases of the lifecycle model plus a final \fBDone\fR phase of the finished states, where within a phase the entry state comes first, the active state second, and the parking state last. The cards of the \fIactive\fR lanes (the states a task is actively worked on) are shown in the accent color (default: blue), the cards of the \fIparking\fR lanes in the normal color, and the cards of the finished lanes in the dim color (default: grey), while the selected card is shown in the signal color (default: red).
+.P
+A card shows the task id (inverse, behind a \fB\[==]\fR, and of an epic, i.e., a task being its own group, additionally behind a \fB♛\fR), its group (if any, between \fB♛\fR and \fB▶\fR), its markers, and its title, the latter cut onto a single line or, toggled with \fBt\fR, wrapped onto at most three lines. The markers are:
+.RS 0
+.IP \(bu 4
+\fB\[lB]✎\[rB]\fR: an edit request of the task is pending (see \fBase-agent-editor\fR(1)).
+.IP \(bu 4
+\fB\[lB]✎…\[rB]\fR: an edit request of the task is being processed.
+.IP \(bu 4
+\fB\[lB]✎✗\[rB]\fR: an edit request of the task failed.
+.IP \(bu 4
+\fB\[lB]⚖\fR\fIsize\fR\fB\[rB]\fR: the effort of the task, i.e., the T-shirt size (\fBXS\fR, \fBS\fR, \fBM\fR, \fBL\fR, or \fBXL\fR) of its valid \fBEffort:\fR key (see \fBase-agent-estimator\fR(1)), absent for an unestimated task.
+.IP \(bu 4
+\fB⚉\fR \fIname\fR: a badge on the top border of the card, naming an agent busy with the task (inverse), resp. the agent the task is assigned to.
+.IP \(bu 4
+\fB☺\fR \fIname\fR: a badge on the top border of the card, naming the person the task is assigned to.
+.RE 0
+.P
+Besides the \fItask lanes\fR view, the boards show the \fItask graph\fR view, the dependency graph of the tasks derived from their \fBAfter:\fR keys (where an epic implicitly comes after all other tasks of its group), the \fIstatistics\fR view with the statistics of the tasks, and with an agent relay the \fIagent logs\fR view and the \fIagent graph\fR view. All views are cycled via \fBv\fR (or a click onto the \fBview:\fR value of the header).
+.P
+The last shown view, the minimized lanes, the collapsed phases, and the shown flags are persisted in \fB.ase/board.yaml\fR (separately for the terminal and the web board).
+.SS "Terminal Board"
+.P
+The terminal board runs in the alternate screen of the terminal and requires a window of at least 40 columns and 16 rows.
+.P
+Its header shows the project, the task lifecycle model, the number of unfinished and of all tasks, the current view, and the \fBfilter:\fR field (with its \fB✕\fR clear button), below it the warnings of the board (e.g. on dependency cycles), and its footer shows the information line, up to three key hint lines (hidden and shown via \fB?\fR), and the status line with the kind and connection state of the task store (\fB●\fR connected, \fB\[ci]\fR disconnected), the number of agents and the connection state of the agent relay (if any), and the \fIASE\fR version, or a notice instead.
+.P
+In the task lanes view, lanes can be minimized (\fBm\fR), lane rows collapsed (\fBC\fR), and phases collapsed (\fBc\fR), and the selected lane can be \fIgrown\fR via \fBg\fR to the full board, showing all its cards in a grid of at least four columns.
+.P
+A card opens its plan in a full-height \fItask dialog\fR (\fB⏎\fR or a mouse double click), which shows the frontmatter keys, the predecessors and successors of the task (a click onto one opens its task dialog), and the plan body, followed by the attachments of the plan as further tabs, where a diff attachment (type \fBtext/x-diff\fR, like the implementation draft or the change set snapshot \fBkind="changeset"\fR of the \fBimplementer\fR and \fBintegrator\fR agents) is colored per line, YAML and JSON data are syntax-highlighted, and a change set snapshot older than the plan is marked \fB(stale)\fR.
+.P
+A task is moved into another state (changing its \fBStatus:\fR) either by picking it up with \fBSPACE\fR and dropping it with a second \fBSPACE\fR onto the selected lane (only lanes whose state is reachable from the current state in the lifecycle model accept the task, and are shown in bold), or via the \fItransfer popup\fR of \fBT\fR, which lists all lane states (as \fIphase\fR \fB▷\fR \fIstate\fR, starting at the current state), where the states not reachable from the current state are dimmed.
+.P
+A task is assigned (changing its \fBAssignee:\fR) via the \fIassign popup\fR of \fBA\fR: its assignee field, prefilled with the current assignee, accepts any name, while its drop-down suggests the names containing the typed one: \fBnone\fR (unassigning the task, like an empty field), then the users of \fBproject.users\fR (else the current user) with \fB☺\fR, then the agents present at the agent relay with \fB⚉\fR, each sorted, except the agents which never take a task by its assignee (the request agents, like \fBase-agent-editor\fR(1), and the phase agents of an \fBunclaimed\fR definition). With a non-empty \fBproject.users\fR, a name neither suggested nor the current user is marked \fBunknown\fR, and its assignment is warned about (see \fBase-task-assign\fR(1)).
+.P
+\fBe\fR edits the selected task plan with \fB$EDITOR\fR (default: \fBvi\fR, run through the shell, with the file passed as \fB$ASE_TASK_FILE\fR), where a draft which failed to save is offered again on the next \fBe\fR. \fBN\fR creates a new task by editing a pre-filled task plan (all frontmatter keys, a free placeholder id, the initial state, and the section template of the task format), which is stored under the id of its \fBId:\fR line (refused for an existing id, while an unchanged text creates no task at all), where a text which failed to save is offered again on the next \fBN\fR (created again even if unchanged) until it is emptied, which discards it. \fBD\fR deletes the selected task after a confirmation.
+.P
+\fBE\fR requests the edit of the selected task by a prompt (refused for a finished task and while an edit of it is in progress), which \fBase-agent-editor\fR(1) then processes via the \fBase-task-edit\fR skill. The prompt popup is prefilled with the prompt of a cancelled request resp. of the most recent failed request (for a retry), and an empty prompt is refused.
+.P
+\fBR\fR requests the selected task by a prompt under a \fIrequest name\fR (see \fBase task request\fR), suggested from the request agents announced to the agent relay (\fBedit\fR for \fBase agent editor\fR, else the request name of any other request agent), which the request agent of the name then processes. An empty prompt is refused, unless all request agents of the name announced to the agent relay accept the prompts of their requests as optional (e.g., the \fBresearch\fR requests of \fBase agent
+researcher\fR, see \fBase-agent-researcher\fR(1)) or ignore them. If all of them ignore the prompts (e.g., the \fBestimate\fR requests of \fBase agent
+estimator --mode request\fR, see \fBase-agent-estimator\fR(1)), the prompt field is disabled, skipped by \fBTAB\fR, and no prompt is sent.
+.P
+\fB/\fR focuses the \fBfilter:\fR field of the header: its keywords are matched case-insensitively against the task id and title, AND-combined when separated by spaces and OR-combined when separated by commas. Each OR-part first matches its keywords as literal substrings, and only if this matches no task at all, it matches them \fIfuzzily\fR (keywords of at least four characters also match words of a similar spelling). A keyword \fBeffort:\fR\fIsize\fR (with \fIsize\fR one of \fBXS\fR, \fBS\fR, \fBM\fR, \fBL\fR, or \fBXL\fR, case-insensitively) instead exactly matches the tasks of this effort size (its \fBEffort:\fR key), while a keyword of any other size is an ordinary one. The lanes show only the matching tasks, the graph additionally their direct predecessors and successors (dimmed and dashed).
+.P
+The terminal board supports the mouse (via SGR mouse reporting): a click onto a card or a lane selects it, a double click onto a card opens it, a double click onto a lane minimizes or maximizes it (resp. shrinks a grown lane, resp. expands its collapsed phase), a click onto the title of a phase selects it like \fB\[<-]\fR/\fB\[->]\fR (its lane in the row of the selected lane), a double click onto it collapses or expands it, a click onto the \fBview:\fR value of the header cycles the view, a click onto the \fBfilter:\fR field focuses it, a click onto its \fB✕\fR clears it, and the mouse wheel over a lane scrolls it. In the task graph view, a click onto a task selects it and a double click opens it.
+.P
+\fBM\fR disables the mouse support to regain the regular text selection of the terminal (and enables it again). The terminal board enables the \fIkitty keyboard protocol\fR if the terminal supports it, as only then \fBShift\fR+\fB⏎\fR is distinguishable from \fB⏎\fR.
+.SS "Web Board"
+.P
+With \fB--web\fR, the web board is served through the \fIASE\fR service of the project (see \fBase-service\fR(1), started if not yet running) under \fBhttp://127.0.0.1:\fR\fIport\fR\fB/task-board\fR, which is printed on standard output and opened in the default browser (via \fBopen\fR, \fBxdg-open\fR, resp. \fBstart\fR).
+.P
+It offers the same views and keys as the terminal board, where a task is additionally moved by dragging its card onto a reachable lane, the graph is zoomed by the mouse wheel (and \fB+\fR, \fB-\fR, and \fB0\fR) and panned by dragging it, and an image attachment is zoomed by the mouse wheel. Its minimized lanes and collapsed phases are stored once per project, not per browser, so all open web boards share them and pick up a change immediately.
+.P
+In the task dialog of the web board, \fBe\fR (or \fB✎\fR) edits the task plan in a Markdown editor (in the task lanes and task graph views, \fBe\fR opens the selected task directly for editing): \fBCtrl\fR/\fB⌘\fR+\fBS\fR saves it, but only if the plan was not changed meanwhile (else it offers to overwrite or discard), and \fBESC\fR cancels (after a confirmation if changed). With the Vim or Emacs key bindings of \fBboard.web.editor.keymap\fR, \fB:w\fR/\fB:q\fR resp. \fBC-x C-s\fR/\fBC-x C-c\fR save resp. cancel instead. A text which failed to save is kept as a draft in the browser and offered on the next edit.
+.P
+A running service with other \fIASE\fR code is never restarted, as this would break the MCP connections of the agent sessions using it: an older service without the web board fails \fB--web\fR (restart it with \fBase service stop\fR once no agent session uses it), while a differing build is only warned about.
+.SS "Text Overview"
+.P
+With \fB--text\fR, and also without an interactive terminal, the lane overview is printed as plain text and the command exits: a header line with the project, the lifecycle model, and the number of tasks, then per phase (\fB━\fR \fIphase\fR) and lane (\fIstate\fR, marked \fB(active)\fR for an active lane, and its number of cards) the cards with their id (plus the \fB✎\fR and \fB⚖\fR markers), title, and the agents busy with them (behind \fB⚙\fR), followed, with an agent relay, by the agents (\fB●\fR busy, \fB\[ci]\fR waiting) with their status and their last processing log line, and finally all warnings of the board (behind \fB⚠\fR, e.g. on dependency cycles).
+.SS "Statistics View"
+.P
+The third view \fIstatistics\fR shows the statistics of the tasks matching the \fBfilter:\fR field (all tasks if empty), refreshed on every change of the tasks, within the time range selected by the buttons \fBtotal\fR (all tasks, with the number of days since the creation of the oldest task), \fBwithin last 30 days\fR, and \fBwithin last 7 days\fR on its top (selected via \fB\[<-]\fR/\fB\[->]\fR or a click, initially \fBtotal\fR):
+.RS 0
+.IP \(bu 4
+\fBTasks per State\fR: a column chart with the number of tasks of each state of the task lifecycle model, labeled by the state, below by the effort of its estimated tasks (blank without any), and below by its phase (of its lane), in the colors of the lanes, and with the \fBtotal tasks:\fR line below it. An effort is the sum of the representative human minutes of the effort sizes of the tasks on the scale \fBproject.task.effort.scale\fR (see \fBase-config\fR(1)), shown in minutes below one hour, else in hours, where the explicit epics carry no effort of their own.
+.IP \(bu 4
+\fBThroughput\fR (besides \fBTasks per State\fR): a column chart with the number of tasks finished (in a terminal state other than \fBCANCELLED\fR) in each of the last 12 weeks (a quarter, ending with the current week), labeled by the ISO week number and, below, by the total and average number of finished tasks per week. As the time of the completion of a task is not tracked, its \fBModified:\fR frontmatter key is taken instead, so the throughput is just an approximation. It always covers the last 12 weeks, independent of the time range.
+.sp
+Below it, the \fBforecast:\fR line shows the number of all unfinished tasks (\fIwork-in-progress\fR and \fIopen\fR, independent of the time range) and the number of weeks to finish them at the average throughput of the last 12 weeks, \fBn/a\fR without any finished task within them.
+.IP \(bu 4
+\fBTask Progress\fR: one stacked bar of the \fIcancelled\fR tasks, the \fIfinished\fR tasks (in a terminal state other than \fBCANCELLED\fR), the tasks \fIwork-in-progress\fR (\fBwip\fR, in an active state, like \fBPLANNING\fR or \fBIMPLEMENTING\fR), and the \fIopen\fR tasks (in any other state, like \fBDRAFTED\fR, \fBPLANNED\fR, or \fBSTALLED\fR), each with its number and share.
+.IP \(bu 4
+\fBOpen Tasks\fR (besides \fBTask Progress\fR): one stacked bar of the open tasks, split into the \fIready\fR tasks (all predecessors in a terminal state, or none at all) and the \fIblocked\fR tasks (any predecessor in another state, including the implicit predecessors of an epic), each with its number and share. The readiness is determined against all tasks, independent of the \fBfilter:\fR field, as a predecessor hidden by the filter blocks a task nevertheless.
+.IP \(bu 4
+\fBUsage\fR: bars of the total accumulated usage of the tasks (see \fBase-task-assign\fR(1) and \fBase-agent\fR(1)) by its \fBtime\fR (AI request, human, and real time, in minutes below one hour, else in hours), its \fBtoken\fR (all tokens, stacked by the cache read, cache write, input, and output tokens), and its \fBcost\fR (AI and human costs, in USD), with the bars of a column scaled to the maximum of the column.
+.IP \(bu 4
+\fBEffort\fR (besides \fBUsage\fR): a column chart with the number of estimated tasks of each effort size, from the smallest (\fBXS\fR) to the largest (\fBXL\fR), where the explicit epics carry no effort of their own, and with the \fBestimated:\fR line below it, the number of the estimated and of all tasks.
+.IP \(bu 4
+\fBTop-5 Tasks\fR: a table of the (up to) five tasks of the highest usage, ranked by their total (AI and human) costs and then by their input and output tokens, with the columns \fBTask Id\fR (inverse behind \fB\[==]\fR, in the color of its lane), \fBTask Title\fR (cut with an ellipsis if too long), \fBTotal Share\fR (a bar of its share of the total costs of all tasks, resp. of their input and output tokens without any costs), \fBCost\fR, and \fBToken\fR (as \fIinput\fR \fB▷\fR \fIoutput\fR, with the uncached input tokens, i.e., without the cache read and write tokens).
+.IP \(bu 4
+\fBFinished Tasks\fR (besides \fBTop-5 Tasks\fR): the average (\fB⌀\fR) AI costs, human costs, and AI tokens (as \fIinput\fR \fB▷\fR \fIoutput\fR, like in \fBTop-5 Tasks\fR) per finished task (the usage of the finished tasks divided by their number, including the finished tasks without any usage), and the \fIlead time\fR (the time from the \fBCreated:\fR to the \fBModified:\fR frontmatter key) of the finished tasks as its median (\fBlead (median)\fR) and its 85th percentile (\fBlead (p85)\fR), in minutes below one hour, in hours below two days, else in days, each \fBn/a\fR without any finished task.
+.sp
+Like the throughput, the lead time is just an approximation, and median and percentile are robust against single outlier tasks.
+.IP \(bu 4
+\fBEfficiency\fR (besides \fBFinished Tasks\fR): the \fIAI/HR time ratio\fR (the AI request time per human time, i.e., the higher, the more AI work per attended human minute) and the \fIAI/HR cost ratio\fR (the AI costs per human costs), each \fBn/a\fR without any human time resp. costs (as booked by the agents, see \fBase-agent\fR(1)), and the \fIAI cache hit ratio\fR (the share of the cache read tokens of all input tokens, i.e., of the cache read, cache write, and uncached input tokens, the main lever on the AI costs), \fBn/a\fR without any input tokens.
+.RE 0
+.P
+Within the last 30 or 7 days, a task counts only if the period from its \fBCreated:\fR to its \fBModified:\fR frontmatter key overlaps with the time range, and the usage of a task counts only with the overlapping part of the period from the \fBCreated:\fR to the \fBModified:\fR key of its usage attachment (i.e., the times of its first and last booking). As the usage attachment does not track when the usage accrued, the usage is taken as being evenly spread over this period, so the usage within these time ranges is just an approximation.
+.SS "Agent Logs View"
+.P
+With an agent relay (see \fB--agent-relay\fR), the boards additionally follow the running agents (see \fBase-agent\fR(1)) live in the view \fIagent logs\fR: a master/detail view, with the framed master list \fBAgents\fR on the left, showing each agent as a card with its name (inverse, behind a \fB⚉\fR), a pulse on its top border while busy (resp. a circle while waiting), and the fields \fBkind:\fR and \fBmode:\fR of its operation (or \fBnone\fR without a mode), and \fBtask:\fR with the ids of the tasks it is busy with (else \fBnone (waiting)\fR).
+.P
+The framed pane \fBOperation\fR on the right shows the operation of the selected agent: its one-line title (in bold) and its brief description (word-wrapped and cut after six lines), as given by its definition (see \fB--title\fR and \fB--description\fR in \fBase-agent-adhoc\fR(1)).
+.P
+Two equally wide framed panes below it show the selected agent: \fBProcess\fR with its \fBhost:\fR, its process id \fBpid:\fR, its user id and user name \fBuid:\fR (e.g. \fB501 (rse)\fR), and its current working directory \fBcwd:\fR (cut at its start if too long), where \fBuid:\fR and \fBcwd:\fR are \fBn/a\fR for an older agent not reporting them, and \fBAccounting\fR with \fBuptime:\fR, the duration since its start, \fBheartbeat:\fR, the age of its latest heartbeat, and \fBusage
+(total):\fR resp. \fBusage (last job):\fR, its usage of the agent tool in total since its start resp. by its last finished job, each as wall time, output tokens, and costs in USD (e.g. \fB12m, 9.2k tok, $3.41\fR, with \fBn/a\fR for what the agent tool does not report, and \fBnone\fR before the first finished job).
+.P
+The framed detail view \fBRecent Log Entries\fR below them shows the recent processing log lines of the selected agent, each with its full timestamp, the id of its task (if any), and its level and content (warnings and errors in the signal color), broken onto multiple rows instead of being cut. The detail view follows the bottom of the log while not scrolled up. When the selected agent vanishes, its neighbor is selected instead.
+.P
+The information line shows the selected agent and the title of its operation (if any). Without an agent relay, the agent logs view is skipped.
+.P
+An agent stopping vanishes from the board immediately, while an agent missing its heartbeat vanishes after 30 to 35 seconds. A relay connection without any traffic for 15 to 30 seconds (e.g. after a network partition) is detected, reported as disconnected (dropping the shown agents), and re-established.
+.SS "Agent Graph View"
+.P
+With an agent relay, the boards additionally show, after the agent logs view, the last view \fIagent graph\fR: like the task graph view, but with the running agents as their agent cards (with the same fields as in the agent logs view), plus the lifecycle states referenced by these agents as state boxes. An edge from a state to an agent card shows a state the agent observes (its incoming states), a dashed edge a state the \fBAfter:\fR predecessors of its tasks have to reach first (its gate), and an edge from an agent card to a state a state the agent writes (its success, failure, and verdict states). The cards of the agents operating in the same activity state (e.g. \fBIMPLEMENTING\fR) are drawn within a dashed container labeled with this state (behind a \fB◉\fR), while unclaimed phase agents (e.g. \fBestimator --mode phase\fR) and request agents (e.g. \fBeditor\fR) are drawn outside of any container, the latter without any edges. The agent graph is laid out top to bottom: the request agents in a row on top, below them the lifecycle states in the grid of the task lanes view, i.e., per phase as a column, the entry states, then the active states (the containers, plus the unclaimed phase agents), and then the parking states. Several running agents of the same kind and mode are merged into one card, with their number behind a \fB\[mu]\fR in its name and the union of the tasks they are busy with.
+.P
+The information line shows the selected agent card with its incoming, activity, written, and gate states (resp. the name of its requests), resp. the selected state with the agents observing, writing, and gating on it. The states are announced by the agents themselves, so agents and agent relay have to be of the same \fIASE\fR version. Without an agent relay, the agent graph view is skipped.
+.SH "OPTIONS"
+.RS 0
+.IP \(bu 4
+\[lB]\fB-h\fR|\fB--help\fR\[rB]: Show usage information and exit.
+.IP \(bu 4
+\[lB]\fB-w\fR|\fB--web\fR\[rB]: Serve the web board through the \fIASE\fR service of the project, print its URL, open it in the default browser, and exit (see \fBWeb Board\fR). Takes precedence over \fB--text\fR.
+.IP \(bu 4
+\[lB]\fB-t\fR|\fB--text\fR\[rB]: Print the lane overview as plain text and exit (see \fBText Overview\fR), instead of starting the interactive terminal board.
+.IP \(bu 4
+\[lB]\fB--agent-relay\fR \fIurl\fR\[rB]: The agent relay to receive the live presence of the agents from, as \fBase://\fR\fIaddr\fR\fB:\fR\fIport\fR\[lB]\fB/\fR\fItoken\fR\[rB] resp. \fBases://\fR\fIaddr\fR\fB:\fR\fIport\fR\[lB]\fB/\fR\fItoken\fR\[rB]\[lB]\fB?insecure\fR\[rB] for HTTPS (optionally without certificate verification), with the bearer token embedded, else from \fB$ASE_AGENT_RELAY_TOKEN\fR, else from \fBproject.relay.token\fR, else of the locally started agent relay (default: the configured \fBproject.relay.url\fR, else none, i.e., without agent logs and agent graph views).
+.sp
+Honored by the terminal board and the text overview only, as the web board always follows the configured \fBproject.relay.url\fR (and hence warns about the option).
+.RE 0
+.SH "KEYS"
+.P
+The following keys are supported by the terminal board (and, unless noted otherwise, equally by the web board). The keys \fBD\fR, \fBE\fR, \fBN\fR, \fBR\fR, \fBT\fR, \fBA\fR, and \fBM\fR are also accepted as \fBShift\fR with the lower-case letter under the kitty keyboard protocol.
+.SS "Every View"
+.RS 0
+.IP \(bu 4
+\fBv\fR: Cycle the view: task lanes, task graph, statistics, and (with an agent relay) agent logs and agent graph.
+.IP \(bu 4
+\fBV\fR: Cycle the view backward.
+.IP \(bu 4
+\fB/\fR: Focus the \fBfilter:\fR field (not in the agent logs and agent graph views).
+.IP \(bu 4
+\fB?\fR: Hide or show the key hint lines (persisted).
+.IP \(bu 4
+\fBD\fR: Delete the selected task, after a confirmation (not in the agent logs and statistics views).
+.IP \(bu 4
+\fBT\fR: Transfer the selected task to another state via the transfer popup (not in the agent logs and statistics views).
+.IP \(bu 4
+\fBA\fR: Assign the selected task via the assign popup (not in the agent logs and statistics views).
+.IP \(bu 4
+\fBE\fR: Request the edit of the selected task by a prompt (not in the agent logs and statistics views).
+.IP \(bu 4
+\fBR\fR: Request the selected task by a prompt under a request name (not in the agent logs and statistics views).
+.IP \(bu 4
+\fBM\fR: Disable or enable the mouse support (terminal board only).
+.IP \(bu 4
+\fBq\fR, \fBCtrl\fR+\fBC\fR: Quit (terminal board only).
+.RE 0
+.SS "Task Lanes View"
+.RS 0
+.IP \(bu 4
+\fB\[ua]\fR/\fB\[da]\fR: Select the previous/next card of the phase (within a collapsed phase, the previous/next lane).
+.IP \(bu 4
+\fB\[<-]\fR/\fB\[->]\fR: Select the card of the same lane in the previous/next phase.
+.IP \(bu 4
+\fBPgUp\fR/\fBPgDn\fR: Select the upper/lower lane of the phase.
+.IP \(bu 4
+\fBHome\fR/\fBEnd\fR: Select the first/last card of the lane.
+.IP \(bu 4
+\fBTab\fR/\fBShift\fR+\fBTab\fR: Step through the lanes of the expanded phases lane row by lane row, wrapping around the board.
+.IP \(bu 4
+\fB⏎\fR: Open the task dialog of the selected task.
+.IP \(bu 4
+\fBe\fR: Edit the selected task plan (terminal: with \fB$EDITOR\fR; web: in the Markdown editor of its task dialog).
+.IP \(bu 4
+\fBN\fR: Create a new task.
+.IP \(bu 4
+\fBSPACE\fR: Pick up the selected task, resp. drop the picked-up task onto the selected lane (dropping it onto its own lane cancels).
+.IP \(bu 4
+\fBESC\fR: Cancel the move of a picked-up task.
+.IP \(bu 4
+\fBm\fR: Minimize or maximize the selected lane (persisted).
+.IP \(bu 4
+\fBc\fR: Collapse or expand the selected phase (persisted).
+.IP \(bu 4
+\fBC\fR: Collapse the lane row of the selected lane, i.e., the lanes at the same position in all expanded phases, resp. expand it again if all its lanes are collapsed already (persisted).
+.IP \(bu 4
+\fBg\fR: Grow the selected lane to the full board (only a maximized lane of an expanded phase), resp. shrink it back again.
+.IP \(bu 4
+\fBt\fR: Cut the card titles onto a single line, resp. wrap them onto at most three lines (persisted).
+.RE 0
+.SS "Grown Lane"
+.RS 0
+.IP \(bu 4
+\fB\[ua]\fR/\fB\[da]\fR/\fB\[<-]\fR/\fB\[->]\fR: Select the card above/below/left/right in the grid.
+.IP \(bu 4
+\fBPgUp\fR/\fBPgDn\fR: Select the card a page of rows above/below.
+.IP \(bu 4
+\fBHome\fR/\fBEnd\fR: Select the first/last card.
+.IP \(bu 4
+\fBg\fR, \fBESC\fR: Shrink the lane back again.
+.IP \(bu 4
+\fB⏎\fR, \fBe\fR, \fBN\fR, \fBSPACE\fR, \fBt\fR: As in the task lanes view.
+.RE 0
+.SS "Task Graph View"
+.RS 0
+.IP \(bu 4
+\fB\[ua]\fR/\fB\[da]\fR/\fB\[<-]\fR/\fB\[->]\fR: Select the nearest task in the direction of the arrow.
+.IP \(bu 4
+\fB⏎\fR: Open the task dialog of the selected task.
+.IP \(bu 4
+\fBe\fR, \fBN\fR, \fBt\fR: As in the task lanes view.
+.IP \(bu 4
+\fBs\fR: Hide or show the standalone tasks, i.e., the tasks without any predecessors and successors (persisted).
+.IP \(bu 4
+\fB+\fR/\fB-\fR/\fB0\fR: Zoom in, out, resp. reset the zoom (web board only).
+.RE 0
+.SS "Statistics View"
+.RS 0
+.IP \(bu 4
+\fB\[<-]\fR/\fB\[->]\fR: Select the previous/next time range (\fBtotal\fR, \fBwithin last
+30 days\fR, or \fBwithin last 7 days\fR).
+.RE 0
+.SS "Agent Logs View"
+.RS 0
+.IP \(bu 4
+\fB\[ua]\fR/\fB\[da]\fR: Select the previous/next agent.
+.IP \(bu 4
+\fBShift\fR+\fB\[ua]\fR/\fB\[da]\fR: Scroll the log of the detail view by one line (terminal board only).
+.IP \(bu 4
+\fBPgUp\fR/\fBPgDn\fR: Scroll the log of the detail view by one page.
+.IP \(bu 4
+\fBHome\fR/\fBEnd\fR: Scroll to the top/bottom of the log of the detail view, where scrolling down to its bottom follows it again.
+.RE 0
+.SS "Agent Graph View"
+.RS 0
+.IP \(bu 4
+\fB\[ua]\fR/\fB\[da]\fR/\fB\[<-]\fR/\fB\[->]\fR, mouse click: Select the nearest agent card or state in the direction of the arrow, resp. the clicked one, where the edges of the selection are highlighted, and the information line of a selected state shows the agents observing, writing, and gating on it.
+.IP \(bu 4
+\fB⏎\fR, mouse double click: Show the agent logs view with the agent of the selected card (of a merged card: its oldest agent) selected.
+.IP \(bu 4
+\fB+\fR, \fB-\fR, \fB0\fR, mouse wheel: Zoom in, out, resp. reset the zoom (web board only), where dragging the background scrolls the agent graph.
+.IP \(bu 4
+\fBPgUp\fR/\fBPgDn\fR, \fBHome\fR/\fBEnd\fR, mouse wheel: Scroll the agent graph by a page, resp. to its top/bottom (terminal board only).
+.RE 0
+.SS "Task Dialog"
+.RS 0
+.IP \(bu 4
+\fB\[<-]\fR/\fB\[->]\fR, \fBTab\fR/\fBShift\fR+\fBTab\fR: Select the previous/next tab.
+.IP \(bu 4
+\fB\[ua]\fR/\fB\[da]\fR: Scroll the content.
+.IP \(bu 4
+\fBPgUp\fR/\fBPgDn\fR: Scroll the content by one page.
+.IP \(bu 4
+\fBe\fR: Edit the task plan.
+.IP \(bu 4
+\fBD\fR, \fBT\fR, \fBA\fR, \fBE\fR, \fBR\fR, \fBM\fR: As in every view.
+.IP \(bu 4
+\fB⏎\fR, \fBESC\fR: Close the task dialog.
+.RE 0
+.SS "Filter Field"
+.RS 0
+.IP \(bu 4
+\fIcharacter\fR: Extend the filter query (applied live).
+.IP \(bu 4
+\fBBackspace\fR: Remove the last character of the filter query.
+.IP \(bu 4
+\fB⏎\fR: Keep the filter query and leave the field.
+.IP \(bu 4
+\fBESC\fR: Clear the filter query and leave the field.
+.RE 0
+.SS "Prompt Popup"
+.RS 0
+.IP \(bu 4
+\fIcharacter\fR: Insert the character (also pasted text) at the cursor.
+.IP \(bu 4
+\fB⏎\fR: Request the edit resp. the request (on the request name field: switch to the prompt; on a button: press it, also a click onto it).
+.IP \(bu 4
+\fBShift\fR+\fB⏎\fR, \fBAlt\fR+\fB⏎\fR, \fBCtrl\fR+\fBJ\fR: Insert a line break (terminal: \fBShift\fR+\fB⏎\fR only under the kitty keyboard protocol, \fBAlt\fR+\fB⏎\fR only under the kitty keyboard protocol or where the terminal sends it as \fBESC\fR+\fB⏎\fR, e.g. with "Option as Meta" on macOS, and \fBCtrl\fR+\fBJ\fR in every terminal; web: \fBShift\fR+\fB⏎\fR only).
+.IP \(bu 4
+\fB\[<-]\fR/\fB\[->]\fR: Move the cursor by one character.
+.IP \(bu 4
+\fBHome\fR/\fBEnd\fR: Move the cursor to the start/end of the prompt.
+.IP \(bu 4
+\fBBackspace\fR/\fBDelete\fR: Remove the character before/at the cursor.
+.IP \(bu 4
+\fBTab\fR/\fBShift\fR+\fBTab\fR: Switch to the next/previous field: the request name (\fBR\fR only), the prompt, and the request and cancel buttons (terminal board: also a click onto a field; web: by the regular focus switching).
+.IP \(bu 4
+\fB\[ua]\fR/\fB\[da]\fR: Cycle through the suggested request names of the drop-down, which offers the names containing the typed request name, while on the request name (\fBR\fR only; also a click onto a name picks it).
+.IP \(bu 4
+\fBESC\fR: Cancel, keeping the prompt as a draft for the task.
+.RE 0
+.SS "Transfer Popup"
+.RS 0
+.IP \(bu 4
+\fB\[ua]\fR/\fB\[da]\fR: Select the previous/next reachable state.
+.IP \(bu 4
+\fB⏎\fR: Transfer the task into the selected state (also a click onto it).
+.IP \(bu 4
+\fBESC\fR: Cancel (also a click outside of the popup).
+.RE 0
+.SS "Assign Popup"
+.RS 0
+.IP \(bu 4
+\fIcharacter\fR: Extend the assignee (web board: edit it freely).
+.IP \(bu 4
+\fBBackspace\fR: Remove the last character of the assignee (terminal board).
+.IP \(bu 4
+\fB\[ua]\fR/\fB\[da]\fR: Cycle through the suggested assignees of the drop-down.
+.IP \(bu 4
+\fB⏎\fR: Assign the task to the assignee (also a click onto a suggested assignee).
+.IP \(bu 4
+\fBESC\fR: Cancel (also a click outside of the popup).
+.RE 0
+.SS "Deletion Confirmation"
+.RS 0
+.IP \(bu 4
+\fBy\fR: Delete the task.
+.IP \(bu 4
+\fBESC\fR: Cancel (web board: also \fBn\fR).
+.IP \(bu 4
+\fB\[<-]\fR/\fB\[->]\fR, \fBTab\fR: Switch between the \fBdelete\fR and \fBcancel\fR buttons (terminal board; web board: by the regular focus switching).
+.IP \(bu 4
+\fB⏎\fR: Press the selected button (default: \fBcancel\fR).
+.RE 0
+.SH "CONFIGURATION"
+.P
+The following configuration keys (on scope \fBuser\fR or \fBproject\fR, see \fBase-config\fR(1)) customize the boards:
+.RS 0
+.IP \(bu 4
+\fBboard.tui.color.dim\fR, \fBboard.tui.color.normal\fR, \fBboard.tui.color.accent\fR, \fBboard.tui.color.signal\fR: The colors of the four color roles of the terminal board (default: \fBgrey\fR, \fBdefault\fR, \fBblue\fR, and \fBred\fR), each either \fBdefault\fR (the foreground color of the terminal), a color name, \fB#rgb\fR, \fB#rrggbb\fR, \fBansi256(\fR\fIn\fR\fB)\fR, or \fBrgb(\fR\fIr\fR\fB,\fR\fIg\fR\fB,\fR\fIb\fR\fB)\fR.
+.IP \(bu 4
+\fBboard.web.color.dim\fR, \fBboard.web.color.normal\fR, \fBboard.web.color.accent\fR, \fBboard.web.color.signal\fR: The base colors of the four color roles of the web board (default: \fBgrey\fR, \fBblack\fR, \fBblue\fR, and \fBorange\fR), each either \fBdefault\fR (the default base color of the role), one of the color names \fBblack\fR, \fBgrey\fR, \fBgray\fR, \fBbrown\fR, \fBred\fR, \fBorange\fR, \fByellow\fR, \fBgreen\fR, \fBteal\fR, \fBcyan\fR, \fBblue\fR, \fBpurple\fR, or \fBmagenta\fR, \fB#rgb\fR, or \fB#rrggbb\fR.
+.IP \(bu 4
+\fBboard.web.editor.keymap\fR: The key bindings of the task plan editor of the web board: \fBdefault\fR, \fBvim\fR, or \fBemacs\fR (default: \fBdefault\fR).
+.IP \(bu 4
+\fBproject.relay.url\fR: The default agent relay of the boards (see \fB--agent-relay\fR).
+.RE 0
+.SH "ENVIRONMENT"
+.RS 0
+.IP \(bu 4
+\fBEDITOR\fR: The text editor of the terminal board for \fBe\fR and \fBN\fR (default: \fBvi\fR), run through the shell, so a value with arguments is supported.
+.IP \(bu 4
+\fBASE_AGENT_RELAY_TOKEN\fR: The bearer token of an agent relay URL without an embedded token.
+.RE 0
+.SH "FILES"
+.RS 0
+.IP \(bu 4
+\fB.ase/board.yaml\fR: The display state of the boards in the project root: separately for the terminal board (\fBtui\fR) and the web board (\fBweb\fR), the shown \fBview\fR (\fBlanes\fR, \fBgraph\fR, \fBstats\fR, \fBagents\fR, or \fBflow\fR), the \fBminimized\fR lanes, the \fBcollapsed\fR phases, and whether the task \fBtitles\fR are wrapped onto multiple lines, the key hint lines are shown (\fBkeys\fR), and the graph shows the \fBstandalone\fR tasks.
+.sp
+The web state is shared by all browsers and tabs showing the web board. It never holds task content, and is covered by the self-ignoring \fB.ase/.gitignore\fR.
+.RE 0
+.SH "EXIT STATUS"
+.P
+The command exits with status \fB0\fR once the terminal board is quit, the text overview is printed, resp. the web board is opened, and with status \fB1\fR on any error (e.g. an \fIASE\fR service without web board on \fB--web\fR).
+.SH "EXAMPLES"
+.P
+.RS 2
+.nf
+# show the interactive terminal board
+$ ase task board
+
+# show the web board in the browser
+$ ase task board --web
+
+# print the lane overview, including the agents of a remote agent relay
+$ ase task board --text --agent-relay ase://relay.example.com:42043
+.fi
+.RE
+.SH "SEE ALSO"
+.P
+\fBase\fR(1), \fBase-task\fR(1), \fBase-task-store\fR(1), \fBase-agent\fR(1), \fBase-agent-editor\fR(1), \fBase-agent-relay\fR(1), \fBase-service\fR(1), \fBase-config\fR(1).
+.SH "AUTHOR"
+.P
+Dr. Ralf S. Engelschall \fI\(larse@engelschall.com\(ra\fR

package/dst/man/ase-task-delete.1

@@ -0,0 +1,35 @@
+.TH "ASE-TASK-DELETE" "1" "October 2026" "2.0.1" "Agentic Software Engineering (ASE)"
+.SH "NAME"
+\fBase-task-delete\fR - Delete a Task Plan
+.SH "SYNOPSIS"
+.P
+\fBase task delete\fR \[lB]\fB-h\fR|\fB--help\fR\[rB] \fIid\fR
+.SH "DESCRIPTION"
+.P
+\fBase task delete\fR deletes the task plan with the given \fIid\fR, including all its attachments, from the task store (see \fBase-task\fR(1)). For a \fBseq\fR task id scheme, the sequence number of the deleted task is never reused by \fBase-task-newid\fR(1), as it raises the high-water mark of the sequence numbers of the project. References to the deleted task in the \fBAfter\fR keys of other task plans are left alone.
+.SH "OPTIONS"
+.RS 0
+.IP \(bu 4
+\[lB]\fB-h\fR|\fB--help\fR\[rB]: Show usage information and exit.
+.RE 0
+.SH "ARGUMENTS"
+.RS 0
+.IP \(bu 4
+\fIid\fR: The id of the task, matching \fB\[lB]A-Za-z0-9#\[rB]\[lB]A-Za-z0-9#_-\[rB]*\fR.
+.RE 0
+.SH "EXIT STATUS"
+.P
+\fB0\fR if the task existed and was deleted, \fB1\fR if no such task existed (reported as \fBtask: no task "\fR\fIid\fR\fB" to remove\fR) or on any error.
+.SH "EXAMPLES"
+.P
+.RS 2
+.nf
+$ ase task delete json-export
+.fi
+.RE
+.SH "SEE ALSO"
+.P
+\fBase\fR(1), \fBase-task\fR(1), \fBase-task-purge\fR(1), \fBase-task-rename\fR(1).
+.SH "AUTHOR"
+.P
+Dr. Ralf S. Engelschall \fI\(larse@engelschall.com\(ra\fR

package/dst/man/ase-task-edit.1

@@ -0,0 +1,46 @@
+.TH "ASE-TASK-EDIT" "1" "October 2026" "2.0.1" "Agentic Software Engineering (ASE)"
+.SH "NAME"
+\fBase-task-edit\fR - Edit a Task Plan in the Editor
+.SH "SYNOPSIS"
+.P
+\fBase task edit\fR \[lB]\fB-h\fR|\fB--help\fR\[rB] \fIid\fR
+.SH "DESCRIPTION"
+.P
+\fBase task edit\fR opens the task plan with the given \fIid\fR of the task store (see \fBase-task\fR(1)) in the editor defined by \fB$EDITOR\fR, else \fB$VISUAL\fR (falling back to \fBvi\fR), run through the shell (so a value with arguments is supported). As the task store is not necessarily local, the plan is round-tripped through a temporary file \fBase-task-\fR\fIXXXXXX\fR\fB/\fR\fIid\fR\fB.md\fR below the system temporary directory. A not yet existing plan starts as its minimal frontmatter (just the \fBType\fR and \fBId\fR keys).
+.P
+After the editor exits, an unchanged text is not saved at all. A changed text is saved like by \fBase-task-save\fR(1), i.e., checked against the task lifecycle model, where the save is \fIconditional\fR on the plan as loaded (resp. create-only for a not yet existing plan), so a change of the task in the meantime (e.g., by an agent) is never overwritten.
+.P
+A changed \fBId\fR frontmatter key renames the task after the save, like \fBase-task-rename\fR(1), where an already existing target id is refused before anything is saved. An id not conforming to the task id scheme of the project is warned about.
+.P
+If the save fails because the task was changed in the meantime, the edits are not saved, but kept in the temporary file, whose path is reported. On any other failure (e.g., an unreachable status), the error is reported and, on a terminal, \fBre-edit? \[lB]Y/n\[rB]\fR is asked: by default the editor is opened again on the edited text, while \fBn\fR (and a non-interactive standard input) gives up, keeping the edits in the temporary file, too.
+.SH "OPTIONS"
+.RS 0
+.IP \(bu 4
+\[lB]\fB-h\fR|\fB--help\fR\[rB]: Show usage information and exit.
+.RE 0
+.SH "ARGUMENTS"
+.RS 0
+.IP \(bu 4
+\fIid\fR: The id of the task, matching \fB\[lB]A-Za-z0-9#\[rB]\[lB]A-Za-z0-9#_-\[rB]*\fR.
+.RE 0
+.SH "ENVIRONMENT"
+.RS 0
+.IP \(bu 4
+\fBEDITOR\fR, \fBVISUAL\fR: The editor command (default: \fBvi\fR).
+.RE 0
+.SH "EXIT STATUS"
+.P
+\fB0\fR on success (also for an unchanged text), \fB1\fR if the edits could not be saved.
+.SH "EXAMPLES"
+.P
+.RS 2
+.nf
+$ EDITOR="code --wait" ase task edit json-export
+.fi
+.RE
+.SH "SEE ALSO"
+.P
+\fBase\fR(1), \fBase-task\fR(1), \fBase-task-save\fR(1), \fBase-task-rename\fR(1), \fBase-task-view\fR(1), \fBase-task-board\fR(1), \fBvi\fR(1).
+.SH "AUTHOR"
+.P
+Dr. Ralf S. Engelschall \fI\(larse@engelschall.com\(ra\fR

package/dst/man/ase-task-idscheme.1

@@ -0,0 +1,65 @@
+.TH "ASE-TASK-IDSCHEME" "1" "October 2026" "2.0.1" "Agentic Software Engineering (ASE)"
+.SH "NAME"
+\fBase-task-idscheme\fR - Get or Set the Task Id Scheme
+.SH "SYNOPSIS"
+.P
+\fBase task idscheme\fR \[lB]\fB-h\fR|\fB--help\fR\[rB] \[lB]\fIscheme\fR\[rB]
+.SH "DESCRIPTION"
+.P
+\fBase task idscheme\fR gets or sets the task id scheme of the current project in the task store (see \fBase-task\fR(1)), i.e., the scheme after which \fBase-task-newid\fR(1) generates new task ids (see \fBTASK ID SCHEMES\fR in \fBase-task\fR(1)).
+.P
+Without \fIscheme\fR, the effective scheme is printed: for a local task store (\fBase:\fR, \fBgithub:\fR, \fBgitlab:\fR, or \fBgitea+\fR\fIscheme\fR\fB:\fR), which always follows the configuration, the \fBproject.task.idscheme\fR configuration (default: \fBslug\fR); for a remote task store (\fBase://\fR or \fBases://\fR), the scheme the project is registered under in the task store, which is shared by all clients of the project and hence registered under \fBproject.task.idscheme\fR on first use only.
+.P
+A configured \fBproject.task.idscheme\fR deviating from the scheme of a remote task store is warned about once per deviation only (tracked in the \fIper-user state directory\fR as \fBtask-lifecycle.json\fR).
+.P
+With \fIscheme\fR, the project in the task store is explicitly switched to this scheme: for a local task store by setting \fBproject.task.idscheme\fR on the \fBproject\fR scope (see \fBase-config\fR(1)), for a remote task store by re-registering the project there. The existing task ids are not changed, but ids not conforming to the new scheme are warned about on their next save, rename, and switch. The switch is logged as \fBtask:
+set task id scheme of project from "\fR\fIfrom\fR\fB" to "\fR\fIscheme\fR\fB"\fR.
+.SH "OPTIONS"
+.RS 0
+.IP \(bu 4
+\[lB]\fB-h\fR|\fB--help\fR\[rB]: Show usage information and exit.
+.RE 0
+.SH "ARGUMENTS"
+.RS 0
+.IP \(bu 4
+\[lB]\fIscheme\fR\[rB]: The task id scheme to switch to:
+.RS 4
+.IP \(bu 4
+\fBslug\fR\[lB]\fB:\fR\fIwords\fR\[rB]: the slug of the first \fIwords\fR (\fB1\fR-\fB16\fR, default: \fB2\fR) words of the task title, e.g., \fBjson-export\fR.
+.IP \(bu 4
+\fBseq\fR\[lB]\fB:\fR\fItemplate\fR\[rB]: a continuously increasing sequence number, rendered through the sprintf-style \fItemplate\fR (default: \fB%d\fR) with exactly one \fB%d\fR or \fB%0\fR\fIwidth\fR\fBd\fR (\fIwidth\fR \fB0\fR-\fB16\fR) and otherwise only the characters \fBA-Z\fR, \fBa-z\fR, \fB#\fR, \fB_\fR, and \fB-\fR (but not starting with \fB_\fR or \fB-\fR), e.g., \fBFOO-%03d\fR or \fB#%d\fR. This scheme is required by the GitHub, GitLab, and Gitea task stores, as their task ids are the issue numbers (e.g., \fBseq:#%d\fR).
+.IP \(bu 4
+\fBany\fR: an arbitrary id, as proposed by the caller.
+.RE 0
+.RE 0
+.SH "FILES"
+.RS 0
+.IP \(bu 4
+\fB.ase/config.yaml\fR: The \fBproject\fR scope configuration receiving \fBproject.task.idscheme\fR on a switch of a local task store.
+.IP \(bu 4
+\fIper-user state directory\fR\fB/task-lifecycle.json\fR: The deviations of the configured task id scheme (and lifecycle model) from the ones of a remote task store already warned about.
+.RE 0
+.SH "EXIT STATUS"
+.P
+\fB0\fR on success, \fB1\fR on an invalid \fIscheme\fR or an unreachable task store.
+.SH "EXAMPLES"
+.P
+.RS 2
+.nf
+# print the effective task id scheme
+$ ase task idscheme
+slug
+
+# switch to sequence numbers like "ASE-007"
+$ ase task idscheme "seq:ASE-%03d"
+
+# switch to issue numbers like "#42" (quoted, as "#" starts a comment)
+$ ase task idscheme "seq:#%d"
+.fi
+.RE
+.SH "SEE ALSO"
+.P
+\fBase\fR(1), \fBase-task\fR(1), \fBase-task-newid\fR(1), \fBase-task-lifecycle\fR(1), \fBase-config\fR(1).
+.SH "AUTHOR"
+.P
+Dr. Ralf S. Engelschall \fI\(larse@engelschall.com\(ra\fR

package/dst/man/ase-task-lifecycle.1

@@ -0,0 +1,57 @@
+.TH "ASE-TASK-LIFECYCLE" "1" "October 2026" "2.0.1" "Agentic Software Engineering (ASE)"
+.SH "NAME"
+\fBase-task-lifecycle\fR - Get or Set the Task Lifecycle Model
+.SH "SYNOPSIS"
+.P
+\fBase task lifecycle\fR \[lB]\fB-h\fR|\fB--help\fR\[rB] \[lB]\fIname\fR\[rB]
+.SH "DESCRIPTION"
+.P
+\fBase task lifecycle\fR gets or sets the task lifecycle model of the current project in the task store (see \fBase-task\fR(1)), i.e., the state machine the \fBStatus\fR frontmatter keys of its task plans follow (see \fBTASK LIFECYCLE MODELS\fR in \fBase-task\fR(1)).
+.P
+Without \fIname\fR, the effective model is printed: for a local task store (\fBase:\fR, \fBgithub:\fR, \fBgitlab:\fR, or \fBgitea+\fR\fIscheme\fR\fB:\fR), which always follows the configuration, the \fBproject.task.lifecycle\fR configuration (default: \fBsolo\fR); for a remote task store (\fBase://\fR or \fBases://\fR), the model the project is registered under in the task store, which is shared by all clients of the project and hence registered under \fBproject.task.lifecycle\fR on first use only.
+.P
+A configured \fBproject.task.lifecycle\fR deviating from the model of a remote task store is warned about once per deviation only (tracked in the \fIper-user state directory\fR as \fBtask-lifecycle.json\fR).
+.P
+With \fIname\fR, the project in the task store is explicitly switched to this model: for a local task store by setting \fBproject.task.lifecycle\fR on the \fBproject\fR scope (see \fBase-config\fR(1)), for a remote task store by re-registering the project there.
+.P
+On every switch of the model, the \fBStatus\fR of the existing task plans is mapped onto the new model: a state also existing in the new model is kept, else the first candidate state existing in the new model wins (for a finished state only a finished one), else the initial state (resp. the first finished state) of the new model is used. For instance, from \fBsolo\fR to \fBteam\fR, \fBOPEN\fR becomes \fBPLANNING\fR and \fBCLOSED\fR becomes \fBIMPLEMENTED\fR, and from \fBenterprise\fR to \fBsolo\fR, \fBPLANNED\fR and \fBIMPLEMENTING\fR become \fBOPEN\fR and \fBINTEGRATED\fR becomes \fBCLOSED\fR.
+.P
+Plans without a \fBStatus\fR key are left alone, as they read as the initial state of any model. The switch is logged as \fBtask: set lifecycle model of project from "\fR\fIfrom\fR\fB" to "\fR\fIname\fR\fB"\fR.
+.SH "OPTIONS"
+.RS 0
+.IP \(bu 4
+\[lB]\fB-h\fR|\fB--help\fR\[rB]: Show usage information and exit.
+.RE 0
+.SH "ARGUMENTS"
+.RS 0
+.IP \(bu 4
+\[lB]\fIname\fR\[rB]: The name of the task lifecycle model to switch to: \fBsolo\fR (the single-phase lifecycle for a local solo developer), \fBteam\fR (the two-phase lifecycle for a distributed small team), or \fBenterprise\fR (the four-phase lifecycle for a gated enterprise pipeline).
+.RE 0
+.SH "FILES"
+.RS 0
+.IP \(bu 4
+\fB.ase/config.yaml\fR: The \fBproject\fR scope configuration receiving \fBproject.task.lifecycle\fR on a switch of a local task store.
+.IP \(bu 4
+\fIper-user state directory\fR\fB/task-lifecycle.json\fR: The deviations of the configured lifecycle model (and task id scheme) from the ones of a remote task store already warned about.
+.RE 0
+.SH "EXIT STATUS"
+.P
+\fB0\fR on success, \fB1\fR on an unknown model \fIname\fR or an unreachable task store.
+.SH "EXAMPLES"
+.P
+.RS 2
+.nf
+# print the effective task lifecycle model
+$ ase task lifecycle
+solo
+
+# switch the project to the enterprise lifecycle model
+$ ase task lifecycle enterprise
+.fi
+.RE
+.SH "SEE ALSO"
+.P
+\fBase\fR(1), \fBase-task\fR(1), \fBase-task-status\fR(1), \fBase-task-idscheme\fR(1), \fBase-task-board\fR(1), \fBase-config\fR(1), \fBase-agent\fR(1).
+.SH "AUTHOR"
+.P
+Dr. Ralf S. Engelschall \fI\(larse@engelschall.com\(ra\fR