@rse/ase 0.9.57 → 0.9.59

package/dst/ase-service.js

@@ -24,8 +24,10 @@ import { MarkdownMCP } from "./ase-markdown.js";
 import { ArtifactMCP } from "./ase-artifact.js";
 import { KVMCP } from "./ase-kv.js";
 import { TimestampMCP } from "./ase-timestamp.js";
+import { SleepMCP } from "./ase-sleep.js";
 import { GetoptMCP } from "./ase-getopt.js";
 import { SkillsMCP } from "./ase-skills.js";
+import { WorktreeMCP } from "./ase-worktree.js";
 import pkg from "../package.json" with { type: "json" };
 /*  shared service host  */
 export const SERVICE_HOST = "127.0.0.1";
@@ -268,8 +270,10 @@ export default class ServiceCommand {
             new ArtifactMCP(this.log).register(mcp);
             new KVMCP().register(mcp);
             new TimestampMCP().register(mcp);
+            new SleepMCP().register(mcp);
             new GetoptMCP().register(mcp);
             new SkillsMCP().register(mcp);
+            new WorktreeMCP().register(mcp);
             new ConfigMCP(this.log).register(mcp);
             return mcp;
         };

package/dst/ase-sleep.js

@@ -0,0 +1,26 @@
+/*
+**  Agentic Software Engineering (ASE)
+**  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+*/
+import { z } from "zod";
+/*  MCP registration entry point for sleep tool  */
+export class SleepMCP {
+    register(mcp) {
+        mcp.registerTool("ase_sleep", {
+            title: "ASE sleep",
+            description: "Wait once for `duration` seconds and then return. " +
+                "The duration can be fractional (e.g. `1.5`) and is at most 120 (default: 60). " +
+                "Returns `OK: slept <duration> seconds` as `text` after the duration elapsed.",
+            inputSchema: {
+                duration: z.number().positive().max(120).default(60)
+                    .describe("wait duration in seconds (fractional values allowed, at most 120, default 60)")
+            }
+        }, async (args) => {
+            await new Promise((resolve) => setTimeout(resolve, args.duration * 1000));
+            return {
+                content: [{ type: "text", text: `OK: slept ${args.duration} seconds` }]
+            };
+        });
+    }
+}

package/dst/ase-worktree.js

