@rse/ase 0.9.61 → 0.9.63

package/plugin/meta/ase-tenets.md

@@ -6,7 +6,7 @@ The following are the **ASE Tenets** -- the guiding principles you
 *MUST* internalize when requested. They are organized into *Generic
 Tenets*, which always apply, and *Operation-Specific Tenets*, which
 apply only to a particular kind of operation (Crafting, Reconciling,
-Refactoring, Resolving).
+Refactoring, Resolving, Specifying).
 
 GENERIC TENETS
 --------------
@@ -149,11 +149,11 @@ you *MUST* honor the following so-called **RECONCILIATION TENETS**:
 -   **Level-Appropriate Translation**:
     Re-express source facts at the *target's* level of abstraction and
     altitude; do not copy verbatim across artifact levels. A SPEC states
-    intent, an ARCH states structure, CODE states realization, DOCS
-    states facts, etc. -- align the *meaning*, not the wording.
+    intent and structure, CODE states realization, DOCS states facts,
+    etc. -- align the *meaning*, not the wording.
 
 -   **Format Conformance**:
-    Keep every formatted target (SPEC, ARCH, TASK) conformant to its
+    Keep every formatted target (SPEC, TASK) conformant to its
     format contract (headings, structure, identifiers). Treat CODE,
     DOCS, INFR, and OTHR kinds of artifacts as foreign-defined, but not
     as free-form.
@@ -221,3 +221,62 @@ you *MUST* honor the following so-called **RESOLVING TENETS**:
     handled *near the origin*. Problems for *theoretical, fictive, or
     unexpected* errors *should* be handled more generally and in parent
     scopes.
+
+SPECIFYING TENETS
+-----------------
+
+When *specifying* -- creating, revising, or editing the statements of a
+specification artifact set -- you *MUST* honor the following so-called
+**SPECIFYING TENETS**:
+
+-   **Intent over Realization**:
+    A specification, in its domain-specific and non-architecture related
+    aspects, states only the *WHAT* and the *WHY*, never the *HOW*.
+    Record intent, structure, constraints, and relationships here.
+    Implementation steps, algorithms, technologies, and code-level
+    details describe the *WHAT* and *HOW* and belong only into
+    the domain-unspecific and architecture-related aspects of the
+    specification.
+
+-   **Statement with Rationale**:
+    Every statement carries its *WHY* behind the `, BECAUSE ` clause in
+    a description. A statement without a rationale can neither be judged
+    nor revised, so never leave the rationale implicit and never restate
+    the statement as its own rationale.
+
+-   **Unambiguous and Verifiable**:
+    Every statement is precise enough that two readers derive the same
+    meaning and that its fulfillment is decidable. Replace vague
+    qualifiers ("fast", "user-friendly", "robust") with the concrete
+    property, threshold, or scenario actually meant.
+
+-   **Single Source of Truth**:
+    Every fact resides in exactly *one* object of the specification. Do
+    not restate a fact in a second place -- point at its owning object
+    with a `[[xxx]]` reference instead, so a later change has exactly
+    one place to land.
+
+-   **Atomic Statement**:
+    Every statement expresses exactly *one* fact with exactly *one*
+    rationale. Split a statement that joins independent facts with
+    "and"/"or" -- otherwise its fulfillment is only partially decidable
+    and its rationale covers more than it explains.
+
+-   **Schema Conformance**:
+    Every object stays conformant to the **SpecBook SCHEMA Model** of
+    the project: allowed kinds, allowed nesting, mandatory and optional
+    properties, and the configured value constraints. Never invent an
+    object kind or a property key the schema does not define.
+
+-   **Referential Integrity**:
+    Every `[[xxx]]` reference resolves to exactly one object. When an
+    object is renamed, moved, or removed, follow *all* references to it
+    through the entire specification corpus and adjust or remove them
+    in the same change set -- a dangling or ambiguous reference is a
+    defect.
+
+-   **No Fabrication**:
+    Never invent specification content the request does not warrant. If
+    the request is silent, ambiguous, or contradictory on something the
+    specification needs, surface the gap explicitly rather than papering
+    over it with a plausible guess.

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.61",
+    "version":                              "0.9.63",
     "license":                              "Apache-2.0",
     "author": {
         "name":                             "Dr. Ralf S. Engelschall",
@@ -15,9 +15,10 @@
     },
     "devDependencies": {
         "@rse/stx":                         "1.1.6",
+        "@rse/specbook":                    "1.0.2",
         "markdownlint":                     "0.41.1",
         "markdownlint-cli2":                "0.23.2",
-        "eslint":                           "10.9.0",
+        "eslint":                           "10.9.1",
         "@eslint/markdown":                 "8.0.3",
         "eslint-markdown":                  "0.14.0"
     },
