@rse/ase 0.9.46 → 0.9.47

package/dst/ase-compat.js

@@ -3,6 +3,7 @@
 **  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
+import { writeStdout } from "./ase-stdout.js";
 /*  the canonical expected values for every ase-meta-compat probe,
     keyed by "<category>/<probe-name>" as used in the skill  */
 const EXPECTED = {
@@ -44,8 +45,8 @@ export default class CompatCommand {
         program
             .command("compat")
             .description("Output expected probe values for the ase-meta-compat self-test skill")
-            .action(() => {
-            process.stdout.write(formatExpected());
+            .action(async () => {
+            await writeStdout(formatExpected());
         });
     }
 }

package/dst/ase-config.js

@@ -14,6 +14,7 @@ import Table from "cli-table3";
 import writeFileAtomic from "write-file-atomic";
 import lockfile from "proper-lockfile";
 import { z } from "zod";
+import { writeStdout } from "./ase-stdout.js";
 /*  classification taxonomy  */
 export const projectClassification = {
     boxing: ["white", "grey", "black"]
@@ -188,7 +189,7 @@ export class Config {
     docs;
     target;
     /*  creation  */
-    constructor(name, schema, log, scope = [{ kind: "project" }]) {
+    constructor(name, schema, log, scope = [{ kind: "user" }, { kind: "project" }]) {
         if (scope.length === 0)
             throw new Error("invalid scope: chain must not be empty");
         this.name = name;
@@ -560,7 +561,7 @@ export default class ConfigCommand {
         configCmd
             .command("list")
             .description("list all configured values as flat dotted keys")
-            .action((_opts, cmd) => {
+            .action(async (_opts, cmd) => {
             const scope = parseScope(cmd.optsWithGlobals().scope);
             const cfg = new Config("config", configSchema, this.log, scope);
             cfg.read();
@@ -573,7 +574,7 @@ export default class ConfigCommand {
                 const val = isScalar(e.value) ? e.value.value : e.value;
                 table.push([e.key, String(val), Config.scopeLabel(e.scope)]);
             }
-            process.stdout.write(`${table.toString()}\n`);
+            await writeStdout(`${table.toString()}\n`);
         });
         /*  register CLI sub-command "ase config edit"  */
         configCmd
@@ -612,7 +613,7 @@ export default class ConfigCommand {
             .command("get")
             .description("print the value at a dotted configuration key")
             .argument("<key>", "configuration key (dotted path)")
-            .action((key, _opts, cmd) => {
+            .action(async (key, _opts, cmd) => {
             const scope = parseScope(cmd.optsWithGlobals().scope);
             const cfg = new Config("config", configSchema, this.log, scope);
             cfg.read();
@@ -621,7 +622,7 @@ export default class ConfigCommand {
                 throw new Error(`key "${key}" is not set`);
             if (isMap(val))
                 throw new Error(`key "${key}" is not a leaf key`);
-            process.stdout.write(`${isScalar(val) ? val.value : val}\n`);
+            await writeStdout(`${isScalar(val) ? val.value : val}\n`);
         });
         /*  register CLI sub-command "ase config set"  */
         configCmd

package/dst/ase-hook.js

@@ -69,6 +69,13 @@ const toolSpecs = {
         approvalEvent: "PermissionRequest"
     }
 };
+/*  schema (and derived type) of the tool invocation input fields
+    inspected by the tool-approval decision logic  */
+const toolInputSchema = v.object({
+    command: v.optional(v.string()),
+    skill: v.optional(v.string()),
+    file_path: v.optional(v.string())
+});
 /*  CLI command "ase hook"  */
 export default class HookCommand {
     log;
@@ -242,16 +249,15 @@ export default class HookCommand {
         const projectId = path.basename(projectDir);
         /*  determine user id  */
         const userId = process.env.USER ?? process.env.LOGNAME ?? "unknown";
-        /*  determine agent persona style  */
-        let persona = process.env.ASE_PERSONA_STYLE ?? "engineer";
-        const val = cfg.get("agent.persona");
-        if (typeof val === "string")
-            persona = val;
-        /*  determine project boxing transparency  */
-        let boxing = process.env.ASE_PROJECT_BOXING ?? "white";
-        const valBoxing = cfg.get("project.boxing");
-        if (typeof valBoxing === "string")
-            boxing = valBoxing;
+        /*  helper function: determine a setting from the configuration,
+            falling back to an environment variable and a default  */
+        const setting = (key, envVar, dflt) => {
+            const val = cfg.get(key);
+            return typeof val === "string" ? val : (process.env[envVar] ?? dflt);
+        };
+        /*  determine agent persona style and project boxing transparency  */
+        const persona = setting("agent.persona", "ASE_PERSONA_STYLE", "engineer");
+        const boxing = setting("project.boxing", "ASE_PROJECT_BOXING", "white");
         /*  determine headless mode  */
         const headless = (process.env.ASE_HEADLESS ?? "false") === "true" ? "true" : "false";
         /*  provide ASE information to Anthropic Claude Code CLI shell commands
@@ -422,13 +428,12 @@ export default class HookCommand {
         let toolInput = {};
         const rawInput = input[spec.toolInputField];
         if (spec.toolInputIsString && typeof rawInput === "string")
-            toolInput = this.parseJSON(rawInput, v.object({
-                command: v.optional(v.string()),
-                skill: v.optional(v.string()),
-                file_path: v.optional(v.string())
-            }));
-        else if (!spec.toolInputIsString && typeof rawInput === "object" && rawInput !== null)
-            toolInput = rawInput;
+            toolInput = this.parseJSON(rawInput, toolInputSchema);
+        else if (!spec.toolInputIsString && typeof rawInput === "object" && rawInput !== null) {
+            const result = v.safeParse(toolInputSchema, rawInput);
+            if (result.success)
+                toolInput = result.output;
+        }
         const command = toolInput.command ?? "";
         if (toolName === spec.bashToolName && /^ase(\s|$)/.test(command)
             && !/[;&|<>`\n]|\$\(/.test(command))

package/dst/ase-kv.js

@@ -72,6 +72,36 @@ export class KV {
         for (const [k, v] of snap)
             KV.store.set(k, v);
     }
+    /*  execute a single key/value command and return its result text  */
+    static execute(c) {
+        if (c.command === "clear")
+            return `OK: removed ${KV.clear(c.prefix)} key(s)`;
+        else if (c.command === "set") {
+            if (c.key === undefined)
+                throw new Error("missing `key`");
+            if (c.val === undefined)
+                throw new Error("missing `val`");
+            KV.set(c.key, c.val);
+            return `OK: stored key "${c.key}"`;
+        }
+        else if (c.command === "get") {
+            if (c.key === undefined)
+                throw new Error("missing `key`");
+            if (!KV.has(c.key))
+                return "";
+            const val = KV.get(c.key);
+            return val === undefined ? "" : JSON.stringify(val);
+        }
+        else if (c.command === "delete") {
+            if (c.key === undefined)
+                throw new Error("missing `key`");
+            return KV.delete(c.key) ?
+                `OK: removed key "${c.key}"` :
+                `WARNING: no key "${c.key}" to remove`;
+        }
+        else
+            throw new Error(`invalid command "${String(c.command)}"`);
+    }
 }
 /*  MCP registration entry point for in-memory key/value tools  */
 export class KVMCP {
@@ -87,10 +117,7 @@ export class KVMCP {
             }
         }, async (args) => {
             try {
-                if (!KV.has(args.key))
-                    return { content: [{ type: "text", text: "" }] };
-                const val = KV.get(args.key);
-                const text = val === undefined ? "" : JSON.stringify(val);
+                const text = KV.execute({ command: "get", key: args.key });
                 return { content: [{ type: "text", text }] };
             }
             catch (err) {
@@ -112,8 +139,8 @@ export class KVMCP {
             }
         }, async (args) => {
             try {
-                KV.set(args.key, args.val);
-                return { content: [{ type: "text", text: `OK: stored key "${args.key}"` }] };
+                const text = KV.execute({ command: "set", key: args.key, val: args.val });
+                return { content: [{ type: "text", text }] };
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);
@@ -133,8 +160,8 @@ export class KVMCP {
             }
         }, async (args) => {
             try {
-                const n = KV.clear(args.prefix);
-                return { content: [{ type: "text", text: `OK: removed ${n} key(s)` }] };
+                const text = KV.execute({ command: "clear", prefix: args.prefix });
+                return { content: [{ type: "text", text }] };
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);
@@ -152,11 +179,8 @@ export class KVMCP {
             }
         }, async (args) => {
             try {
-                const removed = KV.delete(args.key);
-                const msg = removed ?
-                    `OK: removed key "${args.key}"` :
-                    `WARNING: no key "${args.key}" to remove`;
-                return { content: [{ type: "text", text: msg }] };
+                const text = KV.execute({ command: "delete", key: args.key });
+                return { content: [{ type: "text", text }] };
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);
@@ -199,36 +223,7 @@ export class KVMCP {
             const snapshot = tx ? KV.snapshot() : null;
             for (const c of args.commands) {
                 try {
-                    if (c.command === "clear") {
-                        const n = KV.clear(c.prefix);
-                        results.push(`OK: removed ${n} key(s)`);
-                    }
-                    else if (c.command === "set") {
-                        if (c.key === undefined)
-                            throw new Error("missing `key`");
-                        if (c.val === undefined)
-                            throw new Error("missing `val`");
-                        KV.set(c.key, c.val);
-                        results.push(`OK: stored key "${c.key}"`);
-                    }
-                    else if (c.command === "get") {
-                        if (c.key === undefined)
-                            throw new Error("missing `key`");
-                        if (!KV.has(c.key))
-                            results.push("");
-                        else {
-                            const val = KV.get(c.key);
-                            results.push(val === undefined ? "" : JSON.stringify(val));
-                        }
-                    }
-                    else if (c.command === "delete") {
-                        if (c.key === undefined)
-                            throw new Error("missing `key`");
-                        const removed = KV.delete(c.key);
-                        results.push(removed ?
-                            `OK: removed key "${c.key}"` :
-                            `WARNING: no key "${c.key}" to remove`);
-                    }
+                    results.push(KV.execute(c));
                 }
                 catch (err) {
                     const message = err instanceof Error ? err.message : String(err);

package/dst/ase-log.js

@@ -24,11 +24,7 @@ export default class Log {
         this._logFile = _logFile;
     }
     async init() {
-        /*  log messages  */
-        const idx = levels.findIndex((l) => l.name === this._logLevel);
-        if (idx === -1)
-            throw new RangeError(`invalid log level "${this._logLevel}" (expected one of: ${levels.map((l) => l.name).join(", ")})`);
-        this.logLevelIdx = idx;
+        this.logLevel(this._logLevel);
         if (this._logFile !== "-")
             this.stream = this.openStream(this._logFile);
     }
@@ -73,4 +69,16 @@ export default class Log {
                 this.stream.write(line);
         }
     }
+    /*  close the log file stream, flushing all pending writes  */
+    async close() {
+        if (this.stream === null)
+            return;
+        const stream = this.stream;
+        this.stream = null;
+        await new Promise((resolve) => {
+            stream.end(() => {
+                resolve();
+            });
+        });
+    }
 }

package/dst/ase-markdown.js

@@ -69,6 +69,16 @@ export class Markdown {
             n++;
         return n;
     }
+    /*  test whether the newline at offset pos starts a paragraph break,
+        i.e. whether it is followed by a blank line or the end of the text  */
+    static isParagraphBreak(text, pos) {
+        let n = pos + 1;
+        while (n < text.length && (text[n] === " " || text[n] === "\t"))
+            n++;
+        if (text[n] === "\r")
+            n++;
+        return n >= text.length || text[n] === "\n";
+    }
     /*  PASS 1 of rewrite(): rewrite inline code spans that carry
         backslash-escaped backticks (`\``) into CommonMark-correct spans  */
     static rewriteEscapedSpans(text) {
@@ -118,7 +128,7 @@ export class Markdown {
                     k += runLen;
                     continue;
                 }
-                if (c === "\n" && /^[ \t]*\r?(?:\n|$)/.test(text.slice(k + 1)))
+                if (c === "\n" && Markdown.isParagraphBreak(text, k))
                     /*  a code span never crosses a paragraph break  */
                     break;
                 inner += c;
@@ -185,7 +195,7 @@ export class Markdown {
                                 closes = true;
                             p += r;
                         }
-                        else if (text[p] === "\n" && /^[ \t]*\r?(?:\n|$)/.test(text.slice(p + 1)))
+                        else if (text[p] === "\n" && Markdown.isParagraphBreak(text, p))
                             /*  a code span never crosses a paragraph break  */
                             break;
                         else

package/dst/ase-mcp.js

@@ -94,8 +94,11 @@ export default class MCPCommand {
                     return;
                 triggerReconnect("http connection lost");
             };
+            /*  activate the connection and flush buffered messages  */
             await next.start();
             client = next;
+            for (const msg of pending.splice(0, pending.length))
+                sendToClient(msg);
         };
         /*  reconnect loop: restart service if needed, then reconnect client  */
         const reconnect = async (attempt = 0) => {
@@ -132,12 +135,26 @@ export default class MCPCommand {
             this.log.write("warning", `mcp: ${reason} — reconnecting`);
             reconnect(0).catch(() => { });
         };
-        /*  wire stdio server  */
-        server.onmessage = (msg) => {
-            client?.send(msg).catch((err) => {
+        /*  bounded buffer for messages arriving while no HTTP client is connected  */
+        const MAX_PENDING = 100;
+        const pending = [];
+        /*  forward a message to the HTTP client, buffering it while the client
+            is disconnected so requests survive a reconnect window  */
+        const sendToClient = (msg) => {
+            if (client === null) {
+                if (pending.length >= MAX_PENDING) {
+                    this.log.write("warning", "mcp: pending queue overflow, dropping oldest message");
+                    pending.shift();
+                }
+                pending.push(msg);
+                return;
+            }
+            client.send(msg).catch((err) => {
                 this.log.write("error", `mcp: http send: ${this.asError(err).message}`);
             });
         };
+        /*  wire stdio server  */
+        server.onmessage = sendToClient;
         server.onerror = (err) => {
             this.log.write("error", `mcp: stdio: ${err.message}`);
         };

package/dst/ase-persona.js

@@ -20,9 +20,7 @@ export class Persona {
         if (val === undefined)
             return "engineer";
         const style = String(isScalar(val) ? val.value : val);
-        if (!Persona.styles.includes(style))
-            return "engineer";
-        return style;
+        return Persona.styles.find((s) => s === style) ?? "engineer";
     }
     /*  set the persona style on the strongest scope of an optional session  */
     static set(log, style, session) {

package/dst/ase-service.js

@@ -477,6 +477,16 @@ export default class ServiceCommand {
         }
         throw lastErr;
     }
+    /*  build the "POST /command" request options for a command token  */
+    commandRequest(cmd, timeoutMs) {
+        return {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: { command: cmd },
+            signal: AbortSignal.timeout(timeoutMs),
+            ignoreResponseError: true
+        };
+    }
     /*  status flow: report whether the service is running  */
     async doStatus() {
         const ctx = this.loadContext();
@@ -486,13 +496,7 @@ export default class ServiceCommand {
         }
         const match = await probe(ctx.port, ctx.projectId);
         if (match === true) {
-            const r = await ofetch.raw(`http://${HOST}:${ctx.port}/command`, {
-                method: "POST",
-                headers: { "Content-Type": "application/json" },
-                body: { command: "status" },
-                signal: AbortSignal.timeout(2000),
-                ignoreResponseError: true
-            });
+            const r = await ofetch.raw(`http://${HOST}:${ctx.port}/command`, this.commandRequest("status", 2000));
             const d = r._data;
             const uptimeMs = typeof d?.uptimeMs === "number" ? d.uptimeMs : 0;
             const uptime = prettyMs(uptimeMs, { verbose: true });
@@ -509,30 +513,16 @@ export default class ServiceCommand {
     /*  send command: POST /command with the arbitrary cmd token  */
     async doSend(cmd) {
         let ctx = this.loadContext();
-        if (ctx.port === null) {
-            await this.doStart();
-            ctx = this.loadContext();
-            if (ctx.port === null)
-                throw new Error("service not running (no port configured after auto-start)");
-        }
-        let match = await probe(ctx.port, ctx.projectId);
-        if (match !== true) {
+        if (ctx.port === null || await probe(ctx.port, ctx.projectId) !== true) {
+            /*  auto-start the service once, then re-check  */
             await this.doStart();
             ctx = this.loadContext();
             if (ctx.port === null)
                 throw new Error("service not running (no port configured after auto-start)");
-            match = await probe(ctx.port, ctx.projectId);
-            if (match !== true)
+            if (await probe(ctx.port, ctx.projectId) !== true)
                 throw new Error(`service not responding on port ${ctx.port} after auto-start`);
         }
-        const r = await ofetch.raw(`http://${HOST}:${ctx.port}/command`, {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: { command: cmd },
-            signal: AbortSignal.timeout(5000),
-            ignoreResponseError: true,
-            responseType: "text"
-        });
+        const r = await ofetch.raw(`http://${HOST}:${ctx.port}/command`, { ...this.commandRequest(cmd, 5000), responseType: "text" });
         const body = typeof r._data === "string" ? r._data : JSON.stringify(r._data);
         process.stdout.write(body);
         if (!body.endsWith("\n"))

package/dst/ase-setup.js

@@ -63,27 +63,18 @@ export default class SetupCommand {
             path.join(prefix, "bin"),
             path.join(prefix, "lib", "node_modules")
         ];
+        const accessible = (dir, mode) => fs.access(dir, mode).then(() => true, () => false);
         for (const dir of candidates) {
-            try {
-                await fs.access(dir, fs.constants.W_OK);
-            }
-            catch {
-                /*  directory exists but not writable, or does not exist
-                    inside a non-writable parent: require sudo  */
-                try {
-                    await fs.access(dir, fs.constants.F_OK);
-                    return true;
-                }
-                catch {
-                    /*  directory does not exist: check parent writability  */
-                    try {
-                        await fs.access(path.dirname(dir), fs.constants.W_OK);
-                    }
-                    catch {
-                        return true;
-                    }
-                }
-            }
+            /*  a writable directory needs no elevation at all  */
+            if (await accessible(dir, fs.constants.W_OK))
+                continue;
+            /*  the directory exists, but is not writable: require sudo  */
+            if (await accessible(dir, fs.constants.F_OK))
+                return true;
+            /*  the directory does not exist: require sudo unless it can
+                be created inside a writable parent directory  */
+            if (!(await accessible(path.dirname(dir), fs.constants.W_OK)))
+                return true;
         }
         return false;
     }
@@ -110,25 +101,7 @@ export default class SetupCommand {
         for (let i = 0; i < retries; i++) {
             const final = (i === retries - 1);
             try {
-                if (quiet) {
-                    const result = await execa(cmd, args, { stdio: "ignore", cwd, reject: false });
-                    if (typeof result.exitCode === "number" && result.exitCode !== 0) {
-                        if (!final) {
-                            this.log.write("info", `setup: attempt ${i + 1}/${retries} failed for "${cmd} ${args.join(" ")}" ` +
-                                `(exit code: ${result.exitCode}): retrying...`);
-                            await new Promise((resolve) => setTimeout(resolve, 1000));
-                            continue;
-                        }
-                        if (ignoreError !== undefined) {
-                            this.log.write("info", `setup: ${ignoreError} (skipped)`);
-                            return;
-                        }
-                        this.log.write("error", `setup: command failed: exit code: ${result.exitCode}`);
-                        throw new Error(`command "${cmd} ${args.join(" ")}" failed (exit code: ${result.exitCode})`);
-                    }
-                    return;
-                }
-                await execa(cmd, args, { stdio: "pipe", cwd });
+                await execa(cmd, args, { stdio: quiet ? "ignore" : "pipe", cwd });
                 return;
             }
             catch (err) {

package/dst/ase-statusline.js

@@ -166,6 +166,11 @@ const probeMemory = () => {
         return { used: 0, total: 0 };
     }
 };
+/*  memoize a zero-argument function, computing its value at most once on first use  */
+const memoize = (fn) => {
+    let cache = null;
+    return () => (cache ??= { value: fn() }).value;
+};
 /*  command-line handling  */
 export default class StatuslineCommand {
     log;
@@ -263,16 +268,8 @@ export default class StatuslineCommand {
             /*  lazy memoized probes for cross-renderer values: each is computed at most
                 once per run and only when first requested by a renderer (or by the
                 post-loop tmux publish for the Config cascade)  */
-            let sessCache = null;
-            const getSession = () => {
-                if (sessCache === null)
-                    sessCache = data.session_id ?? "unknown";
-                return sessCache;
-            };
-            let cfgCache = null;
-            const getCfg = () => {
-                if (cfgCache !== null)
-                    return cfgCache;
+            const getSession = memoize(() => data.session_id ?? "unknown");
+            const getCfg = memoize(() => {
                 let taskId = process.env.ASE_TASK_ID ?? "";
                 let persona = process.env.ASE_PERSONA_STYLE ?? "";
                 try {
@@ -288,21 +285,10 @@ export default class StatuslineCommand {
                 catch (_e) {
                     /*  cascade unavailable; keep env-var fallbacks  */
                 }
-                cfgCache = { taskId, persona };
-                return cfgCache;
-            };
-            let gitCache = null;
-            const getGit = () => {
-                if (gitCache === null)
-                    gitCache = probeGit(data.workspace?.current_dir ?? "");
-                return gitCache;
-            };
-            let memCache = null;
-            const getMem = () => {
-                if (memCache === null)
-                    memCache = probeMemory();
-                return memCache;
-            };
+                return { taskId, persona };
+            });
+            const getGit = memoize(() => probeGit(data.workspace?.current_dir ?? ""));
+            const getMem = memoize(() => probeMemory());
             /*  identifier to renderer map: each callback fetches its own information
                 directly from data (or via the lazy helpers above for shared values)  */
             const renderers = {
@@ -432,11 +418,11 @@ export default class StatuslineCommand {
                 },
                 /*  ==== VERSIONS ====  */
                 V: () => {
-                    const ccVersion = data.version ?? "";
+                    const toolVersion = data.version ?? "";
                     const aseVersion = pkg.version ?? "";
                     let version = "";
-                    if (ccVersion !== "")
-                        version += `claude/${ccVersion}`;
+                    if (toolVersion !== "")
+                        version += `${tool}/${toolVersion}`;
                     if (aseVersion !== "")
                         version += `${version !== "" ? " " : ""}ase/${aseVersion}`;
                     emit(`${prefix("⎈", "version")}${c.bold(version)}`);

package/dst/ase-task.js

@@ -71,6 +71,8 @@ export class Task {
         };
         const basedir = (read("project.artifact.task.basedir") || ".ase/task")
             .replace(/\\/g, "/").replace(/^\/+|\/+$/g, "");
+        if (basedir.split("/").includes(".."))
+            throw new Error(`task: configured "basedir" "${basedir}" must not escape the project root`);
         const files = read("project.artifact.task.files") || "*.md";
         return { basedir, files };
     }
@@ -89,33 +91,18 @@ export class Task {
     }
     /*  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)  */
+        current <basedir>/TASK-<id>.md layout ("migrateAll" is a cheap
+        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);
+        Task.migrateAll(log);
         return path.join(Task.baseDir(log), `TASK-${id}.md`);
     }
-    /*  cheaply check whether any legacy <basedir>/<id>/plan.md file still
-        exists in the task base directory and thus needs migration  */
-    static needsMigration(log) {
-        const dir = Task.baseDir(log);
-        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))
-                continue;
-            if (fs.existsSync(path.join(dir, entry.name, "plan.md")))
-                return true;
-        }
-        return false;
-    }
     /*  migrate all legacy <basedir>/<id>/plan.md task files to the current
         <basedir>/TASK-<id>.md layout; an existing TASK-<id>.md is never
-        overwritten; the now-empty <id>/ directory is removed afterwards;
-        returns the list of migrated task ids in lexicographic order  */
+        overwritten; the legacy <id>/ directory is removed only if it is
+        empty afterwards; returns the migrated task ids in lexicographic order  */
     static migrateAll(log) {
         const dir = Task.baseDir(log);
         if (!fs.existsSync(dir))
@@ -134,7 +121,12 @@ export class Task {
                 continue;
             }
             fs.renameSync(oldFile, newFile);
-            fs.rmSync(path.join(dir, id), { recursive: true, force: true });
+            /*  drop the legacy directory, but only if it is really empty  */
+            const legacyDir = path.dirname(oldFile);
+            if (fs.readdirSync(legacyDir).length === 0)
+                fs.rmdirSync(legacyDir);
+            else
+                log.write("warning", `task: keeping non-empty legacy directory "${legacyDir}"`);
             migrated.push(id);
         }
         migrated.sort((a, b) => a.localeCompare(b));
@@ -187,8 +179,7 @@ export class Task {
     /*  scan the task base directory (after eager migration) for
         "TASK-<id>.md" files matching the configured "files" miniglob  */
     static scan(log) {
-        if (Task.needsMigration(log))
-            Task.migrateAll(log);
+        Task.migrateAll(log);
         const { basedir, files } = Task.spec(log);
         const dir = path.join(Task.projectRoot(), basedir);
         if (!fs.existsSync(dir))

package/dst/ase.js

@@ -59,12 +59,16 @@ const main = async () => {
     /*  parse program arguments  */
     await program.parseAsync(process.argv);
     /*  gracefully terminate  */
+    await log.close();
     process.exit(0);
 };
-main().catch((err) => {
-    if (err instanceof CommanderError)
+main().catch(async (err) => {
+    if (err instanceof CommanderError) {
+        await log.close();
         process.exit(err.exitCode);
+    }
     const message = err instanceof Error ? err.message : String(err);
     log.write("error", message);
+    await log.close();
     process.exit(1);
 });

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.46",
+    "version":                              "0.9.47",
     "license":                              "Apache-2.0",
     "author": {
         "name":                             "Dr. Ralf S. Engelschall",

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

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

package/plugin/etc/stx.conf

@@ -11,12 +11,12 @@ lint
 
 #   [plugin] build project
 build : lint
-    (   for name in $(cd skills; ls -1 | grep -v ase-meta-intent | sort); do
+    (   for name in $(cd skills; ls -1 | grep -v ase-help-intent | sort); do
             echo "<skill name=\"$name\">"
             cat skills/$name/help.md | sed -e '/^##  SEE ALSO/,$d'
             echo "</skill>"
         done
-    ) >skills/ase-meta-intent/data.md
+    ) >skills/ase-help-intent/data.md
 
 #   [plugin] remove all generated files
 clean

package/plugin/meta/ase-skill.md

@@ -140,6 +140,15 @@ Skill Sequential Processing
 -   *IMPORTANT*: For each <step/> you *MUST* use the `TaskUpdate` tool
     for updating its status *during* processing, once a <step/> finished.
 
+-   *IMPORTANT*: Whenever a skill *stops early* -- because a <step/>
+    instructed you to *STOP* processing (on an error, a cancelled
+    dialog, a short-circuit branch, or any other early exit) -- you
+    *MUST*, *before* emitting the final <template/>, use the `TaskUpdate`
+    tool to set the status of *every* still `pending` or `in_progress`
+    task of the current <flow/> to `deleted`, so that no task of a
+    finished skill remains open. Steps that were *skipped* because their
+    `condition` attribute was not met *MUST* be treated the same way.
+
 -   *IMPORTANT*: You *MUST* *strictly sequentially* execute every <step/> in
     a <flow/>. You *MUST* not implicitly skip any <step/> during
     processing, except you were explicitly requested to do this or the

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.46",
+    "version":                              "0.9.47",
     "license":                              "Apache-2.0",
     "author": {
         "name":                             "Dr. Ralf S. Engelschall",

package/plugin/skills/{ase-meta-intent → ase-help-intent}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: ase-meta-intent
+name: ase-help-intent
 argument-hint: "[--help|-h] <intent>"
 description: >
     Match a free-text intent against the accumulated help of all ASE
@@ -20,12 +20,12 @@ allowed-tools:
 @${CLAUDE_SKILL_DIR}/../../meta/ase-dialog.md
 @${CLAUDE_SKILL_DIR}/../../meta/ase-getopt.md
 
-<skill name="ase-meta-intent">
+<skill name="ase-help-intent">
 Match an Intent to an ASE Command
 </skill>
 
 <expand name="getopt"
-    arg1="ase-meta-intent"
+    arg1="ase-help-intent"
     arg2="">
     $ARGUMENTS
 </expand>
@@ -54,7 +54,7 @@ catalog you match <intent/> against:
     processing the entire current skill:
 
     <template>
-    ⧉ **ASE**: ✪ skill: **ase-meta-intent**, ▶ ERROR: expected a `<intent>` argument
+    ⧉ **ASE**: ✪ skill: **ase-help-intent**, ▶ ERROR: expected a `<intent>` argument
     </template>
     </if>
 

package/plugin/skills/{ase-meta-intent → ase-help-intent}/help.md

@@ -1,19 +1,19 @@
 
 ##  NAME
 
-`ase-meta-intent` - Match an Intent to an ASE Command
+`ase-help-intent` - Match an Intent to an ASE Command
 
 ##  SYNOPSIS
 
-`ase-meta-intent`
+`ase-help-intent`
     [`--help`|`-h`]
     *intent*
 
 ##  DESCRIPTION
 
-The `ase-meta-intent` skill matches a free-text *intent* against the
+The `ase-help-intent` skill matches a free-text *intent* against the
 *accumulated help* of all ASE skills -- the concatenation of every
-skill's `help.md` file into `skills/ase-meta-intent/data.md`, built by
+skill's `help.md` file into `skills/ase-help-intent/data.md`, built by
 `npm start build` in `plugin/` -- and generates the *single* best-fitting
 `/ase:ase-xxx-xxx` command that realizes the intent, complete with
 concrete option flags and positional arguments derived from the selected
@@ -42,15 +42,16 @@ entirely through the intent argument and the interactive dialog.
 Route an intent to the matching command and pick from the dialog:
 
 ```text
-❯ /ase-meta-intent lint the TypeScript sources for high-severity issues only
+❯ /ase-help-intent lint the TypeScript sources for high-severity issues only
 ```
 
 Route a planning intent to the matching command:
 
 ```text
-❯ /ase-meta-intent explain how the authentication module works
+❯ /ase-help-intent explain how the authentication module works
 ```
 
 ##  SEE ALSO
 
-[`ase-meta-proximity`](../ase-meta-proximity/help.md), [`ase-meta-search`](../ase-meta-search/help.md), [`ase-code-craft`](../ase-code-craft/help.md).
+[`ase-help-skill`](../ase-help-skill/help.md), [`ase-meta-proximity`](../ase-meta-proximity/help.md), [`ase-meta-search`](../ase-meta-search/help.md),
+[`ase-code-craft`](../ase-code-craft/help.md).

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

@@ -0,0 +1,203 @@
+---
+name: ase-help-skill
+argument-hint: "[--help|-h] [<skill-name>]"
+description: >
+    Show the manual page of an ASE skill, addressed by its full name, by
+    any abbreviation of it, or by a description of its purpose, and list
+    the entire skill catalog when no name is given. Use when the user
+    wants the "manual", "man page", "manpage", or "help" of a particular
+    ASE skill, or asks what a certain `ase-xxx-xxx` skill does.
+user-invocable: true
+disable-model-invocation: false
+effort: medium
+allowed-tools:
+    - "Read"
+---
+
+@${CLAUDE_SKILL_DIR}/../../meta/ase-control.md
+@${CLAUDE_SKILL_DIR}/../../meta/ase-skill.md
+@${CLAUDE_SKILL_DIR}/../../meta/ase-dialog.md
+@${CLAUDE_SKILL_DIR}/../../meta/ase-getopt.md
+
+<skill name="ase-help-skill">
+Show the Manual Page of an ASE Skill
+</skill>
+
+<expand name="getopt"
+    arg1="ase-help-skill"
+    arg2="">
+    $ARGUMENTS
+</expand>
+
+<objective>
+*Show* the *manual page* of the ASE skill addressed by the following
+skill name, abbreviation of it, or description of its purpose:
+<skill-ref><getopt-arguments/></skill-ref>
+</objective>
+
+The following <catalog/> is index of all ASE skills -- one
+`⎈ **<group/>**` entry per skill group and one
+``○ `<name/>`: <purpose/>`` entry per skill -- and this is
+the *sole* index <skill-ref/> is resolved against:
+
+<catalog>
+@${CLAUDE_SKILL_DIR}/catalog.md
+</catalog>
+
+<flow>
+
+1.  <step id="STEP 1: Resolve Skill Name">
+
+    1.  <if condition="<skill-ref/> is empty">
+        No particular skill was addressed, so render the *entire*
+        <catalog/> as a browsable list with the following <template/>
+        -- one list entry per catalog entry, in catalog order, where
+        <name/> and <purpose/> are the two fields of the entry (and
+        <name-padded/> is <name/>, padded to 22 characters with
+        spaces on the right) -- and then immediately *STOP* processing
+        the entire current skill:
+
+        <template>
+        <ase-tpl-head title="SKILL CATALOG"/>
+
+        <catalog/>
+
+        <ase-tpl-foot title="SKILL CATALOG"/>
+
+        ⧉ **ASE**: ✪ skill: **ase-help-skill**, ▶ hint: **run `/ase-help-skill ase-xxx-xxx` for manual page of individual skill**
+        </template>
+        </if>
+
+    2.  Set <skill-ref-raw/> to <skill-ref/> with only its leading and
+        trailing whitespace stripped, as the *verbatim* wording of the
+        user is required later on.
+
+        *Normalize* <skill-ref/> by stripping all leading and trailing
+        whitespace and then, repeatedly, any leading `/` and `ase:`
+        prefix, so that `ase-code-lint`, `/ase-code-lint`,
+        `ase:ase-code-lint`, and `/ase:ase-code-lint` all normalize to
+        `ase-code-lint`. Do not output anything.
+
+    3.  Resolve the normalized <skill-ref/> against <catalog/> in *three*
+        tiers and store the outcome in <candidates/>. Each tier is tried
+        only if all preceding tiers yielded *no* candidate at all:
+
+        1.  *Exact Name Tier*:
+
+            If a catalog *name* is *equal* to <skill-ref/>, set
+            <candidates/> to exactly that *single* name.
+
+        2.  *Substring Name Tier*:
+
+            Set <candidates/> to *all* catalog *names* *containing*
+            <skill-ref/> as a substring, in alphabetical order.
+
+        3.  *Fuzzy Purpose Tier*:
+
+            Set <candidates/> to *all* catalog names whose *purpose* --
+            the part *after* the colon of the catalog entry -- *fuzzily*
+            matches <skill-ref-raw/>, in *descending* order of match
+            quality. Match against <skill-ref-raw/>, and *not* against
+            <skill-ref/>, as this tier matches free-text wording, which
+            the normalization of sub-step 2 would distort.
+
+            A purpose matches fuzzily if it shares the topic, the
+            wording, or evident synonyms with <skill-ref-raw/>, so
+            that e.g. `manpage` matches `Show the Manual Page of an
+            ASE Skill` and `root cause` matches `Five-Whys Root-Cause
+            Analysis`. Include *plausible* matches only -- if none is
+            plausible, leave <candidates/> empty.
+
+        Set <count/> to the number of entries in <candidates/>.
+        Do not output anything.
+
+    </step>
+
+2.  <step id="STEP 2: Dispatch Resolution">
+
+    1.  <if condition="<count/> is equal 0">
+        Only output the following <template/> and then immediately
+        *STOP* processing the entire current skill:
+
+        <template>
+        ⧉ **ASE**: ✪ skill: **ase-help-skill**, ▶ ERROR: unknown skill: **<skill-ref-raw/>**
+        </template>
+        </if>
+
+    2.  <elseif condition="<count/> is equal 1">
+        Set <name/> to the single entry of <candidates/> and continue
+        processing. Do not output anything.
+        </elseif>
+
+    3.  <else>
+        The abbreviation is *ambiguous*, so let the user pick the
+        intended skill.
+
+        Set <shown/> to the *first* 9 entries of <candidates/>, as the
+        dialog renders at most *nine* answer lines.
+
+        <if condition="<count/> is greater than 9">
+            Set <truncation> (showing 9 of <count/> candidates)</truncation>
+        </if>
+        <else>
+            Set <truncation></truncation> (set to empty)
+        </else>
+
+        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.
+
+        Let the user select the intended skill by raising a question
+        with the following custom dialog, where each answer line
+        corresponds to one entry of <shown/>, using the catalog *name*
+        as the label and its catalog *purpose* as the description:
+
+        <expand name="custom-dialog" arg1="--no-other">
+            Ambiguous Skill: Which skill's manual page should be shown?<truncation/>
+            <name/>: <purpose/>
+            [...]
+        </expand>
+
+        Check the <result/> and dispatch accordingly:
+
+        -   If <result/> is `CANCEL`:
+            *STOP* processing without any further output.
+
+        -   Otherwise: Set <name/> to the selected skill name and
+            continue processing.
+        </else>
+
+    </step>
+
+3.  <step id="STEP 3: Render Manual Page">
+
+    1.  Use the `Read` tool to read the manual page of the resolved
+        skill <name/> and set <manual/> to its content. The file path is
+        formed by joining <ase-plugin-root/> and `skills/<name/>/help.md`
+        with exactly *one* `/` separator, as <ase-plugin-root/> may or
+        may not carry a trailing `/`. Do not output anything related to
+        this tool call.
+
+    2.  <if condition="<manual/> is empty or could not be read">
+        Only output the following <template/> and then immediately
+        *STOP* processing the entire current skill:
+
+        <template>
+        ⧉ **ASE**: ✪ skill: **ase-help-skill**, ▶ ERROR: unreadable manual page: **<name/>**
+        </template>
+        </if>
+
+    3.  Treat <manual/> as *verbatim* Markdown. You *MUST* *NOT*
+        truncate, summarize, reformat, or partially show it. Only output
+        the following <template/>:
+
+        <template>
+        <ase-tpl-head title="MANUAL PAGE: <name/>"/>
+        <manual/>
+        <ase-tpl-foot title="MANUAL PAGE: <name/>"/>
+        </template>
+
+    </step>
+
+</flow>

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

@@ -0,0 +1,60 @@
+
+⎈   **HELP**
+○   `ase-help-skill`:      Show the Manual Page of an ASE Skill
+○   `ase-help-intent`:     Match an Intent to an ASE Command
+
+⎈   **RESEARCH**
+○   `ase-meta-search`:     Search the Internet/Web
+○   `ase-meta-proximity`:  Determine the Conceptual Proximity of a Topic
+○   `ase-meta-brainstorm`: Collaboratively Brainstorm a Topic
+○   `ase-meta-chat`:       Query Foreign LLM for Chat
+○   `ase-meta-quorum`:     Query Multiple AIs for Quorum Answer
+○   `ase-meta-diaboli`:    Play "Devil's Advocate" (Latin: "Advocatus Diaboli")
+○   `ase-meta-steelman`:   Build the "Steelman" Argument
+○   `ase-meta-eli5`:       Explain a Topic Like I'm 5
+○   `ase-meta-why`:        Five-Whys Root-Cause Analysis
+○   `ase-meta-evaluate`:   Evaluate Alternatives
+
+⎈   **ARCHITECTURE**
+○   `ase-arch-analyze`:    Review Software Architecture
+○   `ase-arch-discover`:   Discover Components
+
+⎈   **CODING**
+○   `ase-code-analyze`:    Analyze Source Code
+○   `ase-code-lint`:       Lint Source Code
+○   `ase-code-explain`:    Explain Source Code
+○   `ase-code-insight`:    Project Insight
+○   `ase-code-craft`:      Craft Source Code
+○   `ase-code-refactor`:   Refactor Artifacts
+○   `ase-code-resolve`:    Resolve Problem
+○   `ase-sync-import`:     Import Foreign Sources into Artifact Set
+○   `ase-sync-reconcile`:  Reconcile Artifact Set to Artifact Set
+○   `ase-sync-export`:     Export Artifact Set to Side-by-Side Files
+
+⎈   **DOCUMENTATION**
+○   `ase-docs-distill`:    Distill Document Key Points
+○   `ase-docs-proofread`:  Proofread Documents
+
+⎈   **VERSION CONTROL**
+○   `ase-meta-changelog`:  Update ChangeLog Entries
+○   `ase-meta-commit`:     Git Commit Message
+○   `ase-meta-diff`:       Summarize Diff
+○   `ase-meta-review`:     Review Staged Changes
+
+⎈   **TASK MANAGEMENT**
+○   `ase-task-id`:         Configure Task Id
+○   `ase-task-list`:       List Task Plans
+○   `ase-task-view`:       View a Task Plan
+○   `ase-task-edit`:       Iteratively Edit a Task Plan
+○   `ase-task-grill`:      Iteratively Grill a Task Plan
+○   `ase-task-condense`:   Condense a Task Plan
+○   `ase-task-reboot`:     Reboot a Task Plan
+○   `ase-task-preflight`:  Preflight a Task Plan
+○   `ase-task-implement`:  Implement a Task Plan
+○   `ase-task-rename`:     Rename a Task Plan
+○   `ase-task-delete`:     Delete a Task Plan
+
+⎈   **OTHER SKILLS**
+○   `ase-meta-persona`:    Persona Configuration
+○   `ase-meta-compat`:     Self-Test ASE Compatibility
+

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

@@ -0,0 +1,83 @@
+
+##  NAME
+
+`ase-help-skill` - Show the Manual Page of an ASE Skill
+
+##  SYNOPSIS
+
+`ase-help-skill`
+    [`--help`|`-h`]
+    [*skill-name*]
+
+##  DESCRIPTION
+
+The `ase-help-skill` skill renders the *manual page* (`help.md`) of the
+ASE skill addressed by *skill-name*. The page is emitted verbatim,
+framed between a `( HELP )` header and footer rule.
+
+The *skill-name* is resolved against a *catalog* of all ASE skills --
+one `name: purpose` entry per skill, generated into
+`skills/ase-help-skill/data.md` by `npm start build` in `plugin/`.
+Before resolving, any leading `/` and `ase:` prefix is stripped, so
+`ase-code-lint`, `/ase-code-lint`, and `ase:ase-code-lint` are
+equivalent. Resolution then proceeds in three tiers, each tried only if
+all preceding ones found nothing: an *exact* match on the full skill
+name wins outright, otherwise *every* skill name containing
+*skill-name* as a substring becomes a candidate, and otherwise
+*skill-name* is *fuzzily* matched against the skill *purposes* -- so
+a topical phrase such as `root cause` still finds `ase-meta-why` --
+with the candidates ordered by descending match quality.
+
+A *skill-name* matching no skill in any tier is reported as an error. A
+*skill-name* matching more than one skill opens an interactive dialog
+listing the candidates with their purposes; as the dialog renders at
+most nine answer lines, a broader abbreviation such as `task` shows the
+first nine candidates and states how many exist in total.
+
+If *skill-name* is omitted, the whole catalog is rendered as a
+browsable `Skill`/`Purpose` table instead.
+
+The skill exposes *no* option flags beyond `--help`/`-h`.
+
+##  ARGUMENTS
+
+*skill-name*:
+    The full name of the ASE skill, any abbreviation of it, or a
+    description of its purpose. If omitted, the entire skill catalog is
+    listed.
+
+##  EXAMPLES
+
+Show the manual page of `ase-code-lint` via its shortest abbreviation:
+
+```text
+❯ /ase-help-skill lint
+```
+
+Show the same manual page via its full, plugin-qualified name:
+
+```text
+❯ /ase-help-skill ase:ase-code-lint
+```
+
+Pick a manual page from the candidates of an ambiguous abbreviation:
+
+```text
+❯ /ase-help-skill analyze
+```
+
+Find a manual page by the purpose of the skill instead of its name:
+
+```text
+❯ /ase-help-skill root cause
+```
+
+List the entire skill catalog:
+
+```text
+❯ /ase-help-skill
+```
+
+##  SEE ALSO
+
+[`ase-help-intent`](../ase-help-intent/help.md), [`ase-meta-proximity`](../ase-meta-proximity/help.md).

package/plugin/skills/ase-task-condense/help.md

@@ -47,9 +47,9 @@ After condensing, the user is asked whether to stop or hand off to
     Recognized tokens at this skill: `none` (default, interactive
     answer required), `DONE` (stop), `EDIT` (hand off to
     `ase-task-edit`), `IMPLEMENT` (hand off to `ase-task-implement`),
-    or `PREFLIGHT` (hand off to `ase-task-preflight`). Example: `--next
-    EDIT,DONE` condenses, hands off to editing, and the editing loop will
-    exit immediately.
+    or `PREFLIGHT` (hand off to `ase-task-preflight`). Example:
+    `--next EDIT,DONE` condenses, hands off to editing, and the editing
+    loop will exit immediately.
 
 ##  ARGUMENTS
 

package/plugin/skills/ase-task-reboot/help.md

@@ -33,9 +33,9 @@ unless `--next` pre-selects this choice.
     Recognized tokens at this skill: `none` (default, interactive
     answer required), `DONE` (stop), `EDIT` (hand off to
     `ase-task-edit`), `IMPLEMENT` (hand off to `ase-task-implement`),
-    or `PREFLIGHT` (hand off to `ase-task-preflight`). Example: `--next
-    EDIT,DONE` reboots, hands off to editing, and the editing loop will
-    exit immediately.
+    or `PREFLIGHT` (hand off to `ase-task-preflight`). Example:
+    `--next EDIT,DONE` reboots, hands off to editing, and the editing
+    loop will exit immediately.
 
 ##  ARGUMENTS
 

package/plugin/skills/ase-task-view/help.md

@@ -26,9 +26,9 @@ the plan in full, without any truncation or summarization.
 ##  OPTIONS
 
 `--full`|`-f`:
-    Render the plan in full, without collapsing the `IMPLEMENTATION
-    DRAFT` section. By default, that section is replaced with `[...]`
-    for plans longer than 90 lines.
+    Render the plan in full, without collapsing the
+    `IMPLEMENTATION DRAFT` section. By default, that section is
+    replaced with `[...]` for plans longer than 90 lines.
 
 ##  ARGUMENTS