@rse/ase 2.0.5 → 2.0.7

package/dst/man/ase-spec.md

@@ -1,4 +1,4 @@
-# ase-spec(1) -- Initialize, Lint, Export, and Preview the Project Specification
+# ase-spec(1) -- Initialize, Lint, Export, Query, and Preview the Project Specification
 
 ## SYNOPSIS
 
@@ -6,6 +6,7 @@
 \[`-h`|`--help`\]
 
 `ase spec init`
+\[`-s`|`--sample`\]
 
 `ase spec lint`
 \[`-m`|`--markdown`\]
@@ -14,27 +15,42 @@
 `ase spec export`
 \[`-o`|`--output` \[*format*`:`\]*file*\] \[...\]
 \[`-w`|`--watch`\]
+\[`-S`|`--schema`\]
+
+`ase spec query`
+\[`-P`|`--param` *name*`=`*value*\] \[...\]
+\[`-f`|`--format` *format*\]
+\[`-o`|`--output` \[*format*`:`\]*file*\]
+\[`-S`|`--schema`\]
+*selector*
 
 `ase spec preview`
 \[`-a`|`--addr` *ip-addr*\]
 \[`-p`|`--port` *tcp-port*\]
+\[`-S`|`--schema`\]
 
 ## DESCRIPTION
 
 **ase spec** is the entry point group for initializing, linting,
-exporting, and previewing the *SpecBook*-based project specification
-(SPEC), i.e., the Markdown files (plus their embedded assets) of the
-artifact kind `spec` below the base directory
+exporting, querying, and previewing the *SpecBook*-based project
+specification (SPEC), i.e., the Markdown files (plus their embedded
+assets) of the artifact kind `spec` below the base directory
 `project.artifact.spec.basedir` (default: `docs/specbook`, relative to
-the project root).
+the project root). Every `.md` file below the base directory
+(recursively, except below `.`-prefixed entries), whatever its name,
+is taken as a specification file.
 
 The specification is governed by the *SpecBook* YAML schema
 configuration `project.artifact.spec.schema`: a whitespace-separated
 list of schema files, merged in the given order, where the entry `std`
 names the full standard schema bundled with *SpecBook* (not its
 compressed variant `ase-format-specbook.yaml` bundled with the plugin
-for the agents, see `ase-util-meta`(1)) and every other entry is a file
-path relative to the project root. An unset or empty value means `std`.
+for the agents, see `ase-util-meta`(1)), the entries `meta` and `pm`
+name the meta and project management schemas bundled with *SpecBook*,
+the entries prefixed with `npm:`, `github:`, `http://`, or `https://`
+name remote schemas (fetched and cached by *SpecBook*), and every other
+entry is a file path or glob pattern relative to the project root. An
+unset or empty value means `std`.
 
 All reading specification commands honor the Git exclude rules exactly
 like `ase artifact list` does (see `ase-artifact`(1)): an artifact file
@@ -55,7 +71,7 @@ exits with status `1`.
 
 ## COMMANDS
 
-- `ase spec init`:
+- `ase spec init` \[`-s`|`--sample`\]:
   Initialize the absent specification Markdown files of the schema
   configuration. See `ase-spec-init`(1).
 
@@ -63,11 +79,15 @@ exits with status `1`.
   Lint the specification against the schema configuration, and
   optionally for its generic Markdown formatting. See `ase-spec-lint`(1).
 
-- `ase spec export` \[`-o`|`--output` \[*format*`:`\]*file*\] \[...\] \[`-w`|`--watch`\]:
+- `ase spec export` \[`-o`|`--output` \[*format*`:`\]*file*\] \[...\] \[`-w`|`--watch`\] \[`-S`|`--schema`\]:
   Export the specification as JSON, JSON5, YAML, TOON, HTML, PDF, or
   normalized Markdown. See `ase-spec-export`(1).
 
-- `ase spec preview` \[`-a`|`--addr` *ip-addr*\] \[`-p`|`--port` *tcp-port*\]:
+- `ase spec query` \[`-P`|`--param` *name*`=`*value*\] \[...\] \[`-f`|`--format` *format*\] \[`-o`|`--output` \[*format*`:`\]*file*\] \[`-S`|`--schema`\] *selector*:
+  Query the specification with an *ASTq* selector, writing the matched
+  nodes as JSON, JSON5, YAML, or TOON. See `ase-spec-query`(1).
+
+- `ase spec preview` \[`-a`|`--addr` *ip-addr*\] \[`-p`|`--port` *tcp-port*\] \[`-S`|`--schema`\]:
   Serve the HTML export of the specification as a live preview. See
   `ase-spec-preview`(1).
 
@@ -78,7 +98,8 @@ The group command without a sub-command exits with status `1`.
 ## SEE ALSO
 
 `ase`(1), `ase-spec-init`(1), `ase-spec-lint`(1), `ase-spec-export`(1),
-`ase-spec-preview`(1), `ase-artifact`(1), `ase-config`(1).
+`ase-spec-query`(1), `ase-spec-preview`(1), `ase-artifact`(1),
+`ase-config`(1).
 
 ## AUTHOR
 

