@rse/ase 0.9.63 → 0.9.64

package/dst/ase-hook.js

@@ -353,7 +353,7 @@ export default class HookCommand {
             `\n⧉ ASE: ☯ persona: ${persona}, ▶ guidance: ${guidance}, ▢ boxing: ${boxing}` +
             (guidance === "normal" || guidance === "verbose" ?
                 "\n" +
-                    "\n⧉ ASE: ▷ hint: use \"/ase-help-intent <intent-description>\" for skill command proposal" +
+                    "\n⧉ ASE: ▷ hint: use \"/ase-help-intent <intent-description>\" for skill command proposals" +
                     "\n⧉ ASE: ▷ hint: use \"/ase-help-skill [<skill-name>]\" for skill catalog or skill manpage" : "");
         /*  inject markdown into session context.
             Anthropic Claude Code CLI and OpenAI Codex CLI expect the context nested in

package/dst/ase-spec.js

@@ -32,12 +32,36 @@ export class Spec {
         return path.resolve(Task.projectRoot(), file);
     }
     /*  create the SpecBook API instance, routing its verbose processing
-        messages into the info log if requested, else into the debug log  */
-    static api(log, verbose) {
+        messages into the info log if requested, else into the debug log,
+        while its "notice" messages always reach the warning log and, for
+        consumers which never see the log, the given collector  */
+    static api(log, verbose, notices) {
         return new SpecBook({
-            verbose: (cmd, msg) => log.write(verbose ? "info" : "debug", `specbook: ${cmd}: ${renderVerbose(msg)}`)
+            verbose: (cmd, msg, level) => {
+                const text = renderVerbose(msg);
+                if (level === "notice") {
+                    log.write("warning", `specbook: ${cmd}: ${text}`);
+                    notices?.push(text);
+                }
+                else
+                    log.write(verbose ? "info" : "debug", `specbook: ${cmd}: ${text}`);
+            }
         });
     }
+    /*  SpecBook marks the literal values inside its messages, but only
+        its verbose messages ever reach a renderer, so strip the markers
+        off the error messages here at the API boundary -- unstyled, as
+        they travel on into the log and the MCP tool results  */
+    static async unmarked(result) {
+        try {
+            return await result;
+        }
+        catch (err) {
+            if (err instanceof Error)
+                err.message = renderVerbose(err.message);
+            throw err;
+        }
+    }
     /*  render a diagnostic file path relative to the project root,
         keeping paths outside the project (like the bundled schema) as-is  */
     static relativize(file) {
@@ -49,10 +73,10 @@ export class Spec {
     /*  lint the specification Markdown files below the "spec" artifact
         base directory against the schema configuration  */
     static async lint(log, verbose = false) {
-        const result = await Spec.api(log, verbose).lint({
+        const result = await Spec.unmarked(Spec.api(log, verbose).lint({
             config: Spec.configFile(log),
             basedir: Artifact.basedir(log, "spec")
-        });
+        }));
         return result.diagnostics.map((d) => ({ ...d, file: Spec.relativize(d.file) }));
     }
     /*  render a diagnostic as a multi-line message with the affected
@@ -79,13 +103,14 @@ export class Spec {
         });
     }
     /*  export the specification Markdown files below the "spec" artifact
-        base directory into the requested formats, one buffer per format  */
-    static export(log, formats, verbose = false) {
-        return Spec.api(log, verbose).export({
+        base directory into the requested formats, one buffer per format,
+        collecting the emitted environment notices if requested  */
+    static export(log, formats, verbose = false, notices) {
+        return Spec.unmarked(Spec.api(log, verbose, notices).export({
             config: Spec.configFile(log),
             basedir: Artifact.basedir(log, "spec"),
             formats
-        });
+        }));
     }
 }
 /*  CLI command "ase spec"  */
@@ -204,34 +229,49 @@ export class SpecMCP {
                 "`project.artifact.spec.basedir` configuration) as JSON, JSON5, YAML, TOON, HTML, PDF, " +
                 "or normalized Markdown. The result is written to the `output` file (a relative path " +
                 "resolves against the project root) if given, else it is returned directly " +
-                "(PDF as a base64-encoded resource). The export fails on any lint diagnostic.",
+                "(PDF as a base64-encoded resource). The export fails on any lint diagnostic. " +
+                "The `notices` array carries the environment notices emitted during the export " +
+                "(like a PDF rendering falling back onto a system-installed browser), which are " +
+                "worth reporting to the user verbatim.",
             inputSchema: {
                 format: z.enum(formats).optional()
                     .describe("output format (default: inferred from the `output` file extension, else `json`)"),
                 output: z.string().optional()
                     .describe("output file path (\"-\" or omitted returns the result directly)")
+            },
+            outputSchema: {
+                notices: z.array(z.string())
+                    .describe("environment notices emitted during the export, empty if there were none")
             }
         }, async (args) => {
+            const notices = new Array();
             try {
                 /*  an explicit format takes the output as a plain file path, while
                     otherwise the output is an "[<format>:]<file>" specification  */
                 const spec = args.format !== undefined || args.output === undefined ?
                     { format: args.format ?? "json", output: args.output } :
                     parseOutputSpec(args.output);
-                const [data] = await Spec.export(this.log, [spec.format]);
+                const [data] = await Spec.export(this.log, [spec.format], false, notices);
                 if (spec.output !== undefined && spec.output !== "-") {
                     await fs.promises.writeFile(path.resolve(Task.projectRoot(), spec.output), data);
-                    return { content: [{ type: "text", text: `exported specification into "${spec.output}" (${data.length} bytes)` }] };
+                    return {
+                        structuredContent: { notices },
+                        content: [{ type: "text", text: `exported specification into "${spec.output}" (${data.length} bytes)` }]
+                    };
                 }
                 else if (spec.format === "pdf")
                     return {
+                        structuredContent: { notices },
                         content: [{
                                 type: "resource",
                                 resource: { uri: "ase:specbook-export.pdf", mimeType: "application/pdf", blob: data.toString("base64") }
                             }]
                     };
                 else
-                    return { content: [{ type: "text", text: data.toString("utf8") }] };
+                    return {
+                        structuredContent: { notices },
+                        content: [{ type: "text", text: data.toString("utf8") }]
+                    };
             }
             catch (err) {
                 return mcpToolError(err);

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":                              "0.9.63",
+    "version":                              "0.9.64",
     "license":                              "Apache-2.0",
     "author": {
         "name":                             "Dr. Ralf S. Engelschall",
@@ -66,7 +66,7 @@
         "ofetch":                           "1.5.1",
         "picomatch":                        "4.0.7",
         "lru-cache":                        "11.5.2",
-        "@rse/specbook":                    "1.0.2",
+        "@rse/specbook":                    "1.0.3",
         "source-code-error":                "1.2.0"
     },
     "allowScripts": {

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

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

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.63",
+    "version":                              "0.9.64",
     "license":                              "Apache-2.0",
     "author": {
         "name":                             "Dr. Ralf S. Engelschall",
@@ -15,7 +15,7 @@
     },
     "devDependencies": {
         "@rse/stx":                         "1.1.6",
-        "@rse/specbook":                    "1.0.2",
+        "@rse/specbook":                    "1.0.3",
         "markdownlint":                     "0.41.1",
         "markdownlint-cli2":                "0.23.2",
         "eslint":                           "10.9.1",

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

@@ -40,6 +40,13 @@ covers the *entire* `ase-issue-*` space, including any prefixed results.
     A file, directory, or other reference to the source code that
     is to be analyzed architecturally.
 
+##  SCENARIOS
+
+-   You want the software architecture of your code base reviewed
+-   You want coupling and cohesion problems between packages found
+-   You want an architecture diagram plus PROBLEM and TRADEOFF findings
+-   You want architecture findings persisted for later resolution
+
 ##  EXAMPLES
 
 Analyze architecture of the current project:

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

@@ -57,6 +57,13 @@ demotes dependency-heavy components.
     A short description of the desired functionality the third-party
     component should provide.
 
+##  SCENARIOS
+
+-   You want a third-party library or framework for a needed functionality
+-   You want a ranked survey of candidate components from NPM or Maven Central
+-   You want to know whether a package is healthy or stale and abandoned
+-   You want to decide between a dependency and hand-rolling a small feature
+
 ##  EXAMPLES
 
 Discover components for JSON schema validation:

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

@@ -61,6 +61,14 @@ fixed via `ase-code-edit P<n>`.
     A file, directory, function, or other reference to the source code
     to analyze.
 
+##  SCENARIOS
+
+-   You want your code checked for logic, semantics, and control-flow problems
+-   You want a read-only report of problems without any changes applied
+-   You want performance and efficiency opportunities surfaced
+-   You want a security-focused inspection of your code
+-   You want problems persisted as issue ids like `P1` for later resolving
+
 ##  EXAMPLES
 
 Analyze a specific source file for logic/semantic problems:

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

@@ -89,6 +89,13 @@ entirely and applies the change set to the affected artifacts itself.
     a *task-id* followed by a colon to bind the resulting plan to
     a specific task id.
 
+##  SCENARIOS
+
+-   You want to add a new feature to the code base
+-   You want feature approaches with pros and cons before any code changes
+-   You want a task plan composed for building something new
+-   You want a fast one-shot crafting without any plan ceremony
+
 ##  EXAMPLES
 
 Craft a new logging feature:

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

@@ -89,6 +89,13 @@ cleanly and are then reported as failed; stage everything and use
 The worktree names are *not* argument-driven: they are always derived
 from the *current* project id and the per-part feature slug.
 
+##  SCENARIOS
+
+-   You want a large uncommitted change set split into atomic parts
+-   You want each cohesive part of a diff in its own Git worktree
+-   You want mixed-up changes untangled before committing them
+-   You want a preview of how a change set would be divided
+
 ##  EXAMPLES
 
 Dissect the current working copy changes:

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

@@ -101,6 +101,13 @@ implementation until it passes). The *querying* state and every
     for the query via an interactive `Edit Query` dialog, carrying the
     fixed `STOP SKILL` option plus free-text input.
 
+##  SCENARIOS
+
+-   You want the code base edited in one shot from a plain description
+-   You want an analyzer issue like `P1` fixed directly without a plan
+-   You want a quick change with optional grilling and verification
+-   You want several edits chained in a loop, optionally in a worktree
+
 ##  EXAMPLES
 
 Edit in one shot, without any questions or verification:

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

@@ -24,6 +24,13 @@ notice), and *GOTCHAS* (what to not stumble over).
     A file, directory, function, or other reference to the source code
     to explain.
 
+##  SCENARIOS
+
+-   You want to understand how a piece of code works
+-   You want an explanation with WHAT, WHY, analogy, and diagram
+-   You want the cruxes and gotchas of unfamiliar code pointed out
+-   You want a quick orientation before touching foreign code
+
 ##  EXAMPLES
 
 Explain a single source file:

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

@@ -24,6 +24,13 @@ a *MODULE STRUCTURE* Mermaid diagram of modules and their imports.
     One or more file or directory references to source code that
     should be inspected for insights.
 
+##  SCENARIOS
+
+-   You want a high-level overview of a project
+-   You want to know who wrote the project and which files churn most
+-   You want a module structure diagram of the imports
+-   You want to get familiar with an unknown code base quickly
+
 ##  EXAMPLES
 
 Get insights into the current project:

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

@@ -81,6 +81,14 @@ the code, and comments contradicting the code.
 *source-reference*:
     A file, directory, or other reference to the source code to lint.
 
+##  SCENARIOS
+
+-   You want your code checked for code quality problems
+-   You want corrections proposed which you accept or reject one by one
+-   You want all quality corrections applied automatically
+-   You want only specific quality aspects like formatting or spelling checked
+-   You want missing or excessive code documentation flagged
+
 ##  EXAMPLES
 
 Lint a source file interactively:

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

@@ -82,6 +82,13 @@ entirely and applies the change set to the affected artifacts itself.
     with a *task-id* followed by a colon to bind the resulting plan
     to a specific task id.
 
+##  SCENARIOS
+
+-   You want existing code restructured without changing its behavior
+-   You want refactoring approaches with pros and cons before any changes
+-   You want a task plan composed for a cleanup
+-   You want a one-shot refactoring applied directly in place
+
 ##  EXAMPLES
 
 Refactor a module into smaller files:

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

@@ -88,6 +88,13 @@ entirely and applies the change set to the affected artifacts itself.
     skill. Optionally prefixed with a *task-id* followed by a colon
     to bind the resulting plan to a specific task id.
 
+##  SCENARIOS
+
+-   You want a bug fixed or a problem resolved in the code
+-   You want an issue like `P1` reported by an analyzer resolved
+-   You want resolution approaches with pros and cons before any changes
+-   You want a task plan composed for a bugfix
+
 ##  EXAMPLES
 
 Resolve a free-text problem:

package/plugin/skills/ase-docs-distill/help.md

@@ -52,6 +52,13 @@ non-numeric value falls back to the default *5*.
     *text* itself pasted inline. If it resolves to a readable file the
     file is read; otherwise it is treated verbatim as pasted text.
 
+##  SCENARIOS
+
+-   You want the key points of a document extracted and ranked
+-   You want the essence of a long text without reading all of it
+-   You want each key point backed by verbatim, line-cited evidence
+-   You want a pasted text or file boiled down to what matters
+
 ##  EXAMPLES
 
 Distill the key points of a document file:

package/plugin/skills/ase-docs-proofread/help.md

@@ -36,6 +36,13 @@ hint, which re-proposes the correction without limit) or - with
     A file, directory, or other reference to the documents to
     proofread.
 
+##  SCENARIOS
+
+-   You want documents checked for spelling, punctuation, and grammar
+-   You want corrections proposed which you accept or reject one by one
+-   You want a whole documentation directory corrected automatically
+-   You want a final language pass over a text before publishing
+
 ##  EXAMPLES
 
 Proofread a single document interactively:

package/plugin/skills/ase-help-intent/SKILL.md

@@ -3,11 +3,12 @@ name: ase-help-intent
 argument-hint: "[--help|-h] <intent>"
 description: >
     Match a free-text intent against the accumulated help of all ASE
-    skills, generate the single best-fitting `/ase:ase-xxx-xxx` command
-    with concrete options and arguments, and let the user execute it,
-    refine the intent, or cancel. Use when the user knows what they want
-    but not which skill or flags realize it, or mentions "intent" or
-    requests "help".
+    skills, generate all adequately fitting `/ase:ase-xxx-xxx` commands
+    -- ranked best-fitting first, each with concrete options and
+    arguments -- and let the user execute one of them, refine the
+    intent, or cancel. Use when the user knows what they want but not
+    which skill or flags realize it, or mentions "intent" or requests
+    "help".
 user-invocable: true
 disable-model-invocation: false
 effort: high
@@ -21,7 +22,7 @@ allowed-tools:
 @${CLAUDE_SKILL_DIR}/../../meta/ase-getopt.md
 
 <purpose name="ase-help-intent">
-Match an Intent to an ASE Command
+Match an Intent to ASE Commands
 </purpose>
 
 <expand name="getopt"
@@ -32,8 +33,8 @@ Match an Intent to an ASE Command
 
 <objective>
 *Match* the following free-text intent against the accumulated help of
-all ASE skills and *generate* the single best-fitting `/ase:ase-xxx-xxx`
-command that realizes it:
+all ASE skills and *generate* every adequately fitting `/ase:ase-xxx-xxx`
+command that realizes it, ranked best-fitting first:
 <intent><getopt-arguments/></intent>
 </objective>
 
@@ -63,32 +64,43 @@ catalog you match <intent/> against:
 2.  <step id="STEP 2: Match Intent and Dialog">
 
     *REPEAT* the following sub-steps in a *LOOP* until the user either
-    *executes* the generated command or *cancels* the dialog in sub-step 4:
+    *executes* one of the generated commands or *cancels* the dialog in
+    sub-step 4:
 
     1.  *Match Intent*:
 
-        Match the current <intent/> against the <corpus/> and select the
-        *single* best-fitting skill. From that skill's `##  SYNOPSIS`,
-        `##  OPTIONS`, and `##  ARGUMENTS` sections in <corpus/>,
-        *generate* a concrete command that realizes <intent/>:
-
-        -   Set <name/> to the selected skill's name (e.g. `ase-code-lint`).
-        -   Set <arguments/> to the concrete option flags and positional
-            arguments -- derived from the skill's `##  OPTIONS` and
-            `##  ARGUMENTS` -- that best realize <intent/> (may be empty).
-        -   Set <command>/ase:<name/> <arguments/></command> (the full
-            command line, with surplus inner spaces collapsed).
-        -   Set <rationale/> to a *very brief*, single-sentence
-            justification of why the selected skill and its options match
+        Match the current <intent/> against the <corpus/> and select
+        *every* skill that adequately fits it -- judging the fit
+        primarily by each skill's `##  SCENARIOS` ("You want ...") and
+        `##  DESCRIPTION` sections. Order the selected skills from
+        best-fitting to worst-fitting and keep at most the *8* best
+        ones, so the dispatch dialog of sub-step 4 stays addressable.
+        Set <count/> to the number of kept skills. Then, for each kept
+        skill <n/> (numbered `1` to <count/> in rank order), from that
+        skill's `##  SYNOPSIS`, `##  OPTIONS`, and `##  ARGUMENTS`
+        sections in <corpus/>, *generate* a concrete command that
+        realizes <intent/>:
+
+        -   Set <name<n/>/> to the skill's name (e.g. `ase-code-lint`).
+        -   Set <arguments<n/>/> to the concrete option flags and
+            positional arguments -- derived from the skill's
+            `##  OPTIONS` and `##  ARGUMENTS` -- that best realize
+            <intent/> (may be empty).
+        -   Set <command<n/>>/ase:<name<n/>/> <arguments<n/>/></command<n/>>
+            (the full command line, with surplus inner spaces collapsed).
+        -   Set <rationale<n/>/> to a *very brief*, single-sentence
+            justification of why this skill and its options match
             <intent/>.
-        -   Set <matched>yes</matched>.
+
+        Finally set <matched>yes</matched>.
 
     2.  *Guard No Match*:
 
         <if condition="no skill in <corpus/> adequately matches <intent/>">
         Set <matched>no</matched> and discard the inadequate selection of
-        sub-step 1 by setting <name></name>, <arguments></arguments>, and
-        <command></command> (all set to empty), so that no stale command
+        sub-step 1 by setting <count>0</count> and clearing all
+        <name<n/>/>, <arguments<n/>/>, and <command<n/>/> placeholders
+        (all set to empty), so that no stale command
         can survive into the dialog of sub-step 4. Then output the
         following <template/> and *continue* the *loop* at sub-step 4 to
         prompt the user for a refined or clearer intent via the dialog's
@@ -99,18 +111,22 @@ catalog you match <intent/> against:
         </template>
         </if>
 
-    3.  *Render Command*:
+    3.  *Render Commands*:
 
-        Output the generated command with the following <template/>:
+        Output the generated commands, in rank order, with the following
+        <template/>, where the `[...]` marks the repetition of the
+        command/rationale line pair for each kept skill <n/> from `1`
+        to <count/>:
 
         <template>
-        <ase-tpl-head title="SKILL COMMAND PROPOSAL"/>
+        <ase-tpl-head title="SKILL COMMAND PROPOSALS"/>
 
-        ❯ `<command/>`
+        **C<n/>** ❯ `<command<n/>/>`
+           ▷ *<rationale<n/>/>*
 
-        <ase-tpl-foot title="SKILL COMMAND PROPOSAL"/>
+        [...]
 
-        **RATIONALE**: <rationale/>
+        <ase-tpl-foot title="SKILL COMMAND PROPOSALS"/>
         </template>
 
     4.  *Dispatch Command*:
@@ -123,9 +139,9 @@ catalog you match <intent/> against:
         Let the user decide how to proceed by raising a question with the
         following custom dialog (invoked with `--other`, so that any
         free-text instruction is accepted as an intent refinement). Which
-        dialog is raised depends on <matched/>, so that `EXECUTE` is
-        offered *only* when a command was actually generated in sub-step 1
-        *and* rendered in sub-step 3:
+        dialog is raised depends on <matched/>, so that the `C<n/>`
+        command options are offered *only* when commands were actually
+        generated in sub-step 1 *and* rendered in sub-step 3:
 
         <if condition="<matched/> is `no`">
         <expand name="custom-dialog" arg1="--other">
@@ -136,10 +152,16 @@ catalog you match <intent/> against:
         </if>
         <else>
         <expand name="custom-dialog" arg1="--other">
-            Dispatch: What would you like to do with the generated command?
-            EXECUTE: Execute the generated command now.
-            CANCEL:  Cancel this dialog.
+            Dispatch: Which of the proposed commands would you like to execute?
+            C1: Execute: `<command1/>`
+            [...]
+            CANCEL: Cancel this dialog.
         </expand>
+
+        The `[...]` line stands for one further answer line
+        `C<n/>: Execute `<command<n/>/>` now.` per additionally kept
+        skill <n/> from `2` to <count/>, in rank order, so the dialog
+        offers exactly <count/> command options plus `CANCEL`.
         </else>
 
         Check the tool <result/> and dispatch accordingly:
@@ -148,7 +170,7 @@ catalog you match <intent/> against:
             *Break* out of the *loop* and stop processing without any
             further output.
 
-        -   If <result/> is `REFINE`, or <result/> is `EXECUTE` while
+        -   If <result/> is `REFINE`, or <result/> matches `C<n/>` while
             <matched/> is `no`: do *not* execute anything -- output the
             following <template/> and *continue* the *loop* at sub-step 4
             to obtain a refined intent via the dialog's free-text channel:
@@ -157,13 +179,14 @@ catalog you match <intent/> against:
             <ase-tpl-bullet-secondary/> **HINT**: please enter a refined or clearer intent as free text.
             </template>
 
-        -   If <result/> is `EXECUTE` (which implies <matched/> is `yes`):
-            *Break* out of the *loop*, output the following <template/>,
-            and then call the tool `Skill(skill: "ase:<name/>", args:
-            "<arguments/>")` to *execute* the generated command:
+        -   If <result/> matches `C<n/>` (which implies <matched/> is
+            `yes`): *Break* out of the *loop*, output the following
+            <template/>, and then call the tool `Skill(skill:
+            "ase:<name<n/>/>", args: "<arguments<n/>/>")` to *execute*
+            the selected command:
 
             <template>
-            ⧉ **ASE**: ◉ intent: **<intent/>**, ⌘ command: **<command/>**, ▶ status: **command executing**
+            ⧉ **ASE**: ◉ intent: **<intent/>**, ⌘ command: **<command<n/>/>**, ▶ status: **command executing**
             </template>
 
         -   If <result/> matches `OTHER: <text/>`: