@rse/ase 1.0.6 → 2.0.0

package/plugin/meta/ase-common-grill.md

@@ -4,6 +4,15 @@ Grill Skill Common Steps
 
 <define name="grill-understanding">
 
+Set <grill-perspective><arg2/></grill-perspective> (with any leading
+and trailing whitespace stripped), set <grill-ground><arg3/></grill-ground>,
+and set <grill-facts></grill-facts> (empty). Set <grill-label/> to
+` (<grill-perspective/>, grounded)` if <grill-perspective/> is not empty
+and <grill-ground/> is `true`, to ` (<grill-perspective/>)` if only
+<grill-perspective/> is not empty, to ` (grounded)` if only
+<grill-ground/> is `true`, or to empty otherwise. Do not output
+anything.
+
 -   GOAL:
 
     Interactively interviewing the user *relentlessly* about every
@@ -15,6 +24,24 @@ Grill Skill Common Steps
     during a subsequent implementation, no essential freedom of choice
     exists any longer.
 
+-   PERSPECTIVE:
+
+    <if condition="<grill-perspective/> is not empty">
+    Grill *exclusively* from the logical perspective <grill-perspective/>
+    -- a keyword or short hint like `domain`, `performance`, or
+    `security`. The perspective is an *exclusive lens* over <arg1/>:
+    raise *only* open points which are relevant when <arg1/> is viewed
+    from this perspective, and *drop* all open points which are not,
+    even if they are open otherwise. The perspective does *not* replace
+    the *Focus Areas* below: every question still carries its focus
+    area, severity, and impact -- e.g. a perspective `domain` still
+    yields questions of focus area `ARCHITECTURE`, as long as they are
+    relevant from the domain perspective.
+    </if>
+    <else>
+    Grill *holistically*, i.e. from no particular perspective.
+    </else>
+
 -   FOCUS:
 
     Focusing on the following outside-in *Focus Areas*, in order of
@@ -41,6 +68,16 @@ Grill Skill Common Steps
         is realized in the code base. These aspects *CAN* be
         clarified, as they shape technical inner details only.
 
+    5.  *REGRESSION*: Aspects affecting the regression checks of
+        <arg1/>, i.e. decisions on what must *not* break. These
+        aspects *SHOULD* be clarified, as they decide when the
+        solution counts as safe.
+
+    6.  *CONFIRMATION*: Aspects affecting the confirmation checks of
+        <arg1/>, i.e. decisions on what proves the specified
+        behavior. These aspects *SHOULD* be clarified, as they
+        decide when the solution counts as complete and correct.
+
 -   SEVERITY:
 
     The *Focus Area* indicate the severity of the aspect:
@@ -49,6 +86,23 @@ Grill Skill Common Steps
     -   severity *MUST*   for *INTERFACE*      focus area
     -   severity *SHOULD* for *ARCHITECTURE*   focus area
     -   severity *MAY*    for *IMPLEMENTATION* focus area
+    -   severity *SHOULD* for *REGRESSION*     focus area
+    -   severity *SHOULD* for *CONFIRMATION*   focus area
+
+-   IMPACT:
+
+    Independent of its *Focus Area*, every open point carries an
+    individual *impact* rating, describing how noticeably its decision
+    shapes the solution:
+
+    -   impact *HIGH*:   the decision shapes the solution fundamentally
+    -   impact *MEDIUM*: the decision shapes the solution noticeably
+    -   impact *LOW*:    the decision shapes the solution marginally
+
+    The impact decides *which* open points are raised as questions --
+    points of higher impact first, so points of lowest impact are the
+    first ones to be dropped -- and in which *order* they are raised
+    *within* a focus area.
 
 -   INDICATORS:
 
@@ -87,3 +141,266 @@ Grill Skill Common Steps
 
 </define>
 
+<define name="grill-ground">
+
+Ground the grilling *once*, before its first round, where <arg1/> is
+the grilled subject and <arg2/> is the directory of the working copy
+the local artifacts are read from (or empty for the project working
+copy). It sets <grill-facts/> to the grounding facts, which -- unlike
+all other information gathered by a round -- are *exempt* from the
+forgetting at the start of every round and hence serve *all* rounds.
+Do not output anything, except for the warning below.
+
+<if condition="<grill-ground/> is equal `true`">
+
+1.  LOCAL GROUNDING:
+
+    Resolve the artifact kinds `spec`, `code`, `docs`, `infr`, and
+    `othr` to their project-relative file lists:
+
+    <if condition="<arg2/> is not empty">
+    Run the command `ase artifact list` *once* with <arg2/> as its
+    working directory and parse its `# <kind/>:` and `- <file/>` output
+    lines into the file lists -- the `ase_artifact_list` tool always
+    resolves against the *project* working copy and hence *MUST* *NOT*
+    be used here.
+    </if>
+    <else>
+    Call the `ase_artifact_list(kind: [ "spec", "code", "docs", "infr",
+    "othr" ])` tool of the `ase` MCP server *once* and read the returned
+    `artifacts` array of `{ kind, files }` objects into the file lists.
+    </else>
+
+    From these file lists, determine the files (or their parts) which
+    are relevant for <arg1/>
+    <if condition="<grill-perspective/> is not empty">
+    when viewed from the perspective <grill-perspective/>
+    </if>
+    -- across *all* artifact kinds, not only the grilled subject itself
+    -- and *read* them. Condense their relevant *project facts* --
+    existing decisions, conventions, constraints, and terminology --
+    each with its project-relative file path, into <grill-facts/>.
+
+2.  WEB GROUNDING:
+
+    Use the `ase-meta-search` skill in a sub-agent to gather *world
+    facts* -- established practices, standards, patterns, and pitfalls
+    -- with the following tool call, where <topic/> is a concise,
+    self-contained summary of <arg1/>
+    <if condition="<grill-perspective/> is not empty">
+    from the perspective <grill-perspective/>
+    </if>
+    which mentions *no* confidential project internals:
+
+    `Agent(
+        description: "Query Web Search Service",
+        subagent_type: "ase:ase-meta-search",
+        prompt: "Search the Internet/Web and gather established maxims, principles, tenets, practices, standards, definitions, patterns, and pitfalls about the following topic: <topic/>",
+        run_in_background: false
+    )`
+
+    Condense the returned relevant facts, each with its source, and
+    append them to <grill-facts/>.
+
+3.  <if condition="<grill-facts/> contains no usable facts">
+
+    Set <grill-facts></grill-facts> (empty), so the grilling falls back
+    to model knowledge, and output the following <template/>:
+
+    <template>
+    <ase-tpl-bullet-secondary/> **WARNING**: grounding found no usable facts -- falling back to model knowledge.
+    </template>
+
+    </if>
+
+</if>
+
+</define>
+
+<define name="grill-stop">
+
+The requested number of grilling rounds is a *maximum* only: the
+grilling *stops early* once all open points of severity <arg1/> or
+higher are clear. For this, the freshly determined questions of the
+current round are the *still open points*, ranked by their
+<context-N-severity/> in the descending order `MUST`, `SHOULD`, `MAY`.
+
+<if condition="no question has a <context-N-severity/> of <arg1/> or higher">
+Set <grill-stop>true</grill-stop> and only output the following <template/>:
+
+<template>
+⧉ **ASE**: <arg2/>, ▶ status: **grilling finished early -- all points of severity <arg1/> or higher are clear**
+</template>
+</if>
+<else>
+Set <grill-stop>false</grill-stop>. Do not output anything.
+</else>
+
+</define>
+
+<define name="grill-questions">
+
+Determine, sort, answer, and show the questions of the current grilling
+*round* <round-id/>, where <arg1/> is the severity of the `grill-stop`
+decision, <arg2/> is the skill chrome of its status line, <arg3/> is the
+list of *literal aspects*, <arg4/> is the source of the grounded answer
+alternatives, <arg5/> is an optional *final* sort criterion, and
+<content/> are optional additional instructions for determining the
+questions:
+
+1.  DETERMINE QUESTIONS:
+
+    Determine the questions, comprised of a round-local id
+    <question-N-id/> of `<N/>` -- where <N/> restarts at `1`
+    in *every* round, independent of the numbering of previous
+    rounds --, and a very brief but precise question text
+    <question-N-text/>. Each question is chosen to
+    resolve the open points related to the above understanding
+    of grilling, by focusing on the mentioned *Focus Areas*
+    <if condition="<grill-perspective/> is not empty">
+    and seen *exclusively* through the mentioned *Perspective*
+    <grill-perspective/>
+    </if>.
+
+    <if condition="<grill-facts/> is not empty">
+    Derive the open points primarily from the grounding facts in
+    <grill-facts/> instead of from your world knowledge alone: raise
+    the decisions these facts reveal as open -- like a project
+    convention the subject deviates from, or an established practice
+    or pitfall the subject does not address yet.
+    </if>
+
+    <content/>
+
+    For <question-N-text/> use the format `Shall...?` for
+    questions of focus area `DOMAIN`, `INTERFACE`, `REGRESSION`,
+    and `CONFIRMATION`, the format `Should...?` for questions of
+    focus area `ARCHITECTURE`, and the format `May...?` for
+    questions of focus area `IMPLEMENTATION`.
+
+    In every <question-N-text/>, encode all *literal aspects*
+    -- <arg3/> -- with backticks.
+
+    Keep every <question-N-text/> at most *200 characters* long
+    -- compact the text until it fits --, as a longer question
+    overflows its table cell and silently degrades the entire
+    table into a plain text rendering.
+
+2.  DETERMINE CONTEXT:
+
+    For each question, determine its focus area
+    <context-N-focus/> from the mentioned *Focus Areas*, a 1-3
+    word hint <context-N-topic/>, describing what the question
+    is about, a <context-N-severity/>, describing how
+    important this question is, and a <context-N-impact/> of
+    `HIGH`, `MEDIUM`, or `LOW`, rating the individual impact
+    of the question.
+
+    Set <context-N-id/> to `DOM` for <context-N-focus/> of
+    `DOMAIN`, `IFC` for <context-N-focus/> of `INTERFACE`, `ARC`
+    for <context-N-focus/> of `ARCHITECTURE`, `IMP` for
+    <context-N-focus/> of `IMPLEMENTATION`, `REG` for
+    <context-N-focus/> of `REGRESSION`, and `CON` for
+    <context-N-focus/> of `CONFIRMATION`.
+
+    Finally, decide whether the grilling stops early:
+
+    <expand name="grill-stop" arg1="<arg1/>" arg2="<arg2/>"></expand>
+
+    If <grill-stop/> is `true`, skip all remaining items of this
+    expansion.
+
+3.  SORT QUESTIONS:
+
+    Finally, *sort* the questions by descending focus area
+    order -- first all `DOMAIN`, then all `INTERFACE`, then all
+    `ARCHITECTURE`, then all `IMPLEMENTATION`, then all
+    `REGRESSION`, and then all `CONFIRMATION` ones -- and,
+    within each focus area, by descending
+    <context-N-impact/><arg5/>. If more than 10 questions exist,
+    drop the questions of lowest <context-N-impact/> -- within
+    equal impact the ones of lowest focus area order first --
+    until a maximum of 10 questions remains. Then renumber
+    <N/> according to the sort order, starting at `1`, and set
+    <n/> to the number of remaining questions. Do not output
+    anything.
+
+    Finally, assemble the <question-N/> out of
+    `**<question-N-id/>** ▶ **<context-N-id/>** ▷
+    **<context-N-topic/>**: <question-N-text/>`.
+
+4.  DETERMINE ANSWERS:
+
+    For all remaining <question-N/>, check <arg4/> and
+    <if condition="<grill-facts/> is not empty">
+    the grounding facts in <grill-facts/> -- preferring them over
+    your world knowledge, which only fills their gaps --
+    </if>
+    <else>
+    your world knowledge
+    </else>
+    to find *two to three* grounded answer
+    alternatives <answer-N-K/> with a question-local id
+    <answer-N-K-id/> of the <K/>-th upper-case letter (`A`, `B`,
+    `C`) -- where <K/> restarts at `1` for *every* question,
+    independent of the numbering of other questions --, a 1-3
+    word label <answer-N-K-label/>, and
+    an ultra brief description <answer-N-K-description/> of
+    at most *10 words*. For the answer which reflects the
+    current decision state of the grilled subject, append
+    ` ⚑` to its <answer-N-K-label/>.
+
+    Assemble an <answer-N/> out of `**<answer-N-1-id/>**
+    ▶ **<answer-N-1-label/>**: <answer-N-1-description/>,
+    **<answer-N-2-id/>** ▶ **<answer-N-2-label/>**:
+    <answer-N-2-description/>[, ...]`.
+
+    Keep every assembled <answer-N/> at most *240 characters*
+    long -- drop the least relevant alternative and compact the
+    descriptions until it fits -- as a longer answer overflows
+    its table cell and silently degrades the entire table into a
+    plain text rendering.
+
+5.  SHOW QUESTIONS:
+
+    Output only the following <template/> -- it lists *all*
+    questions of the round up-front, one table row per
+    aspect, so the subsequent dialog only has to ask for the
+    combined answer. Align all column edges of the table.
+
+    In every table cell you *MUST* escape each literal pipe
+    character outside a code span as `\|` and you *MUST*
+    open *and* close every backtick code span within the
+    *same* cell -- an unescaped pipe or an unbalanced
+    backtick run splits the cell and silently degrades the
+    entire table into a plain text rendering:
+
+    <template>
+    ⧉ **ASE**: <round-id/><grill-label/>: *Relentless Interviewing Until Clarity*
+
+    | QUESTION      | ANSWERS     |
+    | ------------- | ----------- |
+    | <question-1/> | <answer-1/> |
+    | <question-2/> | <answer-2/> |
+    | [...]         | [...]       |
+
+    Legend: **DOM**: Domain       (MUST)    **IFC**: Interface      (MUST)    **n**: round-local question number
+            **ARC**: Architecture (SHOULD)  **IMP**: Implementation (MAY)     **X**: question-local answer letter
+            **REG**: Regression   (SHOULD)  **CON**: Confirmation   (SHOULD)  ⚑: current decision state
+    </template>
+
+</define>
+
+<define name="grill-short-responses">
+
+Within the combined reply, recognize every token matching
+the regexp `\d+[a-zA-Z]` (like `1A`, separated by whitespace
+or commas, and freely mixed with keyword text) as a *short
+response*, which cherry-picks for the question with
+<question-N-id/> equal to its number the answer with
+<answer-N-K-id/> equal to its letter (case-insensitive). A
+token referencing a non-existing question or answer is
+treated as plain free text.
+
+</define>
+

