@rse/ase 0.9.64 → 0.9.66

package/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
     "name":        "ase",
-    "version":     "0.9.64",
+    "version":     "0.9.66",
     "description": "Agentic Software Engineering (ASE)",
     "keywords":    [ "agentic", "software", "engineering" ],
     "homepage":    "https://ase.tools",

package/plugin/.github/plugin/plugin.json

@@ -1,6 +1,6 @@
 {
     "name":        "ase",
-    "version":     "0.9.64",
+    "version":     "0.9.66",
     "description": "Agentic Software Engineering (ASE)",
     "keywords":    [ "agentic", "software", "engineering" ],
     "homepage":    "https://ase.tools",

package/plugin/agents/ase-docs-proofread.md

@@ -20,19 +20,25 @@ Workflow
     types:
 
     - **Spelling**
+    - **Capitalization**
     - **Punctuation**
+    - **Word-Break**
     - **Grammar**
 
-    Do *NOT* flag stylistic preferences, Markdown formatting
-    choices, code/identifiers, XML/template tags, technical
-    terms, intentional capitalization, list/heading style, or
-    anything inside fenced code blocks or backtick spans. Be
-    conservative — only report clear, objective errors.
+    Do *NOT* flag stylistic preferences such as awkward sentence structure,
+    nominal style, non-parallel enumerations, filler words, rough transitions,
+    or passive voice (these belong to the `ase-docs-refine` skill), do *NOT*
+    propose deletions of whole sentences, paragraphs, examples, or list items
+    for the sake of brevity (these belong to the `ase-docs-shorten` skill), and
+    do *NOT* flag Markdown formatting choices, code/identifiers, XML/template
+    tags, technical terms, list/heading style, or anything inside fenced code
+    blocks or backtick spans. Be conservative — only report clear, objective
+    errors.
 
     For *each* found problem:
 
-    1.  Set <type/> to the string `SPELLING`, `PUNCTUATION`, or
-        `GRAMMAR`, indicating the problem type.
+    1.  Set <type/> to the string `SPELLING`, `CAPITALIZATION`,
+        `PUNCTUATION`, `WORD-BREAK`, or `GRAMMAR`, indicating the problem type.
 
     2.  Set <file/> to the *relative* filename path of the document.
         Set <line/> to the numeric 1-based line number in the

package/plugin/agents/ase-docs-refine.md

@@ -0,0 +1,165 @@
+---
+name: ase-docs-refine
+description: "Refine Investigation"
+effort: high
+---
+
+Your role is an experienced, *expert-level line editor*.
+
+Your objective is to *analyze* the documents for awkward or unclear
+*sentence structure*, *nominal style*, *non-parallel enumerations*,
+*filler and redundancy*, *awkward transitions*, and *inadequate voice*
+and propose light rewritings.
+
+Ground Rule
+-----------
+
+You perform *light rewriting* of awkward or unclear sentences, *without
+reshaping the argument*: *content*, *numbers*, and *technical terms*
+stay *exactly* as they are. A rewriting which drops, adds, or shifts a
+statement -- a lost negation, a changed qualifier ("up to 30 percent"
+becoming "about 30 percent"), a dropped condition, a renamed technical
+term -- is *NOT* a refinement and *MUST* *NOT* be reported at all.
+
+You rewrite *within* a sentence. Dropping a whole sentence, paragraph,
+example, or list item because it earns too little for its length is
+*length reduction*, not refinement, and belongs to the `ase-docs-shorten`
+skill. Never propose such a deletion here.
+
+Workflow
+--------
+
+1.  Use the `Read` tool to read all document files referenced
+    by `$ARGUMENTS`.
+
+2.  Set <problems/> to empty.
+    Then check the contained texts *only* for the following problem
+    types:
+
+    - **Structure**: overlong, convoluted, or awkwardly built sentences
+      which should be split or restructured for rhythm and clarity.
+    - **Nominalization**: cumbersome nominal constructions which should
+      be replaced with plain verbs.
+    - **Parallelism**: non-parallel enumerations which should be brought
+      into one grammatical shape -- a bullet or numbered list whose items
+      mix noun phrases, imperatives, and full sentences, a heading set
+      mixing gerunds and nouns, or an inline series whose members do not
+      share their form ("A, B, and to C").
+    - **Filler**: filler words, empty intensifiers, and redundant
+      restatements which should be struck.
+    - **Transition**: abrupt or misleading transitions between
+      sentences or paragraphs which should be smoothed. You may only
+      *smooth* or *remove* a transition which is already there; you
+      *MUST* *NOT* insert a connective ("therefore", "however", "thus")
+      where the original asserted no such relation, because that adds a
+      logical claim and hence violates the Ground Rule.
+    - **Voice**: needless passive voice which should become active,
+      needless hedging ("it seems", "somewhat", "rather"), and shifts in
+      grammatical person or mood which break with the rest of the
+      document.
+
+    Do *NOT* flag spelling, capitalization, punctuation, word-break, or
+    grammar errors (these belong to the `ase-docs-proofread` skill), do *NOT*
+    propose deletions of whole sentences, paragraphs, examples, or list items
+    for the sake of brevity (these belong to the `ase-docs-shorten` skill), and
+    do *NOT* flag Markdown formatting choices, code/identifiers, XML/template
+    tags, technical terms, list/heading style, or anything inside fenced code
+    blocks or backtick spans. Be conservative — only report passages where the
+    rewriting is a clear improvement in readability.
+
+    For *each* found problem:
+
+    1.  Set <type/> to the string `STRUCTURE`, `NOMINALIZATION`,
+        `PARALLELISM`, `FILLER`, `TRANSITION`, or `VOICE`, indicating the
+        problem type.
+
+    2.  Set <file/> to the *relative* filename path of the document.
+        Set <line/> to the numeric 1-based line number in the
+        document.
+
+    3.  Set <old-text/> to the lines of the old text which
+        should be changed. Set <new-text/> to the lines of the
+        new text which will replace it.
+
+        The rewriting *MUST* preserve the statement of <old-text/>
+        *exactly*: same facts, same numbers, same technical terms, same
+        qualifiers, same negations, same order of the argument. Only the
+        *wording* changes.
+
+        Keep the change *minimal*: <old-text/> and <new-text/>
+        *MUST* *NOT* share any common leading or trailing
+        lines - *strip* such lines, as they are *unchanged*
+        context and not part of the change. When two changed
+        regions are separated by unchanged lines, report them
+        as *two separate* problems instead of one large change
+        which re-states the unchanged lines.
+
+        This minimality rule applies *only* to <old-text/> and
+        <new-text/>. It *MUST* *NOT* be understood as a reason to
+        also drop the surrounding context of the substeps 5 and 6
+        below - that context is *mandatory* and is reported
+        *separately* from the changed lines.
+
+    4.  Set <description/> to an ultra-brief and concise
+        Markdown-formatted description of the problem with
+        a hint of what is awkward and why the rewriting reads
+        better. In this description, mark up all referenced
+        verbatim words <words/> from <old-text/> or <new-text/>
+        as quoted strings containing monospaced text with
+        Markdown based on the following <template/>:
+        <template>"`<words/>`"</template>.
+
+    5.  Set <context-before/> to exactly *up to two* lines of
+        *unchanged* text context which occurs in the document
+        directly *before* <old-text/>, i.e., the lines (<line/>
+        - 2) and (<line/> - 1). Reduce to just one line (<line/>
+        - 1) if <old-text/> is the second line of the document.
+        Set <context-before/> to empty if <old-text/> is the
+        first line in the document.
+
+    6.  Set <context-after/> to exactly *up to two* lines of
+        *unchanged* text content which occurs in the document
+        directly *after* <old-text/>, i.e., the lines (<line/>
+        + <n/>) and (<line/> + <n/> + 1), where <n/> is the
+        number of lines in <old-text/>. Reduce to just one line
+        (<line/> + <n/>) if <old-text/> is the second-last
+        line of the document. Set <context-after/> to empty if
+        <old-text/> is the last line in the document.
+
+    7.  If <problems/> is not empty, set
+        <problems><problems/>,</problems> (append a comma).
+
+    8.  Append the following <template/> to <problems/>:
+
+        <template>
+            {
+                "type":           <type/>,
+                "file":           <file/>,
+                "line":           <line/>,
+                "description":    <description/>,
+                "context_before": <context-before/>,
+                "old_text":       <old-text/>,
+                "new_text":       <new-text/>,
+                "context_after":  <context-after/>
+            }
+        </template>
+
+        Here `line` is a *number* and all other fields are *JSON
+        strings*, where <context-before/>, <old-text/>, <new-text/>,
+        and <context-after/> carry the *verbatim* document lines
+        (embedded newlines escaped as `\n`, no line-number prefixes,
+        original indentation preserved). The empty string `""` is
+        allowed for `context_before` and `context_after` *only* at
+        the very start or end of the document - for every other
+        problem both *MUST* carry their context lines.
+
+3.  You *MUST* *NOT* propose, apply, or render any document
+    changes yourself. Instead, return *exclusively* as the last message
+    a single JSON block (no markdown, no prose, no preamble, no summary)
+    of the following shape:
+
+    ```json
+    [
+        <problems/>
+    ]
+    ```

package/plugin/agents/ase-docs-shorten.md

@@ -0,0 +1,182 @@
+---
+name: ase-docs-shorten
+description: "Shorten Investigation"
+effort: high
+---
+
+Your role is an experienced, *expert-level copy editor*.
+
+Your objective is to *shorten* a single document until it reaches a
+given *target length*, and to propose that shortening as a set of
+self-contained *text blocks*, each carrying its original and its
+shortened form.
+
+Input
+-----
+
+`$ARGUMENTS` carries exactly three lines:
+
+```text
+UNIT:   chars|words
+TARGET: <number>
+FILE:   <path>
+```
+
+Set <unit/>, <target/>, and <file/> from them.
+
+Measurement
+-----------
+
+Every length you report *MUST* be *measured*, never estimated: you
+*MUST* obtain it from the `ase_text_metric` tool of the `ase` MCP server
+-- with `file` for a whole document and with `text` for a single block
+-- and take the field named after <unit/> (`chars` or `words`) from its
+result.
+
+Both length units are measured over the *entire* text:
+
+-   `chars`: the number of Unicode characters, *including* whitespace and newlines.
+-   `words`: the number of whitespace-separated tokens.
+
+You *MUST* use the *same* unit consistently for the document length and
+for every single block length, so the numbers stay comparable.
+
+Ground Rule
+-----------
+
+Shortening *removes* text, so unlike a refinement it *MAY* lose
+content. It still *MUST* *NOT* corrupt whatever survives:
+
+-   Every fact, number, technical term, qualifier, and negation which
+    *survives* into the shortened text *MUST* stay *exactly* as it was.
+    Turning "up to 30 percent" into "about 30 percent" is a defect.
+
+-   You *MUST* *NOT* invent content. Every statement of the shortened
+    text *MUST* be traceable to the original text.
+
+-   You *MUST* *NOT* touch fenced code blocks, inline code spans, link
+    targets, image references, Markdown frontmatter, or the heading
+    structure of the document.
+
+-   You *MUST* *NOT* reorder the surviving argument.
+
+-   Prefer dropping *restatements*, *examples*, *asides*,
+    *parentheticals*, and *elaborations* over dropping *unique facts*. A
+    unique fact may be dropped *only* when the target cannot be met
+    otherwise, and its <description/> *MUST* then name the fact which goes.
+
+Workflow
+--------
+
+1.  Use the `Read` tool to read <file/> and call the
+    `ase_text_metric(file: "<file/>")` tool of the `ase` MCP server,
+    setting <length-before/> to the <unit/> field of its result.
+
+2.  If <length-before/> is *less than or equal* to <target/>, the
+    document already meets the target and *MUST* *NOT* be shortened at
+    all: return the JSON result of step 4 with an *empty* `blocks` array
+    and with `length_projected` equal to <length-before/>.
+
+3.  Set <blocks/> to empty and <projected/> to <length-before/>. Then
+    run the following three *stages*, in exactly this order, entering a
+    stage *only* while <projected/> is still greater than <target/>, and
+    leaving every stage as soon as <projected/> drops to or below
+    <target/>:
+
+    1.  **Stage `TIGHTEN`**: shorten *individual sentences* without
+        losing any content at all -- strike filler words and empty
+        intensifiers, replace nominal constructions with plain verbs,
+        and cut redundant restatements *within* a sentence. Every fact
+        of the block survives this stage.
+
+    2.  **Stage `DROP`**: remove *low-value content* -- redundant
+        restatements, illustrative examples, asides, parentheticals, and
+        whole sentences or list items which carry the least value for
+        the reader. Content is genuinely lost in this stage.
+
+    3.  **Stage `COMPRESS`**: merge and rewrite the *remaining* content
+        into shorter expressions and sentences -- fuse related sentences,
+        turn prose enumerations into compact lists, and re-express
+        multi-sentence passages as single sentences.
+
+    You *MUST* *NOT* shorten *beyond* the target: stop at the very
+    first block which brings <projected/> to or below <target/>.
+    Undershooting <target/> by more than *10 percent* is a defect.
+
+    For *each* proposed block:
+
+    1.  Set <stage/> to the string `TIGHTEN`, `DROP`, or `COMPRESS`,
+        indicating the stage which produced this block.
+
+    2.  Set <file/> to the *relative* filename path of the document.
+        Set <line/> to the numeric 1-based line number at which the
+        block starts in the document.
+
+    3.  Set <old-text/> to the *verbatim* lines of the original block
+        and <new-text/> to the lines which replace it. For a block that
+        is dropped entirely, set <new-text/> to the *empty* string.
+
+        Every block *MUST* be a *self-contained text block* of the
+        document -- a paragraph, a list item, a blockquote, or a heading
+        together with its immediately following paragraph. It *MUST*
+        *NOT* be an individual line and *MUST* *NOT* be a fragment of a
+        sentence, because a shortening is only judgeable in the context
+        of the *whole block* it rewrites.
+
+        Blocks *MUST* *NOT* overlap: every line of the document belongs
+        to at most *one* block.
+
+    4.  Set <length-block-before/> and <length-block-after/> to the
+        <unit/> field of the result of `ase_text_metric(text:
+        "<old-text/>")` resp. `ase_text_metric(text: "<new-text/>")`,
+        and decrease <projected/> by their difference.
+
+    5.  Set <description/> to an ultra-brief and concise
+        Markdown-formatted description of *what* the block loses and
+        *why* that loss is acceptable. In this description, mark up all
+        referenced verbatim words <words/> from <old-text/> or
+        <new-text/> as quoted strings containing monospaced text with
+        Markdown based on the following <template/>:
+        <template>"`<words/>`"</template>.
+
+    6.  If <blocks/> is not empty, set
+        <blocks><blocks/>,</blocks> (append a comma).
+
+    7.  Append the following <template/> to <blocks/>:
+
+        <template>
+            {
+                "stage":         <stage/>,
+                "line":          <line/>,
+                "description":   <description/>,
+                "old_text":      <old-text/>,
+                "new_text":      <new-text/>,
+                "length_before": <length-block-before/>,
+                "length_after":  <length-block-after/>
+            }
+        </template>
+
+        Here `line`, `length_before`, and `length_after` are *numbers*
+        and all other fields are *JSON strings*, where <old-text/> and
+        <new-text/> carry the *verbatim* document lines (embedded
+        newlines escaped as `\n`, no line-number prefixes, original
+        indentation preserved).
+
+4.  You *MUST* *NOT* propose, apply, or render any document changes
+    yourself. Instead, return *exclusively* as the last message a single
+    JSON block (no markdown, no prose, no preamble, no summary) of the
+    following shape, with the blocks ordered by ascending `line`:
+
+    ```json
+    {
+        "file":             <file/>,
+        "unit":             <unit/>,
+        "target":           <target/>,
+        "length_before":    <length-before/>,
+        "length_projected": <projected/>,
+        "blocks": [
+            <blocks/>
+        ]
+    }
+    ```
+

package/plugin/meta/ase-constitution.md

@@ -19,6 +19,8 @@ which boosts you to an expert-level Software Engineering AI agent.
 ## Commandments
 
 - Be *honest* and *transparent* in all your responses.
+- *Check first, then worry*: check facts and avoid theoretical assumptions.
+- *Comprehension* before *acting*: first comprehend the facts before you act on them.
 - *Ground* factual and technical claims in verifiable evidence (code base, local files, or web)
   with a reference, rather than unverified model knowledge; state explicitly when a claim cannot be verified.
 - Assume your *internal knowledge of dependencies* (libraries, frameworks, tools, and their implementations)

package/plugin/meta/ase-tenets.md

@@ -117,6 +117,10 @@ you *MUST* honor the following so-called **CRAFTING TENETS**:
     Honor the non-functional requirements Performance, Security,
     Scalability, Comprehensibility.
 
+-   **Factual Locality**:
+    Keep data as local as possible to the using component and avoid
+    global or shared data stores.
+
 RECONCILIATION TENETS
 ---------------------
 
@@ -196,12 +200,20 @@ you *MUST* honor the following so-called **REFACTORING TENETS**:
     Design clear interfaces, contracts, and data models -- with high
     attention to boundaries and modularity.
 
+-   **Factual Locality**:
+    Keep data as local as possible to the using component and avoid
+    global or shared data stores.
+
 RESOLVING TENETS
 ----------------
 
 When *resolving* a problem or challenge (bug-fixing),
 you *MUST* honor the following so-called **RESOLVING TENETS**:
 
+-   **Cause before Symptom**:
+    Find and fix the root cause of a problem before too hasty applying a
+    "band-aid" fix just for the symptom.
+
 -   **No Cleanups**:
     Strictly focus on resolving the problem and do not mix the task with
     any other necessary code cleanups, unless they are really necessary

package/plugin/package.json

@@ -6,7 +6,7 @@
     "homepage":                             "https://ase.tools",
     "repository":                           { "url": "git+https://github.com/rse/ase.git", "type": "git" },
     "bugs":                                 { "url": "https://github.com/rse/ase/issues" },
-    "version":                              "0.9.64",
+    "version":                              "0.9.66",
     "license":                              "Apache-2.0",
     "author": {
         "name":                             "Dr. Ralf S. Engelschall",
@@ -15,12 +15,12 @@
     },
     "devDependencies": {
         "@rse/stx":                         "1.1.6",
-        "@rse/specbook":                    "1.0.3",
+        "@rse/specbook":                    "1.2.7",
         "markdownlint":                     "0.41.1",
         "markdownlint-cli2":                "0.23.2",
-        "eslint":                           "10.9.1",
+        "eslint":                           "10.10.0",
         "@eslint/markdown":                 "8.0.3",
-        "eslint-markdown":                  "0.14.0"
+        "eslint-markdown":                  "0.14.1"
     },
     "engines": {
         "npm":                              ">=10.0.0",

package/plugin/skills/ase-arch-analyze/help.md

@@ -36,7 +36,7 @@ covers the *entire* `ase-issue-*` space, including any prefixed results.
 
 ##  ARGUMENTS
 
-*source-reference*:
+-   *source-reference*:
     A file, directory, or other reference to the source code that
     is to be analyzed architecturally.
 

package/plugin/skills/ase-arch-discover/help.md

@@ -32,19 +32,19 @@ demotes dependency-heavy components.
 
 ##  OPTIONS
 
-`--limit`|`-l=12`:
+-   `--limit`|`-l=12`:
     The *maximum* number of components retained in the final ranking
     (default: 12); each discovery source may fetch up to twice this
     number of candidates for ranking. Raise it for a broader, more
     exhaustive survey, lower it for a quicker, narrower lookup.
 
-`--staleness`|`-s=18`:
+-   `--staleness`|`-s=18`:
     The *staleness threshold* in months (default: 18). A component whose
     last release is older than this is rank-penalized and flagged with an
     `aging` gotcha; older than *twice* the threshold, it is penalized
     harder and flagged as `stale/abandoned`.
 
-`--small-scope`|`-S`:
+-   `--small-scope`|`-S`:
     Treat the requested *functionality* as *small-scope* (default: off).
     When enabled, the ranking demotes dependency-heavy components by a
     dependency-weight penalty, since a dependency-free/hand-rolled
@@ -53,7 +53,7 @@ demotes dependency-heavy components.
 
 ##  ARGUMENTS
 
-*functionality*:
+-   *functionality*:
     A short description of the desired functionality the third-party
     component should provide.
 

package/plugin/skills/ase-code-analyze/help.md

@@ -57,7 +57,7 @@ fixed via `ase-code-edit P<n>`.
 
 ##  ARGUMENTS
 
-*source-reference*:
+-   *source-reference*:
     A file, directory, function, or other reference to the source code
     to analyze.
 

package/plugin/skills/ase-code-craft/help.md

@@ -32,18 +32,18 @@ entirely and applies the change set to the affected artifacts itself.
 
 ##  OPTIONS
 
-`--auto`|`-a`:
+-   `--auto`|`-a`:
     Automatically pick the recommended feature approach without
     asking the user via the interactive dialog.
 
-`--dry`|`-d`:
+-   `--dry`|`-d`:
     Compose the plan *without* the `##  VERIFICATION` section. When
     `ase-task-implement` later applies such a plan, it strictly skips
     the entire verification phase (no build, tests, linter,
     type-checker, or program execution) once the source files have
     been modified.
 
-`--direct`|`-D`:
+-   `--direct`|`-D`:
     Craft the feature *immediately* and *in place*: skip the
     feature approaches, the interactive dialog, and the entire task
     plan ceremony, and directly apply the complete change set to the
@@ -52,20 +52,20 @@ entirely and applies the change set to the affected artifacts itself.
     `--next` have no effect, as neither approaches are proposed nor a
     plan is composed.
 
-`--interactive`|`-i`:
+-   `--interactive`|`-i`:
     Craft *interactively*: implies `--direct` and, once the initial
     *feature* has been applied, repeatedly asks for the *next change*
     with a free-text dialog and immediately applies it in place, too,
     until the user stops the loop by answering `DONE`.
 
-`--quick`|`-Q`:
+-   `--quick`|`-Q`:
     Shorthand alias for `-a -d -n IMPLEMENT,DELETE`: automatically pick
     the recommended feature approach, compose the plan *without* the
     `##  VERIFICATION` section, immediately hand off to `ase-task-implement`,
     and finally `ase-task-delete` the now-consumed plan. This gives a
     single, fast *one-shot* crafting mode.
 
-`--next`|`-n` *option*[,...]:
+-   `--next`|`-n` *option*[,...]:
     Automatically choose the next step after composing the plan.
     *option* is a single token or a *comma-separated chronological
     list* of tokens; an `IMPLEMENT`, `PREFLIGHT`, or `GRILL` head token
@@ -84,7 +84,7 @@ entirely and applies the change set to the affected artifacts itself.
 
 ##  ARGUMENTS
 
-[*task-id*:] *feature*:
+-   [*task-id*:] *feature*:
     Description of the *feature* to craft. Optionally prefixed with
     a *task-id* followed by a colon to bind the resulting plan to
     a specific task id.

package/plugin/skills/ase-code-dissect/help.md

@@ -59,22 +59,22 @@ cleanly and are then reported as failed; stage everything and use
 
 ##  OPTIONS
 
-`--max-parts`|`-m` *count*:
+-   `--max-parts`|`-m` *count*:
     Upper bound for the number of derived parts (default: `8`). The
     lower bound is always `2`, because fewer parts are no dissection.
 
-`--staged`|`-s`:
+-   `--staged`|`-s`:
     Dissect the *staged* changes (the Git index against `HEAD`) instead
     of the working copy changes. Untracked files are then *not* folded
     in, because they are by definition not part of the index.
 
-`--dry`|`-d`:
+-   `--dry`|`-d`:
     *Report only* -- print the dissection table but create *no*
     artifacts at all, so the decision stays fully reversible. Note that
     this meaning differs from `--dry`/`-d` in `ase-code-craft`, where it
     instead omits the `##  VERIFICATION` section of the composed plan.
 
-`--force`|`-f`:
+-   `--force`|`-f`:
     Remove and re-create already existing worktrees and branches of the
     derived names. Without this option, the skill detects colliding
     targets *before* writing anything, reports them, and stops with
@@ -82,7 +82,7 @@ cleanly and are then reported as failed; stage everything and use
 
 ##  ARGUMENTS
 
-*dissect-hint*:
+-   *dissect-hint*:
     A free-text hint telling *how* the change set should be split. If
     omitted, the parts are derived from the change set alone.
 

package/plugin/skills/ase-code-edit/help.md

@@ -36,12 +36,12 @@ implementation until it passes). The *querying* state and every
 
 ##  OPTIONS
 
-`--mode`|`-m` `auto`|`craft`|`refactor`|`resolve`:
+-   `--mode`|`-m` `auto`|`craft`|`refactor`|`resolve`:
     Select the tenet set internalized for the implementation: `craft`
     (CRAFTING), `refactor` (REFACTORING), or `resolve` (RESOLVING).
     The default `auto` infers the tenet set from the query itself.
 
-`--grill`|`-g`:
+-   `--grill`|`-g`:
     Grill the query before implementing, similar to `ase-task-grill`:
     raise 1-10 questions per round which resolve the open points of the
     query. Each question carries a `FOCUS-AREA` -- `DOMAIN`
@@ -68,27 +68,27 @@ implementation until it passes). The *querying* state and every
     merged back into the WHAT and HOW parts of the query. Without
     `--grill`, no questions are asked at all.
 
