@rse/ase 2.0.2 → 2.0.4

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

@@ -0,0 +1,46 @@
+# ase-task-delete(1) -- Delete a Task Plan
+
+## SYNOPSIS
+
+`ase task delete`
+\[`-h`|`--help`\]
+*id*
+
+## DESCRIPTION
+
+**ase task delete** deletes the task plan with the given *id*,
+including all its attachments, from the task store (see
+`ase-task`(1)). For a `seq` task id scheme, the sequence number of the
+deleted task is never reused by `ase-task-newid`(1), as it raises the
+high-water mark of the sequence numbers of the project. References to
+the deleted task in the `After` keys of other task plans are left
+alone.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+## ARGUMENTS
+
+- *id*:
+  The id of the task, matching `[A-Za-z0-9#][A-Za-z0-9#_-]*`.
+
+## EXIT STATUS
+
+`0` if the task existed and was deleted, `1` if no such task existed
+(reported as `task: no task "`*id*`" to remove`) or on any error.
+
+## EXAMPLES
+
+```sh
+$ ase task delete json-export
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-task`(1), `ase-task-purge`(1), `ase-task-rename`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

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

@@ -0,0 +1,73 @@
+# ase-task-edit(1) -- Edit a Task Plan in the Editor
+
+## SYNOPSIS
+
+`ase task edit`
+\[`-h`|`--help`\]
+*id*
+
+## DESCRIPTION
+
+**ase task edit** opens the task plan with the given *id* of the task
+store (see `ase-task`(1)) in the editor defined by `$EDITOR`, else
+`$VISUAL` (falling back to `vi`), 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
+`ase-task-`*XXXXXX*`/`*id*`.md` below the system temporary directory.
+A not yet existing plan starts as its minimal frontmatter (just the
+`Type` and `Id` keys).
+
+After the editor exits, an unchanged text is not saved at all. A
+changed text is saved like by `ase-task-save`(1), i.e., checked
+against the task lifecycle model, where the save is *conditional* 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.
+
+A changed `Id` frontmatter key renames the task after the save, like
+`ase-task-rename`(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.
+
+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, `re-edit? [Y/n]` is asked: by
+default the editor is opened again on the edited text, while `n` (and
+a non-interactive standard input) gives up, keeping the edits in the
+temporary file, too.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+## ARGUMENTS
+
+- *id*:
+  The id of the task, matching `[A-Za-z0-9#][A-Za-z0-9#_-]*`.
+
+## ENVIRONMENT
+
+- `EDITOR`, `VISUAL`:
+  The editor command (default: `vi`).
+
+## EXIT STATUS
+
+`0` on success (also for an unchanged text), `1` if the edits could
+not be saved.
+
+## EXAMPLES
+
+```sh
+$ EDITOR="code --wait" ase task edit json-export
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-task`(1), `ase-task-save`(1), `ase-task-rename`(1),
+`ase-task-view`(1), `ase-task-board`(1), `vi`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

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

@@ -0,0 +1,92 @@
+# ase-task-idscheme(1) -- Get or Set the Task Id Scheme
+
+## SYNOPSIS
+
+`ase task idscheme`
+\[`-h`|`--help`\]
+\[*scheme*\]
+
+## DESCRIPTION
+
+**ase task idscheme** gets or sets the task id scheme of the current
+project in the task store (see `ase-task`(1)), i.e., the scheme after
+which `ase-task-newid`(1) generates new task ids (see **TASK ID
+SCHEMES** in `ase-task`(1)).
+
+Without *scheme*, the effective scheme is printed: for a local task
+store (`ase:`, `github:`, `gitlab:`, or `gitea+`*scheme*`:`), which
+always follows the configuration, the `project.task.idscheme`
+configuration (default: `slug`); for a remote task store (`ase://` or
+`ases://`), the scheme the project is registered under in the task
+store, which is shared by all clients of the project and hence
+registered under `project.task.idscheme` on first use only.
+
+A configured `project.task.idscheme` deviating from the scheme of a
+remote task store is warned about once per deviation only (tracked in
+the *per-user state directory* as `task-lifecycle.json`).
+
+With *scheme*, the project in the task store is explicitly switched to
+this scheme: for a local task store by setting `project.task.idscheme`
+on the `project` scope (see `ase-config`(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 `task:
+set task id scheme of project from "`*from*`" to "`*scheme*`"`.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+## ARGUMENTS
+
+- \[*scheme*\]:
+  The task id scheme to switch to:
+    - `slug`\[`:`*words*\]: the slug of the first *words* (`1`-`16`,
+      default: `2`) words of the task title, e.g., `json-export`.
+    - `seq`\[`:`*template*\]: a continuously increasing sequence number,
+      rendered through the sprintf-style *template* (default: `%d`) with
+      exactly one `%d` or `%0`*width*`d` (*width* `0`-`16`) and otherwise
+      only the characters `A-Z`, `a-z`, `#`, `_`, and `-` (but not
+      starting with `_` or `-`), e.g., `FOO-%03d` or `#%d`. This scheme
+      is required by the GitHub, GitLab, and Gitea task stores, as their
+      task ids are the issue numbers (e.g., `seq:#%d`).
+    - `any`: an arbitrary id, as proposed by the caller.
+
+## FILES
+
+- `.ase/config.yaml`:
+  The `project` scope configuration receiving `project.task.idscheme`
+  on a switch of a local task store.
+
+- *per-user state directory*`/task-lifecycle.json`:
+  The deviations of the configured task id scheme (and lifecycle
+  model) from the ones of a remote task store already warned about.
+
+## EXIT STATUS
+
+`0` on success, `1` on an invalid *scheme* or an unreachable task
+store.
+
+## EXAMPLES
+
+```sh
+# 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"
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-task`(1), `ase-task-newid`(1), `ase-task-lifecycle`(1),
+`ase-config`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

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

@@ -0,0 +1,92 @@
+# ase-task-lifecycle(1) -- Get or Set the Task Lifecycle Model
+
+## SYNOPSIS
+
+`ase task lifecycle`
+\[`-h`|`--help`\]
+\[*name*\]
+
+## DESCRIPTION
+
+**ase task lifecycle** gets or sets the task lifecycle model of the
+current project in the task store (see `ase-task`(1)), i.e., the state
+machine the `Status` frontmatter keys of its task plans follow (see
+**TASK LIFECYCLE MODELS** in `ase-task`(1)).
+
+Without *name*, the effective model is printed: for a local task store
+(`ase:`, `github:`, `gitlab:`, or `gitea+`*scheme*`:`), which always
+follows the configuration, the `project.task.lifecycle` configuration
+(default: `solo`); for a remote task store (`ase://` or `ases://`),
+the model the project is registered under in the task store, which is
+shared by all clients of the project and hence registered under
+`project.task.lifecycle` on first use only.
+
+A configured `project.task.lifecycle` deviating from the model of a
+remote task store is warned about once per deviation only (tracked in
+the *per-user state directory* as `task-lifecycle.json`).
+
+With *name*, the project in the task store is explicitly switched to
+this model: for a local task store by setting `project.task.lifecycle`
+on the `project` scope (see `ase-config`(1)), for a remote task store by
+re-registering the project there.
+
+On every switch of the model, the `Status` 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
+`solo` to `team`, `OPEN` becomes `PLANNING` and `CLOSED` becomes
+`IMPLEMENTED`, and from `enterprise` to `solo`, `PLANNED` and
+`IMPLEMENTING` become `OPEN` and `INTEGRATED` becomes `CLOSED`.
+
+Plans without a `Status` key are left alone, as they read as the initial
+state of any model. The switch is logged as
+`task: set lifecycle model of project from "`*from*`" to "`*name*`"`.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+## ARGUMENTS
+
+- \[*name*\]:
+  The name of the task lifecycle model to switch to: `solo` (the
+  single-phase lifecycle for a local solo developer), `team` (the
+  two-phase lifecycle for a distributed small team), or `enterprise`
+  (the four-phase lifecycle for a gated enterprise pipeline).
+
+## FILES
+
+- `.ase/config.yaml`:
+  The `project` scope configuration receiving `project.task.lifecycle`
+  on a switch of a local task store.
+
+- *per-user state directory*`/task-lifecycle.json`:
+  The deviations of the configured lifecycle model (and task id
+  scheme) from the ones of a remote task store already warned about.
+
+## EXIT STATUS
+
+`0` on success, `1` on an unknown model *name* or an unreachable task
+store.
+
+## EXAMPLES
+
+```sh
+# print the effective task lifecycle model
+$ ase task lifecycle
+solo
+
+# switch the project to the enterprise lifecycle model
+$ ase task lifecycle enterprise
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-task`(1), `ase-task-status`(1), `ase-task-idscheme`(1),
+`ase-task-board`(1), `ase-config`(1), `ase-agent`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

package/dst/man/ase-task-list.md

@@ -0,0 +1,86 @@
+# ase-task-list(1) -- List Persisted Task Ids
+
+## SYNOPSIS
+
+`ase task list`
+\[`-h`|`--help`\]
+\[`-v`|`--verbose`\]
+\[`-i`|`--include` *states*\]
+\[`-e`|`--exclude` *states*\]
+
+## DESCRIPTION
+
+**ase task list** lists the ids of the persisted task plans of the
+current project in the task store (see `ase-task`(1)), one per line,
+in natural order (numbers ordered by their value, e.g., `FOO-2` before
+`FOO-10`).
+
+The listed tasks are restricted to those whose lifecycle status
+(the `Status` frontmatter key, or the initial state of the task
+lifecycle model if absent) is in the effective state set of the
+`--include` and `--exclude` options. By default, all tasks except the
+ones in a *finished* state of the task lifecycle model are listed. A
+task whose status is unknown to the task lifecycle model is always
+listed, but warned about.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+- \[`-v`|`--verbose`\]:
+  Annotate each task id with the lifecycle status of its plan, the
+  modification time of its plan as `(YYYY-MM-DD HH:MM)`, its effort
+  size (the T-shirt size `XS`, `S`, `M`, `L`, or `XL` of the valid
+  `Effort` frontmatter key of the plan, else `-`), and its title (the
+  text after `TASK:` of the first `#   TASK:` heading of the plan body,
+  else empty), all separated by a single tab character.
+
+- \[`-i`|`--include` *states*\]:
+  Restrict the listing to the tasks in one of the *states*, a
+  comma-separated list of lifecycle states of the task lifecycle model
+  of the project (given case-insensitively), where the term `finished`
+  expands to the finished states of the model and the term `none` (as
+  well as an empty term) is ignored. An empty list (default: `none`)
+  means all states.
+
+  The states of the models are `OPEN`, `SHELVED`, `CLOSED`, and
+  `CANCELLED` (`solo`), `PLANNING`, `SHELVED`, `IMPLEMENTING`,
+  `STALLED`, `IMPLEMENTED`, and `CANCELLED` (`team`), and `DRAFTED`,
+  `SHELVED`, `PLANNING`, `PLANNED`, `STALLED`, `IMPLEMENTING`,
+  `IMPLEMENTED`, `DECLINED`, `QUALIFYING`, `QUALIFIED`, `DEFERRED`,
+  `INTEGRATING`, `INTEGRATED`, and `CANCELLED` (`enterprise`). A state
+  which is not one of the model is an error.
+
+- \[`-e`|`--exclude` *states*\]:
+  Exclude the tasks in one of the *states* from the listing, a
+  comma-separated list of the same form as for `--include`, applied
+  after `--include` (default: `finished`, i.e., the finished states of
+  the model). Use `none` to exclude nothing. If `--include` and
+  `--exclude` cancel out to an empty state set, this is an error.
+
+## EXIT STATUS
+
+`0` on success, `1` on an error, like an invalid state, an empty
+effective state set, or an unreachable task store.
+
+## EXAMPLES
+
+```sh
+# list all unfinished tasks
+$ ase task list
+
+# list all tasks, including the finished ones, with details
+$ ase task list -v -e none
+
+# list the tasks waiting for their qualification
+$ ase task list -i IMPLEMENTED,DECLINED
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-task`(1), `ase-task-status`(1), `ase-task-board`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

package/dst/man/ase-task-load.md

@@ -0,0 +1,48 @@
+# ase-task-load(1) -- Write a Task Plan to Standard Output
+
+## SYNOPSIS
+
+`ase task load`
+\[`-h`|`--help`\]
+*id*
+
+## DESCRIPTION
+
+**ase task load** loads the task plan with the given *id* from the task
+store (see `ase-task`(1)) and writes it to standard output, in the
+textual task format: the frontmatter block (with its keys in canonical
+order and their values column-aligned), the plan body, and the
+attachment blocks (with their `Data` as literal block scalars). A plan
+in a legacy format is normalized into the current frontmatter shape on
+the fly. If no such task exists, nothing is written.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+## ARGUMENTS
+
+- *id*:
+  The id of the task, matching `[A-Za-z0-9#][A-Za-z0-9#_-]*`.
+
+## EXIT STATUS
+
+`0` on success, also if no such task exists, `1` on an invalid *id*
+or an unreachable task store.
+
+## EXAMPLES
+
+```sh
+# copy a task plan into a file
+$ ase task load json-export >json-export.md
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-task`(1), `ase-task-save`(1), `ase-task-view`(1),
+`ase-task-edit`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

package/dst/man/ase-task-newid.md

@@ -0,0 +1,100 @@
+# ase-task-newid(1) -- Print the Next Free Task Id
+
+## SYNOPSIS
+
+`ase task newid`
+\[`-h`|`--help`\]
+\[`-p`|`--proposal` *id*\]
+\[`-t`|`--taken` *ids*\]
+\[`-v`|`--verbose`\]
+\[*title*\]
+
+## DESCRIPTION
+
+**ase task newid** prints the next free task id according to the
+effective task id scheme of the project (see `ase-task-idscheme`(1)
+and **TASK ID SCHEMES** in `ase-task`(1)), determined by searching all
+existing task ids of the project in the task store, plus the ids given
+via `--taken`, plus the reserved id `default`:
+
+- `slug`\[`:`*words*\]:
+  The slug of the first *words* words of *title* (starting with the
+  first word beginning with a letter, with diacritics stripped,
+  lower-cased, and joined with `-`).
+
+- `seq`\[`:`*template*\]:
+  The highest sequence number of all ids matching *template* plus one,
+  but at least the high-water mark of all ids ever removed (deleted,
+  purged, or renamed) or allocated plus one, so the number of such a
+  task is never reused. Ids not matching the current *template* (e.g.,
+  after a template change) are ignored.
+
+  The allocated number is *reserved* by raising the high-water mark
+  atomically, so a concurrent allocation never yields the same id. The
+  *title* is not used.
+
+- `any`:
+  The proposed id of `--proposal`, sanitized (whitespace runs replaced
+  by `-`, all characters other than `A-Z`, `a-z`, `0-9`, `#`, `_`, and
+  `-` removed, and leading `_` and `-` stripped), else the slug of the
+  first two words of *title*.
+
+A slug or proposed id which is already taken gets a numeric suffix
+`-2`, `-3`, etc. As only a `seq` id is reserved, the first save of the
+new task should be a create-only one (`ase task save --create`, see
+`ase-task-save`(1)), which fails instead of overwriting a concurrently
+created task of the same id.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+- \[`-p`|`--proposal` *id*\]:
+  The proposed task id, honored for the task id scheme `any` only
+  (default: none).
+
+- \[`-t`|`--taken` *ids*\]:
+  A comma-separated list of task ids to consider as taken in addition
+  to the existing ones (default: none), e.g., the ids planned for
+  further tasks not yet saved. Whitespace around the ids is ignored.
+
+- \[`-v`|`--verbose`\]:
+  Instead of the id only, print the three lines `scheme:` (the
+  effective task id scheme), `id:` (the new id), and `match:` (the
+  regular expression matching all ids conforming to the scheme).
+
+## ARGUMENTS
+
+- \[*title*\]:
+  The title of the new task, from which the id is derived for the
+  schemes `slug` and `any` (default: empty). For `slug` (and for `any`
+  without `--proposal`), a title without any word beginning with a
+  letter is an error.
+
+## EXIT STATUS
+
+`0` on success, `1` if no id can be derived (e.g., a missing title)
+or the task store is unreachable.
+
+## EXAMPLES
+
+```sh
+# derive an id from a title under the "slug" scheme
+$ ase task newid "Export the Tasks as JSON"
+export-the
+
+# show the details of the allocation under the "seq:#%d" scheme
+$ ase task newid -v
+scheme: seq:#%d
+id:     #43
+match:  ^#([0-9]+)$
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-task`(1), `ase-task-idscheme`(1), `ase-task-save`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

package/dst/man/ase-task-purge.md

@@ -0,0 +1,49 @@
+# ase-task-purge(1) -- Remove Old Task Plans
+
+## SYNOPSIS
+
+`ase task purge`
+\[`-h`|`--help`\]
+\[*age*\]
+
+## DESCRIPTION
+
+**ase task purge** removes all persisted task plans of the current
+project from the task store (see `ase-task`(1)) whose modification
+time is older than *age*, regardless of their lifecycle status. Each
+removed task is logged as `task: purged "`*id*`"`, or `task: no tasks
+to purge` is logged if none was removed. For a `seq` task id scheme,
+the sequence numbers of the purged tasks are never reused by
+`ase-task-newid`(1).
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+## ARGUMENTS
+
+- \[*age*\]:
+  The maximum age of the task plans to keep, as `<number><unit>`, where
+  *unit* is one of `h` (hour), `d` (day, 24 hours), `m` (month, 30
+  days), or `y` (year, 365 days) (default: `31d`).
+
+## EXIT STATUS
+
+`0` on success (also if no task was removed), `1` on a malformed *age*
+or an unreachable task store.
+
+## EXAMPLES
+
+```sh
+# remove all tasks not modified within the last half year
+$ ase task purge 6m
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-task`(1), `ase-task-delete`(1), `ase-task-list`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

package/dst/man/ase-task-rename.md

@@ -0,0 +1,69 @@
+# ase-task-rename(1) -- Rename a Task Plan
+
+## SYNOPSIS
+
+`ase task rename`
+\[`-h`|`--help`\]
+*old-id*
+*new-id*
+
+## DESCRIPTION
+
+**ase task rename** renames the task plan with the given *old-id* to
+*new-id* in the task store (see `ase-task`(1)), rewriting the `Id`
+frontmatter key inside the plan.
+
+All references to *old-id* in the `After` frontmatter keys of all
+other task plans of the project are rewritten to *new-id* (in the
+frontmatter only, so their `Modified` key stays untouched), and the
+number of updated plans is reported. For an *explicit epic*, i.e., a
+task whose `Group` key equals its old (or already its new) id, its own
+`Group` key and those of all its member task plans are rewritten, too,
+while otherwise the group names are left untouched, as they form a
+namespace of their own.
+
+The task itself is renamed first, so an interruption never leaves both
+ids behind; a failure to update the references afterwards is reported
+together with the plans left behind.
+
+For a `seq` task id scheme, the sequence number of *old-id* is never
+reused by `ase-task-newid`(1). A *new-id* not conforming to the task
+id scheme of the project is warned about. Finally, the rename is
+reported to the `ase service` of the project (if it ever ran, i.e.,
+`.ase/service.yaml` exists), so its AI usage windows follow the task;
+a failure of this report is only warned about.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+## ARGUMENTS
+
+- *old-id*:
+  The current id of the task, matching `[A-Za-z0-9#][A-Za-z0-9#_-]*`.
+
+- *new-id*:
+  The new id of the task, matching `[A-Za-z0-9#][A-Za-z0-9#_-]*`,
+  which must not be in use already.
+
+## EXIT STATUS
+
+`0` on success, `1` if no such task existed (reported as `task: no
+task "`*old-id*`" to rename`), the *new-id* is already in use, or on
+any other error.
+
+## EXAMPLES
+
+```sh
+$ ase task rename json-export export-json
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-task`(1), `ase-task-edit`(1), `ase-task-newid`(1),
+`ase-task-delete`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>