@@ -25,6 +26,9 @@
         "npm":                              ">=10.0.0",
         "node":                             ">=22.13.0"
     },
+    "allowScripts": {
+        "fsevents":                         true
+    },
     "scripts": {
         "start":                            "stx -v4 -l warning -c etc/stx.conf"
     }

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

@@ -482,7 +482,7 @@ interface quality, quality attributes, and architecture governance.
     nothing and hence emit no output at all):
 
     <ase-tpl-hint level="minimal">
-    For deeper analysis, suggestions on solution approaches and then final source code changes, use `/ase-code-resolve <id-prefix/>P{n}` or `/ase-code-resolve <id-prefix/>T{n}` in the same or even a different session.
+    For deeper analysis, suggestions on solution approaches and then final source code changes, use `/ase-code-resolve <id-prefix/>P{n}` or `/ase-code-resolve <id-prefix/>T{n}`, or for a direct one-shot fix use `/ase-code-edit <id-prefix/>P{n}` or `/ase-code-edit <id-prefix/>T{n}`, in the same or even a different session.
     </ase-tpl-hint>
 
     </step>

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

@@ -218,7 +218,7 @@ problems in *performance* and *efficiency*, or problems in *security*.
     nothing and hence emit no output at all):
 
     <ase-tpl-hint level="minimal">
-    For deeper analysis, suggestions on solution approaches and then final problem resolution, use `/ase-code-resolve <id-prefix/>P{n}` in the same or even a different session.
+    For deeper analysis, suggestions on solution approaches and then final problem resolution, use `/ase-code-resolve <id-prefix/>P{n}`, or for a direct one-shot fix use `/ase-code-edit <id-prefix/>P{n}`, in the same or even a different session.
     </ase-tpl-hint>
 
     You *MUST* not output anything else in this STEP 3,

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

@@ -52,7 +52,8 @@ problem as a `PROBLEM` entry with severity (`LOW`, `MEDIUM`, `HIGH`) and
 inline file/line references (in the performance lens, each entry
 additionally carries an *evidence* and a *trade-off* line), and persists
 results in the `ase` MCP key/value store as `ase-issue-P<n>` entries so
-they can later be resolved via `ase-code-resolve P<n>`.
+they can later be resolved via `ase-code-resolve P<n>` or directly
+fixed via `ase-code-edit P<n>`.
 
 ##  ARGUMENTS
 

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

@@ -1,11 +1,11 @@
 ---
 name: ase-code-edit
-argument-hint: "[--help|-h] [--mode|-m auto|craft|refactor|resolve] [--grill|-g] [--grill-rounds|-r <n>] [--verify|-v] [--worktree|-w] [--loop|-l] [<query>]"
+argument-hint: "[--help|-h] [--mode|-m auto|craft|refactor|resolve] [--grill|-g] [--grill-rounds|-r <n>] [--verify|-v] [--worktree|-w] [--loop|-l] [<query>|<issue-id>]"
 description: >
     Edit Source Code: Use when the user wants to "edit" the code base in
-    one shot from a query, fusing crafting, refactoring, and resolving
-    with optional grilling, verification, looping, and Git worktree
-    isolation.
+    one shot from a query or a bare analyzer issue id like "P1", fusing
+    crafting, refactoring, and resolving with optional grilling,
+    verification, looping, and Git worktree isolation.
 user-invocable: true
 disable-model-invocation: false
 effort: xhigh
@@ -33,6 +33,7 @@ resolving in one shot -- through the states *querying*, *discovering*,
 </objective>
 
 @${CLAUDE_SKILL_DIR}/../../meta/ase-tenets.md
+@${CLAUDE_SKILL_DIR}/../../meta/ase-common-grill.md
 
 Procedure
 ---------
@@ -114,7 +115,32 @@ empty <todo-what/> or <todo-how/> renders as `(none)`:
 
         </if>
 