package/plugin/meta/ase-common-resolve.md

@@ -0,0 +1,305 @@
+
+Resolve Skill Common Steps
+==========================
+
+<define name="resolve-conflicts">
+
+*Resolve* the conflicts inside the Git working directory <arg2/> on
+behalf of the skill <arg1/>, where <arg3/> (`true` or `false`) enables
+the *interactive* resolution of otherwise unresolvable hunks, <arg4/>
+(`true` or `false`) enables the *safe* mode which never touches
+non-content conflicts, and <arg5/> is an optional whitespace-separated
+list of paths restricting the files to resolve. This sets
+<resolve-verdict/> to `NONE`, `RESOLVED`, `PARTIAL`, or `FAILED`,
+<resolve-operation/> to the in-progress Git operation,
+<resolve-escalations/> to the list of escalated conflicts, and
+<resolve-backup-dir/> to the backup directory.
+
+The overarching rule is: you *MUST* *NEVER* lose any change of any
+side. When in doubt, a conflict stays *exactly as it is* and is
+escalated -- an unresolved conflict is always acceptable, a silently
+dropped change *never* is.
+
+1.  DETERMINE STATE:
+
+    1.  Set <resolve-verdict>FAILED</resolve-verdict>,
+        <resolve-escalations></resolve-escalations> (empty), and
+        <resolve-backup-dir></resolve-backup-dir> (empty).
+
+    2.  Determine the *repository root* and the *Git directory* by
+        running the commands `git -C "<arg2/>" rev-parse --show-toplevel`
+        and `git -C "<arg2/>" rev-parse --absolute-git-dir` and capturing
+        their outputs into <repo-root/> and <git-dir/>. If a command
+        fails, skip all remaining items of this expansion, as
+        <arg2/> is no Git working directory.
+
+    3.  Determine the *in-progress operation* by running the command
+        `git -C "<repo-root/>" rev-parse --verify --quiet "<ref/>"` for
+        <ref/> being `MERGE_HEAD`, `REBASE_HEAD`, `CHERRY_PICK_HEAD`,
+        and `REVERT_HEAD` (in this order) and set
+        <resolve-operation/> to `merge`, `rebase`, `cherry-pick`, or
+        `revert` for the *first* existing one, and to `none` (e.g.,
+        after `git stash apply`, `git apply --3way`, or `patch --merge`)
+        if none exists. Set <theirs-ref/> to that existing ref (or to
+        empty for `none`).
+
+    4.  Determine the *intents* of both sides: *ours* is `HEAD` and
+        *theirs* is <theirs-ref/>. Inspect them by running the commands
+        `git -C "<repo-root/>" log --oneline -n 10 HEAD` and, if
+        <theirs-ref/> is not empty,
+        `git -C "<repo-root/>" log --oneline -n 10 "<theirs-ref/>"` and
+        `git -C "<repo-root/>" show --stat "<theirs-ref/>"`. Keep in
+        mind that under `rebase` *ours* is the upstream the commits are
+        replayed onto and *theirs* is the replayed commit of the user's
+        branch, and that under `revert` *theirs* is the *inverse* of
+        the reverted commit. Without <theirs-ref/>, derive the sides
+        from the labels of the conflict markers only.
+
+2.  DETERMINE CONFLICTS:
+
+    1.  Determine the *unmerged files* by running the command
+        `git -C "<repo-root/>" -c core.quotepath=off status --porcelain=v1`
+        and taking all entries with the status codes `UU` (both
+        modified), `AA` (both added), `UD`/`DU` (modified/deleted),
+        `AU`/`UA` (added by one side, usually a rename), and `DD` (both
+        deleted). For each of them, additionally capture the output of
+        `git -C "<repo-root/>" ls-files -u -- "<file/>"`, which lists
+        the object ids of the stages `1` (base), `2` (ours), and `3`
+        (theirs) -- these stay retrievable via
+        `git -C "<repo-root/>" cat-file -p <object-id/>` even after the
+        index entry got resolved.
+
+    2.  Determine the *marker files* -- files carrying conflict markers
+        *without* an unmerged index entry (e.g., after `patch --merge`)
+        -- by running the command
+        `git -C "<repo-root/>" -c core.quotepath=off grep -l -I --untracked -E "^<{7}( |$)"`
+        and keeping every listed file which is *not* an unmerged file,
+        *not* below the `.ase/` directory, and additionally contains a
+        matching `^={7}$` and `^>{7}( |$)` line (so that, e.g., a
+        Markdown heading underline alone never qualifies). Additionally
+        determine the *reject files* of `patch` by running the command
+        `git -C "<repo-root/>" -c core.quotepath=off ls-files --others --exclude-standard -- "*.rej"`:
+        they carry hunks which were *not* applied at all, so every one
+        of them is escalated as a whole and *never* touched or removed.
+
+    3.  If <arg5/> is not empty, keep only those unmerged, marker, and
+        reject files which equal or are located below one of the paths
+        in <arg5/> (resolved relative to <arg2/>).
+
+    4.  If no unmerged, marker, or reject files remain, set
+        <resolve-verdict>NONE</resolve-verdict> and skip all remaining
+        items of this expansion.
+
+    5.  Classify every unmerged and marker file into its *conflict
+        kind*: `content` for a text file with conflict markers (`UU`,
+        `AA`, or a marker file), `binary` for a `UU` or `AA` file Git
+        treats as binary (no conflict markers written), `submodule` for
+        a gitlink entry (mode `160000`), `modify/delete` for `UD` and
+        `DU`, `rename` for `AU` and `UA`, and `delete/delete` for `DD`.
+
+3.  BACK UP FILES:
+
+    Set <resolve-backup-dir><git-dir/>/ase-resolve</resolve-backup-dir>.
+    For every unmerged and marker file which exists in the working
+    directory, back it up *before* touching it by running the commands
+    `mkdir -p "<resolve-backup-dir/>/<file-dir/>"` and
+    `cp -p "<repo-root/>/<file/>" "<resolve-backup-dir/>/<file/>"`,
+    where <file-dir/> is the directory part of <file/>. If a backup of
+    this file *already exists* (from an earlier, partial run), you
+    *MUST* *NOT* overwrite it, as it holds the *more original* state.
+    If a backup fails, you *MUST* *NOT* touch this file at all and
+    escalate it with the reason `backup failed`. The backups are
+    especially essential for marker files, whose sides exist *nowhere*
+    else than inside the file itself.
+
+4.  RESOLVE CONFLICTS:
+
+    Resolve every file which is *not* a reject file, one after another,
+    according to its conflict kind:
+
+    1.  `content`:
+
+        1.  Read the file and split it into its *conflict hunks*, each
+            consisting of the *ours* section (after `<<<<<<<`), the
+            optional *base* section (after `|||||||`, written under the
+            `diff3` or `zdiff3` conflict style), and the *theirs*
+            section (after `=======`, up to `>>>>>>>`). If no base
+            section exists and the file is unmerged with a stage `1`,
+            read the *base* version *read-only* by running the command
+            `git -C "<repo-root/>" show ":1:<file/>"`. You *MUST* *NEVER*
+            regenerate the markers via `git checkout --conflict=...` or
+            `git checkout -m`, as this would destroy all manual edits
+            already present in the file.
+
+        2.  For every hunk, understand *what* each side changed relative
+            to the base and *why* (with the help of the intents of
+            item 1.4, the surrounding code, and -- if necessary -- the
+            other places of the code base the hunk depends on), and
+            classify it:
+
+            -   *trivial*: both sides are identical, differ in
+                whitespace only, or one side equals the base -- take
+                the side carrying the change.
+            -   *independent*: both sides changed *different* aspects
+                (e.g., adjacent additions, unrelated edits of the same
+                region) -- combine *both* changes, ordering additions
+                in a sensible way.
+            -   *compatible*: both sides changed the *same* aspect, but
+                in a way that can be *combined* (e.g., one side renamed
+                an identifier, the other side added a use of it) -- merge
+                both, so *both* intents are honored.
+            -   *unresolvable*: both intents *contradict* each other
+                (e.g., the same value changed to two different values),
+                or you are *not confident* about a resolution.
+
+            Replace every *trivial*, *independent*, and *compatible*
+            hunk by its resolution, including the removal of its
+            conflict markers, while keeping every *unresolvable* hunk
+            *verbatim* including its conflict markers. Change *nothing*
+            outside of the conflict hunks, except for a consequence of
+            a *compatible* resolution which is *strictly* needed inside
+            the *same* file (e.g., the renamed identifier in code one
+            side added outside of the hunks).
+
+    2.  `binary` and `submodule`:
+
+        If <arg4/> is `true`, escalate the file untouched. Otherwise
+        compare the object ids of the stages: if the stage `2` or `3`
+        equals the stage `1` (one side left it unchanged), take the
+        other, changed side by running the command
+        `git -C "<repo-root/>" checkout --ours -- "<file/>"` (stage `2`)
+        or `git -C "<repo-root/>" checkout --theirs -- "<file/>"`
+        (stage `3`), which is independent of the swapped side
+        semantics under `rebase`. Otherwise, escalate the file, as two
+        different binary contents or submodule commits cannot be
+        combined.
+
+    3.  `modify/delete`, `rename`, and `delete/delete`:
+
+        If <arg4/> is `true`, escalate the file untouched. Otherwise
+        resolve it only if the intent is *unambiguous* and *no* change
+        gets lost:
+
+        -   `delete/delete`: both sides agree, so remove the file from
+            the index by running the command
+            `git -C "<repo-root/>" rm --quiet -- "<file/>"`.
+        -   `modify/delete` and `rename`: if the deleting side *moved*
+            the content (e.g., renamed or split the file), *port* the
+            modification of the other side *completely* into the new
+            location (then treated like a *compatible* content
+            resolution, including the change preservation check) and
+            remove the old file via `git -C "<repo-root/>" rm --quiet -- "<file/>"`.
+            If the deletion *intentionally* removed a feature, but the
+            other side modified it, the intents contradict each other,
+            so escalate the file. When uncertain, escalate, as keeping
+            the conflict is always safe.
+
+    4.  <if condition="<arg3/> is `true` and <ase-headless/> is not `true`">
+
+        Before a hunk or file is finally escalated, let the user decide
+        on it interactively. For this, first show the hunk (its *ours*,
+        *base*, and *theirs* sections, or the stage summary for a
+        non-content conflict), the determined intents of both sides,
+        and the reason why it is unresolvable. Then, in the following,
+        you *MUST* *NOT* use your built-in <user-dialog-tool/> tool!
+        Instead, you *MUST* just show a custom dialog according to the
+        expanded `custom-dialog` definition. You *MUST* closely follow
+        this definition:
+
+        <expand name="custom-dialog" arg1="--other">
+            Conflict: How shall the conflict be resolved? (free-text: describe the manual resolution)
+            OURS: take the ours side only
+            THEIRS: take the theirs side only
+            BOTH: take both sides, ours first, then theirs
+            KEEP: keep the conflict as it is and escalate it
+        </expand>
+
+        Apply `OURS`, `THEIRS`, or `BOTH` literally, which is an
+        *explicit* user decision and hence exempt from the change
+        preservation check below. For an `OTHER: ` result, strip this
+        prefix and apply the described manual resolution. For `KEEP` or
+        `CANCEL`, escalate the hunk or file as usual.
+
+        </if>
+
+    Record every escalated hunk or file in <resolve-escalations/> with
+    its file, its line range (or the whole file), its conflict kind, a
+    one-line intent of each side, and a one-line reason.
+
+5.  CHECK CHANGE PRESERVATION:
+
+    For every *resolved* hunk (except explicit user decisions), verify
+    that *no* change got lost: every line which *ours* added, removed,
+    or modified relative to the *base*, and every line which *theirs*
+    added, removed, or modified relative to the *base*, *MUST* be
+    reflected in the resolution, unless the deviation is *justified* by
+    the intent of the other side (e.g., a combined line which carries
+    both modifications). Without a base, every line of both sides
+    *MUST* be reflected. Additionally, compare the resolved file against
+    its backup by running the command
+    `git -C "<repo-root/>" diff --no-index -- "<resolve-backup-dir/>/<file/>" "<repo-root/>/<file/>"`
+    (which intentionally exits non-zero when the files differ) and
+    verify that it changed *nothing* outside of the conflict hunks
+    except for the strictly needed consequences of item 4.1.2.
+
+    If any check fails for a hunk, restore this hunk *verbatim* from the
+    backup, including its conflict markers, and escalate it with the
+    reason `change preservation check failed`. If the check cannot be
+    decided at all for a file, restore the entire file from the backup
+    by running the command
+    `cp -p "<resolve-backup-dir/>/<file/>" "<repo-root/>/<file/>"`
+    and escalate all its hunks.
+
+6.  STAGE RESOLVED FILES:
+
+    1.  Determine the *fully resolved* files: all unmerged and marker
+        files without any escalated hunk. Check them for leftover
+        conflict markers by running the command
+        `git -C "<repo-root/>" grep -n -I --untracked -E "^(<{7}|\|{7}|>{7})( |$)" -- <files/>`
+        (with <files/> being the quoted fully resolved files). If it
+        reports lines of a file, treat the reported hunks as escalated
+        with the reason `leftover conflict markers`.
+
+    2.  Stage every fully resolved *unmerged* file by running the
+        command `git -C "<repo-root/>" add -- "<file/>"` (except for
+        files already removed from the index via `git rm` or taken via
+        `git checkout --ours`/`--theirs`, which additionally need this
+        `git add`). You *MUST* *NOT* stage *marker* files, as they were
+        not staged before either, and you *MUST* *NOT* stage *partially*
+        resolved files, which hence stay *unmerged* (resp. carry their
+        remaining conflict markers).
+
+7.  DETERMINE VERDICT:
+
+    If <resolve-escalations/> is empty, set
+    <resolve-verdict>RESOLVED</resolve-verdict> and remove the backups
+    by running the command `rm -rf "<resolve-backup-dir/>"`. Otherwise,
+    set <resolve-verdict>PARTIAL</resolve-verdict> and *keep* the
+    backups, as they hold the original conflict state of the escalated
+    files.
+
+</define>
+
+<define name="resolve-report">
+
+<if condition="<resolve-escalations/> is not empty">
+Set <backups/> to the text `⊚ backups:`, followed by a blank and
+<resolve-backup-dir/> rendered as a code span, if <resolve-backup-dir/>
+is not empty, or to empty otherwise. Then only output the following <template/>, with one entry
+per escalation in <resolve-escalations/>:
+
+<template>
+<ase-tpl-head title="ESCALATIONS" subtitle="<arg1/>"/>
+
+<ase-tpl-bullet-signal/> `<file/>:<lines/>` (<kind/>): <reason/>
+    ◦ ours:   <ours-intent/>
+    ◦ theirs: <theirs-intent/>
+[...]
+
+<backups/>
+
+<ase-tpl-foot title="ESCALATIONS" subtitle="<arg1/>"/>
+</template>
+</if>
+
+</define>