@rse/ase 0.9.7 → 0.9.9

package/dst/ase-skills.js

@@ -242,27 +242,31 @@ export class Skills {
             return [];
     }
     /*  compute composite rank score from weighted metrics:
-        downloads x
-        stars x
+        (downloads + 1) x
+        (stars + 1) x
         ([lifespan =] (updated - created)) x
         ([recentness =] exp(-(now - updated) / halfLife))
-        `"N.A."` factors are treated as neutral `1` so that stacks for which
-        a particular metric is structurally unavailable (e.g. Maven Central
-        exposes no per-artifact download counts) can still be ranked by the
-        remaining metrics, instead of collapsing the entire product to zero.  */
+        Numeric count metrics are shifted by `+1` so that a genuine `0`
+        (e.g. a real package with zero downloads or stars) contributes a
+        neutral `1` instead of collapsing the entire product to zero, while
+        still ordering `0 < 1 < 2 ...`. The `"N.A."` sentinel (a metric that
+        is structurally unavailable, e.g. Maven Central exposes no
+        per-artifact download counts) is likewise treated as neutral `1`, so
+        such stacks can still be ranked by the remaining metrics.  */
     static computeRank(downloads, stars, created, updated) {
-        const d = typeof downloads === "number" ? downloads : 1;
-        const s = typeof stars === "number" ? stars : 1;
+        const d = typeof downloads === "number" ? downloads + 1 : 1;
+        const s = typeof stars === "number" ? stars + 1 : 1;
         const cMs = created !== "" ? Date.parse(created) : NaN;
         const uMs = updated !== "" ? Date.parse(updated) : NaN;
-        if (Number.isNaN(cMs) || Number.isNaN(uMs))
-            return 0;
         const now = Date.now();
         const msPerDay = 1000 * 60 * 60 * 24;
         const halfLife = 365 / 2;
-        const lifespan = Math.max(0, uMs - cMs);
-        const ageDays = Math.max(0, (now - uMs) / msPerDay);
-        const recentness = Math.exp(-ageDays / halfLife);
+        /*  lifespan requires both timestamps; recentness requires the
+            updated timestamp -- any unavailable date-derived factor is
+            treated as neutral `1` so the entry can still be ranked by the
+            remaining metrics, instead of collapsing the product to zero  */
+        const lifespan = (!Number.isNaN(cMs) && !Number.isNaN(uMs)) ? Math.max(0, uMs - cMs) : 1;
+        const recentness = !Number.isNaN(uMs) ? Math.exp(-Math.max(0, (now - uMs) / msPerDay) / halfLife) : 1;
         return d * s * lifespan * recentness;
     }
     /*  compute the per-alternative product-sum (rating) row from a

package/dst/ase-statusline.js

@@ -245,12 +245,14 @@ export default class StatuslineCommand {
                 out += ansi;
                 col += raw.length;
             };
-            /*  active <color> span state: when non-null, renderer/literal output is buffered
-                instead of appended directly, and flushed via c[color](buf) on </color>  */
+            /*  active <color> span state: when non-null, each emitted chunk is colored
+                individually and passed straight through appendOutput, so column
+                accounting and line-wrapping continue to work per-chunk inside the span
+                instead of treating the whole colored run as one atomic chunk  */
             let span = null;
             const emit = (chunk) => {
-                if (span !== null)
-                    span.buf += chunk;
+                if (span !== null && span.color !== "default")
+                    appendOutput((c[span.color])(chunk));
                 else
                     appendOutput(chunk);
             };
