@rse/ase 0.9.5 → 0.9.6

package/dst/ase-artifact.js

@@ -0,0 +1,331 @@
+/*
+**  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 fs from "node:fs";
+import picomatch from "picomatch";
+import { isScalar } from "yaml";
+import { z } from "zod";
+import { Config, configSchema } from "./ase-config.js";
+import { Task } from "./ase-task.js";
+/*  the recognized artifact kinds, in descending precedence order;
+    "othr" is the implicit catch-all and is always resolved last  */
+export const artifactKinds = ["spec", "arch", "code", "docs", "infr", "othr"];
+/*  the five configured kinds (i.e. all kinds except the implicit "othr")  */
+const configuredKinds = ["spec", "arch", "code", "docs", "infr"];
+/*  reusable functionality: resolve artifact kinds to project-relative
+    file lists, driven by the "project.artifact.<kind>" configuration  */
+export class Artifact {
+    /*  validate a requested kind against the known set  */
+    static validateKind(kind) {
+        if (!artifactKinds.includes(kind))
+            throw new Error(`artifact: unknown kind "${kind}" ` +
+                `(expected one of: ${artifactKinds.join(", ")})`);
+        return kind;
+    }
+    /*  translate a single ".gitignore" line into a picomatch-backed rule,
+        honoring the anchored-vs-floating, directory-only, and negation
+        semantics of ".gitignore" patterns  */
+    static compileIgnoreRule(line) {
+        let pattern = line.trim();
+        if (pattern === "" || pattern.startsWith("#"))
+            return null;
+        let negated = false;
+        if (pattern.startsWith("!")) {
+            negated = true;
+            pattern = pattern.slice(1);
+        }
+        let dirOnly = false;
+        if (pattern.endsWith("/")) {
+            dirOnly = true;
+            pattern = pattern.slice(0, -1);
+        }
+        const anchored = pattern.includes("/");
+        if (pattern.startsWith("/"))
+            pattern = pattern.slice(1);
+        const glob = anchored ? pattern : `**/${pattern}`;
+        const isMatch = picomatch(glob, { dot: true });
+        return { matcher: (p) => isMatch(p), negated, dirOnly };
+    }
+    /*  load the ".gitignore" rules located directly in a directory  */
+    static loadIgnoreRules(dir) {
+        const file = path.join(dir, ".gitignore");
+        if (!fs.existsSync(file))
+            return [];
+        const rules = [];
+        for (const line of fs.readFileSync(file, "utf8").split(/\r?\n/)) {
+            const rule = Artifact.compileIgnoreRule(line);
+            if (rule !== null)
+                rules.push(rule);
+        }
+        return rules;
+    }
+    /*  decide whether a project-relative path is ignored by the given
+        ordered ".gitignore" rule set (last matching rule wins)  */
+    static isIgnored(rel, isDir, rules) {
+        let ignored = false;
+        for (const rule of rules) {
+            if (rule.dirOnly && !isDir)
+                continue;
+            if (rule.matcher(rel))
+                ignored = !rule.negated;
+        }
+        return ignored;
+    }
+    /*  build the file universe by walking the project tree from the
+        project root, honoring ".gitignore" rules (root plus nested) and
+        always pruning ".git". Yields POSIX project-relative, sorted,
+        de-duplicated file paths  */
+    static universe() {
+        const root = Task.projectRoot();
+        const files = new Set();
+        const walk = (dir, relDir, inherited) => {
+            const rules = [...inherited, ...Artifact.loadIgnoreRules(dir)];
+            for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+                if (entry.name === ".git")
+                    continue;
+                const rel = relDir === "" ? entry.name : `${relDir}/${entry.name}`;
+                const isDir = entry.isDirectory();
+                if (Artifact.isIgnored(rel, isDir, rules))
+                    continue;
+                if (isDir)
+                    walk(path.join(dir, entry.name), rel, rules);
+                else if (entry.isFile())
+                    files.add(rel);
+            }
+        };
+        walk(root, "", []);
+        return [...files].sort((a, b) => a.localeCompare(b));
+    }
+    /*  raw-resolve a single kind's configuration spec against the file
+        universe via "seed-then-mutate" miniglob semantics: the spec is a
+        whitespace-separated list of tokens.  */
+    static rawResolve(spec, all) {
+        const tokens = spec.split(/\s+/).filter((t) => t !== "");
+        if (tokens.length === 0)
+            return new Set();
+        const result = new Set(tokens[0].startsWith("!") ? all : []);
+        for (const token of tokens) {
+            const negated = token.startsWith("!");
+            const glob = negated ? token.slice(1) : token;
+            if (glob === "")
+                continue;
+            const isMatch = picomatch(glob, { dot: true });
+            for (const file of all) {
+                if (!isMatch(file))
+                    continue;
+                if (negated)
+                    result.delete(file);
+                else
+                    result.add(file);
+            }
+        }
+        return result;
+    }
+    /*  read a single scalar configuration value as a plain string  */
+    static configString(cfg, key) {
+        const val = cfg.get(key);
+        if (val === undefined)
+            return "";
+        return String(isScalar(val) ? val.value : val);
+    }
+    /*  read the configured "basedir" anchor and "files" miniglob spec
+        for a single kind; "basedir" is project-root-relative (POSIX,
+        "" ≡ project root) and "files" resolves relative to "basedir"  */
+    static spec(log, kind) {
+        const cfg = new Config("config", configSchema, log);
+        cfg.read();
+        const basedir = Artifact.configString(cfg, `project.artifact.${kind}.basedir`)
+            .replace(/\\/g, "/").replace(/^\/+|\/+$/g, "")
+            .replace(/^\.$/, "");
+        const files = Artifact.configString(cfg, `project.artifact.${kind}.files`);
+        return { basedir, files };
+    }
+    /*  raw-resolve a single kind's "basedir"/"files" spec against the
+        file universe: the "files" miniglob resolves relative to
+        "basedir", then matches are re-prefixed with "basedir" to stay
+        project-relative  */
+    static resolveKind(basedir, files, all) {
+        if (basedir === "")
+            return Artifact.rawResolve(files, all);
+        const prefix = `${basedir}/`;
+        const local = all
+            .filter((file) => file.startsWith(prefix))
+            .map((file) => file.slice(prefix.length));
+        const result = new Set();
+        for (const file of Artifact.rawResolve(files, local))
+            result.add(`${prefix}${file}`);
+        return result;
+    }
+    /*  resolve the requested kinds to project-relative file lists  */
+    static list(log, kinds) {
+        const all = Artifact.universe();
+        /*  raw-resolve all five configured kinds  */
+        const raw = new Map();
+        for (const kind of configuredKinds) {
+            const { basedir, files } = Artifact.spec(log, kind);
+            raw.set(kind, Artifact.resolveKind(basedir, files, all));
+        }
+        /*  partition the universe by descending precedence  */
+        const claimed = new Set();
+        const part = new Map();
+        for (const kind of configuredKinds) {
+            const own = [];
+            for (const file of raw.get(kind).size > 0 ? all : []) {
+                if (raw.get(kind).has(file) && !claimed.has(file)) {
+                    own.push(file);
+                    claimed.add(file);
+                }
+            }
+            part.set(kind, own);
+        }
+        part.set("othr", all.filter((file) => !claimed.has(file)));
+        /*  project onto the requested kinds  */
+        return kinds.map((kind) => ({
+            kind,
+            files: part.get(kind) ?? []
+        }));
+    }
+    /*  resolve a base-relative "filename" within a kind's "basedir" to a
+        project-root-relative POSIX path; the implicit "othr" catch-all
+        has no configured "basedir" and is therefore rejected  */
+    static name(log, kind, filename) {
+        if (kind === "othr")
+            throw new Error("artifact: kind \"othr\" has no configured basedir");
+        const file = filename.replace(/\\/g, "/").replace(/^\/+/, "");
+        if (file === "")
+            throw new Error("artifact: filename must not be empty");
+        const { basedir } = Artifact.spec(log, kind);
+        return basedir === "" ? file : `${basedir}/${file}`;
+    }
+}
+/*  CLI command "ase artifact"  */
+export default class ArtifactCommand {
+    log;
+    constructor(log) {
+        this.log = log;
+    }
+    /*  register commands  */
+    register(program) {
+        /*  register CLI top-level command "ase artifact"  */
+        const artifact = program
+            .command("artifact")
+            .description("Resolve project artifact kinds to project-relative file lists")
+            .action(() => {
+            artifact.outputHelp();
+            process.exit(1);
+        });
+        /*  register CLI sub-command "ase artifact list"  */
+        artifact
+            .command("list")
+            .description("Resolve one or more artifact kinds to project-relative file paths")
+            .option("--kind <kinds>", "comma-separated list of artifact kinds " +
+            `(${artifactKinds.join("|")})`, artifactKinds.join(","))
+            .action((opts) => {
+            const kinds = opts.kind.split(",").map((k) => Artifact.validateKind(k.trim()));
+            const result = Artifact.list(this.log, kinds);
+            const single = result.length === 1;
+            for (const { kind, files } of result) {
+                if (!single)
+                    process.stdout.write(`# ${kind}:\n`);
+                for (const file of files)
+                    process.stdout.write(`- ${file}\n`);
+            }
+            process.exit(0);
+        });
+        /*  register CLI sub-command "ase artifact name"  */
+        artifact
+            .command("name")
+            .description("Resolve a base-relative filename within an artifact kind to a project-relative path")
+            .argument("<filename>", "base-relative filename within the kind's basedir")
+            .option("--kind <kind>", "artifact kind " +
+            `(${configuredKinds.join("|")})`, "code")
+            .action((filename, opts) => {
+            const kind = Artifact.validateKind(opts.kind.trim());
+            process.stdout.write(`${Artifact.name(this.log, kind, filename)}\n`);
+            process.exit(0);
+        });
+    }
+}
+/*  MCP registration entry point for artifact tools  */
+export class ArtifactMCP {
+    log;
+    constructor(log) {
+        this.log = log;
+    }
+    /*  register MCP tools  */
+    register(mcp) {
+        mcp.registerTool("ase_artifact_list", {
+            title: "ASE artifact list",
+            description: "Resolve one or more artifact `kind`s to project-relative file lists. " +
+                "Recognized kinds are `spec`, `arch`, `code`, `docs`, `infr`, and `othr`. " +
+                "Returns an `artifacts` array of `{ kind, files }` objects. " +
+                "If `kind` is omitted or empty, all kinds are resolved.",
+            inputSchema: {
+                kind: z.array(z.string()).optional()
+                    .describe("list of artifact kinds (`spec`, `arch`, `code`, `docs`, `infr`, " +
+                    "`othr`); if omitted or empty, all kinds are resolved")
+            },
+            outputSchema: {
+                artifacts: z.array(z.object({
+                    kind: z.string().describe("artifact kind"),
+                    files: z.array(z.string()).describe("project-relative file paths for the kind")
+                })).describe("resolved artifacts, one entry per requested kind")
+            }
+        }, async (args) => {
+            try {
+                const requested = args.kind !== undefined && args.kind.length > 0 ?
+                    args.kind : [...artifactKinds];
+                const kinds = requested.map((k) => Artifact.validateKind(k));
+                const result = { artifacts: Artifact.list(this.log, kinds) };
+                return {
+                    structuredContent: result,
+                    content: [{ type: "text", text: JSON.stringify(result) }]
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `ERROR: ${message}` }]
+                };
+            }
+        });
+        mcp.registerTool("ase_artifact_name", {
+            title: "ASE artifact name",
+            description: "Resolve a base-relative `filename` within an artifact `kind` to a project-relative path " +
+                "by prefixing it with the kind's configured `basedir`. " +
+                "Recognized kinds are `spec`, `arch`, `code`, `docs`, and `infr` " +
+                "(the implicit `othr` catch-all has no basedir and is rejected). " +
+                "If `kind` is omitted, it defaults to `code`. " +
+                "Returns the resolved path as `name`.",
+            inputSchema: {
+                kind: z.string().optional()
+                    .describe("artifact kind (`spec`, `arch`, `code`, `docs`, `infr`); defaults to `code`"),
+                filename: z.string()
+                    .describe("base-relative filename within the kind's basedir")
+            },
+            outputSchema: {
+                name: z.string().describe("project-relative file path")
+            }
+        }, async (args) => {
+            try {
+                const kind = Artifact.validateKind(args.kind ?? "code");
+                const result = { name: Artifact.name(this.log, kind, args.filename) };
+                return {
+                    structuredContent: result,
+                    content: [{ type: "text", text: JSON.stringify(result) }]
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `ERROR: ${message}` }]
+                };
+            }
+        });
+    }
+}