package/dst/man/ase.md

@@ -25,8 +25,8 @@ hook handlers, the statusline rendering, the persisted task plan
 management (including a task store server and an interactive task
 board), the autonomous task lifecycle agents (plus their agent relay
 and fleet supervisor), the project artifact resolution, the
-*SpecBook*-based specification initializing, linting, exporting and
-previewing, and miscellaneous utilities like diagram rendering,
+*SpecBook*-based specification initializing, linting, exporting,
+querying, and previewing, and miscellaneous utilities like diagram rendering,
 identifier minting, and text measuring.
 
 Most commands are sub-command groups. Each group and each command has
@@ -100,7 +100,7 @@ The following top-level commands exist:
   `ase-artifact`(1).
 
 - `ase spec` *command* \[...\]:
-  Initialize, lint, export, and preview the *SpecBook*-based project
+  Initialize, lint, export, query, and preview the *SpecBook*-based project
   specification. See `ase-spec`(1).
 
 - `ase util` *command* \[...\]:

package/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":                              "2.0.5",
+    "version":                              "2.0.7",
     "license":                              "Apache-2.0",
     "author": {
         "name":                             "Dr. Ralf S. Engelschall",
@@ -21,22 +21,23 @@
         "./package.json":                   "./package.json"
     },
     "devDependencies": {
-        "eslint":                           "10.13.0",
+        "eslint":                           "10.14.0",
         "@eslint/js":                       "10.0.1",
-        "@typescript-eslint/parser":        "8.72.0",
-        "@typescript-eslint/eslint-plugin": "8.72.0",
-        "typescript-eslint":                "8.72.0",
+        "@typescript-eslint/parser":        "8.72.1",
+        "@typescript-eslint/eslint-plugin": "8.72.1",
+        "typescript-eslint":                "8.72.1",
         "eslint-plugin-promise":            "7.3.0",
         "neostandard":                      "0.14.1",
-        "globals":                          "17.13.0",
+        "globals":                          "17.14.0",
         "typescript":                       "6.0.3",
-        "eslint-plugin-vue":                "10.11.1",
+        "eslint-plugin-vue":                "10.12.0",
         "vue-eslint-parser":                "10.4.1",
-        "vue-tsc":                          "3.3.13",
+        "vue-tsc":                          "3.3.14",
 
         "@rse/stx":                         "1.1.7",
         "nodemon":                          "3.1.14",
         "shx":                              "0.4.0",
+        "sync-directory":                   "6.0.6",
         "stylus":                           "0.64.0",
         "vite":                             "8.3.5",
         "@vitejs/plugin-vue":               "6.0.10",
@@ -55,10 +56,10 @@
         "source-sans":                      "3.52.0",
         "@fontsource/dejavu-mono":          "5.3.0",
 
-        "@types/node":                      "26.6.5",
+        "@types/node":                      "26.6.6",
         "@types/luxon":                     "3.7.6",
         "@types/which":                     "3.0.4",
-        "@types/update-notifier":           "6.0.8",
+        "@types/update-notifier":           "6.0.9",
         "@types/semver":                    "7.8.0",
         "@types/shell-quote":               "1.7.5",
         "@types/proper-lockfile":           "4.1.4",
@@ -77,15 +78,16 @@
         "valibot":                          "1.5.0",
         "execa":                            "10.2.1",
         "mkdirp":                           "3.0.1",
-        "@hapi/hapi":                       "21.4.11",
+        "@hapi/hapi":                       "21.4.12",
         "beautiful-mermaid":                "1.1.3",
         "@d2lang/d2":                       "0.1.34",
-        "elkjs":                            "0.12.0",
+        "elkjs":                            "0.12.1",
         "ink":                              "8.0.0",
+        "string-width":                     "8.3.0",
         "react":                            "19.3.1",
         "chokidar":                         "6.0.0",
-        "marked":                           "18.1.1",
-        "shiki":                            "4.5.0",
+        "marked":                           "18.1.3",
+        "shiki":                            "4.6.0",
         "cli-table3":                       "0.6.5",
         "chalk":                            "6.0.1",
         "pretty-ms":                        "10.0.0",
@@ -95,7 +97,7 @@
         "zod":                              "4.6.7",
         "which":                            "7.0.0",
         "update-notifier":                  "7.3.1",
-        "semver":                           "7.8.5",
+        "semver":                           "7.8.6",
         "shell-quote":                      "1.12.0",
         "get-stdin":                        "10.0.0",
         "proper-lockfile":                  "4.1.2",
@@ -106,12 +108,12 @@
         "undici":                           "8.12.3",
         "picomatch":                        "4.0.7",
         "lru-cache":                        "11.5.3",
-        "@rse/specbook":                    "1.5.2",
+        "@rse/specbook":                    "1.6.2",
         "markdownlint":                     "0.42.0",
         "tail":                             "2.2.6",
         "source-code-error":                "1.2.0",
         "pure-uuid":                        "2.0.0",
-        "ws":                               "8.22.0",
+        "ws":                               "8.22.1",
         "@rse/mrcs":                        "0.9.2",
         "@octokit/core":                    "7.0.8",
         "@octokit/plugin-rest-endpoint-methods": "18.0.0",
@@ -142,6 +144,7 @@
         "!plugin/node_modules/**",
         "!plugin/package.json",
         "!plugin/etc/**",
+        "!plugin/mods/claude-code.d.ts",
         ".claude-plugin/**/*",
         "README.md"
     ],