@@ -0,0 +1,162 @@
+/*
+**  Agentic Software Engineering (ASE)
+**  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+*/
+import path from "node:path";
+import fs from "node:fs";
+import { execaSync } from "execa";
+import { z } from "zod";
+import { writeStdout } from "./ase-stdio.js";
+/*  the repository-root-relative path components of the base directory
+    which holds all ASE-managed Git worktrees  */
+const baseComponents = [".ase", "worktree"];
+/*  reusable functionality: safe resolution of the ASE worktree
+    directories under <repo-root>/.ase/worktree/<id>  */
+export class Worktree {
+    /*  validate a worktree id to keep it safe both as a single path
+        component and as the Git branch name derived from it  */
+    static validateId(id) {
+        if (typeof id !== "string" || id.length === 0)
+            throw new Error("worktree: id must be a non-empty string");
+        if (!/^[A-Za-z0-9_-]+$/.test(id))
+            throw new Error("worktree: id must match [A-Za-z0-9_-]+");
+    }
+    /*  determine the fully resolved top-level directory of the Git
+        working tree, as a Git worktree can only be created from
+        inside one  */
+    static repoRoot() {
+        let top = "";
+        try {
+            top = execaSync("git", ["rev-parse", "--show-toplevel"], { stderr: "ignore" }).stdout.trim();
+        }
+        catch {
+            /*  not inside a Git working tree  */
+        }
+        if (top === "")
+            throw new Error("worktree: not inside a Git working tree -- cannot create a worktree");
+        return fs.realpathSync(top);
+    }
+    /*  assert that an already existing path is a real, non-aliased
+        directory: "git worktree add" silently follows a symlinked path
+        component, so a repository carrying a committed ".ase" or
+        ".ase/worktree" symlink would make it write outside the
+        repository entirely  */
+    static assertRealDir(dir) {
+        let st;
+        try {
+            st = fs.lstatSync(dir);
+        }
+        catch {
+            /*  a not yet existing path component is created later on  */
+            return;
+        }
+        if (st.isSymbolicLink())
+            throw new Error(`worktree: "${dir}" is a symbolic link -- ` +
+                "refusing to create a worktree through it");
+        if (!st.isDirectory())
+            throw new Error(`worktree: "${dir}" exists but is not a directory`);
+        const real = fs.realpathSync(dir);
+        if (real !== dir)
+            throw new Error(`worktree: "${dir}" resolves to "${real}" -- ` +
+                "refusing to create a worktree through an aliased path");
+    }
+    /*  resolve the base directory holding all ASE worktrees, asserting
+        that every path component below the repository root is a real
+        directory; the base directory is created on demand only  */
+    static baseDir(create = false) {
+        let dir = Worktree.repoRoot();
+        for (const component of baseComponents) {
+            dir = path.join(dir, component);
+            Worktree.assertRealDir(dir);
+        }
+        if (create) {
+            fs.mkdirSync(dir, { recursive: true });
+            Worktree.assertRealDir(dir);
+        }
+        return dir;
+    }
+    /*  resolve the worktree directory of a single id; the leaf itself is
+        created by "git worktree add" and hence only has to be free of an
+        aliasing entry left behind by an earlier run  */
+    static dir(id, create = false) {
+        Worktree.validateId(id);
+        const dir = path.join(Worktree.baseDir(create), id);
+        Worktree.assertRealDir(dir);
+        return dir;
+    }
+}
+/*  CLI command "ase worktree"  */
+export default class WorktreeCommand {
+    /*  register commands  */
+    register(program) {
+        /*  register CLI top-level command "ase worktree"  */
+        const worktree = program
+            .command("worktree")
+            .description("Safely resolve the ASE worktree directories under <repo-root>/.ase/worktree")
+            .action(() => {
+            worktree.outputHelp();
+            process.exit(1);
+        });
+        /*  register CLI sub-command "ase worktree base"  */
+        worktree
+            .command("base")
+            .description("Print the validated base directory holding all ASE worktrees")
+            .option("-c, --create", "create the base directory if it does not exist yet")
+            .action(async (opts) => {
+            await writeStdout(`${Worktree.baseDir(opts.create ?? false)}\n`);
+        });
+        /*  register CLI sub-command "ase worktree path"  */
+        worktree
+            .command("path")
+            .description("Print the validated worktree directory of a single <id>")
+            .argument("<id>", "Worktree identifier")
+            .option("-c, --create", "create the base directory if it does not exist yet")
+            .action(async (id, opts) => {
+            await writeStdout(`${Worktree.dir(id, opts.create ?? false)}\n`);
+        });
+    }
+}
+/*  render a caught error as an MCP tool error result  */
+const mcpToolError = (err) => ({
+    isError: true,
+    content: [{ type: "text", text: `ERROR: ${err instanceof Error ? err.message : String(err)}` }]
+});
+/*  MCP registration entry point for worktree tools  */
+export class WorktreeMCP {
+    register(mcp) {
+        mcp.registerTool("ase_worktree_path", {
+            title: "ASE worktree path",
+            description: "Resolve the absolute, validated directory of an ASE-managed Git worktree. " +
+                "Returns `<repo-root>/.ase/worktree/<id>` as `text` if `id` is given, and the " +
+                "base directory `<repo-root>/.ase/worktree` otherwise. " +
+                "You MUST call this to obtain the directory of every worktree instead of " +
+                "assembling the path yourself: it rejects a path leading through a symbolic " +
+                "link, through a non-directory, or out of the repository, which `git worktree " +
+                "add` would otherwise silently follow and thereby write outside the repository. " +
+                "Set `create` to `true` to also create the base directory. " +
+                "Fails with an error if the path is unsafe or the current directory is not a " +
+                "Git working tree; in that case you MUST NOT create the worktree at all.",
+            inputSchema: {
+                id: z.string().optional()
+                    .describe("worktree identifier (allowed characters: A-Z, a-z, 0-9, '_', '-'); " +
+                    "if omitted, the base directory holding all ASE worktrees is returned"),
+                create: z.boolean().optional()
+                    .describe("if true, create the base directory if it does not exist yet (default: false)")
+            }
+        }, async (args) => {
+            try {
+                const create = args.create ?? false;
+                const text = args.id !== undefined ?
+                    Worktree.dir(args.id, create) :
+                    Worktree.baseDir(create);
+                return {
+                    content: [{ type: "text", text }]
+                };
+            }
+            catch (err) {
+                return mcpToolError(err);
+            }
+        });
+    }
+}

