@rse/ase 0.9.53 → 0.9.55

package/dst/ase-log.js

@@ -12,6 +12,8 @@ const levels = [
     { name: "info", style: chalk.blue },
     { name: "debug", style: chalk.green }
 ];
+/*  check whether an arbitrary string is a valid log level  */
+export const isLogLevel = (level) => levels.some((l) => l.name === level);
 export default class Log {
     _program;
     _logLevel;
@@ -36,11 +38,14 @@ export default class Log {
         return stream;
     }
     logLevel(level) {
+        if (level === undefined)
+            return this._logLevel;
         const idx = levels.findIndex((l) => l.name === level);
         if (idx === -1)
             throw new RangeError(`invalid log level "${level}" (expected one of: ${levels.map((l) => l.name).join(", ")})`);
         this._logLevel = level;
         this.logLevelIdx = idx;
+        return this._logLevel;
     }
     logFile(file) {
         if (file === this._logFile)

package/dst/ase-service.js

@@ -16,6 +16,7 @@ import * as v from "valibot";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { Config, configSchema, ConfigMCP } from "./ase-config.js";
+import { isLogLevel } from "./ase-log.js";
 import { CompatMCP } from "./ase-compat.js";
 import { DiagramMCP } from "./ase-diagram.js";
 import { TaskMCP } from "./ase-task.js";
@@ -61,11 +62,18 @@ export const probe = async (port, projectId) => {
 };
 const SERVE_ENV = "ASE_SERVICE_SERVE";
 const PORT_ENV = "ASE_SERVICE_PORT";
+const LEVEL_ENV = "ASE_SERVICE_LOG_LEVEL";
 const IDLE_MS = 30 * 60 * 1000;
 const TICK_MS = 60 * 1000;
 const PORT_MIN = 42000;
 const PORT_MAX = 44000;
 const PORT_TRIES = 20;
+/*  bounds for the append-only ".ase/service.log" file:
+    maximum tolerated size, number of tail lines surviving a trim,
+    and maximum length of the MCP tool call arguments logged per request  */
+const LOG_MAX_SIZE = 1024 * 1024;
+const LOG_KEEP_LINES = 2000;
+const LOG_ARGS_MAX = 200;
 /*  load the optional "config.yaml" and "service.yaml" files and derive
     the service identity context (project id, port, service config)  */
 export const loadServiceContext = (log) => {
@@ -130,15 +138,32 @@ export class Service {
                 svc.write();
         });
     }
+    /*  trim the log file down to its tail if it grew beyond the size limit  */
+    static trimLog(logFile) {
+        try {
+            if (!fs.existsSync(logFile) || fs.statSync(logFile).size <= LOG_MAX_SIZE)
+                return;
+            const tail = Service.readLogTail(logFile, LOG_KEEP_LINES);
+            fs.writeFileSync(logFile, tail.length > 0 ? `${tail}\n` : "");
+        }
+        catch {
+            /*  intentionally ignore all trimming errors, as a
+                non-trimmable log file must never block the service  */
+        }
+    }
     /*  spawn the current executable detached as a background service  */
-    static spawnDetached(aseDir, port) {
+    static spawnDetached(aseDir, port, logLevel) {
         fs.mkdirSync(aseDir, { recursive: true });
         const logFile = path.join(aseDir, "service.log");
+        /*  trim the log before handing it to the service, as the detached
+            service inherits the file descriptor for its entire lifetime and
+            hence cannot rotate the file itself while it is running  */
+        Service.trimLog(logFile);
         const fd = fs.openSync(logFile, "a");
         const entry = fileURLToPath(new URL("./ase.js", import.meta.url));
         const child = spawn(process.execPath, [entry, "service", "start"], {
             detached: true,
-            env: { ...process.env, [SERVE_ENV]: "1", [PORT_ENV]: String(port) },
+            env: { ...process.env, [SERVE_ENV]: "1", [PORT_ENV]: String(port), [LEVEL_ENV]: logLevel },
             stdio: ["ignore", fd, fd]
         });
         fs.closeSync(fd);
@@ -285,11 +310,20 @@ export default class ServiceCommand {
                 bodyInfo = ` [${bMethod}]`;
                 if (bName !== null) {
                     bodyInfo += ` ${bName}`;
-                    if (bArgs !== null)
-                        bodyInfo += ` ${JSON.stringify(bArgs)}`;
+                    if (bArgs !== null) {
+                        /*  cap the arguments, as payload-carrying tool calls
+                            (task plans, key/value batches, etc) would
+                            otherwise dominate the entire log file  */
+                        const args = JSON.stringify(bArgs);
+                        bodyInfo += ` ${args.length > LOG_ARGS_MAX ? `${args.slice(0, LOG_ARGS_MAX)}…` : args}`;
+                    }
                 }
             }
-            this.log.write("info", `mcp: ${request.method.toUpperCase()} ${request.path}${bodyInfo}`);
+            /*  log tool calls regularly, but all remaining MCP traffic
+                (session handshakes, notifications, SSE stream opens) at
+                debug level only, as it carries no diagnostic value  */
+            const level = bMethod === "tools/call" ? "info" : "debug";
+            this.log.write(level, `mcp: ${request.method.toUpperCase()} ${request.path}${bodyInfo}`);
             const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
             const mcp = buildMcpServer();
             request.raw.res.on("close", () => {
@@ -394,6 +428,11 @@ export default class ServiceCommand {
         const ctx = this.loadContext();
         let port = ctx.port;
         if (process.env[SERVE_ENV] === "1") {
+            /*  adopt the log level of the spawning process, as the
+                detached service is started without any CLI options  */
+            const level = process.env[LEVEL_ENV];
+            if (level !== undefined && isLogLevel(level))
+                this.log.logLevel(level);
             const raw = process.env[PORT_ENV];
             port = raw !== undefined ? Number(raw) : await Service.allocatePort();
             await this.runService({ ...ctx, port });
@@ -411,7 +450,7 @@ export default class ServiceCommand {
         let lastErr = new Error("service failed to start within timeout");
         for (let attempt = 0; attempt < 3; attempt++) {
             port = await Service.allocatePort();
-            const { child, logFile } = Service.spawnDetached(ctx.aseDir, port);
+            const { child, logFile } = Service.spawnDetached(ctx.aseDir, port, this.log.logLevel());
             let exited = false;
             let exitCode = null;
             let resolveExit = () => { };

package/dst/ase-task.js

@@ -14,6 +14,12 @@ import { LRUCache } from "lru-cache";
 import { Config, configSchema, parseScope } from "./ase-config.js";
 import { Markdown } from "./ase-markdown.js";
 import { readStdin, writeStdout } from "./ase-stdio.js";
+/*  the lifecycle states a task plan can be in, i.e., the accepted
+    values of the "Status:" frontmatter key of a task plan  */
+export const taskStates = [
+    "DRAFTED", "REJECTED", "APPROVED", "DEFERRED",
+    "STARTED", "BLOCKED", "COMPLETED", "CANCELLED"
+];
 /*  reusable functionality: persisted task plans under
     <project>/<basedir>/TASK-<id>.md (driven by the
     "project.artifact.task.{basedir,files}" configuration)  */
@@ -141,12 +147,54 @@ export class Task {
         migrated.sort((a, b) => a.localeCompare(b));
         return migrated;
     }
-    /*  load a task; returns empty string if no task exists  */
+    /*  the legacy task plan header lines, each mapped onto the
+        frontmatter key which superseded it  */
+    static legacy = [
+        { key: "Created", re: /^⎈[ \t]+Created:[ \t]*(.*)$/m },
+        { key: "Modified", re: /^⚙[ \t]+Modified:[ \t]*(.*)$/m },
+        { key: "Kind", re: /^☯[ \t]+Kind:[ \t]*(.*)$/m }
+    ];
+    /*  render a single frontmatter line with a column-aligned key  */
+    static frontLine(key, value) {
+        return (key + ":").padEnd(12) + value;
+    }
+    /*  normalize a legacy task plan -- one carrying its metadata in the
+        "#   TASK <id>: <title>" heading and the "⎈"/"⚙"/"☯" glyph header
+        lines -- into the current Markdown frontmatter shape, so every
+        consumer sees a single plan shape only; a plan already carrying a
+        frontmatter block, and any content without a task heading at all,
+        is passed through verbatim -- in particular, absent optional keys
+        are never materialized, as they read as their default value  */
+    static normalize(id, text) {
+        if (text === "" || /^---\r?\n/.test(text))
+            return text;
+        const heading = /^#[ \t]+TASK(?:[ \t]+[A-Za-z0-9_-]+)?[ \t]*:[ \t]*(.*)$/m.exec(text);
+        if (heading === null)
+            return text;
+        /*  lift the glyph header lines into their frontmatter keys, with
+            the task id taken from the authoritative filename-derived id  */
+        let body = text.replace(heading[0], "");
+        const front = [Task.frontLine("Id", id)];
+        for (const legacy of Task.legacy) {
+            const m = legacy.re.exec(body);
+            if (m === null)
+                continue;
+            front.push(Task.frontLine(legacy.key, m[1].trim()));
+            body = body.replace(m[0], "");
+        }
+        /*  re-assemble the plan from the frontmatter block, the reduced
+            heading, and the body stripped of its now leading blank lines  */
+        return `---\n${front.join("\n")}\n---\n\n` +
+            `#   TASK: ${heading[1].trim()}\n\n` +
+            body.replace(/^(?:[ \t]*\r?\n)+/, "");
+    }
+    /*  load a task, normalized into the current Markdown frontmatter
+        shape; returns empty string if no task exists  */
     static load(log, id) {
         const file = Task.path(log, id);
         if (!fs.existsSync(file))
             return "";
-        return fs.readFileSync(file, "utf8");
+        return Task.normalize(id, fs.readFileSync(file, "utf8"));
     }
     /*  save a task as UTF-8 text under the given id into the
         <project>/<basedir>/TASK-<id>.md file  */
@@ -167,10 +215,11 @@ export class Task {
         return true;
     }
     /*  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  */
+        to <project>/<basedir>/TASK-<newId>.md; the embedded "Id:"
+        frontmatter key inside the plan content is rewritten to the new id
+        (falling back to the "#   TASK <id>:" heading of a still legacy,
+        not yet normalized plan); 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);
@@ -179,7 +228,9 @@ export class Task {
         if (fs.existsSync(newFile))
             throw new Error(`task: target id "${newId}" already exists`);
         const text = fs.readFileSync(oldFile, "utf8");
-        const updated = text.replace(/(^#\s+TASK\s+)[A-Za-z0-9_-]+(\s*:)/m, `$1${newId}$2`);
+        const updated = /^---\r?\n/.test(text) ?
+            text.replace(/^(Id:[ \t]*)[A-Za-z0-9_-]+[ \t]*$/m, `$1${newId}`) :
+            text.replace(/(^#\s+TASK\s+)[A-Za-z0-9_-]+(\s*:)/m, `$1${newId}$2`);
         fs.mkdirSync(path.dirname(newFile), { recursive: true });
         fs.writeFileSync(newFile, updated, "utf8");
         fs.rmSync(oldFile, { force: true });
@@ -207,17 +258,55 @@ export class Task {
         }
         return out;
     }
-    /*  list all persisted tasks in lexicographic id order; if verbose is true,
-        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  */
+    /*  read the "Status:" frontmatter key of a task plan file, falling back
+        to the "DRAFTED" default of the task plan format for a plan whose
+        frontmatter is absent or carries no such key  */
+    static status(file) {
+        const fm = /^---\r?\n([\s\S]*?\r?\n)---\r?\n/.exec(fs.readFileSync(file, "utf8"));
+        if (fm === null)
+            return "DRAFTED";
+        const m = /^Status:[ \t]*(\S+)[ \t]*$/m.exec(fm[1]);
+        if (m === null)
+            return "DRAFTED";
+        return m[1];
+    }
+    /*  list all persisted tasks in lexicographic id order, each with the
+        `status` of its plan; if verbose is true, 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) {
         const out = Task.scan(log).map((entry) => ({
             id: entry.id,
+            status: Task.status(entry.file),
             mtime: verbose ? DateTime.fromJSDate(entry.st.mtime).toFormat("yyyy-LL-dd HH:mm") : undefined
         }));
         out.sort((a, b) => a.id.localeCompare(b.id));
         return out;
     }
+    /*  resolve an "include" and an "exclude" comma-separated lifecycle
+        state list into the effective state set a task plan has to be in
+        to be listed at all; the "none" sentinel and empty tokens are
+        silently dropped, an empty "include" list means all states, and
+        the "exclude" list is applied after the "include" list  */
+    static states(include, exclude) {
+        const parse = (list) => list.split(",")
+            .map((token) => token.trim())
+            .filter((token) => token !== "" && token.toUpperCase() !== "NONE")
+            .map((token) => {
+            const state = token.toUpperCase();
+            if (!taskStates.includes(state))
+                throw new Error(`task: invalid state "${token}" ` +
+                    `(expected one of: ${taskStates.join(", ")})`);
+            return state;
+        });
+        const included = parse(include);
+        const excluded = parse(exclude);
+        const states = (included.length > 0 ? included : taskStates)
+            .filter((state) => !excluded.includes(state));
+        if (states.length === 0)
+            throw new Error("task: options \"--include\" and \"--exclude\" cancel out to an empty state set");
+        return states;
+    }
     /*  purge tasks whose modification time is older than the given cutoff in
         milliseconds; returns the list of removed task ids  */
     static purge(log, maxAgeMs) {
@@ -274,12 +363,19 @@ export default class TaskCommand {
         task
             .command("list")
             .description("List all persisted task ids, one per line")
-            .option("-v, --verbose", "also show the task file modification time as (YYYY-MM-DD HH:MM)")
+            .option("-v, --verbose", "also show the task plan status and the task file " +
+            "modification time as (YYYY-MM-DD HH:MM)")
+            .option("-i, --include <states>", "comma-separated list of lifecycle states to list " +
+            `(${taskStates.join("|")}), or "none" for no restriction`, "none")
+            .option("-e, --exclude <states>", "comma-separated list of lifecycle states to not list " +
+            `(${taskStates.join("|")}), or "none" for no exclusion`, "COMPLETED,CANCELLED")
             .action(async (opts) => {
-            const items = Task.list(this.log, opts.verbose ?? false);
+            const states = Task.states(opts.include, opts.exclude);
+            const items = Task.list(this.log, opts.verbose ?? false)
+                .filter((item) => states.includes(item.status));
             for (const item of items) {
                 if (opts.verbose)
-                    await writeStdout(`${item.id}\t(${item.mtime})\n`);
+                    await writeStdout(`${item.id}\t${item.status}\t(${item.mtime})\n`);
                 else
                     await writeStdout(`${item.id}\n`);
             }
@@ -395,7 +491,8 @@ export class TaskMCP {
             title: "ASE task list",
             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 " +
+                "task `id` and the `status` of its plan (the `Status:` frontmatter key, defaulting " +
+                "to `DRAFTED`). If `verbose` is `true`, each item additionally has an `mtime` field " +
                 "(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: {
@@ -405,6 +502,7 @@ export class TaskMCP {
             outputSchema: {
                 tasks: z.array(z.object({
                     id: z.string().describe("task identifier"),
+                    status: z.string().describe("task plan lifecycle status (`Status:` frontmatter key, default `DRAFTED`)"),
                     mtime: z.string().optional()
                         .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")
@@ -414,8 +512,8 @@ export class TaskMCP {
                 const verbose = args.verbose ?? false;
                 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 }));
+                    items.map((item) => ({ id: item.id, status: item.status, mtime: item.mtime ?? "" })) :
+                    items.map((item) => ({ id: item.id, status: item.status }));
                 const result = { tasks };
                 return {
                     structuredContent: result,
@@ -430,7 +528,8 @@ export class TaskMCP {
         mcp.registerTool("ase_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`.",
+                "Returns the task as `text`, normalized into the current Markdown frontmatter shape; " +
+                "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, '_', '-')")
@@ -501,7 +600,7 @@ export class TaskMCP {
         mcp.registerTool("ase_task_rename", {
             title: "ASE task rename",
             description: "Rename a previously persisted task from `old` to `new` by moving the " +
-                "task `TASK-<id>.md` file and rewriting its embedded task heading. " +
+                "task `TASK-<id>.md` file and rewriting its embedded `Id:` frontmatter key. " +
                 "Returns a status `text` indicating whether the rename succeeded. " +
                 "Fails with an error if the target id already exists.",
             inputSchema: {

package/package.json

@@ -6,7 +6,7 @@
     "homepage":                             "https://ase.tools",
     "repository":                           { "url": "git+https://github.com/rse/ase.git", "type": "git" },
     "bugs":                                 { "url": "https://github.com/rse/ase/issues" },
-    "version":                              "0.9.53",
+    "version":                              "0.9.55",
     "license":                              "Apache-2.0",
     "author": {
         "name":                             "Dr. Ralf S. Engelschall",
@@ -31,7 +31,7 @@
         "shx":                              "0.4.0",
 
         "@types/node":                      "26.1.2",
-        "@types/luxon":                     "3.7.2",
+        "@types/luxon":                     "3.7.3",
         "@types/which":                     "3.0.4",
         "@types/update-notifier":           "6.0.8",
         "@types/shell-quote":               "1.7.5",

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

@@ -1,6 +1,6 @@
 {
     "name":        "ase",
-    "version":     "0.9.53",
+    "version":     "0.9.55",
     "description": "Agentic Software Engineering (ASE)",
     "keywords":    [ "agentic", "software", "engineering" ],
     "homepage":    "https://ase.tools",

package/plugin/.codex-plugin/plugin.json

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

package/plugin/meta/ase-common-code.md

@@ -0,0 +1,34 @@
+
+Code Skill Common Steps
+=======================
+
+<define name="code-tenets">
+
+You *MUST* internalize and strictly honor the **GENERIC TENETS**, and
+the **<arg1/> TENETS** of the **ASE Tenets** in the following creation
+and updating of code. Do not output anything.
+
+</define>
+
+<define name="code-tenets-from-plan">
+
+Determine the *kind of change* the task plan describes and internalize
+the corresponding tenet sets:
+
+-   If the frontmatter of <task-content/> carries a `Kind: <text/>` key
+    and <text/> is one of `CRAFTING`, `REFACTORING`, or `RESOLVING`:
+    Set <task-kind><text/></task-kind> (set task kind to the stated kind).
+
+-   Else:
+    The plan states no kind at all, or an unrecognized one, so *infer*
+    the kind from the plan content itself: `RESOLVING` if the plan
+    predominantly fixes a defect, `REFACTORING` if it predominantly
+    re-structures existing artifacts without changing their observable
+    behavior, and `CRAFTING` otherwise. Set <task-kind/> to the inferred
+    kind, defaulting to `CRAFTING` if the inference stays inconclusive.
+
+Then honor the tenet sets of <task-kind/>:
+
+<expand name="code-tenets" arg1="<task-kind/>"></expand>
+
+</define>

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

@@ -103,11 +103,12 @@ format, which has to be determined by calling the
 `ase_timestamp(format: "yyyy-LL-dd HH:mm")` tool of the `ase`
 MCP server and use the `text` field of its response. If
 <timestamp-created/> is still unset (because the plan content
-had no `Created:` line), set
+had no `Created:` frontmatter key), set
 <timestamp-created><timestamp-modified/></timestamp-created>
 (fall back to the modified timestamp). Re-insert the current
 <ase-task-id/>, the original <timestamp-created/>, and the
-refreshed <timestamp-modified/> into <task-content/> and calculate
+refreshed <timestamp-modified/> into the frontmatter keys `Id:`,
+`Created:`, and `Modified:` of <task-content/> and calculate
 the number of words <words/> of <task-content/>.
 
 Call the `ase_task_save(id: "<ase-task-id/>", text:

package/plugin/meta/ase-constitution.md

@@ -14,12 +14,16 @@ which boosts you to an expert-level Software Engineering AI agent.
 - Do *not* insist on early "return" in "if" blocks, if an "else" block exists.
 - Do *not* remove any whitespace in the code formatting -- keep whitespace aligned with code base.
 - Do *not* produce any trailing white-spaces on any lines.
+- Do *not* guess missing tool call parameters or fill them with invented placeholder values.
 
 ## Commandments
 
 - Be *honest* and *transparent* in all your responses.
 - *Ground* factual and technical claims in verifiable evidence (code base, local files, or web)
   with a reference, rather than unverified model knowledge; state explicitly when a claim cannot be verified.
+- Assume your *internal knowledge of dependencies* (libraries, frameworks, tools, and their implementations)
+  is *outdated*; always verify the current API, version, and usage pattern against the local sources
+  or the web before writing any code against them.
 - Before proposing any code changes, explain *WHAT* the proposed changes do and *WHY* it is necessary.
 - Use *concise* and *type-safe code* only.
 - Use *precise* and *surgical code changes* only.
@@ -37,7 +41,8 @@ which boosts you to an expert-level Software Engineering AI agent.
 - Use *double-quotes* (`"[...]"`) instead of single-quotes (`'[...]'`) for all strings.
 - Use K&R coding style with *opening braces* at the end of lines and *closing braces* at the beginning of lines.
 - When a language has a *more strongly-typed variant*, prefer that variant.
-- When generating temporary helper programs, prefer the *target project's primary programming language*.
+- When generating temporary helper programs or scratch test files, prefer the *target project's primary
+  programming language* and *clean them up* once they are no longer needed.
 
 @./ase-persona.md
 

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

@@ -5,11 +5,16 @@ Task
 Every *task* uses a strict and fixed format:
 
 <format>
+---
+Id:         <task-id/>
+Created:    <timestamp-created/>
+Modified:   <timestamp-modified/>
+Status:     <task-status/>
+Properties: <task-properties/>
+Kind:       <task-kind/>
+---
 
-#   TASK <task-id/>: <title/>
-
-⎈   Created:  <timestamp-created/>
-⚙   Modified: <timestamp-modified/>
+#   TASK: <title/>
 
 ##  CONTEXT
 
@@ -33,8 +38,19 @@ Every *task* uses a strict and fixed 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.
+-   The content *MUST* begin with the `---` opening delimiter of the
+    *Markdown frontmatter* as its very *first* line -- there is *no*
+    leading empty line, as any line before the `---` would degrade the
+    frontmatter into ordinary Markdown. You *MUST* always keep the empty
+    line between the closing `---` delimiter and the `#` heading, and
+    always keep the last empty line. If one of them is missing, add it
+    back.
+
+-   The *frontmatter* carries the keys `Id`, `Created`, `Modified`,
+    `Status`, `Properties`, and `Kind`, in exactly this order, with their
+    values being *unquoted* plain scalars and vertically aligned one
+    space after the longest key. Only `Id` is *mandatory* -- every other
+    key is *optional* and, when absent, falls back to its default value.
 
 -   In all descriptions, highlight *code* as
     <template>`<code/>`</template> and *key aspects* as
@@ -46,11 +62,80 @@ You *MUST* honor the following hints on this *task* format:
     is changed, what benefit results or what the rationale is behind the
     change.
 
--   The <task-id/> has to be substituted with the current value of
-    <ase-task-id/> in the current session context.
-
--   The <timestamp-created/> is the timestamp when this task plan was
-    created. The <timestamp-modified/> is the timestamp when this
+-   The <task-id/> of the `Id:` frontmatter key has to be substituted
+    with the current value of <ase-task-id/> in the current session
+    context.
+
+-   The `Status:` frontmatter key states the current *lifecycle state*
+    of the task plan. The key is *optional* and defaults to `DRAFTED`:
+    an *absent* key reads as `DRAFTED`, and a *newly created* plan
+    carries `DRAFTED` explicitly. The <task-status/> value is *strictly*
+    one of the following eight states:
+
+    -   `DRAFTED`: plan exists but is still provisional and not yet
+        cleared for implementation.
+    -   `REJECTED`: plan was reviewed and refused, and has to be reworked
+        before it can be approved.
+    -   `APPROVED`: plan is accepted as authoritative and cleared for
+        implementation, but no work has begun.
+    -   `DEFERRED`: plan is approved and unobstructed, but its start was
+        deliberately postponed.
+    -   `STARTED`: implementation of the plan is actively underway.
+    -   `BLOCKED`: implementation is halted by an impediment which
+        someone has to remove before it can resume.
+    -   `COMPLETED`: plan was implemented in full and reached its
+        intended outcome.
+    -   `CANCELLED`: plan was terminated before completion, because it
+        failed, was called off, or became obsolete.
+
+-   The eight states form a *state machine*. Whoever sets the `Status:`
+    key *MUST* only move along one of the following transitions, whereby
+    a *single* operation *MAY* traverse *several* transitions at once if
+    it performs the corresponding stages in one go:
+
+    ```text
+    DRAFTED   ──reject───▶ REJECTED      STARTED   ──block────▶ BLOCKED
+    REJECTED  ──redraft──▶ DRAFTED       BLOCKED   ──unblock──▶ STARTED
+    DRAFTED   ──approve──▶ APPROVED      STARTED   ──complete─▶ COMPLETED
+    APPROVED  ──defer────▶ DEFERRED
+    DEFERRED  ──resume───▶ APPROVED      any non-terminal state
+    APPROVED  ──start────▶ STARTED       ──cancel───▶ CANCELLED
+    ```
+
+    `COMPLETED` and `CANCELLED` are the two *terminal* states: a plan
+    which reached one of them is *finished* and leaves the state machine.
+
+-   The `Properties:` frontmatter key states which *stages* the task
+    plan already passed through. The <task-properties/> value is
+    *strictly* either `none` or a comma-separated list of the values
+    `grilled`, `preflighted`, `implemented`, and `verified`, listed in
+    exactly this order, each at most once. The key is *optional* and
+    defaults to `none`: an *absent* key reads as `none`, and a *newly
+    created* plan carries `none` explicitly. The list only ever
+    *accumulates*: a skill *adds* its own value if still absent and
+    *MUST NOT* drop any value already present, except when a plan is
+    *recreated from scratch*, which resets it to `none`.
+
+-   The `Kind:` frontmatter key states the *kind of change* the task plan
+    describes, and hence which *operation-specific tenet set* of the
+    **ASE Tenets** a subsequent preflight or implementation has to
+    honor. The <task-kind/> value is *strictly* one of `CRAFTING`,
+    `REFACTORING`, or `RESOLVING`.
+
+-   The `Kind:` frontmatter key is *optional*: a skill *authoring* or
+    *updating* a task plan *CAN* update an already present key or pass
+    it through *verbatim* and *MAY* create a missing one by *inferring*
+    the kind from the plan content (defaulting to `CRAFTING`). A
+    `--dry` run *never* drops this key, as `--dry` only omits the
+    `##  VERIFICATION` section.
+
+-   A skill *writing* an optional key which is still *absent* inserts it
+    at its position in the key order above and re-aligns the values of
+    the whole frontmatter block.
+
+-   The <timestamp-created/> of the `Created:` frontmatter key is the
+    timestamp when this task plan was created. The <timestamp-modified/>
+    of the `Modified:` frontmatter key is the timestamp when this
     task plan was last modified. Both use an ISO-style format
     value. The value of both can be determined by a call to the
     `ase_timestamp(format: "yyyy-LL-dd HH:mm")` tool of the `ase` MCP

package/plugin/package.json

@@ -6,7 +6,7 @@
     "homepage":                             "https://ase.tools",
     "repository":                           { "url": "git+https://github.com/rse/ase.git", "type": "git" },
     "bugs":                                 { "url": "https://github.com/rse/ase/issues" },
-    "version":                              "0.9.53",
+    "version":                              "0.9.55",
     "license":                              "Apache-2.0",
     "author": {
         "name":                             "Dr. Ralf S. Engelschall",