package/plugin/.claude-plugin/plugin.json

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

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

@@ -1,6 +1,6 @@
 {
     "name":        "ase",
-    "version":     "2.0.5",
+    "version":     "2.0.7",
     "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":     "2.0.5",
+    "version":     "2.0.7",
     "description": "Agentic Software Engineering (ASE)",
     "keywords":    [ "agentic", "software", "engineering" ],
     "homepage":    "https://ase.tools",

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

@@ -227,10 +227,18 @@ related to this MCP call except the following <template/>:
     custom dialog according to the expanded `custom-dialog`
     definition. You *MUST* closely follow this definition:
 
-    <expand name="custom-dialog" arg1="--no-other">
+    <expand name="custom-dialog" arg1="--other">
         <content/>
     </expand>
 
+    If <result/> matches `OTHER: <text/>`, the user typed a free-text
+    request instead of choosing an option: treat it as an implicit
+    `DONE`, i.e., set <result>DONE</result>, and let the calling skill
+    finish along its `DONE` dispatch (output its `DONE` template).
+    Its *STOP* then ends only the skill, *not* the current turn:
+    immediately afterwards, handle <text/> as a regular user request,
+    outside of any skill, without re-opening this dialog.
+
 </define>
 
 <define name="task-next-handoff">

package/plugin/meta/ase-control.md

@@ -187,3 +187,17 @@ Control Flow Constructs
     the order of their occurrence in <parallel-body/>. This construct is
     expanded to its <parallel-body/>. Do not output anything else.
 
+-   *IMPORTANT*: You *MUST* honor the following rule for *all*
+    concurrently dispatched sub-agents -- whether invoked through
+    <parallel/> or through multiple `Agent` tool invocations emitted in
+    one single message:
+
+    The agent tool may run sub-agents in the *background* (e.g.
+    *Anthropic Claude Code CLI* ignores `run_in_background: false`) and
+    then notifies you of each returned sub-agent individually. While
+    these notifications arrive, you *MUST* *NOT* output anything -- no
+    progress messages (like `Batch 3 of 8 is back, 5 still running`),
+    no intermediate results, and no waiting notices -- but silently wait
+    for the remaining sub-agents. Only once *all* of them have returned,
+    continue with the processing which consumes their results.
+

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

@@ -20,16 +20,40 @@ SpecBook Project Instantiation
         with **ASE** in the file `meta/ase-format-specbook.yaml`
         (relative to the plugin root).
 
+    -   For each entry `meta`, `pm`, or `npm:...`, `github:...`,
+        `http://...`, or `https://...` in the list:
+
+        The entry names a YAML schema configuration bundled with or
+        fetched by **SpecBook** itself (the meta, the project
+        management, or a remote one), which has no file to read.
+        Instead, obtain the *effective* (merged) schema configuration
+        once via the `ase_specbook_query(schema: true, selector: "/
+        artifact", format: "yaml")` tool of the `ase` MCP server, which
+        describes it as a **SpecBook** document.
+
     -   For each *other* entry in the list:
 
-        The entry names a custom YAML schema configuration file of the
-        project (relative to the project root).
+        The entry names a custom YAML schema configuration file (or
+        glob pattern of files) of the project (relative to the project
+        root).
 
     You *MUST* read all resulting schema configuration files via the
     `Read` tool before working on the specification of the **SpecBook
     SPEC Model**.
 
 -   The **SpecBook SPEC Model** of this project is the set of specification
-    Markdown files in the directory <ase-spec-basedir/> (relative
-    to the project root), whose files are resolved via the
-    `ase_artifact_list(kind: [ "spec" ])` tool of the `ase` MCP server.
+    Markdown files below the directory <ase-spec-basedir/> (relative
+    to the project root, recursively, where every `.md` file is a
+    specification file, whatever its name), whose files are resolved
+    via the `ase_artifact_list(kind: [ "spec" ])` tool of the `ase` MCP
+    server.
+
+-   The **SpecBook SPEC Model** of this project can be queried
+    *structurally* via the `ase_specbook_query(selector: "<selector/>")`
+    tool of the `ase` MCP server, with an XPath-like *ASTq* selector
+    like `// USE-CASE [ @STATUS == 'Done' ]` (object nodes typed by
+    their kind with whitespace dashed, attributes `id`, `name`,
+    `description`, `rationale`, and one per property key, and the
+    function `refs()` yielding the objects referenced by an object).
+    Prefer it over reading many artifact files when a question spans
+    objects of entire kinds, property values, or reference relations.