package/dst/ase.js

@@ -17,6 +17,7 @@ import ArtifactCommand from "./ase-artifact.js";
 import MetaCommand from "./ase-meta.js";
 import CompatCommand from "./ase-compat.js";
 import DiagramCommand from "./ase-diagram.js";
+import WorktreeCommand from "./ase-worktree.js";
 import pkg from "../package.json" with { type: "json" };
 /*  globally initialize logger  */
 const log = new Log("ase", "info", "-");
@@ -56,6 +57,7 @@ const main = async () => {
     new MetaCommand(log).register(program);
     new CompatCommand().register(program);
     new DiagramCommand(log).register(program);
+    new WorktreeCommand().register(program);
     /*  parse program arguments  */
     await program.parseAsync(process.argv);
     /*  gracefully terminate  */

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

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

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

package/plugin/agents/ase-code-lint.md

@@ -334,6 +334,12 @@ Workflow
                 pure-insertion hunk at its new location - *never* by
                 deleting and re-adding the unchanged lines in between.
 
+                This minimality rule applies *only* to <old-text/> and
+                <new-text/>. It *MUST* *NOT* be understood as a reason to
+                also drop the surrounding context of the two following
+                substeps - that context is *mandatory* and is reported
+                *separately* from the changed lines.
+
             3.  Set <context-before/> to exactly *up to two* lines of
                 *unchanged* code context which occurs in <file/>
                 directly *before* <old-text/>, i.e., the lines (<line/>
@@ -365,6 +371,15 @@ Workflow
                     }
                 </template>
 
+                Here `line` is a *number* and all four other fields are
+                *JSON strings* carrying the *verbatim* source lines
+                (embedded newlines escaped as `\n`, no line-number
+                prefixes, original indentation preserved). The empty
+                string `""` is allowed for `context_before` and
+                `context_after` *only* at the very start or end of the
+                file - for every other hunk both *MUST* carry their
+                context lines.
+
         3.  If <change-set/> is not empty, set
             <change-set><change-set/>,</change-set> (append a comma).
             Then append the following <template/> to <change-set/>:

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

@@ -50,6 +50,12 @@ Workflow
         as *two separate* problems instead of one large change
         which re-states the unchanged lines.
 
+        This minimality rule applies *only* to <old-text/> and
+        <new-text/>. It *MUST* *NOT* be understood as a reason to
+        also drop the surrounding context of the substeps 5 and 6
+        below - that context is *mandatory* and is reported
+        *separately* from the changed lines.
+
     4.  Set <description/> to an ultra-brief and concise
         Markdown-formatted description of the problem with
         a hint of what is wrong and why it is wrong. In
@@ -94,6 +100,15 @@ Workflow
             }
         </template>
 
+        Here `line` is a *number* and all other fields are *JSON
+        strings*, where <context-before/>, <old-text/>, <new-text/>,
+        and <context-after/> carry the *verbatim* document lines
+        (embedded newlines escaped as `\n`, no line-number prefixes,
+        original indentation preserved). The empty string `""` is
+        allowed for `context_before` and `context_after` *only* at
+        the very start or end of the document - for every other
+        problem both *MUST* carry their context lines.
+
 3.  You *MUST* *NOT* propose, apply, or render any document
     changes yourself. Instead, return *exclusively* as the last message
     a single JSON block (no markdown, no prose, no preamble, no summary)

