@rse/ase 2.0.3 → 2.0.4

package/dst/man/ase-statusline.1

@@ -1,189 +0,0 @@
-.TH "ASE-STATUSLINE" "1" "October 2026" "2.0.3" "Agentic Software Engineering (ASE)"
-.SH "NAME"
-\fBase-statusline\fR - Render the Statusline of the Agent Tool
-.SH "SYNOPSIS"
-.P
-\fBase statusline\fR \[lB]\fB-h\fR|\fB--help\fR\[rB] \[lB]\fB-t\fR|\fB--tool\fR \fItool\fR\[rB] \[lB]\fB-w\fR|\fB--width\fR \fIn\fR\[rB] \[lB]\fB-m\fR|\fB--margin\fR \fIn\fR\[rB] \[lB]\fB-p\fR|\fB--padding\fR \fIn\fR\[rB] \[lB]\fB--no-icons\fR\[rB] \[lB]\fB--no-labels\fR\[rB] \[lB]\fIline\fR \[lB]...\[rB]\[rB]
-.SH "DESCRIPTION"
-.P
-\fBase statusline\fR renders the statusline of \fIAnthropic Claude Code CLI\fR or \fIGitHub Copilot CLI\fR from the JSON payload the agent tool passes on standard input, and writes the ANSI-colored result on standard output. It is intended to be configured as the \fBstatusLine\fR command in the \fBsettings.json\fR of \fIAnthropic Claude Code CLI\fR resp. as the \fBstatusLine.command\fR entry of \fB~/.copilot/settings.json\fR of \fIGitHub Copilot CLI\fR (usually via \fBase setup statusline activate\fR, see \fBase-setup-statusline\fR(1)), and not to be invoked directly by end users.
-.P
-The output is composed from one or more template \fIline\fR arguments, each rendered as one output line (or more, see \fBWRAPPING\fR). A \fIline\fR may contain literal characters, \fB%\fR-prefixed placeholders (see \fBPLACEHOLDERS\fR), and color markup (see \fBCOLORS\fR). Without any \fIline\fR, the single default line \fB%m %e %t\fR is rendered.
-.P
-Each placeholder is rendered as an optional icon glyph, an optional label followed by \fB: \fR, and the value in bold, e.g., \fB⚙ model:
-\fR\fBOpus\fR. A \fB%\fR followed by any other character is emitted literally.
-.P
-Under \fB--tool copilot\fR, the top-level \fBcwd\fR field of the payload is mapped onto \fBworkspace.current_dir\fR, and, as \fIGitHub Copilot CLI\fR passes no \fBeffort\fR field but embeds the reasoning effort as a \fB\[pc]\fR separated segment of \fBmodel.display_name\fR (e.g., \fBgpt-5.4 (2x) \[pc] high \[pc]
-1M context\fR), the segment matching a known effort level (\fBlow\fR, \fBmedium\fR, \fBhigh\fR, \fBxhigh\fR, or \fBmax\fR) is split off again, so \fB%m\fR renders the plain model and \fB%e\fR the effort.
-.P
-When run inside a \fItmux\fR(1) pane (i.e., with \fBTMUX\fR and \fBTMUX_PANE\fR set), the resolved task id is additionally published as the per-pane user option \fB@ase_task_id\fR of the pane, so external tools can pick it up via \fB#{@ase_task_id}\fR.
-.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-t\fR|\fB--tool\fR \fItool\fR\[rB]: Select the agent tool producing the payload: \fBclaude\fR (\fIAnthropic Claude Code CLI\fR) or \fBcopilot\fR (\fIGitHub Copilot CLI\fR) (default: the value of \fBASE_TOOL\fR, else \fBclaude\fR). The value \fBcodex\fR is rejected with an error, as \fIOpenAI Codex CLI\fR has no scriptable custom statusline mechanism, and any other value is invalid.
-.IP \(bu 4
-\[lB]\fB-w\fR|\fB--width\fR \fIn\fR\[rB]: Force the terminal width to \fIn\fR characters, a non-negative integer (default: \fB0\fR, i.e., auto-detect the width of the controlling terminal via \fBtput cols\fR on \fB/dev/tty\fR, as standard output is a pipe under the agent tool).
-.IP \(bu 4
-\[lB]\fB-m\fR|\fB--margin\fR \fIn\fR\[rB]: Reduce the maximum used terminal width by \fIn\fR characters on each side, a non-negative integer (default: \fB2\fR). The margin only shrinks the width budget and emits no characters.
-.IP \(bu 4
-\[lB]\fB-p\fR|\fB--padding\fR \fIn\fR\[rB]: Pad each non-empty rendered line with \fIn\fR spaces on the left and right side, a non-negative integer (default: \fB0\fR). In contrast to the margin, the padding spaces are actually emitted (and hence also shrink the width budget). Empty lines stay unpadded. Under \fB--tool
-copilot\fR, a padded output is prefixed with a zero-width space, so the first line keeps its indentation.
-.IP \(bu 4
-\[lB]\fB--no-icons\fR\[rB]: Disable the leading icon glyph (e.g., \fB※\fR, \fB⚑\fR, or \fB⚙\fR) of each placeholder rendering.
-.IP \(bu 4
-\[lB]\fB--no-labels\fR\[rB]: Disable the textual label (e.g., \fBuser:\fR, \fBproject:\fR, or \fBmodel:\fR) in front of the bold value of each placeholder rendering.
-.RE 0
-.SH "ARGUMENTS"
-.RS 0
-.IP \(bu 4
-\[lB]\fIline\fR \[lB]...\[rB]\[rB]: The template lines (default: \fB%m %e %t\fR). Each argument yields its own output line. Quote each line for the shell.
-.RE 0
-.SH "PLACEHOLDERS"
-.P
-The following placeholders are recognized. Unless stated otherwise, a placeholder is always rendered. A placeholder marked as \fIsuppressed\fR is silently omitted (including its icon and label) if its source is missing, e.g., in older agent tool versions or in synthetic payloads.
-.P
-Scope:
-.RS 0
-.IP \(bu 4
-\fB%u\fR: The user (\fBUSER\fR, else \fBLOGNAME\fR, else \fBunknown\fR), with icon \fB※\fR.
-.IP \(bu 4
-\fB%p\fR: The project id, derived from the basename of the current directory of the workspace (\fBworkspace.current_dir\fR), with icon \fB⚑\fR.
-.IP \(bu 4
-\fB%T\fR: The active task id of the session (from its internal session state), else \fBASE_TASK_ID\fR, else \fBdefault\fR, with icon \fB◉\fR.
-.IP \(bu 4
-\fB%s\fR: The session id (\fBsession_id\fR, else \fBunknown\fR), with icon \fB⏻\fR.
-.RE 0
-.P
-Model:
-.RS 0
-.IP \(bu 4
-\fB%m\fR: The model (\fBmodel.display_name\fR), with icon \fB⚙\fR.
-.IP \(bu 4
-\fB%e\fR: The reasoning effort (\fBeffort.level\fR, else the effort segment of the \fIGitHub Copilot CLI\fR model, else \fBunknown\fR), with icon \fB⚒\fR.
-.IP \(bu 4
-\fB%t\fR: Whether extended thinking is enabled (\fBthinking.enabled\fR), as \fByes\fR or \fBno\fR, with icon \fB⚛\fR.
-.RE 0
-.P
-Output:
-.RS 0
-.IP \(bu 4
-\fB%O\fR: The output style (\fBoutput_style.name\fR), with icon \fB\[==]\fR, \fIsuppressed\fR.
-.IP \(bu 4
-\fB%P\fR: The persona style (\fBagent.persona\fR), with icon \fB☯\fR, \fIsuppressed\fR if empty.
-.IP \(bu 4
-\fB%h\fR: The guidance level (\fBagent.guidance\fR), with icon \fB▶\fR, \fIsuppressed\fR if empty.
-.IP \(bu 4
-\fB%B\fR: The project boxing transparency (\fBproject.boxing\fR), with icon \fB▢\fR, \fIsuppressed\fR if empty.
-.IP \(bu 4
-\fB%L\fR: The project task lifecycle model (\fBproject.task.lifecycle\fR), with icon \fB⟳\fR, \fIsuppressed\fR if empty.
-.sp
-The values of \fB%P\fR, \fB%h\fR, \fB%B\fR, and \fB%L\fR are resolved from the \fIASE\fR configuration cascade of the session (\fBsession:\fR\fIid\fR), falling back to the environment variables \fBASE_PERSONA_STYLE\fR, \fBASE_GUIDANCE_LEVEL\fR, \fBASE_PROJECT_BOXING\fR, and \fBASE_PROJECT_TASK_LIFECYCLE\fR.
-.RE 0
-.P
-Context:
-.RS 0
-.IP \(bu 4
-\fB%c\fR: The context usage (\fBcontext_window.used_percentage\fR) as a progress bar of 20 cells (\fB█\fR filled, \fB░\fR empty) plus the percentage, with icon \fB◔\fR.
-.IP \(bu 4
-\fB%C\fR: The current and the maximum context tokens, e.g., \fB334.0k/1.0M\fR, with icon \fB◆\fR. The current tokens are taken from \fBcontext_window.current_context_tokens\fR, else \fBlast_call_input_tokens\fR, else \fBtotal_input_tokens\fR; the maximum from \fBcontext_window.displayed_context_limit\fR, else \fBcontext_window_size\fR, else derived from the current tokens and the used percentage. \fISuppressed\fR without a maximum.
-.RE 0
-.P
-Rate limits:
-.RS 0
-.IP \(bu 4
-\fB%S\fR: The used percentage of the 5-hour rate-limit window, with icon \fB⏲\fR, or \fB-\fR if unknown.
-.IP \(bu 4
-\fB%D\fR: The time until the reset of the 5-hour window, e.g., \fB4hr 27m\fR, with icon \fB⏱\fR, or \fB-\fR if unknown.
-.IP \(bu 4
-\fB%W\fR: The used percentage of the 7-day rate-limit window, with icon \fB⏲\fR, or \fB-\fR if unknown.
-.IP \(bu 4
-\fB%Q\fR: The time until the reset of the 7-day window, e.g., \fB6d 12hr 7m\fR, with icon \fB⏱\fR, or \fB-\fR if unknown.
-.sp
-The windows are taken from \fBrate_limits.five_hour\fR and \fBrate_limits.seven_day\fR of the payload. If the payload carries none, the model matches \fBgpt-*\fR, and a template references one of these placeholders, the windows are instead fetched from the \fIChatGPT\fR backend with the credential stored by \fIOpenAI Codex CLI\fR (\fB$CODEX_HOME/auth.json\fR, default \fB~/.codex/auth.json\fR), with a timeout of 3 seconds, and cached (also on failure) for 60 seconds.
-.RE 0
-.P
-Costs:
-.RS 0
-.IP \(bu 4
-\fB%H\fR: The wall-clock duration of the session (\fBcost.total_duration_ms\fR) as hours and minutes, e.g., \fB92hr 40m\fR, with icon \fB⏱\fR, \fIsuppressed\fR if zero or missing.
-.IP \(bu 4
-\fB%X\fR: The session costs in USD (\fBcost.total_cost_usd\fR), e.g., \fB$54.44\fR, with icon \fB$\fR, \fIsuppressed\fR.
-.RE 0
-.P
-Version control:
-.RS 0
-.IP \(bu 4
-\fB%a\fR: The lines added in this session (\fBcost.total_lines_added\fR, else \fB0\fR), with icon \fB\[c+]\fR.
-.IP \(bu 4
-\fB%r\fR: The lines removed in this session (\fBcost.total_lines_removed\fR, else \fB0\fR), with icon \fB⊖\fR.
-.IP \(bu 4
-\fB%b\fR: The Git branch of the workspace directory, or \fBno git\fR outside of a Git working tree, with icon \fB⎇\fR.
-.IP \(bu 4
-\fB%g\fR: The changed lines of the Git working tree against \fBHEAD\fR, e.g., \fB+42/-7\fR, with icon \fB\[+-]\fR, \fIsuppressed\fR outside of a Git working tree.
-.IP \(bu 4
-\fB%G\fR: The number of untracked files of the Git working tree, with icon \fB⁈\fR, \fIsuppressed\fR outside of a Git working tree.
-.IP \(bu 4
-\fB%d\fR: The full path of the workspace directory, with icon \fB▶\fR, \fIsuppressed\fR.
-.RE 0
-.P
-Resources and versions:
-.RS 0
-.IP \(bu 4
-\fB%M\fR: The used and total memory of the host, e.g., \fB33.2G/64.0G\fR, with icon \fB⛁\fR.
-.IP \(bu 4
-\fB%V\fR: The agent tool and \fIASE\fR versions (\fBversion\fR of the payload), e.g., \fBclaude/2.1.90 ase/1.0.7\fR, with icon \fB⎈\fR.
-.RE 0
-.SH "COLORS"
-.P
-A \fIline\fR may contain the markup \fB<\fR\fIcolor\fR\fB>\fR...\fB</\fR\fIcolor\fR\fB>\fR to colorize its text (including rendered placeholders), where \fIcolor\fR is one of \fBblack\fR, \fBred\fR, \fBgreen\fR, \fByellow\fR, \fBblue\fR, \fBmagenta\fR, \fBcyan\fR, \fBwhite\fR, or \fBdefault\fR. A closing tag (of any recognized color name) ends the colored span, returning to the default foreground color. Spans do not nest: an opening tag inside a span is removed, but ignored. A span still open at the end of a line ends there. A tag with an unrecognized color name is kept literally in the output.
-.SH "WRAPPING"
-.P
-Each rendered line is automatically wrapped before the next chunk (a literal character or a whole placeholder rendering) which would exceed the width budget, where the budget is the terminal width (see \fB--width\fR) reduced by \fB2 *\fR (\fImargin\fR \fB+\fR \fIpadding\fR) characters. Without a known terminal width, no wrapping happens.
-.SH "INPUT"
-.P
-The input is the standard statusline JSON payload of the agent tool, of which the fields \fBworkspace.current_dir\fR (resp. \fBcwd\fR for \fIGitHub Copilot CLI\fR), \fBsession_id\fR, \fBversion\fR, \fBmodel.display_name\fR, \fBeffort.level\fR, \fBthinking.enabled\fR, \fBoutput_style.name\fR, \fBcontext_window.*\fR, \fBrate_limits.five_hour\fR and \fBrate_limits.seven_day\fR (each with \fBused_percentage\fR and \fBresets_at\fR), and \fBcost.total_cost_usd\fR, \fBcost.total_duration_ms\fR, \fBcost.total_lines_added\fR, and \fBcost.total_lines_removed\fR are used.
-.P
-Invalid JSON is an error.
-.SH "ENVIRONMENT"
-.RS 0
-.IP \(bu 4
-\fBASE_TOOL\fR: The default of \fB--tool\fR.
-.IP \(bu 4
-\fBASE_TASK_ID\fR, \fBASE_PERSONA_STYLE\fR, \fBASE_GUIDANCE_LEVEL\fR, \fBASE_PROJECT_BOXING\fR, \fBASE_PROJECT_TASK_LIFECYCLE\fR: The fallbacks of \fB%T\fR, \fB%P\fR, \fB%h\fR, \fB%B\fR, and \fB%L\fR.
-.IP \(bu 4
-\fBUSER\fR, \fBLOGNAME\fR: The user of \fB%u\fR.
-.IP \(bu 4
-\fBCODEX_HOME\fR: The configuration directory of \fIOpenAI Codex CLI\fR (default: \fB~/.codex\fR), holding the credential \fBauth.json\fR for the rate limits of the \fBgpt-*\fR models.
-.IP \(bu 4
-\fBTMUX\fR, \fBTMUX_PANE\fR: The \fItmux\fR pane to publish the task id \fB@ase_task_id\fR to.
-.RE 0
-.SH "FILES"
-.RS 0
-.IP \(bu 4
-\fIper-user state directory\fR\fB/statusline-codex-usage.json\fR: The cache of the rate-limit windows fetched for the \fBgpt-*\fR models.
-.IP \(bu 4
-\fIper-user state directory\fR\fB/session/\fR\fIid\fR\fB/config.yaml\fR and \fBstate.yaml\fR: The configuration and the internal state (active task) of the session.
-.RE 0
-.SH "EXIT STATUS"
-.P
-\fB0\fR on success, \fB1\fR on invalid JSON, an invalid option value, or \fB--tool codex\fR.
-.SH "EXAMPLES"
-.P
-.RS 2
-.nf
-# render two lines from a sample payload
-$ echo '{"model":{"display_name":"Opus"},"context_window":{"used_percentage":42}}' | \[rs]
-  ase statusline "%m %e %t" "<blue>%c</blue>"
-
-# a compact statusline without icons and labels, padded by one space
-$ ase statusline --no-icons --no-labels -p 1 "%p %T %b %g" "%m %c %X"
-.fi
-.RE
-.SH "SEE ALSO"
-.P
-\fBase\fR(1), \fBase-setup-statusline\fR(1), \fBase-config\fR(1), \fBtmux\fR(1).
-.SH "AUTHOR"
-.P
-Dr. Ralf S. Engelschall \fI\(larse@engelschall.com\(ra\fR

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

@@ -1,71 +0,0 @@
-.TH "ASE-TASK-ASSIGN" "1" "October 2026" "2.0.3" "Agentic Software Engineering (ASE)"
-.SH "NAME"
-\fBase-task-assign\fR - Assign a Task
-.SH "SYNOPSIS"
-.P
-\fBase task assign\fR \[lB]\fB-h\fR|\fB--help\fR\[rB] \[lB]\fB-s\fR|\fB--session\fR \fIid\fR\[rB] \[lB]\fIid\fR\[lB]\fB:\fR\[rB]\[rB] \fIassignee\fR
-.SH "DESCRIPTION"
-.P
-\fBase task assign\fR assigns the task plan with the given \fIid\fR in the task store (see \fBase-task\fR(1)) by setting its \fBAssignee\fR frontmatter key to \fIassignee\fR, where \fBme\fR stands for the current user and \fBnone\fR removes the key. The change is done in a conditional save of the task plan (retried on a concurrent change of the task), leaving the \fBModified\fR key alone, as it tracks the changes of the plan body only. The change is logged as \fBtask: assigned "\fR\fIid\fR\fB" from "\fR\fIfrom\fR\fB" to
-"\fR\fIto\fR\fB"\fR.
-.P
-If the configuration key \fBproject.users\fR (see \fBase-config\fR(1)) lists the known users, an \fIassignee\fR which is neither \fBnone\fR, the current user, one of these users, nor the name of an agent present at the agent relay (see \fBase-agent-relay\fR(1)) is still assigned, but with the warning \fBtask: unknown assignee "\fR\fIassignee\fR\fB" (neither one of the
-users of "project.users" nor a known agent)\fR (with \fB--session\fR reported as part of its notice).
-.P
-With \fB--session\fR, the assignment is instead done on behalf of an agent tool session through the running \fBase service\fR of the project (see \fBase-service\fR(1)), which handles the \fIAI usage window\fR of the task, too (only if the AI usage accounting is enabled via \fBtelemetry.enabled\fR, else a notice is reported):
-.RS 0
-.IP \(bu 4
-Assigning the task to oneself opens its usage window (or attaches the session to an already open one).
-.IP \(bu 4
-Assigning the task to anybody else closes its usage window and, after a grace period of 10 seconds for late telemetry, atomically adds the usage accumulated from the OTLP records of its sessions (see \fBase-setup-telemetry\fR(1)) to the YAML data of the usage attachment of the task (\fBType: application/yaml; kind="usage"\fR, created on the first booking): \fBtime.ai\fR (the AI request time in minutes), \fBtime.hr\fR (the human time in minutes, i.e., the whole real time of the window), \fBtime.real\fR (the wall-clock time of the window in minutes), \fBtoken.cread\fR, \fBtoken.cwrite\fR, \fBtoken.input\fR, and \fBtoken.output\fR (the disjoint token counts of the cache reads, cache writes, uncached input, and output), \fBcost.ai\fR (the AI costs in USD, as reported by the agent tool, else derived from \fBtelemetry.prices.ai\fR), and \fBcost.hr\fR (the human costs in USD, at the hourly rate of the assignee in \fBtelemetry.prices.hr\fR).
-.RE 0
-.P
-A usage window also closes when its last session ends, and when the \fBAssignee\fR of its task is changed elsewhere while the task is the active task of an attached session. Conversely, once the \fBAssignee\fR of a task is changed to oneself elsewhere (e.g., on the task board), the service opens its window (starting \fIpaused\fR) and attaches every session of the project whose active task it is.
-.P
-Unless disabled via \fBtelemetry.implicit\fR, the service also accounts an \fIunassigned\fR task \fIimplicitly\fR: it opens its window (starting \fIpaused\fR) and attaches every interactive session of the project whose active task it is, without setting the \fBAssignee\fR, but only as long as the task stays the active task of the session and unassigned (task \fBdefault\fR excluded). Assigning such a task to oneself turns the implicit attachment into a regular one, and unassigning a task assigned to oneself elsewhere turns its attachments into implicit ones.
-.P
-Open windows additionally book every \fBtelemetry.service.interval\fR minutes, pause after \fBtelemetry.service.idle\fR minutes without any AI request of an attached session (resumed silently by the next one, without accounting the paused gap), and are closed and booked after 7 days without any activity. The result is logged together with the action on the usage window and the booked usage. This is what the \fBase_task_assign\fR MCP tool of the \fBase-task-assign\fR skill does for the current session.
-.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-s\fR|\fB--session\fR \fIid\fR\[rB]: Assign the task on behalf of the agent tool session \fIid\fR through the running \fBase service\fR of the project (whose port is read from \fB.ase/service.yaml\fR), which additionally handles the AI usage window of the task (see \fBDESCRIPTION\fR). The service is not started on demand, so it has to run already.
-.RE 0
-.SH "ARGUMENTS"
-.RS 0
-.IP \(bu 4
-\[lB]\fIid\fR\[lB]\fB:\fR\[rB]\[rB]: The id of the task (default: \fB$ASE_TASK_ID\fR, else \fBdefault\fR). A trailing colon is stripped. If only a single argument is given, it is taken as \fIassignee\fR, unless it has a trailing colon (then it is the \fIid\fR, and the missing \fIassignee\fR is an error).
-.IP \(bu 4
-\fIassignee\fR: The new assignee of the task: \fBme\fR for the current user (the value of \fB$USER\fR, else \fB$LOGNAME\fR, else \fBunknown\fR), \fBnone\fR to remove the \fBAssignee\fR key, or any other non-empty single-line name without commas.
-.RE 0
-.SH "ENVIRONMENT"
-.RS 0
-.IP \(bu 4
-\fBASE_TASK_ID\fR: The default task id (default: \fBdefault\fR).
-.IP \(bu 4
-\fBUSER\fR, \fBLOGNAME\fR: The current user, as substituted for \fBme\fR.
-.RE 0
-.SH "EXIT STATUS"
-.P
-\fB0\fR on success, \fB1\fR if the \fIassignee\fR is missing or invalid, no such task exists, or (with \fB--session\fR) the service is not reachable.
-.SH "EXAMPLES"
-.P
-.RS 2
-.nf
-# take the task "json-export"
-$ ase task assign json-export me
-
-# give the task back
-$ ase task assign json-export none
-
-# hand the task of $ASE_TASK_ID over to the implementer agent
-$ ase task assign implementer
-.fi
-.RE
-.SH "SEE ALSO"
-.P
-\fBase\fR(1), \fBase-task\fR(1), \fBase-service\fR(1), \fBase-setup-telemetry\fR(1), \fBase-config\fR(1), \fBase-agent\fR(1).
-.SH "AUTHOR"
-.P
-Dr. Ralf S. Engelschall \fI\(larse@engelschall.com\(ra\fR