package/dst/ase-config.js

@@ -25,29 +25,41 @@ export const agentClassification = {
 /*  classification presets  */
 export const projectClassificationPresets = {
     vibe: {
+        "agent.persona": "writer",
         "project.id": "example",
         "project.name": "Example Project",
-        "project.boxing": "black",
-        "agent.persona": "writer"
+        "project.boxing": "black"
     },
     pro: {
+        "agent.persona": "engineer",
         "project.id": "example",
         "project.name": "Example Project",
-        "project.boxing": "white",
-        "agent.persona": "engineer"
+        "project.boxing": "white"
     },
     default: {
+        "agent.task": "default",
+        "agent.persona": "engineer",
         "project.id": "example",
         "project.name": "Example Project",
         "project.boxing": "white",
-        "agent.persona": "engineer",
-        "agent.task": "default"
+        "project.artifact.task.basedir": ".ase/task",
+        "project.artifact.task.files": "*.md",
+        "project.artifact.spec.basedir": "doc/spec",
+        "project.artifact.spec.files": "*.{md,txt}",
+        "project.artifact.arch.basedir": "doc/arch",
+        "project.artifact.arch.files": "*.{md,txt}",
+        "project.artifact.code.basedir": "src",
+        "project.artifact.code.files": "** !**/etc/** !**/{.gitignore,.npmignore,package.json}",
+        "project.artifact.docs.basedir": "doc",
+        "project.artifact.docs.files": "** **/{README,LICENSE,CHANGELOG}.{md,txt} !{spec,arch}/**",
+        "project.artifact.infr.basedir": "",
+        "project.artifact.infr.files": "**/{.github,.claude*,etc}/** **/{AGENTS.md,{package,tsconfig*}.json,.{git,npm}ignore}"
     },
     industry: {
+        "agent.persona": "engineer",
         "project.id": "example",
         "project.name": "Example Project",
-        "project.boxing": "grey",
-        "agent.persona": "engineer"
+        "project.boxing": "grey"
     }
 };
 /*  hard-coded map: which scope kinds each variable may be SET on
@@ -55,7 +67,19 @@ export const projectClassificationPresets = {
     keys absent from this map default to all non-"default" scope kinds  */
 export const configWritableScopes = {
     "agent.task": ["session"],
-    "agent.skill": ["session"]
+    "agent.skill": ["session"],
+    "project.artifact.task.basedir": ["user", "project"],
+    "project.artifact.task.files": ["user", "project"],
+    "project.artifact.spec.basedir": ["user", "project"],
+    "project.artifact.spec.files": ["user", "project"],
+    "project.artifact.arch.basedir": ["user", "project"],
+    "project.artifact.arch.files": ["user", "project"],
+    "project.artifact.code.basedir": ["user", "project"],
+    "project.artifact.code.files": ["user", "project"],
+    "project.artifact.docs.basedir": ["user", "project"],
+    "project.artifact.docs.files": ["user", "project"],
+    "project.artifact.infr.basedir": ["user", "project"],
+    "project.artifact.infr.files": ["user", "project"]
 };
 /*  default set of scope kinds writable for any unrestricted key  */
 const configWritableScopesDefault = ["user", "project", "task", "session"];
@@ -130,7 +154,15 @@ 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))),
-        boxing: v.optional(v.picklist(projectClassification.boxing))
+        boxing: v.optional(v.picklist(projectClassification.boxing)),
+        artifact: v.optional(v.strictObject({
+            spec: v.optional(v.strictObject({ basedir: v.optional(v.string()), files: v.optional(v.string()) })),
+            arch: v.optional(v.strictObject({ basedir: v.optional(v.string()), files: v.optional(v.string()) })),
+            code: v.optional(v.strictObject({ basedir: v.optional(v.string()), files: v.optional(v.string()) })),
+            docs: v.optional(v.strictObject({ basedir: v.optional(v.string()), files: v.optional(v.string()) })),
+            infr: v.optional(v.strictObject({ basedir: v.optional(v.string()), files: v.optional(v.string()) })),
+            task: v.optional(v.strictObject({ basedir: v.optional(v.string()), files: v.optional(v.string()) }))
+        }))
     })),
     agent: v.optional(v.strictObject({
         persona: v.optional(v.picklist(agentClassification.persona)),
@@ -614,6 +646,20 @@ export default class ConfigCommand {
                 cfg.write();
             });
         });