-    2.  Convert the <query/> *fresh* into <todo-what/> -- the
+    2.  <if condition="<query/> matches the regexp `^([a-zA-Z][a-zA-Z0-9_]*-)?[PT]\d+$`">
+
+        The <query/> is a bare issue identifier (like `P1`, `T1`, or
+        `<prefix>-P1`) previously produced by `ase-code-analyze` or
+        `ase-arch-analyze`. Set <issue-id><query/></issue-id> and call
+        the `ase_kv_get(key: "ase-issue-<issue-id/>")` tool of the
+        `ase` MCP server to retrieve the persisted problem description.
+        If the returned `text` is non-empty, set <query><text/></query>
+        and only output the following <template/>:
+
+        <template>
+        ⧉ **ASE**: ✪ skill: **ase-code-edit**, ⇌ issue: **<issue-id/>**, ▶ status: **issue retrieved**
+        </template>
+
+        Otherwise, set <issue-id></issue-id> (empty) and only output the
+        following <template/>, then, under `--loop`, continue with the
+        *next* iteration at item 3.1 above, or, without `--loop`,
+        immediately *STOP* processing the entire current skill:
+
+        <template>
+        ⧉ **ASE**: ✪ skill: **ase-code-edit**, ▶ ERROR: no analyzer result exists for issue **<query/>**
+        </template>
+
+        </if>
+
+    3.  Convert the <query/> *fresh* into <todo-what/> -- the
         domain-specific, non-implementation-detail information -- and
         <todo-how/> -- the remaining information -- discarding all
         <todo-what/>/<todo-how/> content of any previous iteration.
@@ -122,11 +148,11 @@ empty <todo-what/> or <todo-how/> renders as `(none)`:
         and during later implementation just interpret the query best-effort.
         Do not output anything.
 
-    3.  Expand the following:
+    4.  Expand the following:
 
         <expand name="todo-box" arg1="current state (after querying)"></expand>
 
-    4.  Set <query></query> (clear the query, so every further `--loop`
+    5.  Set <query></query> (clear the query, so every further `--loop`
         iteration asks for a fresh one). Do not output anything.
 
 4.  **State: discovering:**
@@ -144,85 +170,16 @@ empty <todo-what/> or <todo-how/> renders as `(none)`:
 
     1.  Understand what "grilling" is about:
 
-        -   GOAL:
-
-            Interactively interviewing the user *relentlessly* about every
-            *essential aspect* of the edit query in <todo-what/> and
-            <todo-how/> *until* reaching a shared understanding and no
-            major decisions/questions are left open.
-
-            This especially means that you *MUST* clarify as many aspects as
-            necessary to ensure that for at least the most important decisions,
-            during a subsequent implementation, no essential freedom of choice
-            exists any longer.
-
-        -   FOCUS:
-
-            Focusing on the following outside-in *Focus Areas*, in order of
-            descending importance for the grilling operation:
-
-            1.  *DOMAIN*: Aspects affecting domain-specifics. These
-                aspects *MUST* be clarified, as they are about
-                the "what" of the solution and they
-                non-technically shape the solution noticeably.
-
-            2.  *INTERFACE*: Aspects affecting externally observable
-                behavior or interfaces, especially aspects about user (UI)
-                and machine (API) interfaces. These aspects *MUST* be
-                clarified, as they are externally visible and
-                shape the boundary of the solution.
-
-            3.  *ARCHITECTURE*: Aspects affecting software and system
-                architecture, especially decisions on structure, wiring,
-                placement, or dependencies. These aspects *SHOULD*
-                be clarified, as they technically shape the solution noticeably.
-
-            4.  *IMPLEMENTATION*: Aspects affecting any other
-                implementation details, especially how the edit query
-                is realized in the code base. These aspects *CAN* be
-                clarified, as they shape technical inner details only.
-
-        -   INDICATORS:
-
-            Check the following indicators for identifying problematic
-            aspects:
-
-            -   *Fuzzy Language*:
-                When the user uses vague or overloaded terms instead of
-                a precise or canonical term.
-
-            -   *Conflicting Terminology*:
-                When the user uses a term that conflicts with the
-                existing terminology in the code base.
-
-            -   *Conflicting Code*:
-                When the user states how something works, check whether the
-                current code state really agrees.
-
-            -   *Non-Concrete Scenarios*:
-                When domain relationships are being discussed,
-                stress-test them with specific scenarios. Theoretically
-                invent realistic scenarios that probe edge cases and
-                force the user to be precise about the boundaries
-                between concepts.
-
-            -   *Unspecified Architecture Patterns*:
-                When the realization of the functionality is known to
-                be reasonably realizable with more than one decent
-                architecture pattern, but no such pattern was
-                mentioned.
-
-            -   *Unspecified Dependencies*:
-                When the realization of functionality usually is known
-                to be supported by the use of frameworks or libraries,
-                but no dependencies on such solutions were mentioned.
+        <expand name="grill-understanding" arg1="the edit query in <todo-what/> and <todo-how/>"></expand>
 
     2.  Perform <getopt-option-grill-rounds/> grilling *rounds*,
         numbered <m/> (1-<getopt-option-grill-rounds/>).
 
         For each round:
 
-        1.  Explicitly start *from scratch* from *only* the current
+        1.  INITIALIZE TODO:
+
+            Explicitly start *from scratch* from *only* the current
             <todo-what/> and <todo-how/> and *forget* all information
             gathered in previous rounds. Set <round-id/> to
             `GRILLING ROUND <m/>/<getopt-option-grill-rounds/>` if
@@ -230,50 +187,76 @@ empty <todo-what/> or <todo-how/> renders as `(none)`:
             `GRILLING` otherwise (a single round needs no round
             numbering). Do not output anything.
 
-        2.  Determine the very brief but precise questions <question-N/>,
-            chosen to resolve the open points related to the above
-            understanding of grilling, by focusing on the mentioned
-            *Focus Areas*.
-
-            For each <question-N/> determine its <focus-area-N/> and a
-            <topic-N/>, a 1-2 word hint describing what the question is
-            about. Render <focus-area-N/> in the tables below as
-            `**DOMAIN** (MUST)`, `**INTERFACE** (MUST)`,
-            `**ARCHITECTURE** (SHOULD)`, or `**IMPLEMENTATION** (MAY)`
-            correspondingly.
-
-            Use the format `Shall...?` for questions of
-            focus area *DOMAIN* and *INTERFACE*, the format `Should...?`
-            for questions of focus area *ARCHITECTURE*, and the format
-            `May...?` for questions of focus area *IMPLEMENTATION*.
-
-            In every <question-N/>, encode all *literal aspects* -- file
-            and directory paths, identifiers, symbols, types, commands,
-            options, configuration keys, and literal values -- with
-            backticks.
-
-            Keep every <question-N/> at most *200 characters* long, as a
-            longer question overflows its table cell and silently
-            degrades the entire table into a plain text rendering.
-
-        3.  Finally, *sort* the questions by descending
-            focus area order -- first all `DOMAIN`, then all
-            `INTERFACE`, then all `ARCHITECTURE`, and then all
-            `IMPLEMENTATION` ones -- and renumber <N/> according to this
-            order. Truncate the list after a maximum of 10 questions and
-            set <n/> to the number of remaining questions. Do not output
+        2.  DETERMINE QUESTIONS:
+
+            Determine the questions, comprised of a round-local id
+            <question-N-id/> of `Q<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*.
+
+            For <question-N-text/> use the format `Shall...?` for
+            questions of focus area `DOMAIN` and `INTERFACE`, 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*
+            -- file and directory paths, identifiers, symbols, types,
+            commands, options, configuration keys, and literal values --
+            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.
+
+        3.  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, and a <context-N-severity/>, describing how
+            important this question is.
+
+            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`, and `IMP` for
+            <context-N-focus/> of `IMPLEMENTATION`.
+
+        4.  SORT QUESTIONS:
+
+            Finally, *sort* the questions by descending focus area
+            order -- first all `DOMAIN`, then all `INTERFACE`, then all
+            `ARCHITECTURE`, and then all `IMPLEMENTATION` ones -- and
+            renumber <N/> according to this order, starting at `1`.
+            Truncate the list after a maximum of 10 questions and set
+            <n/> to the number of remaining questions. Do not output
             anything.
 
-        4.  For all remaining <question-N/>, check the code base
-            and your world knowledge to find *two to three*
-            grounded answer alternatives <answer-N-K/> with 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
-            <todo-what/>/<todo-how/> understanding prefixing its
-            description with `✻ **CURRENT** ✻`. Assemble a <answer-N/>
-            out of `**A1**: **<answer-N-1-label/>**: <answer-N-1-description/> ─◇─
-            **A2**: **<answer-N-2-label/>**: <answer-N-2-description/> ─◇─ [...]`.
+            Finally, assemble the <question-N/> out of
+            `**<question-N-id/>** ▶ **<context-N-id/>** ▷
+            **<context-N-topic/>**: <question-N-text/>`.
+
+        5.  DETERMINE ANSWERS:
+
+            For all remaining <question-N/>, check the code base and
+            your world knowledge to find *two to three* grounded answer
+            alternatives <answer-N-K/> with a question-local id
+            <answer-N-K-id/> of `A<K/>` -- 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 <todo-what/>/<todo-how/> understanding, 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
@@ -281,7 +264,9 @@ empty <todo-what/> or <todo-how/> renders as `(none)`:
             its table cell and silently degrades the entire table into a
             plain text rendering.
 
-        5.  In the following, you *MUST* *NOT* use your built-in
+        6.  INTERACTIVE DIALOG:
+
+            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. The
@@ -289,8 +274,8 @@ empty <todo-what/> or <todo-how/> renders as `(none)`:
             `SKIP GRILLING` and `STOP SKILL`, dispatched as follows:
 
             -   If a <result/> is `SKIP GRILLING` or `CANCEL`, ask no
-                further questions, continue with item 6 below (merging
-                the answers gathered so far), and after item 7 skip all
+                further questions, continue with item 7 below (merging
+                the answers gathered so far), and after item 8 skip all
                 remaining rounds and continue with the *implementing*
                 state.
 
@@ -305,9 +290,7 @@ empty <todo-what/> or <todo-how/> renders as `(none)`:
             1.  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. If
-                <getopt-option-grill-rounds/> is equal `1`, *omit* the
-                leading `<round-id/>` line.
+                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*
@@ -317,13 +300,16 @@ empty <todo-what/> or <todo-how/> renders as `(none)`:
                 entire table into a plain text rendering:
 
                 <template>
-                ⧉ **ASE**: <round-id/>:
+                ⧉ **ASE**: <round-id/>: *Relentless Interviewing Until Clarity*
+
+                | QUESTION      | ANSWERS     |
+                | ------------- | ----------- |
+                | <question-1/> | <answer-1/> |
+                | <question-2/> | <answer-2/> |
+                | [...]         | [...]       |
 
-                | #      | FOCUS ▶ TOPIC                 | **QUESTION**      | **ANSWERS** |
-                | :----: | ----------------------------- | ----------------- | ----------- |
-                | **Q1** | <focus-area-1/> ▶ <topic-1/>  | **<question-1/>** | <answer-1/> |
-                | **Q2** | <focus-area-2/> ▶ <topic-2/>  | **<question-2/>** | <answer-2/> |
-                | [..]   | [...]                         | [...]             | [...]       |
+                Legend: **DOM**: Domain (MUST), **IFC**: Interface (MUST), **ARC**: Architecture (SHOULD), **IMP**: Implementation (MAY)
+                        **Qn**: round-local question id, **An**: question-local answer id, ⚑: current decision state
                 </template>
 
             2.  Show a custom dialog. Its only answer options are the
@@ -331,7 +317,7 @@ empty <todo-what/> or <todo-how/> renders as `(none)`:
                 *one* free-text reply:
 
                 <expand name="custom-dialog" arg1="--other">
-                    <round-id/>: What is your (combined) answer to all (or a subset) of the above questions? (keywords are sufficient)
+                    <round-id/>: What is your (combined) answer to all (or a subset) of the above questions? (keywords or `Qn:An` references are sufficient)
                     SKIP GRILLING: skip all remaining grilling and continue with the implementation
                     STOP SKILL: stop the entire skill immediately
                 </expand>
@@ -342,11 +328,15 @@ empty <todo-what/> or <todo-how/> renders as `(none)`:
                 combined free-text answers to all questions of the
                 round.
 
-        6.  Merge all gathered answers of the round -- the combined
-            reply -- *exclusively* back into <todo-what/> and
+        7.  MERGE ANSWERS INTO TODO:
+
+            Merge all gathered answers in <result/> of the round -- the
+            combined reply -- *exclusively* back into <todo-what/> and
             <todo-how/>. Do not output anything.
 
-        7.  Set <round-suffix/> to
+        8.  SHOW CURRENT TODO:
+
+            Set <round-suffix/> to
             ` round <m/>/<getopt-option-grill-rounds/>` if
             <getopt-option-grill-rounds/> is greater than 1, or to
             empty otherwise, and expand the following -- this
@@ -363,6 +353,10 @@ empty <todo-what/> or <todo-how/> renders as `(none)`:
             `resolve`: Set <task-kind/> to `CRAFTING`, `REFACTORING`,
             or `RESOLVING` correspondingly.
 
+        -   Else if <issue-id/> is not empty (`auto` with a retrieved
+            analyzer issue): Set <task-kind/> to `RESOLVING`, as the
+            edit fixes a reported problem.
+
         -   Else (`auto`): *Infer* the <task-kind/> from <todo-what/> and
             <todo-how/>: set to `RESOLVING` if the edit predominantly
             fixes a defect, set to `REFACTORING` if it predominantly
@@ -447,7 +441,15 @@ empty <todo-what/> or <todo-how/> renders as `(none)`:
         user keeps full control over the final commit.
         </if>
 
-    4.  Output only the following <template/>. You *MUST* *NOT* output a
+    4.  <if condition="<issue-id/> is not empty">
+        Call the `ase_kv_delete(key: "ase-issue-<issue-id/>")` tool of
+        the `ase` MCP server to remove the now-resolved analyzer result
+        from the key/value store, then set <issue-id></issue-id> (empty),
+        so every further `--loop` iteration starts without an issue.
+        Do not output anything.
+        </if>
+
+    5.  Output only the following <template/>. You *MUST* *NOT* output a
         change summary, a list of modified artifacts, a rationale, or a
         unified diff of the changes -- *independent* of
         <ase-project-boxing/>, whose exposure rules are explicitly
@@ -467,7 +469,7 @@ empty <todo-what/> or <todo-how/> renders as `(none)`:
     1.  Verify whether the implementation fulfills <todo-what/> and
         <todo-how/> by running available verification commands
         (build, tests, linter, type-checker)
-        <if condition=" <worktree-dir/> is not empty">
+        <if condition="<worktree-dir/> is not empty">
         , each with <worktree-dir/> as its working directory
         </if>.
 

package/plugin/skills/ase-code-lint/SKILL.md

@@ -20,7 +20,7 @@ Lint Source Code
 
 <expand name="getopt"
     arg1="ase-code-lint"
-    arg2="--auto|-a --severity|-S=(LOW|MEDIUM|HIGH) --include|-i=(none|A01|A02|A03|A04|A05|A06|A07|A08|A09|A10|A11|A12|A13|A14|A15|A16|A17|A18|A19|A20)... --exclude|-e=(none|A01|A02|A03|A04|A05|A06|A07|A08|A09|A10|A11|A12|A13|A14|A15|A16|A17|A18|A19|A20)...">
+    arg2="--auto|-a --severity|-S=(LOW|MEDIUM|HIGH) --include|-i=(none|A01|A02|A03|A04|A05|A06|A07|A08|A09|A10|A11|A12|A13|A14|A15|A16|A17|A18|A19|A20|A21)... --exclude|-e=(none|A01|A02|A03|A04|A05|A06|A07|A08|A09|A10|A11|A12|A13|A14|A15|A16|A17|A18|A19|A20|A21)...">
     $ARGUMENTS
 </expand>
 
@@ -53,16 +53,16 @@ related to a set of code quality aspects.
     <getopt-option-include/> and <getopt-option-exclude/> as
     comma-separated token lists, silently dropping the `none` sentinel
     and any empty token. If a token <token/> is *not* one of the aspect
-    ids `A01`...`A20`, only output the following <template/> and then
+    ids `A01`...`A21`, only output the following <template/> and then
     *STOP* the entire flow (do not perform any further steps):
 
     <template>
     ⧉ **ASE**: ✪ skill: **ase-code-lint**, ▶ ERROR: invalid aspect id: **<token/>**
     </template>
 
-    Otherwise set <aspects/> to *all* twenty aspect ids `A01`...`A20`
+    Otherwise set <aspects/> to *all* twenty-one aspect ids `A01`...`A21`
     if both lists are empty, to the *include* list if only it is
-    non-empty, to all twenty *minus* the *exclude* list if only it is
+    non-empty, to all twenty-one *minus* the *exclude* list if only it is
     non-empty, and to the *include* list *minus* the *exclude* list if
     both are non-empty. If the resulting <aspects/> is *empty*, only
     output the following <template/> and then *STOP* the entire flow
@@ -143,7 +143,7 @@ related to a set of code quality aspects.
 
     Use the following <template/> to output a summary of the detected
     problems in <problems/> (if any were found), in the original aspect
-    ordering `A01 - XXX`...`A20 - XXX`.
+    ordering `A01 - XXX`...`A21 - XXX`.
 
     <template>
     <ase-tpl-bullet-secondary/> **LINT SUMMARY**:

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

@@ -27,22 +27,31 @@ correction interactively (or refine it via a free-text hint, which
 re-proposes the correction without limit) or - with `--auto` - applies
 all corrections automatically.
 
-By default all twenty code quality aspects are checked. The `--include`
+By default all twenty-one code quality aspects are checked. The `--include`
 and `--exclude` options narrow this to an *effective aspect set*: with
 `--include` only, exactly the listed aspects are checked; with
 `--exclude` only, all aspects except the listed ones; with both, the
 included ones minus the excluded ones. An unknown aspect id, or a
 combination which cancels out to an empty set, aborts the skill with an
-error. The twenty aspect ids are:
+error. The twenty-one aspect ids are:
 
 ```text
-A01 FORMATTING     A06 REDUNDANCY       A11 TYPING          A16 SECURITY
-A02 COMPREHENSION  A07 PATTERNS         A12 ERROR-HANDLING  A17 ARCHITECTURE
-A03 CLEANLINESS    A08 COMPLICATEDNESS  A13 MEMORY-LEAK     A18 LOGIC
-A04 SPELLING       A09 CONCISENESS      A14 CONCURRENCY     A19 FLOW
-A05 COMPLEXITY     A10 SMELLS           A15 PERFORMANCE     A20 DEAD-CODE
+A01 FORMATTING     A07 PATTERNS         A13 MEMORY-LEAK    A19 FLOW
+A02 COMPREHENSION  A08 COMPLICATEDNESS  A14 CONCURRENCY    A20 DEAD-CODE
+A03 CLEANLINESS    A09 CONCISENESS      A15 PERFORMANCE    A21 DOCUMENTATION
+A04 SPELLING       A10 SMELLS           A16 SECURITY
+A05 COMPLEXITY     A11 TYPING           A17 ARCHITECTURE
+A06 REDUNDANCY     A12 ERROR-HANDLING   A18 LOGIC
 ```
 
+The `A21 DOCUMENTATION` aspect checks the code documentation in *both*
+directions: it flags functions, methods, classes, and modules - *private
+ones included* - which lack a minimal 1-2 line description in the
+idiomatic documentation convention of the target language, *and* it
+flags excessive comments (narrated decision logs, change history,
+line-by-line explanations of the obvious), comments merely restating
+the code, and comments contradicting the code.
+
 ##  OPTIONS
 
 `--auto`|`-a`:
@@ -60,7 +69,7 @@ A05 COMPLEXITY     A10 SMELLS           A15 PERFORMANCE     A20 DEAD-CODE
 `--include`|`-i`=*aspect*[`,`...]:
     Restrict the checked code quality aspects to the given
     comma-separated list of aspect ids (e.g. `A01,A04`). Without this
-    option, all twenty aspects are checked.
+    option, all twenty-one aspects are checked.
 
 `--exclude`|`-e`=*aspect*[`,`...]:
     Remove the given comma-separated list of aspect ids from the checked
@@ -104,6 +113,12 @@ Lint a directory for all aspects except dead code:
 ❯ /ase-code-lint --exclude A20 src/handlers/
 ```
 
+Lint a directory for the documentation aspect only:
+
+```text
+❯ /ase-code-lint -i A21 src/handlers/
+```
+
 ##  SEE ALSO
 
 [`ase-code-analyze`](../ase-code-analyze/help.md), [`ase-code-resolve`](../ase-code-resolve/help.md), [`ase-code-refactor`](../ase-code-refactor/help.md),