@rse/ase 1.0.7 → 2.0.0

package/plugin/meta/ase-format-task.md

@@ -1,155 +1,404 @@
 
-Task
-----
+Task Format
+-----------
 
-Every *task* uses a strict and fixed format:
+Every *task* uses a strict and fixed textual format:
 
 <format>
 ---
-Id:         <task-id/>
-Created:    <timestamp-created/>
-Modified:   <timestamp-modified/>
-Status:     <task-status/>
-Properties: <task-properties/>
-Kind:       <task-kind/>
+Type:      text/vnd.ase.task
+Id:        <task-id/>
+Created:   <timestamp-created/>
+Modified:  <timestamp-modified/>
+Group:     <task-group/>
+Phase:     <task-phase/>
+After:     <task-after/>
+Status:    <task-status/>
+Assignee:  <task-assignee/>
+Kind:      <task-kind/>
+Effort:    <task-effort/>
+Tags:      <task-tags/>
+Source:    <task-source/>
+Changeset: <task-changeset/>
+Target:    <task-target/>
 ---
 
-#   TASK: <title/>
+#   TASK: <task-title/>
 
-##  CONTEXT
+##  SPECIFICATION (WHAT)
 
--   **WHAT**: <summary-what/>
+-   [ ] DOM: **[...]**: [...]
 
--   **WHY**: <summary-why/>
+-   [...]
 
-##  CHANGES
+-   [ ] IFC: **[...]**: [...]
 
 -   [...]
 
+##  DESIGN (HOW)
+
+-   [ ] ARC: **[...]**: [...]
+
 -   [...]
 
-##  VERIFICATION
+-   [ ] IMP: **[...]**: [...]
 
 -   [...]
 
+##  VERIFICATION (WHEN)
+
+-   [ ] REG: **[...]**: [...]
+
 -   [...]
 
+-   [ ] CON: **[...]**: [...]
+
+-   [...]
+
+---
+Type:      <task-attachment-type/>
+Desc:      <task-attachment-desc/>
+Created:   <task-attachment-created/>
+Modified:  <task-attachment-modified/>
+Data:      |4+
+    <task-attachment-payload/>
+---
+Type:      <task-attachment-type/>
+Desc:      <task-attachment-desc/>
+Created:   <task-attachment-created/>
+Modified:  <task-attachment-modified/>
+File:      <task-attachment-file/>
 </format>
 
 You *MUST* honor the following hints on this *task* format:
 
--   The content *MUST* begin with the `---` opening delimiter of the
-    *Markdown frontmatter* as its very *first* line -- there is *no*
-    leading empty line, as any line before the `---` would degrade the
-    frontmatter into ordinary Markdown. You *MUST* always keep the empty
-    line between the closing `---` delimiter and the `#` heading, and
-    always keep the last empty line. If one of them is missing, add it
-    back.
-
--   The *frontmatter* carries the keys `Id`, `Created`, `Modified`,
-    `Status`, `Properties`, and `Kind`, in exactly this order, with their
-    values being *unquoted* plain scalars and vertically aligned one
-    space after the longest key. Only `Id` is *mandatory* -- every other
-    key is *optional* and, when absent, falls back to its default value.
-
--   In all descriptions, highlight *code* as
-    <template>`<code/>`</template> and *key aspects* as
-    <template>*<aspect/>*</template>.
-
--   For <summary-what/> and <summary-why/> use an *ultra brief* but
-    *as precise as possible* description of the overall change. In
-    <summary-what/> tell what is changed. In <summary-why/> tell why it
-    is changed, what benefit results or what the rationale is behind the
-    change.
-
--   The <task-id/> of the `Id:` frontmatter key has to be substituted
+-   A task consists of at least two blocks, each *starting* with a `---` line.
+    There is *no* terminating line: a block ends where the next block starts
+    or where the file ends. The first block is named the "frontmatter" and is
+    a YAML metadata block with the task's metadata. The second block is named
+    the "body" and is a Markdown task plan. The third and following blocks are
+    named the "backmatter" and are zero or more attachment blocks, each based
+    on a YAML metadata block.
+
+-   The content *MUST* begin with the `---` line starting the
+    *frontmatter* as its very *first* line -- there is *no* leading empty line,
+    as any line before the `---` would degrade the frontmatter into ordinary
+    Markdown. You *MUST* always keep the empty line between the `---` line
+    starting the "body" and the `#` heading, and always keep the last empty
+    line of the Markdown "body" (second block) just before the `---` line starting
+    the "backmatter" or the end of the file. If one of them is missing, add it
+    back. This trailing empty line is required for the Markdown "body" *only*.
+
+-   As `---` lines start the blocks, the *body* *MUST NOT* contain a line
+    consisting of just `---` outside a fenced code block, as it could be read
+    as the start of the "backmatter" -- use `***` for a Markdown horizontal
+    rule instead. Inside a fenced code block, `---` lines are fine, but every
+    fenced code block of the *body* *MUST* be closed.
+
+-   The *frontmatter* can carry the keys `Type`, `Id`, `Created`, `Modified`,
+    `Group`, `Phase`, `After`, `Status`, `Assignee`, `Kind`, `Effort`, `Tags`, `Source`,
+    `Changeset`, and `Target` in exactly this order, with their values being
+    *unquoted* plain scalars and vertically aligned at a *fixed* column: each
+    `<key/>:` is padded with spaces to a width of 11 characters, so every value
+    starts at column 12 (one space after `Changeset:`) -- independent of which
+    keys are actually present. Only `Type` and `Id` are *mandatory* -- every
+    other key is *optional* and, when absent, falls back to its default value.
+    A skill *writing* an optional key which is still *absent* inserts it at its
+    position in the key order above, aligned at the same fixed column.
+
+-   The `Type` frontmatter key has to use the value `text/vnd.ase.task` for
+    consistency (with the backmatter) and identification reasons. A plan
+    *lacking* the `Type` key is a *legacy* plan, whose `Status` value is
+    migrated onto the current task lifecycle model on load.
+
+-   The <task-id/> of the `Id` frontmatter key has to be substituted
     with the current value of <ase-task-id/> in the current session