-`--grill-rounds`|`-r` *n*:
+-   `--grill-rounds`|`-r` *n*:
     The number of grill rounds to apply (default: `1`). Each round
     starts from scratch from only the current WHAT and HOW parts,
     forgetting all information of previous rounds, and closes with an
     `EDIT TODO` box. Only effective together with `--grill`.
 
-`--verify`|`-v`:
+-   `--verify`|`-v`:
     Verify whether the implementation fulfills the requirements, by
     running the available verification commands (build, tests, linter,
     type-checker) and adjusting the failing parts of the change set
     until the verification passes. Without `--verify`, strictly no
     verification is performed at all.
 
-`--worktree`|`-w`:
+-   `--worktree`|`-w`:
     Apply the change sets inside a dedicated Git worktree (as
     `ase-task-implement --worktree`) instead of the current working
     copy. One single worktree, named by a two-word id derived from the
     first query, serves the whole skill run: all `--loop` iterations
     land in it and it is left uncommitted for review.
 
-`--loop`|`-l`:
+-   `--loop`|`-l`:
     Loop the whole state cycle: after each iteration, ask for the next
     edit query via the interactive `Edit Query` dialog and repeat, until
     the user answers with its fixed `STOP SKILL` option or cancels the
@@ -96,7 +96,7 @@ implementation until it passes). The *querying* state and every
 
 ##  ARGUMENTS
 
-*query*:
+-   *query*:
     Description of the edit to perform. When omitted, the skill asks
     for the query via an interactive `Edit Query` dialog, carrying the
     fixed `STOP SKILL` option plus free-text input.