package/plugin/meta/ase-constitution.md

@@ -31,6 +31,10 @@ which boosts you to an expert-level Software Engineering AI agent.
 - Place a *blank line before any comment line*,
   but not when it is the first line of a block or an end-of-line comment.
 - Keep code and comment *formatting exactly as in the existing code*.
+- Keep comments *brief*: target *1-2 lines*, only as an exception use up to *4 lines*,
+  and only for *very complex algorithms* go up to at most *8 lines*.
+  If an existing comment is already at its limit and still has to be expanded,
+  first *compact* its wording before adding new content.
 - Use *regular comments* `/*  [...]  */` instead of end-of-line comments `//  [...]`.
 - Use *two leading/trailing spaces within comments* as in `/*  [...]  */`.
 - Always use *parentheses around arrow function parameters*, even for a single parameter.

package/plugin/meta/ase-control.md

@@ -95,6 +95,45 @@ Control Flow Constructs
     is finished and no further repetitions are performed. This construct
     is expanded into nothing. Do not output anything.
 
+-   *IMPORTANT*: You *MUST* honor the following control flow construct:
+    <sleep duration="<sleep-duration/>"/>:
+
+    This specifies a single *wait* of <sleep-duration/> seconds
+    (fractional values like `1.5` are allowed).
+
+    The wait is performed with the `ase_sleep(duration:
+    <chunk-duration/>)` tool of the `ase` MCP server, which returns once
+    <chunk-duration/> has elapsed. To stay safely inside the tool's own
+    duration limit, <chunk-duration/> is *never* above `60`: a
+    <sleep-duration/> above `60` is therefore *split* into consecutive
+    calls -- as many `60` second calls as fit, followed by one final
+    call carrying the remaining seconds -- so the calls sum up to
+    exactly <sleep-duration/>.
+
+    This construct is expanded into nothing. Do not output anything.
+
+-   *IMPORTANT*: You *MUST* honor the following control flow construct:
+    <await condition="<await-condition/>" [interval="<await-interval/>"]><await-body/></await>:
+
+    This specifies an <await-body/> whose execution *waits* until
+    <await-condition/> is met: if <await-condition/> is met, the
+    <await-body/> is executed once and the construct is finished. If
+    <await-condition/> is *not* met, wait for <await-interval/> seconds
+    (default: `60`) and then *start over* by re-evaluating
+    <await-condition/>.
+
+    A single wait is performed with the `ase_sleep(duration:
+    <chunk-duration/>)` tool of the `ase` MCP server. To stay safely
+    inside the tool's own duration limit, <chunk-duration/> is *never*
+    above `60`: an <await-interval/> above `60` is therefore *split* into
+    consecutive calls -- as many `60` second calls as fit, followed by
+    one final call carrying the remaining seconds -- so the calls sum up
+    to exactly <await-interval/>. You *MUST* *NOT* re-evaluate
+    <await-condition/> between the calls of one such wait.
+
+    This construct is expanded to its <await-body/>. Do not output
+    anything else.
+
 -   *IMPORTANT*: You *MUST* honor the following control flow construct:
     <agent <attr/>="<value/>" [...]><agent-body/></agent>:
 

package/plugin/meta/ase-skill.md

@@ -292,8 +292,10 @@ Artifact Boxing Transparency
         -   Internals exposed: *none* (no diffs, no code, no per-artifact explanation)
 
 -   *IMPORTANT*: Precedence rule: a skill's *explicit* `black` branches
+    and a skill's *explicit* output suppression instructions
     deterministically skip or suppress and *win* over the implicit decisions
-    above. Where no such branches exist, the decisions above apply.
+    above. Where no such branches or instructions exist, the decisions
+    above apply.
 
 Guidance Hint Level
 -------------------