@@ -446,13 +448,7 @@ export default class StatuslineCommand {
             };
             /*  walk each template line and render  */
             const closeSpan = () => {
-                if (span !== null) {
-                    const wrapped = span.color === "default" ?
-                        span.buf :
-                        (c[span.color])(span.buf);
-                    span = null;
-                    appendOutput(wrapped);
-                }
+                span = null;
             };
             for (const line of tmpl) {
                 let i = 0;
@@ -465,7 +461,7 @@ export default class StatuslineCommand {
                             if (m[1] === "/")
                                 closeSpan();
                             else if (span === null)
-                                span = { color: m[2], buf: "" };
+                                span = { color: m[2] };
                             i += m[0].length;
                             continue;
                         }

package/dst/ase-task.js

@@ -20,8 +20,8 @@ export class Task {
     static validateId(id) {
         if (typeof id !== "string" || id.length === 0)
             throw new Error("task: id must be a non-empty string");
-        if (!/^[A-Za-z0-9-]+$/.test(id))
-            throw new Error("task: id must match [A-Za-z0-9-]+");
+        if (!/^[A-Za-z0-9_-]+$/.test(id))
+            throw new Error("task: id must match [A-Za-z0-9_-]+");
     }
     /*  determine the project root (Git top-level if inside a Git
         working tree, otherwise the current working directory)  */
@@ -59,12 +59,22 @@ export class Task {
     static baseDir(log) {
         return path.join(Task.projectRoot(), Task.spec(log).basedir);
     }
+    /*  ensure a task id's "TASK-<id>.md" filename satisfies
+        the configured "files" miniglob  */
+    static enforceFiles(log, id) {
+        const { files } = Task.spec(log);
+        const filename = `TASK-${id}.md`;
+        if (!picomatch(files, { dot: true })(filename))
+            throw new Error(`task: id "${id}" yields filename "${filename}" ` +
+                `which does not match the configured "files" glob "${files}"`);
+    }
     /*  resolve the on-disk path for a given task id; as a side effect,
         eagerly migrate any legacy <basedir>/<id>/plan.md files to the
         current <basedir>/TASK-<id>.md layout on first access (guarded by
         a cheap check, so it is a no-op once the store is migrated)  */
     static path(log, id) {
         Task.validateId(id);
+        Task.enforceFiles(log, id);
         if (Task.needsMigration(log))
             Task.migrateAll(log);
         return path.join(Task.baseDir(log), `TASK-${id}.md`);
@@ -76,7 +86,7 @@ export class Task {
         if (!fs.existsSync(dir))
             return false;
         for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-            if (!entry.isDirectory() || !/^[A-Za-z0-9-]+$/.test(entry.name))
+            if (!entry.isDirectory() || !/^[A-Za-z0-9_-]+$/.test(entry.name))
                 continue;
             if (fs.existsSync(path.join(dir, entry.name, "plan.md")))
                 return true;
@@ -93,7 +103,7 @@ export class Task {
             return [];
         const migrated = [];
         for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-            if (!entry.isDirectory() || !/^[A-Za-z0-9-]+$/.test(entry.name))
+            if (!entry.isDirectory() || !/^[A-Za-z0-9_-]+$/.test(entry.name))
                 continue;
             const id = entry.name;
             const oldFile = path.join(dir, id, "plan.md");
@@ -138,7 +148,7 @@ export class Task {
     }
     /*  rename a task by moving its <project>/<basedir>/TASK-<oldId>.md file
         to <project>/<basedir>/TASK-<newId>.md; the embedded
-        "# ✪ TASK <id>:" heading inside the plan content is rewritten to
+        "#   TASK <id>:" heading inside the plan content is rewritten to
         the new id; returns true on success, false if the source task does
         not exist; throws if the target id already exists  */
     static rename(log, oldId, newId) {
@@ -149,7 +159,7 @@ export class Task {
         if (fs.existsSync(newFile))
             throw new Error(`task: target id "${newId}" already exists`);
         const text = fs.readFileSync(oldFile, "utf8");
-        const updated = text.replace(/(^#\s+(?:✪\s+)?TASK\s+)[A-Za-z0-9-]+(\s*:)/m, `$1${newId}$2`);
+        const updated = text.replace(/(^#\s+TASK\s+)[A-Za-z0-9_-]+(\s*:)/m, `$1${newId}$2`);
         fs.mkdirSync(path.dirname(newFile), { recursive: true });
         fs.writeFileSync(newFile, updated, "utf8");
         fs.rmSync(oldFile, { force: true });
@@ -168,7 +178,7 @@ export class Task {
         const isMatch = picomatch(files, { dot: true });
         const out = [];
         for (const entry of fs.readdirSync(dir)) {
-            const m = /^TASK-([A-Za-z0-9-]+)\.md$/.exec(entry);
+            const m = /^TASK-([A-Za-z0-9_-]+)\.md$/.exec(entry);
             if (m === null || !isMatch(entry))
                 continue;
             const file = path.join(dir, entry);
@@ -194,7 +204,7 @@ export class Task {
         const cutoff = Date.now() - maxAgeMs;
         const removed = [];
         for (const entry of fs.readdirSync(dir)) {
-            const m = /^TASK-([A-Za-z0-9-]+)\.md$/.exec(entry);
+            const m = /^TASK-([A-Za-z0-9_-]+)\.md$/.exec(entry);
             if (m === null || !isMatch(entry))
                 continue;
             const file = path.join(dir, entry);
@@ -417,7 +427,7 @@ export class TaskMCP {
                 "Returns the task as `text`; returns an empty string if no task exists for the `id`.",
             inputSchema: {
                 id: z.string()
-                    .describe("task identifier (allowed characters: A-Z, a-z, 0-9, '-')")
+                    .describe("task identifier (allowed characters: A-Z, a-z, 0-9, '_', '-')")
             }
         }, async (args) => {
             try {
@@ -442,16 +452,15 @@ export class TaskMCP {
                 "Overwrites any existing task for the same `id`.",
             inputSchema: {
                 id: z.string()
-                    .describe("task identifier (allowed characters: A-Z, a-z, 0-9, '-')"),
+                    .describe("task identifier (allowed characters: A-Z, a-z, 0-9, '_', '-')"),
                 text: z.string()
                     .describe("text content of the task")
             }
         }, async (args) => {
             try {
-                const text = Markdown.prepare(args.text);
-                Task.save(this.log, args.id, text);
+                Task.save(this.log, args.id, args.text);
                 return {
-                    content: [{ type: "text", text: `task_save: OK: saved task "${args.id}"` }]
+                    content: [{ type: "text", text: `OK: saved task "${args.id}"` }]
                 };
             }
             catch (err) {
@@ -469,14 +478,14 @@ export class TaskMCP {
                 "Returns a status `text` indicating whether a task existed and was removed.",
             inputSchema: {
                 id: z.string()
-                    .describe("task identifier (allowed characters: A-Z, a-z, 0-9, '-')")
+                    .describe("task identifier (allowed characters: A-Z, a-z, 0-9, '_', '-')")
             }
         }, async (args) => {
             try {
                 const removed = Task.delete(this.log, args.id);
                 const msg = removed ?
-                    `task_delete: OK: removed task "${args.id}"` :
-                    `task_delete: WARNING: no task "${args.id}" to remove`;
+                    `OK: removed task "${args.id}"` :
+                    `WARNING: no task "${args.id}" to remove`;
                 return {
                     content: [{ type: "text", text: msg }]
                 };
@@ -497,16 +506,16 @@ export class TaskMCP {
                 "Fails with an error if the target id already exists.",
             inputSchema: {
                 old: z.string()
-                    .describe("old task identifier (allowed characters: A-Z, a-z, 0-9, '-')"),
+                    .describe("old task identifier (allowed characters: A-Z, a-z, 0-9, '_', '-')"),
                 new: z.string()
-                    .describe("new task identifier (allowed characters: A-Z, a-z, 0-9, '-')")
+                    .describe("new task identifier (allowed characters: A-Z, a-z, 0-9, '_', '-')")
             }
         }, async (args) => {
             try {
                 const renamed = Task.rename(this.log, args.old, args.new);
                 const msg = renamed ?
-                    `task_rename: OK: renamed task "${args.old}" to "${args.new}"` :
-                    `task_rename: WARNING: no task "${args.old}" to rename`;
+                    `OK: renamed task "${args.old}" to "${args.new}"` :
+                    `WARNING: no task "${args.old}" to rename`;
                 return {
                     content: [{ type: "text", text: msg }]
                 };
@@ -527,16 +536,16 @@ export class TaskMCP {
                 "otherwise it returns the current task `id` of the `session`.",
             inputSchema: {
                 id: z.string().optional()
-                    .describe("task identifier to set (allowed characters: A-Z, a-z, 0-9, '-'); " +
+                    .describe("task identifier to set (allowed characters: A-Z, a-z, 0-9, '_', '-'); " +
                     "if omitted, the current task id is returned"),
                 session: z.string()
-                    .describe("session identifier (allowed characters: A-Z, a-z, 0-9, '-')")
+                    .describe("session identifier (allowed characters: A-Z, a-z, 0-9, '_', '-')")
             }
         }, async (args) => {
             try {
                 if (args.id !== undefined) {
                     Task.setId(this.log, args.session, args.id);
-                    const msg = `task_id: OK: set agent.task to "${args.id}" ` +
+                    const msg = `OK: set agent.task to "${args.id}" ` +
                         `for session "${args.session}"`;
                     return {
                         content: [{ type: "text", text: msg }]

package/package.json

@@ -6,7 +6,7 @@
     "homepage":                             "http://github.com/rse/ase",
     "repository":                           { "url": "git+https://github.com/rse/ase.git", "type": "git" },
     "bugs":                                 { "url": "http://github.com/rse/ase/issues" },
-    "version":                              "0.9.7",
+    "version":                              "0.9.9",
     "license":                              "GPL-3.0-only",
     "author": {
         "name":                             "Dr. Ralf S. Engelschall",
@@ -30,7 +30,7 @@
         "nodemon":                          "3.1.14",
         "shx":                              "0.4.0",
 
-        "@types/node":                      "25.9.2",
+        "@types/node":                      "25.9.3",
         "@types/luxon":                     "3.7.1",
         "@types/which":                     "3.0.4",
         "@types/update-notifier":           "6.0.8",
@@ -42,7 +42,7 @@
     },
     "dependencies": {
         "commander":                        "15.0.0",
-        "@dotenvx/dotenvx":                 "1.71.2",
+        "@dotenvx/dotenvx":                 "1.71.3",
         "yaml":                             "2.9.0",
         "valibot":                          "1.4.1",
         "execa":                            "9.6.1",

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

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

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

@@ -62,9 +62,9 @@ Workflow
     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/> + 1) and (<line/> + <n/> + 2), where <n/> is the
+        + <n/>) and (<line/> + <n/> + 1), where <n/> is the
         number of lines in <old-text/>. Reduce to just one line
-        (<line/> + <n/> + 1) if <old-text/> is the second-last
+        (<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.
 

package/plugin/meta/ase-constitution.md

@@ -16,6 +16,13 @@ you *MUST* once and immediately output the following <template/> now:
 ⧉ **ASE**: ☯ persona: **<ase-persona-style/>**
 </template>
 
+In case your harness instructions indicate that the user is shown
+only the *final* text message of each turn (e.g. *Claude Code* with
+"focus mode" enabled), you *MUST* ensure this <template/> output (and
+*every* <template/> output requested by ASE skills) lands in a final
+text message (after the last tool call of a turn) instead of between
+tool calls -- repeat it there if necessary.
+
 Prohibitions
 ------------
 

package/plugin/meta/ase-control.md

@@ -14,7 +14,7 @@ Control Flow Constructs
     Do not output anything.
 
 -   *IMPORTANT*: You *MUST* honor the following control flow construct:
-    <expand name="<define-name/>" [arg1="<expand-arg1/>" [arg2="<expand-arg2/>" [...]]]><expand-content/></expand>:
+    <expand name="<define-name/>" [arg1="<expand-arg1/>" [arg2="<expand-arg2/>" [...]]]>[<expand-content/>]</expand>:
 
     This specifies the *expansion* of previous <define/>. This
     construct is expanded to the <define-body/> of <define/> with
@@ -48,14 +48,35 @@ Control Flow Constructs
 
     This specifies a simple condition which is expanded to <if-body/>
     if <if-condition/> is met, or to empty string if <if-condition/> is
-    *not* met. Do not output anything else.
+    *not* met. It can be optionally followed by one or more <elseif/>
+    constructs and/or one final <else/> construct. Do not output anything else.
+
+-   *IMPORTANT*: You *MUST* honor the following control flow construct:
+    <elseif condition="<elseif-condition/>"><elseif-body/></elseif>:
+
+    This specifies an *alternative condition* and has to directly
+    follow an <if/> or another <elseif/> construct. It is expanded
+    to <elseif-body/> if the conditions of all preceding <if/> and
+    <elseif/> constructs of the chain were *not* met and its own
+    <elseif-condition/> is met, or to the empty string otherwise.
+    Do not output anything else.
+
+-   *IMPORTANT*: You *MUST* honor the following control flow construct:
+    <else><else-body/></else>:
+
+    This specifies the *fallback alternative* and has to directly
+    follow an <if/> or <elseif/> construct. It is expanded to
+    <else-body/> if the conditions of all preceding <if/> and
+    <elseif/> constructs of the chain were *not* met, or to the empty
+    string otherwise. Do not output anything else.
 
 -   *IMPORTANT*: You *MUST* honor the following control flow construct:
     <while condition="<while-condition/>"><while-body/></while>:
 
     This specifies a <while-body/> which is *repeated* as long as
     <while-condition/> is met. This construct is expanded to the
-    repetition of <while-body/>. Do not output anything else.
+    repetition of <while-body/>. A <break/> in <while-body/> can stop
+    the repetition early. Do not output anything else.
 
 -   *IMPORTANT*: You *MUST* honor the following control flow construct:
     <for items="<for-item/> [...]"><for-body/></for>:

package/plugin/meta/ase-dialog.md

@@ -1,5 +1,4 @@
 
-
 User Dialog
 ===========
 
@@ -15,13 +14,16 @@ User Dialog
 Let the *user interactively choose* an answer.
 
 1.  Take the following question specification:
+
     <spec>
         <content/>
     </spec>
 
-    Each line of <spec/> (separated by newlines) is of the format:
+    The first line of <spec/> (separated by newlines) is of the format:
+    `<question-label/>: <question-description/>`
 
-    `<label/>: <description/>`.
+    The second and following lines of <spec/> (separated by newlines) are of the format:
+    `<label/>: <description/>`
 
     The first line provides the question label and the question
     description. The second and following lines each provide an
@@ -49,8 +51,8 @@ Let the *user interactively choose* an answer.
 
             If <n/> is less than 2:
             Set <result>ERROR: user-dialog requires 2-4 answer lines, got <n/></result>
-            and *SKIP* the following step 2 (do not call `AskUserQuestion`)
-            and continue with step 3 dispatch.
+            and *SKIP* the following step 2.2 (do not call `AskUserQuestion`)
+            and continue with step 2.3 dispatch.
 
         2.  Call the `AskUserQuestion` tool of the agent harness with:
 
@@ -103,8 +105,8 @@ Let the *user interactively choose* an answer.
 
             If <n/> is less than 2:
             Set <result>ERROR: user-dialog requires 2-4 answer lines, got <n/></result>
-            and *SKIP* the following step 2 (do not call `ask_user`)
-            and continue with step 3 dispatch.
+            and *SKIP* the following step 2.2 (do not call `ask_user`)
+            and continue with step 2.3 dispatch.
 
         2.  Call the `ask_user` tool of the agent harness with:
 
@@ -137,3 +139,99 @@ Let the *user interactively choose* an answer.
 
 </define>
 
+<define name="custom-dialog">
+Let the *user interactively choose* an answer.
+
+1.  Take the following question specification:
+
+    <spec>
+        <content/>
+    </spec>
+
+    The first line of <spec/> (separated by newlines) is of the format:
+    `<question-label/>: <question-description/>`
+
+    The second and following lines of <spec/> (separated by newlines) are of the format:
+    `<label/>: <description/>`
+
+    The first line provides the question label and the question
+    description. The second and following lines each provide an
+    answer label and an answer description.
+
+    Do not output anything in this step!
+
+2.  Dispatch according to the agent tool:
+
+    1.  You *MUST* not output anything in this step.
+
+        Set <text></text> (set to empty).
+        Set <keys></keys> (set to empty).
+        Set <n>1</n> (set entry count to one).
+        Set <width/> to the maximum length plus 3 of all <label/> strings in <spec/>.
+
+        <for items="2 3 4 5 6 7 8 9">
+            Take from <spec/> the line number <item/>.
+            If this line does not exist, <break/>.
+            If this line exists, parse it according to the format `<label/>: <description/>`.
+            Set <label-key/> to <ase-tpl-key digit="<n/>"/>.
+            Set <label-text/> to `<ase-tpl-pad width="<width/>" text="<label/>:"/>`.
+            Append an entry to <text/>:
+
+            <text>
+            <text/>
+            <ase-tpl-boxline><label-key/>  ▶  **<label-text/>** <description/></ase-tpl-boxline>
+            </text>
+
+            Set <n/> to <n/> + 1 (increment entry count).
+            <if condition="<keys/> is empty">
+                Set <keys><label-key/></keys>
+            </if>
+            <else>
+                Set <keys><keys/>/<label-key/></keys>
+            </else>
+        </for>
+
+        Set:
+
+        <text>
+        <ase-tpl-boxed title="QUESTION" subtitle="<question-label/>">
+
+        <ase-tpl-boxline>**<question-description/>**</ase-tpl-boxline>
+
+        <text/>
+
+        Please choose *one* option by typing <keys/>/**CANCEL** or free-text instruction.
+
+        </ase-tpl-boxed>
+        </text>
+
+        If <n/> is less than 3:
+        Set <result>ERROR: user-dialog requires 2-8 answer lines, got less</result>
+        and *SKIP* the following step 2 and continue with step 3 dispatch.
+
+    2.  Output the following <template/>, end the current turn, wait for the
+        user input, store the user input in <result/> and then continue with step 3:
+
+        <template>
+        <text/>
+        </template>
+
+    3.  Check the result and dispatch accordingly:
+
+        -   If <result/> indicates that the user doesn't want to proceed,
+            or the user declined to answer the question, or that the dialog
+            was cancelled, rejected or skipped, set <result>CANCEL</result>.
+
+        -   Otherwise, determine the selected <label/>
+            by mapping the <result/> (usually containing one of the
+            "key" or "label" strings) to one of the answer labels. Set
+            <result><label/></result>.
+
+            If <result/> is then *NOT* one of the "label" values from
+            <spec/>, set <result>OTHER: <result/></result> (prefix
+            result with "OTHER").
+
+        Do not output anything in this step!
+
+</define>
+

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

@@ -8,8 +8,8 @@ Every *task* uses a strict and fixed format:
 
 #   TASK <task-id/>: <title/>
 
-Created:  <timestamp-created/>
-Modified: <timestamp-modified/>
+⎈   Created:  <timestamp-created/>
+⚙   Modified: <timestamp-modified/>
 
 ##  CONTEXT
 

package/plugin/meta/ase-getopt.md

@@ -8,30 +8,39 @@ Do not output anything in the following steps. The entire purpose is to
 set placeholders into the context as a side-effect.
 
 1.  **Determine Parameters**:
-    Set <getopt-skill><arg1/></getopt-skill>.
-    Set <getopt-spec>--help|-h <arg2/></getopt-spec>.
-    Set <getopt-args><content/></getopt-args>.
+    Set <getopt-skill><arg1/></getopt-skill>
+    Set <getopt-spec>--help|-h <arg2/></getopt-spec>
+    Set <getopt-args><content/></getopt-args>
 
 2.  **Short-Circuit Processing**:
-    If <getopt-args/> does *NOT* match the regexp `(^|\s)-` (i.e.
-    contains no options at all):
-
-    For each option token in <getopt-spec/> of the form
-    `--<long/>[|-<short/>][=<default/>|=(<c1/>|<c2/>|...)[...]]`, set
-    <getopt-option-<long/>/> to <default/> (for `=<default/>`
-    form), or to <c1/> (the first choice, for `=(<c1/>|<c2>/|...)`
-    form, or for the list form `=(<c1/>|<c2>/|...)...`),
-    or to `false` (for value-less options). Then set
-    <getopt-arguments><getopt-args/></getopt-arguments>.
-
-    Additionally, simulate <getopt-info/> as a comma-separated
-    markdown rendering of the parsed options in the form `<longN/>:
-    **<valueN/>**, [...]` (joined with `, `, with each value
-    shell-quoted if value contains spaces or special characters, and
-    excluding the `help` option).
-
-    Then silently *SKIP* only the following steps 3-6
-    and proceed directly to step 7 to display the results.
+    You *MUST* decide here, via the following *mandatory* <if/> control
+    construct, whether the options are parsed *locally* (no MCP call) or
+    *remotely* (via the MCP call in steps 3-6). This is a *hard branch*,
+    not an optional optimization: when the <if/> branch is taken, steps
+    3-6 are *structurally unreachable* and you *MUST NOT* call the
+    `ase_getopt` MCP tool under any circumstances.
+
+    <if condition="<getopt-args/> does *NOT* match the regexp `(^|\s)-` (i.e. it does not start with an option)">
+        Parse the options *locally*, without any MCP call:
+
+        For each option token in <getopt-spec/> of the form
+        `--<long/>[|-<short/>][=<default/>|=(<c1/>|<c2/>|...)[...]]`, set
+        <getopt-option-<long/>/> to <default/> (for `=<default/>`
+        form), or to <c1/> (the first choice, for `=(<c1/>|<c2>/|...)`
+        form, or for the list form `=(<c1/>|<c2>/|...)...`),
+        or to `false` (for value-less options). Then set
+        <getopt-arguments><getopt-args/></getopt-arguments>.
+
+        Additionally, simulate <getopt-info/> as a comma-separated
+        markdown rendering of the parsed options in the form `<longN/>:
+        **<valueN/>**, [...]` (joined with `, `, with each value
+        shell-quoted if value contains spaces or special characters, and
+        excluding the `help` option and any *internal* option whose long
+        name starts with `int-`).
+
+        You then *MUST* silently *SKIP* the steps 3-6 below
+        and proceed directly to step 7 to display the results.
+    </if>
 
 3.  **MCP Call**:
     Call the `ase_getopt(name: "<getopt-skill/>", spec: