@rse/ase 0.9.62 → 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.62",
+    "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-code-edit/SKILL.md

@@ -189,9 +189,11 @@ empty <todo-what/> or <todo-how/> renders as `(none)`:
 
         2.  DETERMINE QUESTIONS:
 
-            Determine the questions, comprised of a globally-unique id
-            <question-N-id/> of `Q<N/>`, and a very brief but precise
-            question text <question-N-text/>. Each question is chosen to
+            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*.
 
@@ -229,9 +231,10 @@ empty <todo-what/> or <todo-how/> renders as `(none)`:
             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 anything.
+            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.
 
             Finally, assemble the <question-N/> out of
             `**<question-N-id/>** ▶ **<context-N-id/>** ▷
@@ -241,8 +244,10 @@ empty <todo-what/> or <todo-how/> renders as `(none)`:
 
             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 an id <answer-N-K-id/>
-            of `A<K/>`, a 1-3 word label <answer-N-K-label/>, and
+            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
@@ -304,7 +309,7 @@ empty <todo-what/> or <todo-how/> renders as `(none)`:
                 | [...]         | [...]       |
 
                 Legend: **DOM**: Domain (MUST), **IFC**: Interface (MUST), **ARC**: Architecture (SHOULD), **IMP**: Implementation (MAY)
-                        **Qn**: global question id, **An**: question-local answer id, ⚑: current decision state
+                        **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

package/plugin/skills/ase-help-skill/catalog.md

@@ -20,6 +20,9 @@
 ○   `ase-arch-analyze`:    Review Software Architecture
 ○   `ase-arch-discover`:   Discover Components
 
+⎈   **SPECIFICATION**
+○   `ase-spec-edit`:       Edit Specification
+
 ⎈   **CODING**
 ○   `ase-code-analyze`:    Analyze Source Code
 ○   `ase-code-lint`:       Lint Source Code

package/plugin/skills/ase-meta-review/help.md

@@ -27,7 +27,7 @@ naming, abstraction level), **clarity** (readability and
 self-documentation for a future reader), **robustness** (error handling,
 resource and concurrency safety), **security** and **performance** (risks
 introduced by the change), **convention** (conformance to the
-project's documented conventions - code style and the plan/spec/arch
+project's documented conventions - code style and the plan/spec
 formats described in `AGENTS.md` and the `ase-format-*` meta documents),
 **testing** (inadequate coverage for the change - new or fixed behavior
 left untested, adjacent tests not updated, or existing tests silently