@rse/ase 0.0.16 → 0.0.18

package/dst/ase-config.js

@@ -13,100 +13,45 @@ import * as v from "valibot";
 import Table from "cli-table3";
 /*  classification taxonomy  */
 export const projectClassification = {
-    source: {
-        ambition: ["artist", "craftsman", "engineer"],
-        boxing: ["white", "grey", "black"],
-        size: ["small", "medium", "large"],
-        structure: ["bare", "library", "framework"]
-    },
-    process: {
-        actors: ["person", "team", "crew"],
-        drive: ["spec", "code", "test"]
-    },
-    result: {
-        target: ["prototype", "mvp", "product"]
-    }
+    boxing: ["white", "grey", "black"]
 };
 /*  agent classification taxonomy  */
 export const agentClassification = {
-    persona: {
-        style: ["writer", "engineer", "telegrapher", "caveman"],
-        creativity: ["none", "lite", "full"]
-    },
-    process: {
-        autonomy: ["assistant", "hotl", "agent"]
-    }
+    persona: ["writer", "engineer", "telegrapher", "caveman"]
 };
 /*  classification presets  */
 export const projectClassificationPresets = {
     vibe: {
         "project.id": "example",
         "project.name": "Example Project",
-        "project.source.ambition": "engineer",
-        "project.source.boxing": "black",
-        "project.source.size": "small",
-        "project.source.structure": "bare",
-        "project.process.actors": "person",
-        "project.process.drive": "spec",
-        "project.result.target": "prototype",
-        "agent.persona.style": "writer",
-        "agent.persona.creativity": "full",
-        "agent.process.autonomy": "agent"
+        "project.boxing": "black",
+        "agent.persona": "writer"
     },
     pro: {
         "project.id": "example",
         "project.name": "Example Project",
-        "project.source.ambition": "artist",
-        "project.source.boxing": "white",
-        "project.source.size": "medium",
-        "project.source.structure": "framework",
-        "project.process.actors": "person",
-        "project.process.drive": "code",
-        "project.result.target": "product",
-        "agent.persona.style": "engineer",
-        "agent.persona.creativity": "none",
-        "agent.process.autonomy": "assistant"
+        "project.boxing": "white",
+        "agent.persona": "engineer"
     },
     default: {
         "project.id": "example",
         "project.name": "Example Project",
-        "project.source.ambition": "artist",
-        "project.source.boxing": "white",
-        "project.source.size": "medium",
-        "project.source.structure": "framework",
-        "project.process.actors": "person",
-        "project.process.drive": "code",
-        "project.result.target": "product",
-        "project.artifact.build": "{etc/**,README.md,AGENTS.md,LICENSE.txt,package.json}",
-        "project.artifact.code": "src/**/*",
-        "project.artifact.docs": "doc/user/**/*.md",
-        "project.artifact.spec": "doc/spec/**/*.md",
-        "project.artifact.arch": "doc/arch/**/*.md",
-        "agent.persona.style": "engineer",
-        "agent.persona.creativity": "none",
-        "agent.process.autonomy": "assistant",
-        "task.id": "default"
+        "project.boxing": "white",
+        "agent.persona": "engineer",
+        "agent.task": "default"
     },
     industry: {
         "project.id": "example",
         "project.name": "Example Project",
-        "project.source.ambition": "craftsman",
-        "project.source.boxing": "grey",
-        "project.source.size": "large",
-        "project.source.structure": "framework",
-        "project.process.actors": "crew",
-        "project.process.drive": "code",
-        "project.result.target": "mvp",
-        "agent.persona.style": "engineer",
-        "agent.persona.creativity": "none",
-        "agent.process.autonomy": "hotl"
+        "project.boxing": "grey",
+        "agent.persona": "engineer"
     }
 };
 /*  hard-coded map: which scope kinds each variable may be SET on
     (reads always cascade through the full chain, this restricts writes only);
     keys absent from this map default to all non-"default" scope kinds  */
 export const configWritableScopes = {
-    "task.id": ["session"]
+    "agent.task": ["session"]
 };
 /*  default set of scope kinds writable for any unrestricted key  */
 const configWritableScopesDefault = ["user", "project", "task", "session"];