+        /*  register CLI sub-command "ase config delete"  */
+        configCmd
+            .command("delete")
+            .description("delete the value at a dotted configuration key")
+            .argument("<key>", "configuration key (dotted path)")
+            .action((key, _opts, cmd) => {
+            const scope = parseScope(cmd.optsWithGlobals().scope);
+            const cfg = new Config("config", configSchema, this.log, scope);
+            cfg.lock(() => {
+                cfg.read();
+                cfg.delete(key);
+                cfg.write();
+            });
+        });
     }
 }
 /*  MCP registration entry point for layered YAML configuration access  */

package/dst/ase-service.js

@@ -18,6 +18,7 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
 import { Config, configSchema, ConfigMCP } from "./ase-config.js";
 import { DiagramMCP } from "./ase-diagram.js";
 import { TaskMCP } from "./ase-task.js";
+import { ArtifactMCP } from "./ase-artifact.js";
 import { KVMCP } from "./ase-kv.js";
 import PersonaMCP from "./ase-persona.js";
 import { TimestampMCP } from "./ase-timestamp.js";
@@ -236,6 +237,7 @@ export default class ServiceCommand {
             new ServiceMCP({ projectId: ctx.projectId, port: ctx.port, startTime }).register(mcp);
             new DiagramMCP().register(mcp);
             new TaskMCP(this.log).register(mcp);
+            new ArtifactMCP(this.log).register(mcp);
             new KVMCP().register(mcp);
             new PersonaMCP(this.log).register(mcp);
             new TimestampMCP().register(mcp);

package/dst/ase-task.js

@@ -7,11 +7,13 @@ import path from "node:path";
 import fs from "node:fs";
 import { execaSync } from "execa";
 import { DateTime } from "luxon";
+import picomatch from "picomatch";
 import { isScalar } from "yaml";
 import { z } from "zod";
 import { Config, configSchema, parseScope } from "./ase-config.js";
 /*  reusable functionality: persisted task plans under
-    <project>/.ase/task/<id>/plan.md  */
+    <project>/<basedir>/TASK-<id>.md (driven by the
+    "project.artifact.task.{basedir,files}" configuration)  */
 export class Task {
     /*  validate the task id to keep it safe as a filename component  */
     static validateId(id) {
@@ -34,100 +36,173 @@ export class Task {
         }
         return process.cwd();
     }
+    /*  read the configured "basedir" anchor and "files" miniglob spec for
+        task storage; "basedir" is project-root-relative (POSIX, defaults
+        to ".ase/task") and "files" constrains the task filenames
+        (defaults to "*.md")  */
+    static spec(log) {
+        const cfg = new Config("config", configSchema, log);
+        cfg.read();
+        const read = (key) => {
+            const val = cfg.get(key);
+            if (val === undefined)
+                return "";
+            return String(isScalar(val) ? val.value : val);
+        };
+        const basedir = (read("project.artifact.task.basedir") || ".ase/task")
+            .replace(/\\/g, "/").replace(/^\/+|\/+$/g, "");
+        const files = read("project.artifact.task.files") || "*.md";
+        return { basedir, files };
+    }
     /*  resolve the on-disk base directory for task storage  */
-    static baseDir() {
-        return path.join(Task.projectRoot(), ".ase", "task");
+    static baseDir(log) {
+        return path.join(Task.projectRoot(), Task.spec(log).basedir);
     }
-    /*  resolve the on-disk path for a given task id  */
-    static path(id) {
+    /*  resolve the on-disk path for a given task id; as a side effect,
+        eagerly migrate any legacy <basedir>/<id>/plan.md files to the
+        current <basedir>/TASK-<id>.md layout on first access (guarded by
+        a cheap check, so it is a no-op once the store is migrated)  */
+    static path(log, id) {
         Task.validateId(id);
-        return path.join(Task.baseDir(), id, "plan.md");
+        if (Task.needsMigration(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  */
+    static migrateAll(log) {
+        const dir = Task.baseDir(log);
+        if (!fs.existsSync(dir))
+            return [];
+        const migrated = [];
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (!entry.isDirectory() || !/^[A-Za-z0-9-]+$/.test(entry.name))
+                continue;
+            const id = entry.name;
+            const oldFile = path.join(dir, id, "plan.md");
+            const newFile = path.join(dir, `TASK-${id}.md`);
+            if (!fs.existsSync(oldFile))
+                continue;
+            if (fs.existsSync(newFile)) {
+                log.write("warning", `task: not migrating "${id}": target "TASK-${id}.md" already exists`);
+                continue;
+            }
+            fs.renameSync(oldFile, newFile);
+            fs.rmSync(path.join(dir, id), { recursive: true, force: true });
+            migrated.push(id);
+        }
+        migrated.sort((a, b) => a.localeCompare(b));
+        return migrated;
     }
     /*  load a task; returns empty string if no task exists  */
-    static load(id) {
-        const file = Task.path(id);
+    static load(log, id) {
+        const file = Task.path(log, 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 <project>/.ase/task/<id>/ is owned by ASE and removed
-        in full by Task.delete, so callers must not place foreign files there  */
-    static save(id, text) {
+    /*  save a task as UTF-8 text under the given id into the
+        <project>/<basedir>/TASK-<id>.md file  */
+    static save(log, id, text) {
         if (typeof text !== "string")
             throw new Error("task: text must be a string");
-        const file = Task.path(id);
+        const file = Task.path(log, id);
         fs.mkdirSync(path.dirname(file), { recursive: true });
         fs.writeFileSync(file, text, "utf8");
     }
-    /*  delete a task by id; removes the entire task home directory
-        <project>/.ase/task/<id>/ (owned by ASE); returns true if a task existed  */
-    static delete(id) {
-        const file = Task.path(id);
+    /*  delete a task by id; removes the single
+        <project>/<basedir>/TASK-<id>.md file; returns true if a task existed  */
+    static delete(log, id) {
+        const file = Task.path(log, id);
         if (!fs.existsSync(file))
             return false;
-        fs.rmSync(path.dirname(file), { recursive: true, force: true });
+        fs.rmSync(file, { force: true });
         return true;
     }
-    /*  rename a task by moving the entire task home directory
-        <project>/.ase/task/<oldId>/ to <project>/.ase/task/<newId>/;
-        returns true on success, false if the source task does not exist;
-        throws if the target id already exists  */
-    static rename(oldId, newId) {
-        const oldDir = path.dirname(Task.path(oldId));
-        const newDir = path.dirname(Task.path(newId));
-        if (!fs.existsSync(oldDir))
+    /*  rename a task by moving its <project>/<basedir>/TASK-<oldId>.md file
+        to <project>/<basedir>/TASK-<newId>.md; the embedded
+        "# ✪ TASK <id>:" heading inside the plan content is rewritten to
+        the new id; returns true on success, false if the source task does
+        not exist; throws if the target id already exists  */
+    static rename(log, oldId, newId) {
+        const oldFile = Task.path(log, oldId);
+        const newFile = Task.path(log, newId);
+        if (!fs.existsSync(oldFile))
             return false;
-        if (fs.existsSync(newDir))
+        if (fs.existsSync(newFile))
             throw new Error(`task: target id "${newId}" already exists`);
-        fs.mkdirSync(path.dirname(newDir), { recursive: true });
-        fs.renameSync(oldDir, newDir);
+        const text = fs.readFileSync(oldFile, "utf8");
+        const updated = text.replace(/(^#\s+(?:✪\s+)?TASK\s+)[A-Za-z0-9-]+(\s*:)/m, `$1${newId}$2`);
+        fs.mkdirSync(path.dirname(newFile), { recursive: true });
+        fs.writeFileSync(newFile, updated, "utf8");
+        fs.rmSync(oldFile, { force: true });
         return true;
     }
     /*  list all persisted tasks in lexicographic id order; if verbose is true,
-        each entry's `mtime` is set to the `plan.md` modification time formatted
-        as "YYYY-MM-DD HH:MM", otherwise it is left undefined  */
-    static list(verbose = false) {
-        const dir = Task.baseDir();
+        each entry's `mtime` is set to the task file's modification time
+        formatted as "YYYY-MM-DD HH:MM", otherwise it is left undefined  */
+    static list(log, verbose = false) {
+        if (Task.needsMigration(log))
+            Task.migrateAll(log);
+        const { basedir, files } = Task.spec(log);
+        const dir = path.join(Task.projectRoot(), basedir);
         if (!fs.existsSync(dir))
             return [];
+        const isMatch = picomatch(files, { dot: true });
         const out = [];
         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))
+            const m = /^TASK-([A-Za-z0-9-]+)\.md$/.exec(entry);
+            if (m === null || !isMatch(entry))
                 continue;
+            const file = path.join(dir, entry);
             const st = fs.statSync(file);
             if (!st.isFile())
                 continue;
             const mtime = verbose ? DateTime.fromJSDate(st.mtime).toFormat("yyyy-LL-dd HH:mm") : undefined;
-            out.push({ id: entry, mtime });
+            out.push({ id: m[1], mtime });
         }
         out.sort((a, b) => a.id.localeCompare(b.id));
         return out;
     }
     /*  purge tasks whose modification time is older than the given cutoff in
         milliseconds; returns the list of removed task ids  */
-    static purge(maxAgeMs) {
-        const dir = Task.baseDir();
+    static purge(log, maxAgeMs) {
+        if (Task.needsMigration(log))
+            Task.migrateAll(log);
+        const { basedir, files } = Task.spec(log);
+        const dir = path.join(Task.projectRoot(), basedir);
         if (!fs.existsSync(dir))
             return [];
+        const isMatch = picomatch(files, { dot: true });
         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))
+            const m = /^TASK-([A-Za-z0-9-]+)\.md$/.exec(entry);
+            if (m === null || !isMatch(entry))
                 continue;
+            const file = path.join(dir, entry);
             const st = fs.statSync(file);
             if (!st.isFile())
                 continue;
             if (st.mtimeMs < cutoff) {
-                fs.rmSync(sub, { recursive: true, force: true });
-                removed.push(entry);
+                fs.rmSync(file, { force: true });
+                removed.push(m[1]);
             }
         }
         return removed;
@@ -173,7 +248,7 @@ export default class TaskCommand {
         /*  register CLI top-level command "ase task"  */
         const task = program
             .command("task")
-            .description("Manage persisted tasks under <project>/.ase/task/<id>/plan.md")
+            .description("Manage persisted tasks under <project>/<basedir>/TASK-<id>.md")
             .action(() => {
             task.outputHelp();
             process.exit(1);
@@ -182,9 +257,9 @@ export default class TaskCommand {
         task
             .command("list")
             .description("List all persisted task ids, one per line")
-            .option("-v, --verbose", "also show the plan.md modification time as (YYYY-MM-DD HH:MM)")
+            .option("-v, --verbose", "also show the task file modification time as (YYYY-MM-DD HH:MM)")
             .action((opts) => {
-            const items = Task.list(opts.verbose ?? false);
+            const items = Task.list(this.log, opts.verbose ?? false);
             for (const item of items) {
                 if (opts.verbose)
                     process.stdout.write(`${item.id}\t(${item.mtime})\n`);
@@ -199,7 +274,7 @@ export default class TaskCommand {
             .description("Load a task by id and write it to stdout")
             .argument("<id>", "Task identifier")
             .action((id) => {
-            const text = Task.load(id);
+            const text = Task.load(this.log, id);
             process.stdout.write(text);
             process.exit(0);
         });
@@ -209,7 +284,7 @@ export default class TaskCommand {
             .description("Edit a task by id with $EDITOR")
             .argument("<id>", "Task identifier")
             .action((id) => {
-            const file = Task.path(id);
+            const file = Task.path(this.log, id);
             const editor = process.env.EDITOR ?? process.env.VISUAL ?? "vi";
             fs.mkdirSync(path.dirname(file), { recursive: true });
             if (!fs.existsSync(file))
@@ -225,7 +300,7 @@ export default class TaskCommand {
             .argument("<id>", "Task identifier")
             .action(async (id) => {
             const text = await readStdin();
-            Task.save(id, text);
+            Task.save(this.log, id, text);
             this.log.write("info", `task: saved "${id}"`);
             process.exit(0);
         });
@@ -235,7 +310,7 @@ export default class TaskCommand {
             .description("Delete a task by id")
             .argument("<id>", "Task identifier")
             .action((id) => {
-            const removed = Task.delete(id);
+            const removed = Task.delete(this.log, id);
             if (removed)
                 this.log.write("info", `task: removed "${id}"`);
             else
@@ -249,7 +324,7 @@ export default class TaskCommand {
             .argument("<old>", "Old task identifier")
             .argument("<new>", "New task identifier")
             .action((oldId, newId) => {
-            const renamed = Task.rename(oldId, newId);
+            const renamed = Task.rename(this.log, oldId, newId);
             if (renamed)
                 this.log.write("info", `task: renamed "${oldId}" to "${newId}"`);
             else
@@ -276,7 +351,7 @@ export default class TaskCommand {
                 unit === "d" ? day :
                     unit === "m" ? month :
                         year;
-            const removed = Task.purge(n * factor);
+            const removed = Task.purge(this.log, n * factor);
             if (removed.length === 0)
                 this.log.write("info", "task: no tasks to purge");
             else
@@ -300,7 +375,7 @@ export class TaskMCP {
             description: "List all persisted tasks. " +
                 "Returns a `tasks` array (in lexicographic `id` order) where each item has the " +
                 "task `id`. If `verbose` is `true`, each item additionally has an `mtime` field " +
-                "(last modification time of the task's `plan.md`, formatted as `YYYY-MM-DD HH:MM`). " +
+                "(last modification time of the task's `TASK-<id>.md` file, formatted as `YYYY-MM-DD HH:MM`). " +
                 "Returns an empty array if no tasks exist.",
             inputSchema: {
                 verbose: z.boolean().optional()
@@ -310,13 +385,13 @@ export class TaskMCP {
                 tasks: z.array(z.object({
                     id: z.string().describe("task identifier"),
                     mtime: z.string().optional()
-                        .describe("plan.md modification time (`YYYY-MM-DD HH:MM`); only present if `verbose` is true")
+                        .describe("`TASK-<id>.md` modification time (`YYYY-MM-DD HH:MM`); only present if `verbose` is true")
                 })).describe("all persisted tasks in lexicographic id order")
             }
         }, async (args) => {
             try {
                 const verbose = args.verbose ?? false;
-                const items = Task.list(verbose);
+                const items = Task.list(this.log, verbose);
                 const tasks = verbose ?
                     items.map((item) => ({ id: item.id, mtime: item.mtime ?? "" })) :
                     items.map((item) => ({ id: item.id }));
@@ -345,7 +420,7 @@ export class TaskMCP {
             }
         }, async (args) => {
             try {
-                const text = Task.load(args.id);
+                const text = Task.load(this.log, args.id);
                 return {
                     content: [{ type: "text", text }]
                 };
@@ -371,7 +446,7 @@ export class TaskMCP {
             }
         }, async (args) => {
             try {
-                Task.save(args.id, args.text);
+                Task.save(this.log, args.id, args.text);
                 return {
                     content: [{ type: "text", text: `task_save: OK: saved task "${args.id}"` }]
                 };
@@ -395,7 +470,7 @@ export class TaskMCP {
             }
         }, async (args) => {
             try {
-                const removed = Task.delete(args.id);
+                const removed = Task.delete(this.log, args.id);
                 const msg = removed ?
                     `task_delete: OK: removed task "${args.id}"` :
                     `task_delete: WARNING: no task "${args.id}" to remove`;
@@ -415,7 +490,7 @@ export class TaskMCP {
         mcp.registerTool("ase_task_rename", {
             title: "ASE task rename",
             description: "Rename a previously persisted task from `old` to `new` by atomically moving the " +
-                "task home directory. Returns a status `text` indicating whether the rename succeeded. " +
+                "task `TASK-<id>.md` file. Returns a status `text` indicating whether the rename succeeded. " +
                 "Fails with an error if the target id already exists.",
             inputSchema: {
                 old: z.string()
@@ -425,7 +500,7 @@ export class TaskMCP {
             }
         }, async (args) => {
             try {
-                const renamed = Task.rename(args.old, args.new);
+                const renamed = Task.rename(this.log, args.old, args.new);
                 const msg = renamed ?
                     `task_rename: OK: renamed task "${args.old}" to "${args.new}"` :
                     `task_rename: WARNING: no task "${args.old}" to rename`;

package/dst/ase.js

@@ -14,6 +14,7 @@ import DiagramCommand from "./ase-diagram.js";
 import SetupCommand from "./ase-setup.js";
 import StatuslineCommand from "./ase-statusline.js";
 import TaskCommand from "./ase-task.js";
+import ArtifactCommand from "./ase-artifact.js";
 import pkg from "../package.json" with { type: "json" };
 /*  globally initialize logger  */
 const log = new Log("ase", "warning", "-");
@@ -49,6 +50,7 @@ const main = async () => {
     new HookCommand(log).register(program);
     new StatuslineCommand(log).register(program);
     new TaskCommand(log).register(program);
+    new ArtifactCommand(log).register(program);
     new DiagramCommand(log).register(program);
     /*  parse program arguments  */
     await program.parseAsync(process.argv);

package/package.json

@@ -6,7 +6,7 @@
     "homepage":                             "http://github.com/rse/ase",
     "repository":                           { "url": "git+https://github.com/rse/ase.git", "type": "git" },
     "bugs":                                 { "url": "http://github.com/rse/ase/issues" },
-    "version":                              "0.9.5",
+    "version":                              "0.9.6",
     "license":                              "GPL-3.0-only",
     "author": {
         "name":                             "Dr. Ralf S. Engelschall",
@@ -37,7 +37,8 @@
         "@types/shell-quote":               "1.7.5",
         "@types/proper-lockfile":           "4.1.4",
         "@types/write-file-atomic":         "4.0.3",
-        "@types/pacote":                    "11.1.8"
+        "@types/pacote":                    "11.1.8",
+        "@types/picomatch":                 "4.0.3"
     },
     "dependencies": {
         "commander":                        "15.0.0",
@@ -60,7 +61,8 @@
         "proper-lockfile":                  "4.1.2",
         "write-file-atomic":                "8.0.0",
         "pacote":                           "21.5.0",
-        "ofetch":                           "1.5.1"
+        "ofetch":                           "1.5.1",
+        "picomatch":                        "4.0.4"
     },
     "engines": {
         "npm":                              ">=10.0.0",

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

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

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

@@ -16,12 +16,15 @@ Artifact Meta Information
         (SAS)", "Architecture Description", or "Architecture Decision
         Record (ADR)".
 
-    -   `Software` (`SOFT`), aka "Software Implementation Results (IMP)".
+    -   `Source Code` (`CODE`), aka "Software Implementation Results (IMP)",
+        "Code", or "Software".
 
     -   `Documentation` (`DOCS`), aka "Software Documentation Results (DOC)".
 
+    -   `Tasks` (`TASK`), aka "Task Plans", "Issues", or "User Stories".
+
     Each **Artifact Set** has a unique identifier <artifact-set-id/>,
-    which is one of `SPEC`, `ARCH`, `SOFT`, or `DOCS`.
+    which is one of `SPEC`, `ARCH`, `CODE`, `DOCS`, or `TASK`.
 
 -   **Artifact**:
 

package/plugin/meta/{ase-format-plan.md → ase-format-task.md}

@@ -1,14 +1,15 @@
 
-Plan Format
------------
+Task
+----
 
-Every *task plan* uses a strict and fixed format:
+Every *task* uses a strict and fixed format:
 
 <format>
 
-# ✪ TASK PLAN: **<title/>**
+# ✪ TASK <task-id/>: <title/>
 
-◉ task id: **<task-id/>** // ✳ created: **<timestamp-created/>** // ✎ modified: **<timestamp-modified/>**
+✳ Created:  **<timestamp-created/>**
+✎ Modified: **<timestamp-modified/>**
 
 ## ※ CONTEXT
 
@@ -30,7 +31,7 @@ Every *task plan* uses a strict and fixed format:
 
 </format>
 
-You *MUST* honor the following hints on this *task plan* format:
+You *MUST* honor the following hints on this *task* format:
 
 -   You *MUST* always keep the first empty line and the last empty line.
     If one of them is missing, add it back.

package/plugin/package.json

@@ -6,7 +6,7 @@
     "homepage":                             "http://github.com/rse/ase",
     "repository":                           { "url": "git+https://github.com/rse/ase.git", "type": "git" },
     "bugs":                                 { "url": "http://github.com/rse/ase/issues" },
-    "version":                              "0.9.5",
+    "version":                              "0.9.6",
     "license":                              "GPL-3.0-only",
     "author": {
         "name":                             "Dr. Ralf S. Engelschall",

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

@@ -38,7 +38,7 @@ From scratch *craft* the following feature:
 <feature><getopt-arguments/></feature>
 </objective>
 
-@${CLAUDE_SKILL_DIR}/../../meta/ase-format-plan.md
+@${CLAUDE_SKILL_DIR}/../../meta/ase-format-task.md
 
 Procedure
 ---------

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

@@ -38,7 +38,7 @@ to `true`, <getopt-option-dry/> to `true`, and <getopt-option-next/> to
 <request><getopt-arguments/></request>
 </objective>
 
-@${CLAUDE_SKILL_DIR}/../../meta/ase-format-plan.md
+@${CLAUDE_SKILL_DIR}/../../meta/ase-format-task.md
 
 Procedure
 ---------

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

@@ -38,7 +38,7 @@ to `true`, <getopt-option-dry/> to `true`, and <getopt-option-next/> to
 <problem><getopt-arguments/></problem>
 </objective>
 
-@${CLAUDE_SKILL_DIR}/../../meta/ase-format-plan.md
+@${CLAUDE_SKILL_DIR}/../../meta/ase-format-task.md
 
 Procedure
 ---------

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

@@ -30,7 +30,7 @@ Condense a Task Plan
 semantics exactly.
 </objective>
 
-@${CLAUDE_SKILL_DIR}/../../meta/ase-format-plan.md
+@${CLAUDE_SKILL_DIR}/../../meta/ase-format-task.md
 
 Procedure
 ---------

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

@@ -17,10 +17,6 @@ session context) is used. When the deleted task is the current task
 and not the `default` task, the current task id is automatically
 switched back to `default`.
 
-The task plan is stored in `.ase/tasks/`*id*`/plan.md` files of the
-project and can be alternatively deleted with the
-"`ase task delete` *id*" command from outside the agent tool.
-
 ##  ARGUMENTS
 
 *id*:

package/plugin/skills/ase-task-edit/SKILL.md

@@ -34,7 +34,7 @@ continued refinement, finalization, or hand-off to implementation or
 preflight.
 </objective>
 
-@${CLAUDE_SKILL_DIR}/../../meta/ase-format-plan.md
+@${CLAUDE_SKILL_DIR}/../../meta/ase-format-task.md
 
 Procedure
 ---------
@@ -271,7 +271,7 @@ Set <content-dirty>true</content-dirty>.
             </template>
         </if>
 
-    4.  <if condition="<content/> does not contain '# ✪ TASK PLAN:' AND <instruction/> is empty">
+    4.  <if condition="<content/> does not contain '# ✪ TASK' AND <instruction/> is empty">
         Set <instruction><content/></instruction> (set instruction to content).
         Set <content></content> (set content to empty).
         Set <content-dirty>true</content-dirty>.
@@ -327,9 +327,9 @@ Set <content-dirty>true</content-dirty>.
         Use the following <template/>:
 
         <template>
-        <ase-tpl-head title="TASK-PLAN"/>
+        <ase-tpl-head title="TASK"/>
         <content/>
-        <ase-tpl-foot title="TASK-PLAN"/>
+        <ase-tpl-foot title="TASK"/>
         </template>
 
     4.  *Determine next step*:

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

@@ -19,10 +19,6 @@ through a *chat-driven loop*. The user steers each round via an
 interactive dialog that offers continued refinement, finalization, or
 hand-off to implementation or preflight.
 
-The task plan is stored in `.ase/tasks/`*id*`/plan.md` files of the
-project and can be alternatively edited with the "`ase task edit` *id*"
-command from outside the agent tool.
-
 ##  OPTIONS
 
 `--plan`|`-p` *option*:

package/plugin/skills/ase-task-grill/SKILL.md

@@ -31,7 +31,7 @@ Interview the user relentlessly about every essential aspect of the
 task plan until reaching a shared understanding.
 </objective>
 
-@${CLAUDE_SKILL_DIR}/../../meta/ase-format-plan.md
+@${CLAUDE_SKILL_DIR}/../../meta/ase-format-task.md
 
 Procedure
 ---------

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

@@ -27,10 +27,6 @@ lets the user pick via an interactive dialog. It honors checks for
 updated and persisted, and the user is offered a hand-off to editing,
 implementation, or preflight.
 
-The task plan is stored in `.ase/tasks/`*id*`/plan.md` files of the
-project and can be alternatively edited with the "`ase task edit` *id*"
-command from outside the agent tool.
-
 ##  OPTIONS
 
 `--next`|`-n` *option*[,...]:

package/plugin/skills/ase-task-implement/SKILL.md

@@ -30,7 +30,7 @@ Implement a Task Plan
 with a corresponding, complete *change set*.
 </objective>
 
-@${CLAUDE_SKILL_DIR}/../../meta/ase-format-plan.md
+@${CLAUDE_SKILL_DIR}/../../meta/ase-format-task.md
 
 Procedure
 ---------

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

@@ -12,12 +12,11 @@
 
 ##  DESCRIPTION
 
-The `ase-task-implement` skill performs the *final implementation*
-of a task plan by modifying the corresponding *artifacts* with a
-complete *change set*. The plan is loaded from
-`.ase/tasks/`*id*`/plan.md`, and any optional `IMPLEMENTATION DRAFT`
-section produced by `ase-task-preflight` is used as a hint - the
-plain plan content always overrules the draft.
+The `ase-task-implement` skill performs the *final implementation* of
+a task plan by modifying the corresponding *artifacts* with a complete
+*change set*. The plan is loaded and any optional `IMPLEMENTATION DRAFT`
+section produced by `ase-task-preflight` is used as a hint - the plain
+plan content always overrules the draft.
 
 If the task plan deliberately *omits* the `※ VERIFICATION` section
 (as produced by `ase-code-craft`, `ase-code-refactor`,

package/plugin/skills/ase-task-preflight/SKILL.md

@@ -30,7 +30,7 @@ Preflight a Task Plan
 for a corresponding, *complete source code change set*.
 </objective>
 
-@${CLAUDE_SKILL_DIR}/../../meta/ase-format-plan.md
+@${CLAUDE_SKILL_DIR}/../../meta/ase-format-task.md
 
 Procedure
 ---------

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

@@ -30,7 +30,7 @@ Reboot a Task Plan
 based on the existing *WHAT* and *WHY*.
 </objective>
 
-@${CLAUDE_SKILL_DIR}/../../meta/ase-format-plan.md
+@${CLAUDE_SKILL_DIR}/../../meta/ase-format-task.md
 
 Procedure
 ---------