-    context.
-
--   The `Status:` frontmatter key states the current *lifecycle state*
-    of the task plan. The key is *optional* and defaults to `DRAFTED`:
-    an *absent* key reads as `DRAFTED`, and a *newly created* plan
-    carries `DRAFTED` explicitly. The <task-status/> value is *strictly*
-    one of the following eight states:
-
-    -   `DRAFTED`: plan exists but is still provisional and not yet
-        cleared for implementation.
-    -   `REJECTED`: plan was reviewed and refused, and has to be reworked
-        before it can be approved.
-    -   `APPROVED`: plan is accepted as authoritative and cleared for
-        implementation, but no work has begun.
-    -   `DEFERRED`: plan is approved and unobstructed, but its start was
-        deliberately postponed.
-    -   `STARTED`: implementation of the plan is actively underway.
-    -   `BLOCKED`: implementation is halted by an impediment which
-        someone has to remove before it can resume.
-    -   `COMPLETED`: plan was implemented in full and reached its
-        intended outcome.
-    -   `CANCELLED`: plan was terminated before completion, because it
-        failed, was called off, or became obsolete.
-
--   The eight states form a *state machine*. Whoever sets the `Status:`
-    key *MUST* only move along one of the following transitions, whereby
-    a *single* operation *MAY* traverse *several* transitions at once if
-    it performs the corresponding stages in one go:
-
-    ```text
-    DRAFTED   ──reject───▶ REJECTED      STARTED   ──block────▶ BLOCKED
-    REJECTED  ──redraft──▶ DRAFTED       BLOCKED   ──unblock──▶ STARTED
-    DRAFTED   ──approve──▶ APPROVED      STARTED   ──complete─▶ COMPLETED
-    APPROVED  ──defer────▶ DEFERRED
-    DEFERRED  ──resume───▶ APPROVED      any non-terminal state
-    APPROVED  ──start────▶ STARTED       ──cancel───▶ CANCELLED
-    ```
-
-    `COMPLETED` and `CANCELLED` are the two *terminal* states: a plan
-    which reached one of them is *finished* and leaves the state machine.
-
--   The `Properties:` frontmatter key states which *stages* the task
-    plan already passed through. The <task-properties/> value is
-    *strictly* either `none` or a comma-separated list of the values
-    `grilled`, `preflighted`, `implemented`, and `verified`, listed in
-    exactly this order, each at most once. The key is *optional* and
-    defaults to `none`: an *absent* key reads as `none`, and a *newly
-    created* plan carries `none` explicitly. The list only ever
-    *accumulates*: a skill *adds* its own value if still absent and
-    *MUST NOT* drop any value already present, except when a plan is
-    *recreated from scratch*, which resets it to `none`.
-
--   The `Kind:` frontmatter key states the *kind of change* the task plan
-    describes, and hence which *operation-specific tenet set* of the
-    **ASE Tenets** a subsequent preflight or implementation has to
-    honor. The <task-kind/> value is *strictly* one of `CRAFTING`,
-    `REFACTORING`, or `RESOLVING`.
-
--   The `Kind:` frontmatter key is *optional*: a skill *authoring* or
-    *updating* a task plan *CAN* update an already present key or pass
-    it through *verbatim* and *MAY* create a missing one by *inferring*
-    the kind from the plan content (defaulting to `CRAFTING`). A
-    `--dry` run *never* drops this key, as `--dry` only omits the
-    `##  VERIFICATION` section.
-
--   A skill *writing* an optional key which is still *absent* inserts it
-    at its position in the key order above and re-aligns the values of
-    the whole frontmatter block.
-
--   The <timestamp-created/> of the `Created:` frontmatter key is the
+    context. A task id consists of the characters `A-Z`, `a-z`, `0-9`,
+    `#`, `_`, and `-` only, and a *new* task id is always obtained via
+    the `ase_task_newid` MCP tool, which honors the task id scheme of
+    the project.
+
+-   The <timestamp-created/> of the `Created` frontmatter key is the
     timestamp when this task plan was created. The <timestamp-modified/>