@@ -151,7 +96,7 @@ const hasProjectContext = () => {
     "project" term is implicitly added only when a project context
     exists (Git repository or ".ase" directory at or above cwd), and
     an explicit "project" term requires that same context  */
-const parseScope = (value) => {
+export const parseScope = (value) => {
     const projectActive = hasProjectContext();
     const input = (value === undefined || value === "") ?
         (projectActive ? "project" : "user") :
@@ -181,38 +126,11 @@ export const configSchema = v.nullish(v.strictObject({
     project: v.optional(v.strictObject({
         id: v.optional(v.pipe(v.string(), v.minLength(1))),
         name: v.optional(v.pipe(v.string(), v.minLength(1))),
-        source: v.optional(v.strictObject({
-            ambition: v.optional(v.picklist(projectClassification.source.ambition)),
-            boxing: v.optional(v.picklist(projectClassification.source.boxing)),
-            size: v.optional(v.picklist(projectClassification.source.size)),
-            structure: v.optional(v.picklist(projectClassification.source.structure))
-        })),
-        process: v.optional(v.strictObject({
-            actors: v.optional(v.picklist(projectClassification.process.actors)),
-            drive: v.optional(v.picklist(projectClassification.process.drive))
-        })),
-        result: v.optional(v.strictObject({
-            target: v.optional(v.picklist(projectClassification.result.target))
-        })),
-        artifact: v.optional(v.strictObject({
-            build: v.optional(v.pipe(v.string(), v.minLength(1))),
-            code: v.optional(v.pipe(v.string(), v.minLength(1))),
-            docs: v.optional(v.pipe(v.string(), v.minLength(1))),
-            spec: v.optional(v.pipe(v.string(), v.minLength(1))),
-            arch: v.optional(v.pipe(v.string(), v.minLength(1)))
-        }))
+        boxing: v.optional(v.picklist(projectClassification.boxing))
     })),
     agent: v.optional(v.strictObject({
-        persona: v.optional(v.strictObject({
-            style: v.optional(v.picklist(agentClassification.persona.style)),
-            creativity: v.optional(v.picklist(agentClassification.persona.creativity))
-        })),
-        process: v.optional(v.strictObject({
-            autonomy: v.optional(v.picklist(agentClassification.process.autonomy))
-        }))
-    })),
-    task: v.optional(v.strictObject({
-        id: v.optional(v.pipe(v.string(), v.minLength(1)))
+        persona: v.optional(v.picklist(agentClassification.persona)),
+        task: v.optional(v.pipe(v.string(), v.minLength(1)))
     }))
 }));
 /*  encapsulate read/write access to a stack of "<name>.yaml" configuration files,

package/dst/ase-hook.js

@@ -6,14 +6,40 @@
 import path from "node:path";
 import fs from "node:fs";
 import { execaSync } from "execa";
+import Version from "./ase-version.js";
+import { Config, configSchema, parseScope } from "./ase-config.js";
 /*  CLI command "ase hook"  */
 export default class HookCommand {
     log;
     constructor(log) {
         this.log = log;
     }
+    /*  recursively expand "@<path>" file references in a Markdown text,
+        resolving paths relative to the directory of the containing file  */
+    expandReferences(text, baseDir, visited = new Set()) {
+        return text.replace(/@([^\s]+)/g, (match, ref) => {
+            let resolved = ref;
+            if (resolved.startsWith("~/"))
+                resolved = path.join(process.env.HOME ?? "", resolved.slice(2));
+            const abs = path.isAbsolute(resolved) ? resolved : path.resolve(baseDir, resolved);
+            if (visited.has(abs))
+                return match;
+            if (!fs.existsSync(abs))
+                return match;
+            let content;
+            try {
+                content = fs.readFileSync(abs, "utf8");
+            }
+            catch (_e) {
+                return match;
+            }
+            const next = new Set(visited);
+            next.add(abs);
+            return this.expandReferences(content, path.dirname(abs), next);
+        });
+    }
     /*  handler for "ase hook session-start"  */
-    doSessionStart() {
+    async doSessionStart() {
         /*  determine plugin root  */
         const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT ?? "";
         if (pluginRoot === "")
@@ -25,34 +51,85 @@ export default class HookCommand {
         const pkg = fs.readFileSync(filePkg, "utf8");
         let md = fs.readFileSync(fileMd, "utf8");
         /*  determine own version  */
-        const version = JSON.parse(pkg).version ?? "";
+        const versionCurrentPlugin = JSON.parse(pkg).version ?? "";
+        const versionCurrentTool = Version.current();
+        const versionLatestTool = await Version.latest();
+        /*  sanity check situation  */
+        const versionHints = [];
+        if (versionCurrentPlugin !== versionCurrentTool)
+            versionHints.push("**WARNING:** version *mismatch*: " +
+                `tool: **${versionCurrentPlugin}**, plugin: **${versionCurrentTool}**`);
+        if (versionCurrentTool !== versionLatestTool)
+            versionHints.push(`**NOTICE:** *latest* version: **${versionLatestTool}**, please update!`);
+        if (process.env.ASE_SETUP_DEV !== undefined)
+            versionHints.push("**NOTICE:** *development* setup");
+        const versionHint = versionHints.length > 0 ? "(" + versionHints.join(", ") + ")" : "";
         /*  read session information  */
         const stdin = fs.readFileSync(0, "utf8");
         const input = stdin.trim() !== "" ? JSON.parse(stdin) : {};
         /*  determine session id  */
         const sessionId = input.session_id ?? "";
+        /*  establish config context  */
+        const cfg = new Config("config", configSchema, this.log, parseScope(`session:${sessionId}`));
+        try {
+            cfg.read();
+        }
+        catch (_e) {
+            /*  best-effort: ignore failures  */
+        }
         /*  determine task id  */
         const taskId = process.env.ASE_TASK_ID ?? "default";
         try {
-            execaSync("ase", ["config", `--scope=session:${sessionId}`, "set", "task.id", taskId], { stdio: ["ignore", "ignore", "ignore"] });
+            cfg.set("agent.task", taskId);
+            cfg.write();
         }
         catch (_e) {
             /*  best-effort: ignore failures  */
         }
-        /*  provide session and task id to Claude Code shell commands  */
+        /*  determine project id  */
+        const cwd = input.cwd ?? process.cwd();
+        let projectDir = cwd;
+        try {
+            const result = execaSync("git", ["rev-parse", "--show-toplevel"], {
+                stderr: "ignore", cwd
+            });
+            if (result.stdout.trim() !== "")
+                projectDir = result.stdout.trim();
+        }
+        catch {
+            /*  not inside a Git working tree  */
+        }
+        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;
+        /*  provide ASE information to Claude Code shell commands  */
         const envFile = process.env.CLAUDE_ENV_FILE ?? "";
         if (envFile !== "") {
-            const script = `export ASE_VERSION="${version}"\n` +
-                `export ASE_SESSION_ID="${sessionId}"\n` +
-                `export ASE_TASK_ID="${taskId}"\n`;
+            const script = `export ASE_VERSION="${versionCurrentPlugin}"\n` +
+                `export ASE_USER_ID="${userId}"\n` +
+                `export ASE_PROJECT_ID="${projectId}"\n` +
+                `export ASE_TASK_ID="${taskId}"\n` +
+                `export ASE_SESSION_ID="${sessionId}"\n`;
             fs.appendFileSync(envFile, script, "utf8");
         }
         /*  prepend ASE information to constitution markdown  */
         md =
-            `<ase-version>${version}</ase-version>\n` +
+            `<ase-version>${versionCurrentPlugin}</ase-version>\n` +
+                `<ase-version-hint>${versionHint}</ase-version-hint>\n` +
+                `<ase-persona-style>${persona}</ase-persona-style>\n` +
+                `<ase-user-id>${userId}</ase-user-id>\n` +
+                `<ase-project-id>${projectId}</ase-project-id>\n` +
                 `<ase-task-id>${taskId}</ase-task-id>\n` +
                 `<ase-session-id>${sessionId}</ase-session-id>\n` +
                 "\n" + md;
+        /*  expand all @<file> references manually  */
+        md = this.expandReferences(md, path.dirname(fileMd));
+        fs.writeFileSync("/tmp/xxx", md, "utf8");
         /*  inject markdown into session context  */
         process.stdout.write(JSON.stringify({
             "hookSpecificOutput": {
@@ -110,8 +187,8 @@ export default class HookCommand {
         hookCmd
             .command("session-start")
             .description("handle Claude Code SessionStart hook event")
-            .action(() => {
-            process.exit(this.doSessionStart());
+            .action(async () => {
+            process.exit(await this.doSessionStart());
         });
         /*  register CLI sub-command "ase hook pre-tool-use"  */
         hookCmd

package/dst/ase-plan.js

@@ -0,0 +1,143 @@
+/*
+**  Agentic Software Engineering (ASE)
+**  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under GPL 3.0 <https://spdx.org/licenses/GPL-3.0-only>
+*/
+import path from "node:path";
+import os from "node:os";
+import fs from "node:fs";
+/*  validate the plan id to keep it safe as a filename component  */
+const validateId = (id) => {
+    if (typeof id !== "string" || id.length === 0)
+        throw new Error("plan: id must be a non-empty string");
+    if (!/^[A-Za-z0-9-]+$/.test(id))
+        throw new Error("plan: id must match [A-Za-z0-9-]+");
+};
+/*  resolve the on-disk path for a given plan id  */
+const planPath = (id) => {
+    validateId(id);
+    return path.join(os.homedir(), ".ase", "plan", `${id}.md`);
+};
+/*  load a plan; returns empty string if no plan exists  */
+export const planLoad = (id) => {
+    const file = planPath(id);
+    if (!fs.existsSync(file))
+        return "";
+    return fs.readFileSync(file, "utf8");
+};
+/*  save a plan as UTF-8 text under the given id  */
+export const planSave = (id, text) => {
+    if (typeof text !== "string")
+        throw new Error("plan: text must be a string");
+    const file = planPath(id);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, text, "utf8");
+};
+/*  delete a plan by id; returns true if a plan existed and was removed  */
+export const planDelete = (id) => {
+    const file = planPath(id);
+    if (!fs.existsSync(file))
+        return false;
+    fs.rmSync(file);
+    return true;
+};
+/*  purge plans whose modification time is older than the given cutoff in
+    milliseconds; returns the list of removed plan ids  */
+export const planPurge = (maxAgeMs) => {
+    const dir = path.join(os.homedir(), ".ase", "plan");
+    if (!fs.existsSync(dir))
+        return [];
+    const cutoff = Date.now() - maxAgeMs;
+    const removed = [];
+    for (const entry of fs.readdirSync(dir)) {
+        if (!entry.endsWith(".md"))
+            continue;
+        const file = path.join(dir, entry);
+        const st = fs.statSync(file);
+        if (!st.isFile())
+            continue;
+        if (st.mtimeMs < cutoff) {
+            fs.rmSync(file);
+            removed.push(entry.slice(0, -3));
+        }
+    }
+    return removed;
+};
+/*  read all of stdin as a UTF-8 string  */
+const readStdin = () => {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        process.stdin.on("data", (chunk) => chunks.push(chunk));
+        process.stdin.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        process.stdin.on("error", (err) => reject(err));
+    });
+};
+/*  CLI command "ase plan"  */
+export default class PlanCommand {
+    log;
+    constructor(log) {
+        this.log = log;
+    }
+    /*  register commands  */
+    register(program) {
+        /*  register CLI top-level command "ase plan"  */
+        const plan = program
+            .command("plan")
+            .description("Manage persisted plans under ~/.ase/plan/<id>.md")
+            .action(() => {
+            plan.outputHelp();
+            process.exit(1);
+        });
+        /*  register CLI sub-command "ase plan load"  */
+        plan
+            .command("load")
+            .description("Load a plan by id and write it to stdout")
+            .argument("<id>", "Plan identifier")
+            .action((id) => {
+            const text = planLoad(id);
+            process.stdout.write(text);
+            process.exit(0);
+        });
+        /*  register CLI sub-command "ase plan save"  */
+        plan
+            .command("save")
+            .description("Save a plan by id, reading content from stdin")
+            .argument("<id>", "Plan identifier")
+            .action(async (id) => {
+            const text = await readStdin();
+            planSave(id, text);
+            this.log.write("info", `plan: saved "${id}"`);
+            process.exit(0);
+        });
+        /*  register CLI sub-command "ase plan delete"  */
+        plan
+            .command("delete")
+            .description("Delete a plan by id")
+            .argument("<id>", "Plan identifier")
+            .action((id) => {
+            const removed = planDelete(id);
+            if (removed)
+                this.log.write("info", `plan: removed "${id}"`);
+            else
+                this.log.write("info", `plan: no plan "${id}" to remove`);
+            process.exit(removed ? 0 : 1);
+        });
+        /*  register CLI sub-command "ase plan purge"  */
+        plan
+            .command("purge")
+            .description("Remove all plans with a modification time older than <days> (default: 31)")
+            .argument("[<days>]", "Maximum plan age in days", "31")
+            .action((days) => {
+            const n = Number.parseInt(days, 10);
+            if (!Number.isFinite(n) || n < 0)
+                throw new Error("plan: <days> must be a non-negative integer");
+            const removed = planPurge(n * 24 * 60 * 60 * 1000);
+            if (removed.length === 0)
+                this.log.write("info", "plan: no plans to purge");
+            else
+                for (const id of removed)
+                    this.log.write("info", `plan: purged "${id}"`);
+            process.exit(0);
+        });
+    }
+}

package/dst/ase-service.js

@@ -10,14 +10,15 @@ import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
 import Hapi from "@hapi/hapi";
 import axios from "axios";
-import { isMap } from "yaml";
+import { isMap, isScalar } from "yaml";
 import * as v from "valibot";
 import prettyMs from "pretty-ms";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { z } from "zod";
-import { Config, configSchema } from "./ase-config.js";
+import { Config, configSchema, parseScope } from "./ase-config.js";
 import { renderDiagram } from "./ase-diagram.js";
+import { taskLoad, taskSave, taskDelete, taskList } from "./ase-task.js";
 import pkg from "../package.json" with { type: "json" };
 const SERVE_ENV = "ASE_SERVICE_SERVE";
 const PORT_ENV = "ASE_SERVICE_PORT";
@@ -260,6 +261,198 @@ export default class ServiceCommand {
                     };
                 }
             });
+            mcp.registerTool("task_list", {
+                title: "ASE task list",
+                description: "List all persisted task `id`s. " +
+                    "Returns the ids as `text`, one per line, in lexicographic order; " +
+                    "returns an empty string if no tasks exist.",
+                inputSchema: {}
+            }, async () => {
+                try {
+                    const ids = taskList();
+                    return {
+                        content: [{ type: "text", text: ids.join("\n") }]
+                    };
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    return {
+                        isError: true,
+                        content: [{ type: "text", text: `task_list: ERROR: ${message}` }]
+                    };
+                }
+            });
+            mcp.registerTool("task_load", {
+                title: "ASE task load",
+                description: "Load a previously persisted task by `id`. " +
+                    "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, '-')")
+                }
+            }, async (args) => {
+                try {
+                    const text = taskLoad(args.id);
+                    return {
+                        content: [{ type: "text", text }]
+                    };
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    return {
+                        isError: true,
+                        content: [{ type: "text", text: `task_load: ERROR: ${message}` }]
+                    };
+                }
+            });
+            mcp.registerTool("task_save", {
+                title: "ASE task save",
+                description: "Persist a task as `text` under `id`. " +
+                    "Overwrites any existing task for the same `id`.",
+                inputSchema: {
+                    id: z.string()
+                        .describe("task identifier (allowed characters: A-Z, a-z, 0-9, '-')"),
+                    text: z.string()
+                        .describe("text content of the task")
+                }
+            }, async (args) => {
+                try {
+                    taskSave(args.id, args.text);
+                    return {
+                        content: [{ type: "text", text: `task_save: OK: saved task "${args.id}"` }]
+                    };
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    return {
+                        isError: true,
+                        content: [{ type: "text", text: `task_save: FAILED: ${message}` }]
+                    };
+                }
+            });
+            mcp.registerTool("task_delete", {
+                title: "ASE task delete",
+                description: "Delete a previously persisted task by `id`. " +
+                    "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, '-')")
+                }
+            }, async (args) => {
+                try {
+                    const removed = taskDelete(args.id);
+                    const msg = removed ?
+                        `task_delete: OK: removed task "${args.id}"` :
+                        `task_delete: WARNING: no task "${args.id}" to remove`;
+                    return {
+                        content: [{ type: "text", text: msg }]
+                    };
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    return {
+                        isError: true,
+                        content: [{ type: "text", text: `task_delete: ERROR: ${message}` }]
+                    };
+                }
+            });
+            mcp.registerTool("persona", {
+                title: "ASE persona style get/set",
+                description: "Get or set the active ASE agent persona `style`. " +
+                    "If `style` is provided, it sets the persona style, " +
+                    "otherwise it returns the current persona `style`. " +
+                    "If `session` is provided, the operation is scoped to that session, " +
+                    "otherwise it operates on the broadest scope (user/project cascade). " +
+                    "Allowed styles: \"writer\" (decorative, eloquent, explaining), " +
+                    "\"engineer\" (brief, factual, accurate), " +
+                    "\"telegrapher\" (very brief, factual, abbreviating), " +
+                    "\"caveman\" (ultra brief, rough, stuttering).",
+                inputSchema: {
+                    style: z.enum(["writer", "engineer", "telegrapher", "caveman"]).optional()
+                        .describe("persona style to set; if omitted, the current persona style is returned"),
+                    session: z.string().optional()
+                        .describe("session identifier (allowed characters: A-Z, a-z, 0-9, '-'); " +
+                        "if omitted, the operation is not scoped to a specific session")
+                }
+            }, async (args) => {
+                try {
+                    const scope = args.session !== undefined ?
+                        parseScope(`session:${args.session}`) :
+                        parseScope(undefined);
+                    const cfg = new Config("config", configSchema, this.log, scope);
+                    cfg.read();
+                    if (args.style !== undefined) {
+                        cfg.set("agent.persona", args.style);
+                        cfg.write();
+                        const where = args.session !== undefined ?
+                            ` for session "${args.session}"` : "";
+                        const msg = `persona: OK: set agent.persona to "${args.style}"${where}`;
+                        return {
+                            content: [{ type: "text", text: msg }]
+                        };
+                    }
+                    const val = cfg.get("agent.persona");
+                    if (val === undefined)
+                        return {
+                            content: [{ type: "text", text: "" }]
+                        };
+                    const text = String(isScalar(val) ? val.value : val);
+                    return {
+                        content: [{ type: "text", text }]
+                    };
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    return {
+                        isError: true,
+                        content: [{ type: "text", text: `persona: ERROR: ${message}` }]
+                    };
+                }
+            });
+            mcp.registerTool("task_id", {
+                title: "ASE task id get/set",
+                description: "Get or set the active ASE task `id` for a given `session`. " +
+                    "If `id` is provided, it set the task id in the given `session`, " +
+                    "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, '-'); " +
+                        "if omitted, the current task id is returned"),
+                    session: z.string()
+                        .describe("session identifier (allowed characters: A-Z, a-z, 0-9, '-')")
+                }
+            }, async (args) => {
+                try {
+                    const scope = parseScope(`session:${args.session}`);
+                    const cfg = new Config("config", configSchema, this.log, scope);
+                    cfg.read();
+                    if (args.id !== undefined) {
+                        cfg.set("agent.task", args.id);
+                        cfg.write();
+                        const msg = `task_id: OK: set agent.task to "${args.id}" ` +
+                            `for session "${args.session}"`;
+                        return {
+                            content: [{ type: "text", text: msg }]
+                        };
+                    }
+                    const val = cfg.get("agent.task");
+                    if (val === undefined)
+                        return {
+                            content: [{ type: "text", text: "" }]
+                        };
+                    const text = String(isScalar(val) ? val.value : val);
+                    return {
+                        content: [{ type: "text", text }]
+                    };
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    return {
+                        isError: true,
+                        content: [{ type: "text", text: `task_id: ERROR: ${message}` }]
+                    };
+                }
+            });
             return mcp;
         };
         /*  listen to HTTP/REST endpoints  */

package/dst/ase-setup.js

@@ -6,28 +6,47 @@
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { execa } from "execa";
-import pkg from "../package.json" with { type: "json" };
+import which from "which";
+import Version from "./ase-version.js";
 /*  CLI command "ase setup"  */
 export default class SetupCommand {
     log;
     constructor(log) {
         this.log = log;
     }
-    /*  run a sub-process with inherited stdio so users see live output  */
-    async run(cmd, args, cwd) {
-        this.log.write("info", `setup: running: $ ${cmd} ${args.join(" ")}` +
-            (cwd !== undefined ? ` (cwd: ${cwd})` : ""));
-        await execa(cmd, args, { stdio: "inherit", cwd });
+    /*  ensure a tool is available  */
+    async ensureTool(tool) {
+        return which(tool).catch(() => {
+            throw new Error(`mandatory tool "${tool}" not found in $PATH`);
+        });
     }
-    /*  capture stdout of a sub-process  */
-    async capture(cmd, args, cwd) {
-        this.log.write("info", `setup: running: $ ${cmd} ${args.join(" ")}` +
+    /*  run a sub-process, suppressing output on success and emitting it on failure  */
+    async run(cmd, args, opts = {}) {
+        const { cwd, quiet = false } = opts;
+        this.log.write("info", `setup: $ ${cmd} ${args.join(" ")}` +
             (cwd !== undefined ? ` (cwd: ${cwd})` : ""));
-        const r = await execa(cmd, args, { stdio: ["ignore", "pipe", "pipe"], cwd });
-        return r.stdout.trim();
+        if (quiet) {
+            await execa(cmd, args, { stdio: "ignore", cwd, reject: false });
+            return;
+        }
+        await execa(cmd, args, { stdio: "pipe", cwd }).catch((err) => {
+            const exitCode = typeof err?.exitCode === "number" ? err.exitCode : -1;
+            this.log.write("error", `setup: command failed: exit code: ${exitCode}`);
+            if (typeof err?.stdout === "string" && err.stdout.length > 0) {
+                this.log.write("error", "setup: command failed: stdout:");
+                process.stdout.write(err.stdout);
+            }
+            if (typeof err?.stderr === "string" && err.stderr.length > 0) {
+                this.log.write("error", "setup: command failed: stderr:");
+                process.stderr.write(err.stderr);
+            }
+            throw err;
+        });
     }
     /*  handler for "ase setup install"  */
     async doInstall(dev) {
+        await this.ensureTool("npm");
+        await this.ensureTool("claude");
         this.log.write("info", `setup: install${dev ? "[dev]" : ""}: ` +
             `installing ASE Claude Code plugin (origin: ${dev ? "local" : "remote"})`);
         const source = dev ? process.cwd() : "rse/ase";
@@ -37,12 +56,18 @@ export default class SetupCommand {
     }
     /*  handler for "ase setup update"  */
     async doUpdate(force, dev) {
+        await this.ensureTool("npm");
+        await this.ensureTool("claude");
+        /*  best-effort stop of background service  */
+        this.log.write("info", `setup: update${dev ? "[dev]" : ""}: ` +
+            "stopping potentially running ASE service");
+        await this.run("ase", ["service", "stop"], { quiet: true });
         if (dev) {
             /*  update ASE CLI Tool  */
             this.log.write("info", "setup: update[dev]: re-build ASE CLI tool (origin: local)");
             const tooldir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
-            await this.run("npm", ["install"], tooldir);
-            await this.run("npm", ["start", "build"], tooldir);
+            await this.run("npm", ["install"], { cwd: tooldir });
+            await this.run("npm", ["start", "build"], { cwd: tooldir });
             /*  in development mode the local plugin files are already current
                 but there is no version change in the plugin manifest,
                 so just re-install the plugin to let Claude Code update its copy  */
@@ -52,15 +77,8 @@ export default class SetupCommand {
         }
         else {
             /*  perform NPM version check  */
-            const current = pkg.version;
-            let latest = "";
-            try {
-                latest = await this.capture("npm", ["view", "@rse/ase", "version"]);
-            }
-            catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
-                this.log.write("warning", `setup: update: failed to query latest ASE version: ${message}`);
-            }
+            const current = Version.current();
+            const latest = await Version.latest();
             if (!force && latest !== "" && latest === current) {
                 this.log.write("info", `setup: update: ASE already at latest version ${current}`);
                 return 0;
@@ -77,6 +95,12 @@ export default class SetupCommand {
     }
     /*  handler for "ase setup uninstall"  */
     async doUninstall(dev) {
+        await this.ensureTool("npm");
+        await this.ensureTool("claude");
+        /*  best-effort stop of background service  */
+        this.log.write("info", `setup: uninstall${dev ? "[dev]" : ""}: ` +
+            "stopping potentially running ASE service");
+        await this.run("ase", ["service", "stop"], { quiet: true });
         /*  uninstall ASE Claude Code plugin  */
         this.log.write("info", `setup: uninstall${dev ? "[dev]" : ""}: ` +
             `uninstalling ASE Claude Code plugin (origin: ${dev ? "local" : "remote"})`);

package/dst/ase-task.js

@@ -0,0 +1,195 @@
+/*
+**  Agentic Software Engineering (ASE)
+**  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under GPL 3.0 <https://spdx.org/licenses/GPL-3.0-only>
+*/
+import path from "node:path";
+import os from "node:os";
+import fs from "node:fs";
+import { execaSync } from "execa";
+/*  validate the task id to keep it safe as a filename component  */
+const 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-]+");
+};
+/*  resolve the on-disk path for a given task id  */
+const taskPath = (id) => {
+    validateId(id);
+    return path.join(os.homedir(), ".ase", "task", id, "plan.md");
+};
+/*  load a task; returns empty string if no task exists  */
+export const taskLoad = (id) => {
+    const file = taskPath(id);
+    if (!fs.existsSync(file))
+        return "";
+    return fs.readFileSync(file, "utf8");
+};
+/*  save a task as UTF-8 text under the given id; the task's home
+    directory ~/.ase/task/<id>/ is owned by ASE and removed in full
+    by taskDelete, so callers must not place foreign files there  */
+export const taskSave = (id, text) => {
+    if (typeof text !== "string")
+        throw new Error("task: text must be a string");
+    const file = taskPath(id);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, text, "utf8");
+};
+/*  delete a task by id; removes the entire task home directory
+    ~/.ase/task/<id>/ (owned by ASE); returns true if a task existed  */
+export const taskDelete = (id) => {
+    const file = taskPath(id);
+    if (!fs.existsSync(file))
+        return false;
+    fs.rmSync(path.dirname(file), { recursive: true, force: true });
+    return true;
+};
+/*  list all persisted task ids in lexicographic order  */
+export const taskList = () => {
+    const dir = path.join(os.homedir(), ".ase", "task");
+    if (!fs.existsSync(dir))
+        return [];
+    const ids = [];
+    for (const entry of fs.readdirSync(dir)) {
+        if (!/^[A-Za-z0-9-]+$/.test(entry))
+            continue;
+        const file = path.join(dir, entry, "plan.md");
+        if (!fs.existsSync(file))
+            continue;
+        const st = fs.statSync(file);
+        if (!st.isFile())
+            continue;
+        ids.push(entry);
+    }
+    ids.sort();
+    return ids;
+};
+/*  purge tasks whose modification time is older than the given cutoff in
+    milliseconds; returns the list of removed task ids  */
+export const taskPurge = (maxAgeMs) => {
+    const dir = path.join(os.homedir(), ".ase", "task");
+    if (!fs.existsSync(dir))
+        return [];
+    const cutoff = Date.now() - maxAgeMs;
+    const removed = [];
+    for (const entry of fs.readdirSync(dir)) {
+        if (!/^[A-Za-z0-9-]+$/.test(entry))
+            continue;
+        const sub = path.join(dir, entry);
+        const file = path.join(sub, "plan.md");
+        if (!fs.existsSync(file))
+            continue;
+        const st = fs.statSync(file);
+        if (!st.isFile())
+            continue;
+        if (st.mtimeMs < cutoff) {
+            fs.rmSync(sub, { recursive: true, force: true });
+            removed.push(entry);
+        }
+    }
+    return removed;
+};
+/*  read all of stdin as a UTF-8 string  */
+const readStdin = () => {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        process.stdin.on("data", (chunk) => chunks.push(chunk));
+        process.stdin.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+        process.stdin.on("error", (err) => reject(err));
+    });
+};
+/*  CLI command "ase task"  */
+export default class TaskCommand {
+    log;
+    constructor(log) {
+        this.log = log;
+    }
+    /*  register commands  */
+    register(program) {
+        /*  register CLI top-level command "ase task"  */
+        const task = program
+            .command("task")
+            .description("Manage persisted tasks under ~/.ase/task/<id>/plan.md")
+            .action(() => {
+            task.outputHelp();
+            process.exit(1);
+        });
+        /*  register CLI sub-command "ase task list"  */
+        task
+            .command("list")
+            .description("List all persisted task ids, one per line")
+            .action(() => {
+            const ids = taskList();
+            for (const id of ids)
+                process.stdout.write(`${id}\n`);
+            process.exit(0);
+        });
+        /*  register CLI sub-command "ase task load"  */
+        task
+            .command("load")
+            .description("Load a task by id and write it to stdout")
+            .argument("<id>", "Task identifier")
+            .action((id) => {
+            const text = taskLoad(id);
+            process.stdout.write(text);
+            process.exit(0);
+        });
+        /*  register CLI sub-command "ase task edit"  */
+        task
+            .command("edit")
+            .description("Edit a task by id with $EDITOR")
+            .argument("<id>", "Task identifier")
+            .action((id) => {
+            const file = taskPath(id);
+            const editor = process.env.EDITOR ?? process.env.VISUAL ?? "vi";
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            if (!fs.existsSync(file))
+                fs.writeFileSync(file, "", "utf8");
+            execaSync(editor, [file], { stdio: "inherit" });
+            this.log.write("info", `task: edited "${id}"`);
+            process.exit(0);
+        });
+        /*  register CLI sub-command "ase task save"  */
+        task
+            .command("save")
+            .description("Save a task by id, reading content from stdin")
+            .argument("<id>", "Task identifier")
+            .action(async (id) => {
+            const text = await readStdin();
+            taskSave(id, text);
+            this.log.write("info", `task: saved "${id}"`);
+            process.exit(0);
+        });
+        /*  register CLI sub-command "ase task delete"  */
+        task
+            .command("delete")
+            .description("Delete a task by id")
+            .argument("<id>", "Task identifier")
+            .action((id) => {
+            const removed = taskDelete(id);
+            if (removed)
+                this.log.write("info", `task: removed "${id}"`);
+            else
+                this.log.write("info", `task: no task "${id}" to remove`);
+            process.exit(removed ? 0 : 1);
+        });
+        /*  register CLI sub-command "ase task purge"  */
+        task
+            .command("purge")
+            .description("Remove all tasks with a modification time older than <days> (default: 31)")
+            .argument("[<days>]", "Maximum task age in days", "31")
+            .action((days) => {
+            const n = Number.parseInt(days, 10);
+            if (!Number.isFinite(n) || n < 0)
+                throw new Error("task: <days> must be a non-negative integer");
+            const removed = taskPurge(n * 24 * 60 * 60 * 1000);
+            if (removed.length === 0)
+                this.log.write("info", "task: no tasks to purge");
+            else
+                for (const id of removed)
+                    this.log.write("info", `task: purged "${id}"`);
+            process.exit(0);
+        });
+    }
+}

package/dst/ase-version.js

@@ -0,0 +1,27 @@
+/*
+**  Agentic Software Engineering (ASE)
+**  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under GPL 3.0 <https://spdx.org/licenses/GPL-3.0-only>
+*/
+import { execa } from "execa";
+import pkg from "../package.json" with { type: "json" };
+/*  determination of current and available ASE versions  */
+export default class Version {
+    /*  return current ASE version  */
+    static current() {
+        return pkg.version;
+    }
+    /*  return latest ASE version available on the NPM registry  */
+    static async latest() {
+        let latest = "";
+        try {
+            const r = await execa("npm", ["view", "@rse/ase", "version"], { stdio: ["ignore", "pipe", "pipe"] });
+            latest = r.stdout.trim();
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            throw new Error(`failed to query latest ASE version: ${message}`, { cause: err });
+        }
+        return latest;
+    }
+}

package/dst/ase.js

@@ -12,6 +12,7 @@ import MCPCommand from "./ase-mcp.js";
 import HookCommand from "./ase-hook.js";
 import DiagramCommand from "./ase-diagram.js";
 import SetupCommand from "./ase-setup.js";
+import TaskCommand from "./ase-task.js";
 import pkg from "../package.json" with { type: "json" };
 /*  globally initialize logger  */
 const log = new Log("ase", "warning", "-");
@@ -46,6 +47,7 @@ const main = async () => {
     new HookCommand(log).register(program);
     new DiagramCommand(log).register(program);
     new SetupCommand(log).register(program);
+    new TaskCommand(log).register(program);
     /*  parse program arguments  */
     await program.parseAsync(process.argv);
     /*  gracefully terminate  */

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.0.16",
+    "version":                              "0.0.18",
     "license":                              "GPL-3.0-only",
     "author": {
         "name":                             "Dr. Ralf S. Engelschall",
@@ -32,7 +32,8 @@
         "shx":                              "0.4.0",
 
         "@types/node":                      "25.6.0",
-        "@types/luxon":                     "3.7.1"
+        "@types/luxon":                     "3.7.1",
+        "@types/which":                     "3.0.4"
     },
     "dependencies": {
         "commander":                        "14.0.3",
@@ -48,7 +49,8 @@
         "pretty-ms":                        "9.3.0",
         "luxon":                            "3.7.2",
         "@modelcontextprotocol/sdk":        "1.29.0",
-        "zod":                              "4.4.2"
+        "zod":                              "4.4.2",
+        "which":                            "6.0.1"
     },
     "engines": {
         "npm":                              ">=10.0.0",