-    of the `Modified:` frontmatter key is the timestamp when this
-    task plan was last modified. Both use an ISO-style format
-    value. The value of both can be determined by a call to the
-    `ase_timestamp(format: "yyyy-LL-dd HH:mm")` tool of the `ase` MCP
-    server, using the `text` field of its response.
-
--   The <title/> is a short summary of the <summary-what/>, no longer than
-    50 characters.
-
--   The sections `##  CHANGES` and `##  VERIFICATION` are each just a short
-    list of 1-5 bullet points. Each bullet point is formatted as
-    `-   **<aspect/>**: <specification/>` where <aspect/> indicates
-    the aspect of the section and <specification/> is 1-3 sentences
-    giving an *ultra precise* but also *ultra brief* and *ultra concise*
-    description of the aspect.
+    of the `Modified` frontmatter key is the timestamp when the *body*
+    of this task plan was last modified: a change to *frontmatter* keys
+    only (like `Status` or `Changeset`) or to the *backmatter* only *MUST
+    NOT* refresh it. Both use an ISO-style format value. The value of
+    both has to be determined by a call to the `ase_timestamp(format:
+    "yyyy-LL-dd HH:mm")` tool of the `ase` MCP server, using the `text`
+    field of its response.
+
+-   The `Group` frontmatter key content-wise places the task into a single group.
+    The <task-group/> usually is the unique name of a "master task" or "epic".
+    An epic is created either *implicitly*, by just using the same plain
+    <task-group/> in the `Group` key of all its member tasks, or *explicitly*,
+    by an additional task whose `Id` equals the <task-group/> and whose
+    own `Group` equals its `Id`, too. Such an explicit epic task implicitly
+    comes `After` all other member tasks of its group, i.e., these need
+    not be listed in its `After` key.
+
+-   The `Phase` frontmatter key chronologically places the task into a single phase.
+    The <task-phase/> usually is the unique name of a "phase", "stage", or "sprint".
+
+-   The `After` frontmatter key places the task execution *after* one or more
+    other referenced tasks. The <task-after/> has to be a comma-and-space-separated
+    list of <task-id/> identifiers and hence should be formatted
+    `<task-id-1/>, <task-id-2/>[, ...]`.
+
+-   The `Status` frontmatter key states the current *lifecycle state*
+    of the task, as defined by **Task Lifecycle Models** below. A *newly
+    created* task carries the *default* state explicitly. The <task-status/>
+    value is *strictly* one of the pre-defined states of the task lifecycle
+    model configured for the current project.
+
+-   The `Assignee` frontmatter key states the current *assignee* of the task,
+    which is either a human or an agent. A *newly created* task carries no
+    assignee and there is no default value. The <task-assignee/> is an arbitrary
+    but unique name of the assignee.
+
+-   The `Kind` frontmatter key states the *kind of change* the task plan
+    describes, and hence which *operation-specific tenet set* of the **ASE
+    Tenets** a subsequent draft or implementation has to honor. The
+    <task-kind/> value is *strictly* one of `SPECIFYING`, `CRAFTING`,
+    `REFACTORING`, or `RESOLVING`. The `Kind` frontmatter key is *optional*:
+    a skill *authoring* or *updating* a task plan *CAN* update an already
+    present key or pass it through *verbatim* and *MAY* create a missing one by
+    *inferring* the kind from the plan content (defaulting to `CRAFTING`).
+
+-   The `Effort` frontmatter key states the *estimated effort* of the task: the
+    expected *human time* of its *entire* lifecycle (including planning), which
+    matches the human time `time.hr` of its usage attachment. The <task-effort/>
+    value is formatted `<size/> <hash/>`, with <size/> *strictly* one of the
+    T-shirt sizes `XS`, `S`, `M`, `L`, or `XL` -- bands on a *logarithmic* scale
+    (factor 4) with the upper bounds `15`, `60`, `240`, and `960` human minutes
+    for `XS` to `L` (configuration `project.task.effort.scale`), while `XL` is
+    open-ended -- and <hash/> the short *content hash* of the "body" the size was
+    given for. The `Effort` frontmatter key is *optional*: an absent key means
+    *not estimated*, and explicit epic tasks carry none, as their effort is the
+    sum of their member tasks. It is written by `ase-task-estimate` (or by hand)
+    and *never* refreshes the `Modified` key.
+
+    The size is *bound* to the plan *content*: the content hash covers the
+    "body" with its checkboxes and whitespace left out and its bullet-points in
+    the inert states `[-]` and `[>]` left out entirely. Hence, mere checkbox state
+    changes and whitespace-only edits (like re-wrapping) keep the size valid, while
+    every other content change (including cancelling or deferring a bullet-point)
+    makes it *stale*. The task store *drops* a stale `Effort` key on load and save,
+    and *stamps* a key given without <hash/> (like `Effort: M`) with the content
+    hash of the current "body" on save. Every skill *rewriting* a plan passes the
+    key through *verbatim*, and *never* invents or changes a <hash/>. A skill
+    persisting a plan again from its *own* copy of a previous save (like the
+    `text` argument of a previous `ase_task_save`) *MUST* first take over the
+    `Effort` key *as stored* by that save (stamped, or dropped) into its copy
+    -- or else load the plan again -- as a key without <hash/> would otherwise
+    be stamped again on the next save, even against a meanwhile changed "body".
+
+-   The `Tags` frontmatter key can be used to tag a task with arbitrary key/value
+    information. The <task-tags/> value has to be a comma-and-space-separated
+    list of `<key/>:<value/>` or plain `<key/>` identifiers and hence should be
+    formatted `<key/>[:<value/>], <key/>[:<value/>][, ...]`. A plain `<key/>`
+    tag is a boolean marker, e.g. `foo` marks the task as `foo`.
+
+-   The `Source`, `Changeset`, and `Target` frontmatter keys control the *flow*
+    of the change set of the task: `ase-task-implement` creates the change set
+    from the `Source` into the `Changeset`, and `ase-task-integrate` delivers
+    the change set from the `Changeset` into the `Target`. Their `worktree`
+    values refer to the *origin working copy* (the current Git working copy)
+    for `Source` and `Target`, and to the *context worktree* for `Changeset`:
+    the ASE worktree `.ase/worktree/<name/>` selected by the
+    `--worktree <name/>` option of these skills, or else the origin working
+    copy itself.
+
+    -   The <task-source/> of the `Source` key is the *code basis* of the
+        change set: `worktree` (built-in default) is the origin working copy with its
+        checked-out branch, and `branch:<name/>` is the existing Git branch
+        <name/>.
+
+    -   The <task-changeset/> of the `Changeset` key is the *location* of the
+        change set: `worktree` (built-in default) leaves it *uncommitted* in the context
+        worktree, `branch:<name/>` *commits* it onto the Git branch <name/>
+        (created from the `Source` if missing) inside a worktree carrying this
+        branch, and `attachment:<name/>` stores it as a *unified diff* in the
+        attachment block of `Type: text/x-diff; charset=utf-8; kind="<name/>"`
+        of the task, leaving all artifacts untouched.
+
+    -   The <task-target/> of the `Target` key is the *integration target* of
+        the change set: `worktree` is the origin working copy with its
+        checked-out branch, `branch:<name/>` is the existing Git branch
+        <name/>, and `source` (built-in default) is whatever the `Source` key refers to.
+
+    A branch <name/> is non-empty, consists of the characters `A-Z`, `a-z`,
+    `0-9`, `_`, `-`, `.`, and `/` only, does *not* start with `-`, `.`, or
+    `/`, does *not* end with `/`, `.`, or `.lock`, and does *not* contain
+    `..` or `//`. An attachment <name/> is non-empty and consists of the
+    characters `A-Z`, `a-z`, `0-9`, `_`, and `-` only. The attachment name
+    `draft` is the *implementation draft*, selected by the `--draft` option
+    of `ase-task-implement` and `ase-task-integrate`.
+
+    A branch or attachment <name/> can carry the placeholder `{id}`, which
+    reads as the task id with every character other than `A-Z`, `a-z`,
+    `0-9`, `_`, and `-` replaced by `-`, then every run of multiple `-`
+    reduced to a single `-`, and finally all leading and trailing `-`
+    and `_` removed (e.g., the `Changeset` value
+    `branch:cs-{id}` commits the change set of the task `foo` onto the
+    branch `cs-foo`, and the one of the task `#12` onto the branch
+    `cs-12`). The placeholder is mainly intended for the
+    configured defaults, giving every task its own branch or attachment.
+
+    An *absent* `Source`, `Changeset`, or `Target` key reads as its
+    *configured default* at the time of use: <ase-project-task-default-source/>,
+    <ase-project-task-default-changeset/>, resp. <ase-project-task-default-target/>
+    (configuration `project.task.default.{source,changeset,target}`, with the
+    built-in defaults `worktree`, `worktree`, resp. `source`). Hence, a skill
+    *creating* or *rebooting* a task plan *MUST* leave these keys *out*, and a
+    skill *writing* one of these keys *MUST* leave it out if its value equals
+    the configured default (with the placeholder `{id}` of both replaced),
+    so the plan keeps following the configuration.
+
+-   A task can have zero or more attachments in the "backmatter". Each attachment is
+    realized with its own dedicated block. When no attachments exist, these
+    "backmatter" blocks are omitted. Each attachment block in the "backmatter"
+    carries the *mandatory* `Type` key and *exactly one* of the keys `Data`
+    or `File`. The `Type` key has the value <task-attachment-type/> which
+    is a regular MIME type, but has to be not equal to the vendor MIME type
+    `text/vnd.ase.task`.
+
+    For embedded content, the `Data` key contains the content data as a YAML
+    "literal block scalar" with the block header `|4+`, i.e., with an explicit
+    indentation of exactly 4 spaces (which are stripped from the content) and
+    with all trailing blank lines kept as part of the content -- except for
+    *one* blank line directly before the `---` line of the next block, which
+    only separates the blocks. Content without
+    a trailing newline instead uses the block header `|4-`, and empty content
+    is given as an empty `Data:` value.
+
+    When loaded via `ase_task_load` (by default), the content of a `Data` key
+    is *elided*, i.e., given as the single-line marker value
+    `[elided: <n/> lines]` instead. Keep such a marker *verbatim* to keep the
+    content unchanged, as `ase_task_save` restores it from the stored
+    attachment. Fetch the content via `ase_task_attachment` only if it has
+    to be read or changed, and then replace the marker with the complete
+    changed content. A marker *MUST* *NEVER* be copied into another block or
+    another task.
+
+    For referenced content, the `File` key contains the filename relative to the
+    task storage location. Every attachment can optionally have a `Desc` key
+    where <task-attachment-desc/> is a short and concise single-line description
+    of the attachment, and the optional keys `Created` and `Modified`, whose
+    values <task-attachment-created/> and <task-attachment-modified/> are the
+    timestamps when the attachment was created and last modified, in the same
+    format and determined the same way as their frontmatter counterparts.
+
+    The keys of an attachment block are ordered `Type`, `Desc`, `Created`,
+    `Modified`, and `Data` or `File`, with their values aligned at the same
+    *fixed* column as the frontmatter keys (each `<key/>:` padded to a width of
+    11 characters).
+
+-   An attachment is *stale* when its `Modified` key is *absent* or *older*
+    than the `Modified` key of the frontmatter, as its content was then
+    produced for an *earlier* version of the plan "body". In particular, a
+    *change set* attachment produced by the skill `ase-task-implement` for a
+    `Changeset` of `attachment:<name/>` (like the *implementation draft*
+    of `--draft`) carries the `Type` key value `text/x-diff; charset=utf-8;
+    kind="<name/>"` and is delivered by the skill `ase-task-integrate` only
+    while it is *not* stale. Its `Desc` key carries `base <commit/>`, the full Git commit id the
+    unified diff is based on. Once it is delivered and kept (`ase-task-integrate --no-cleanup`),
+    its `Desc` key additionally carries `, merged <commit/>`, the full Git commit id of the target
+    branch after the integration, and the attachment is *delivered*: it is then neither delivered
+    again by `ase-task-integrate` nor re-applied by `ase-task-implement`.
+
+    For a `Changeset` of `worktree` or `branch:<name/>`, the `ase agent`
+    agents `implementer` and `integrator` (and every agent configured with
+    `--attach-changeset`) additionally maintain the *change set snapshot*: a
+    *view-only*, text-only unified diff of the change set, which makes it
+    viewable wherever the task is visible (e.g. on the task boards during its
+    qualification). The skills never create or change it, but pass it through
+    *verbatim*. It carries the `Type` key value
+    `text/x-diff; charset=utf-8; kind="<kind/>"` (with <kind/> being
+    `changeset` for the built-in agents), is *replaced* in place on every run
+    (keeping its `Created` key), and its `Desc` key carries `base <commit/>`
+    (plus `, partial` for an incomplete change set) after an implementation,
+    resp. `base <commit/>, merged <commit/>` after an integration. It is
+    *never* delivered by `ase-task-integrate`, unless the `Changeset` is
+    `attachment:<kind/>`, in which case this attachment *is* the change set
+    itself. A stale snapshot just shows an outdated change set.
+
+    The *usage attachment* carries the *accumulated AI and human usage* of the
+    task, as booked by `ase-task-assign` and the `ase agent` jobs. It carries the
+    `Type` key value `application/yaml; kind="usage"`, is created on the first
+    booking, and is *replaced* in place on every booking (keeping its `Created`
+    key and refreshing its `Modified` key, but leaving the `Modified` key of the
+    frontmatter alone). Its `Data` is YAML with the amounts `time: { ai, hr,
+    real }` (AI request, human, and real time, in minutes), `token: { cread,
+    cwrite, input, output }` (cache read, cache write, uncached input, and output
+    tokens), and `cost: { ai, hr }` (AI and human costs, in USD). As it does not
+    depend on the "body", it is *never* stale, and a skill *never* changes it:
+    the task store keeps it on every overwrite of the plan (silently ignoring a
+    changed, removed, or added usage attachment), and the entity tag of a
+    conditional save does not cover it, so a booking meanwhile never fails a save.
+
+    A skill which changes the content of an attachment refreshes its `Modified`
+    key with the current timestamp -- the very same value it writes into the
+    `Modified` key of the frontmatter if it changes the "body", too. Hence,
+    `ase-task-implement` stamps a change set attachment with the same value
+    it writes into the frontmatter when ticking checkboxes, so the attachment
+    does not fall behind the plan it was produced for.
+
+-   A skill which *rewrites* the "frontmatter" or the "body" of a task *MUST*
+    pass the entire "backmatter" through *verbatim* -- every attachment block
+    byte-for-byte (with its elided `Data` marker), in its original order -- unless the skill *explicitly*
+    manages attachments itself. Attachments are *never* dropped, reordered,
+    re-indented, or re-flowed as a side-effect of a body rewrite.
+
+-   All content is contained in bullet-points. Those bullet-points use
+    the format `-   <box/> <type/>: **<summary/>**: <text/>`.
+
+    The embedded checkbox <box/> allows the following variants to express states of <text/>:
+
+    -   `[ ]`: todo       (the bullet-point was still not resolved)
+    -   `[?]`: question   (the bullet-point was still not resolved due to a question)
+    -   `[/]`: incomplete (the bullet-point was only partially resolved)
+    -   `[x]`: done       (the bullet-point was fully resolved)
+    -   `[-]`: cancelled  (the bullet-point was cancelled and should not be resolved)
+    -   `[>]`: deferred   (the bullet-point was deferred  and should be resolved later)
+
+    The `[?]` state is *set* by grilling on every bullet-point whose
+    grilling question stayed *unanswered* and *reset* to `[ ]` once the
+    question is answered in a later grilling. The `[-]` and `[>]` states
+    make a bullet-point *inert*: grilling asks *no* question about it,
+    drafting and implementation neither realize nor check it, and
+    *every* skill leaves its checkbox *untouched* until the user changes it.
+    On implementation, a `[?]` bullet-point is a *regular* todo like `[ ]`,
+    a `[x]` bullet-point is *skipped* as already resolved, and a `[/]`
+    bullet-point is *re-examined* for its still unresolved parts.
+
+    The <type/> classifies the <text/>:
+
+    -   `DOM`: Domain         (what to change from Domain    perspective)
+    -   `IFC`: Interface      (what to change from Interface perspective)
+    -   `ARC`: Architecture   (how  to change Architecture   details)
+    -   `IMP`: Implementation (how  to change Implementation details)
+    -   `REG`: Regression     (ensure change does not break anything)
+    -   `CON`: Confirmation   (ensure change behaves as specified)
+
+    Changes to `CHANGELOG.md` files should be classified as `IMP`. Running linting (static code
+    analysis) and build (generating files) procedures should be classified as `REG`.
+
+    Bullet-points of types `DOM` and `IFC` (in this order) belong to the `SPECIFICATION (WHAT)` section.
+    Bullet-points of types `ARC` and `IMP` (in this order) belong to the `DESIGN (HOW)` section.
+    Bullet-points of types `REG` and `CON` (in this order) belong to the `VERIFICATION (WHEN)` section.
+
+    The <summary/> summarizes <text/> and is 1-3 words only. It is for
+    quickly identifying upfront what <text/> is about.
+
+    The <text/> can span multiple lines. In all <text/> parts, highlight
+    *code* as <template>`<code/>`</template> and *key aspects* as
+    <template>*<aspect/>*</template>. Each <text/> should be just 1-3 sentences
+    and be *very precise*, but also *ultra brief* and *ultra concise*.
+
+-   Section `SPECIFICATION` tells `WHAT` is changed,
+    section `DESIGN` tells `HOW` it is changed, and
+    section `VERIFICATION` tells `WHEN` the change counts as complete and correct.
 
 -   In all sections, break all lines with a newline character
     after about 100 characters per line for better subsequent
@@ -161,3 +410,298 @@ You *MUST* honor the following hints on this *task* format:
     backtick or *after* its closing backtick, even if this means
     breaking the line noticeably earlier than after 100 characters.
 
+-   The <task-title/> is a short summary of the task, usually by summarizing the
+    `DOM` bullet-points of the `SPECIFICATION (WHAT)` section. It is no longer
+    than 50 characters. It has to be catchy and expressive.
+
+Task Lifecycle Models
+---------------------
+
+Every **ASE** *task* carries an optional `Status` frontmatter key, stating its current *lifecycle
+state*. The `Status` key is the *attribute*; its value is always one of the *states* of the task
+lifecycle model. When `Status` is absent, the task is in the *default* state of the selected task
+lifecycle model.
+
+The lifecycle model is a *state machine*. Whoever sets the `Status` frontmatter key *MUST* only move
+along one of the defined state transitions, whereby a *single* operation *MAY* traverse *several*
+transitions at once if it performs the corresponding stages in one go.
+
+**ASE** pre-defines three reusable task lifecycle models. The lifecycle model of the current project
+is defined by <ase-project-task-lifecycle/>, with allowed values `solo` (default), `team`, and
+`enterprise`.
+
+### Solo Task Lifecycle Model (`solo`)
+
+The 1+3 states and the transitions between them form the following state machine which realizes a
+task management scheme based on just a single activity phase. It is intended for local use of a solo
+developer.
+
+```mermaid
+stateDiagram-v2
+    [*]          --> OPEN
+
+    OPEN         --> SHELVED
+    SHELVED      --> OPEN
+
+    OPEN         --> CLOSED
+
+    OPEN         --> CANCELLED
+    SHELVED      --> CANCELLED
+
+    CLOSED       --> [*]
+    CANCELLED    --> [*]
+```
+
+```txt
+      ●
+      │
+      ▼
+┏━━━━━━━━━━━━┓      ┌────────────┐
+┃    OPEN    ┃─────▶│  SHELVED   │
+┃            ┃◀─────│            │
+┗━━━━━━━━━━━━┛      └────────────┘
+      │    │              │
+      │    └──────────────┴───────────┐
+      ▼                               │
+┌────────────┐      ┌────────────┐    │
+│   CLOSED   │      │ CANCELLED  │◀───┘
+│            │      │            │
+└────────────┘      └────────────┘
+      │                   │
+      ├───────────────────┘
+      │
+      ▼
+      ◉
+```
+
+The 1 "activity" state expresses:
+
+-   `OPEN`:      task is currently work in progress (idea to code-base).
+
+The 3 "rest" states express:
+
+-   `SHELVED`:   task was temporarily shelved into backlog.
+-   `CLOSED`:    task was implemented and reached its intended outcome.
+-   `CANCELLED`: task was cancelled at any time, because it failed, was called off, or became obsolete.
+
+The *default* state is the "activity" state `OPEN`.
+
+### Team Task Lifecycle Model (`team`)
+
+The 2+4 states and the transitions between them form the following state machine which realizes a
+task management scheme based on the two activity phases Planning and Implementation. It is intended
+for distributed use by a small team of developers.
+
+```mermaid
+stateDiagram-v2
+    [*]          --> PLANNING
+
+    PLANNING     --> SHELVED
+    SHELVED      --> PLANNING
+
+    PLANNING     --> IMPLEMENTING
+    IMPLEMENTING --> PLANNING
+    IMPLEMENTING --> STALLED
+    STALLED      --> IMPLEMENTING
+
+    IMPLEMENTING --> IMPLEMENTED
+
+    PLANNING     --> CANCELLED
+    SHELVED      --> CANCELLED
+    IMPLEMENTING --> CANCELLED
+    STALLED      --> CANCELLED
+
+    IMPLEMENTED  --> [*]
+    CANCELLED    --> [*]
+```
+
+```txt
+           ●
+           │
+           ▼
+     ┏━━━━━━━━━━━━┓      ┌────────────┐
+┌───▶┃  PLANNING  ┃─────▶│  SHELVED   │
+│    ┃            ┃◀─────│            │
+│    ┗━━━━━━━━━━━━┛      └────────────┘
+│          │    │              │
+│          │    └──────────────┴───────────┐
+│          ▼                               │
+│    ┏━━━━━━━━━━━━┓      ┌────────────┐    │
+└────┃IMPLEMENTING┃─────▶│  STALLED   │    │
+     ┃            ┃◀─────│            │    │
+     ┗━━━━━━━━━━━━┛      └────────────┘    │
+           │    │              │           │
+           │    └──────────────┴───────────┤
+           ▼                               │
+     ┌────────────┐      ┌────────────┐    │
+     │IMPLEMENTED │      │ CANCELLED  │◀───┘
+     │            │      │            │
+     └────────────┘      └────────────┘
+           │                   │
+           ├───────────────────┘
+           │
+           ▼
+           ◉
+```
+
+The 2 "activity" states express:
+
+-   `PLANNING`:     task is currently in change planning       (idea to plan).
+-   `IMPLEMENTING`: task is currently in change implementation (plan to code-base).
+
+The 4 "rest" states express:
+
+-   `SHELVED`:      task was shelved during planning into backlog.
+-   `STALLED`:      task was stalled during implementation by an impediment.
+-   `IMPLEMENTED`:  task was implemented and reached its intended outcome.
+-   `CANCELLED`:    task was cancelled at any time, because it failed, was called off, or became obsolete.
+
+The *default* state is the "activity" state `PLANNING`.
+
+### Enterprise Task Lifecycle Model (`enterprise`)
+
+The 4+10 states and the transitions between them form the following state machine which realizes
+a task management scheme based on the four activity phases Planning, Implementation, Qualification
+and Integration. It is intended for distributed use by an enterprise where engineers and agents act
+in a gated development pipeline.
+
+```mermaid
+stateDiagram-v2
+    [*]          --> DRAFTED
+    DRAFTED      --> SHELVED
+    SHELVED      --> DRAFTED
+    DRAFTED      --> PLANNING
+    PLANNING     --> DRAFTED
+    PLANNING     --> SHELVED
+
+    PLANNING     --> PLANNED
+    PLANNED      --> STALLED
+    STALLED      --> PLANNED
+    PLANNED      --> IMPLEMENTING
+    IMPLEMENTING --> PLANNED
+    IMPLEMENTING --> STALLED
+
+    IMPLEMENTING --> IMPLEMENTED
+    IMPLEMENTED  --> DECLINED
+    DECLINED     --> IMPLEMENTED
+    IMPLEMENTED  --> QUALIFYING
+    QUALIFYING   --> IMPLEMENTED
+    QUALIFYING   --> DECLINED
+
+    QUALIFYING   --> QUALIFIED
+    QUALIFIED    --> DEFERRED
+    DEFERRED     --> QUALIFIED
+    QUALIFIED    --> INTEGRATING
+    INTEGRATING  --> QUALIFIED
+    INTEGRATING  --> DEFERRED
+
+    INTEGRATING  --> INTEGRATED
+
+    IMPLEMENTING --> DRAFTED
+    QUALIFYING   --> DRAFTED
+    QUALIFYING   --> PLANNED
+    INTEGRATING  --> DRAFTED
+    INTEGRATING  --> PLANNED
+
+    DRAFTED      --> CANCELLED
+    SHELVED      --> CANCELLED
+    PLANNING     --> CANCELLED
+    PLANNED      --> CANCELLED
+    STALLED      --> CANCELLED
+    IMPLEMENTING --> CANCELLED
+    IMPLEMENTED  --> CANCELLED
+    DECLINED     --> CANCELLED
+    QUALIFYING   --> CANCELLED
+    QUALIFIED    --> CANCELLED
+    DEFERRED     --> CANCELLED
+    INTEGRATING  --> CANCELLED
+
+    INTEGRATED   --> [*]
+    CANCELLED    --> [*]
+```
+
+```txt
+             ●
+             │
+             │     ┌──────────────────────────────┐
+             ▼     │                              │
+      ┌──────────────┐       ┌──────────────┐     │
+┌────▶│   DRAFTED    │──────▶│   SHELVED    │─────┤
+│     │              │◀──────│              │     │
+│     └──────────────┘       └──────────────┘     │
+│        │       ▲                  ▲             │
+│        ▼       │                  │             │
+│     ┏━━━━━━━━━━━━━━┓              │             │
+│     ┃   PLANNING   ┃──────────────┘             │
+│     ┃              ┃────────────────────────────┤
+│     ┗━━━━━━━━━━━━━━┛                            │
+│            │     ┌──────────────────────────────┤
+│            ▼     │                              │
+│     ┌──────────────┐       ┌──────────────┐     │
+├────▶│   PLANNED    │──────▶│   STALLED    │─────┤
+│     │              │◀──────│              │     │
+│     └──────────────┘       └──────────────┘     │
+│        │       ▲                  ▲             │
+│        ▼       │                  │             │
+│     ┏━━━━━━━━━━━━━━┓              │             │
+├─────┃ IMPLEMENTING ┃──────────────┘             │
+│     ┃              ┃────────────────────────────┤
+│     ┗━━━━━━━━━━━━━━┛                            │
+│            │     ┌──────────────────────────────┤
+│            ▼     │                              │
+│     ┌──────────────┐       ┌──────────────┐     │
+│     │ IMPLEMENTED  │──────▶│   DECLINED   │─────┤
+│     │              │◀──────│              │     │
+│     └──────────────┘       └──────────────┘     │
+│        │       ▲                  ▲             │
+│        ▼       │                  │             │
+│     ┏━━━━━━━━━━━━━━┓              │             │
+├─────┃  QUALIFYING  ┃──────────────┘             │
+│     ┃              ┃────────────────────────────┤
+│     ┗━━━━━━━━━━━━━━┛                            │
+│            │     ┌──────────────────────────────┤
+│            ▼     │                              │
+│     ┌──────────────┐       ┌──────────────┐     │
+│     │  QUALIFIED   │──────▶│   DEFERRED   │─────┤
+│     │              │◀──────│              │     │
+│     └──────────────┘       └──────────────┘     │
+│        │       ▲                  ▲             │
+│        ▼       │                  │             │
+│     ┏━━━━━━━━━━━━━━┓              │             │
+└─────┃ INTEGRATING  ┃──────────────┘             │
+      ┃              ┃────────────────────────────┤
+      ┗━━━━━━━━━━━━━━┛                            │
+             │                                    │
+             ▼                                    │
+      ┌──────────────┐       ┌──────────────┐     │
+      │  INTEGRATED  │       │  CANCELLED   │◀────┘
+      │              │       │              │
+      └──────────────┘       └──────────────┘
+             │                      │
+             ├──────────────────────┘
+             │
+             ▼
+             ◉
+```
+
+The 4 "activity" states express:
+
+-   `PLANNING`:     task is currently in change planning       (idea to plan).
+-   `IMPLEMENTING`: task is currently in change implementation (plan to change-set).
+-   `QUALIFYING`:   task is currently in change qualification  (change-set to decision).
+-   `INTEGRATING`:  task is currently in change integration    (change-set to code-base).
+
+The 10 "rest" states express:
+
+-   `DRAFTED`:      task is still provisional, incoherent and incomplete.
+-   `SHELVED`:      task was shelved during planning into backlog.
+-   `PLANNED`:      task is coherent and complete and ready for implementation.
+-   `STALLED`:      task was stalled during implementation by an impediment.
+-   `IMPLEMENTED`:  task is implemented and is ready for qualification.
+-   `DECLINED`:     task was declined during qualification.
+-   `QUALIFIED`:    task is qualified and ready for integration.
+-   `DEFERRED`:     task was deferred during integration due to release decision.
+-   `INTEGRATED`:   task is integrated and reached its intended outcome.
+-   `CANCELLED`:    task was cancelled at any time, because it failed, was called off, or became obsolete.
+
+The *default* state is the "rest" state `DRAFTED`.