@rse/ase 0.0.9 → 0.0.10

package/dst/ase-config.js

@@ -21,7 +21,6 @@ export const projectClassification = {
     },
     process: {
         actors: ["person", "team", "crew"],
-        control: ["human", "hitl", "agent"],
         drive: ["spec", "code", "test"]
     },
     result: {
@@ -48,12 +47,11 @@ export const projectClassificationPresets = {
         "project.source.size": "small",
         "project.source.structure": "bare",
         "project.process.actors": "person",
-        "project.process.control": "agent",
         "project.process.drive": "spec",
         "project.result.target": "prototype",
         "agent.persona.style": "writer",
         "agent.persona.creativity": "full",
-        "agent.process.autonomy": "agent",
+        "agent.process.autonomy": "agent"
     },
     pro: {
         "project.id": "example",
@@ -63,12 +61,11 @@ export const projectClassificationPresets = {
         "project.source.size": "medium",
         "project.source.structure": "framework",
         "project.process.actors": "person",
-        "project.process.control": "human",
         "project.process.drive": "code",
         "project.result.target": "product",
         "agent.persona.style": "engineer",
         "agent.persona.creativity": "none",
-        "agent.process.autonomy": "assistant",
+        "agent.process.autonomy": "assistant"
     },
     default: {
         "project.id": "example",
@@ -78,12 +75,17 @@ export const projectClassificationPresets = {
         "project.source.size": "medium",
         "project.source.structure": "framework",
         "project.process.actors": "person",
-        "project.process.control": "human",
         "project.process.drive": "code",
         "project.result.target": "product",
+        "project.artifact.build": "{etc/**,README.md,AGENTS.md,LICENSE.txt,package.json}",
+        "project.artifact.code": "src/**/*",
+        "project.artifact.docs": "doc/user/**/*.md",
+        "project.artifact.spec": "doc/spec/**/*.md",
+        "project.artifact.arch": "doc/arch/**/*.md",
         "agent.persona.style": "engineer",
         "agent.persona.creativity": "none",
         "agent.process.autonomy": "assistant",
+        "task.id": "default"
     },
     industry: {
         "project.id": "example",
@@ -93,14 +95,21 @@ export const projectClassificationPresets = {
         "project.source.size": "large",
         "project.source.structure": "framework",
         "project.process.actors": "crew",
-        "project.process.control": "hitl",
         "project.process.drive": "code",
         "project.result.target": "mvp",
         "agent.persona.style": "engineer",
         "agent.persona.creativity": "none",
-        "agent.process.autonomy": "hotl",
+        "agent.process.autonomy": "hotl"
     }
 };
+/*  hard-coded map: which scope kinds each variable may be SET on
+    (reads always cascade through the full chain, this restricts writes only);
+    keys absent from this map default to all non-"default" scope kinds  */
+export const configWritableScopes = {
+    "task.id": ["session"]
+};
+/*  default set of scope kinds writable for any unrestricted key  */
+const configWritableScopesDefault = ["user", "project", "task", "session"];
 /*  canonical ordering rank of a scope kind  */
 const scopeRank = (kind) => ({ default: -1, user: 0, project: 1, task: 2, session: 3 })[kind];
 /*  parse a single scope term  */
@@ -180,11 +189,17 @@ export const configSchema = v.nullish(v.strictObject({
         })),
         process: v.optional(v.strictObject({
             actors: v.optional(v.picklist(projectClassification.process.actors)),
-            control: v.optional(v.picklist(projectClassification.process.control)),
             drive: v.optional(v.picklist(projectClassification.process.drive))
         })),
         result: v.optional(v.strictObject({
             target: v.optional(v.picklist(projectClassification.result.target))
+        })),
+        artifact: v.optional(v.strictObject({
+            build: v.optional(v.pipe(v.string(), v.minLength(1))),
+            code: v.optional(v.pipe(v.string(), v.minLength(1))),
+            docs: v.optional(v.pipe(v.string(), v.minLength(1))),
+            spec: v.optional(v.pipe(v.string(), v.minLength(1))),
+            arch: v.optional(v.pipe(v.string(), v.minLength(1)))
         }))
     })),
     agent: v.optional(v.strictObject({
@@ -195,6 +210,9 @@ export const configSchema = v.nullish(v.strictObject({
         process: v.optional(v.strictObject({
             autonomy: v.optional(v.picklist(agentClassification.process.autonomy))
         }))
+    })),
+    task: v.optional(v.strictObject({
+        id: v.optional(v.pipe(v.string(), v.minLength(1)))
     }))
 }));
 /*  encapsulate read/write access to a stack of "<name>.yaml" configuration files,
@@ -259,14 +277,12 @@ export class Config {
                 (fs.existsSync(path.join(cwd, rel)) ? path.join(cwd, rel) : null);
             return found ?? path.join(top ?? cwd, rel);
         }
-        else {
-            const sub = term.kind === "session" ? "sessions" : "tasks";
-            const top = this.gitToplevel();
-            if (top !== null)
-                return path.join(top, ".ase", sub, term.id, `${name}.yaml`);
-            else
-                return path.join(this.userConfigDir(), sub, term.id, `${name}.yaml`);
+        else if (term.kind === "task") {
+            const top = this.gitToplevel() ?? process.cwd();
+            return path.join(top, ".ase", "task", term.id, `${name}.yaml`);
         }
+        else
+            return path.join(os.homedir(), ".ase", "session", term.id, `${name}.yaml`);
     }
     /*  upward-walk on filesystem for a file path relative to a start directory,
         bounded above (inclusive) by a stop directory  */
@@ -482,8 +498,26 @@ export class Config {
         result.sort((a, b) => a.key.localeCompare(b.key));
         return result;
     }
+    /*  determine whether a key is writable on a given scope kind  */
+    isWritableOn(key, kind) {
+        if (kind === "default")
+            return false;
+        const resolved = this.resolveKey(key);
+        const allowed = configWritableScopes[resolved] ?? configWritableScopesDefault;
+        return allowed.includes(kind);
+    }
+    /*  enforce write-scope policy for the current target scope  */
+    assertWritable(key) {
+        const td = this.docs[this.target];
+        const resolved = this.resolveKey(key);
+        const allowed = configWritableScopes[resolved] ?? configWritableScopesDefault;
+        if (!allowed.includes(td.scope.kind))
+            throw new Error(`cannot set "${resolved}" on scope "${Config.scopeLabel(td.scope)}": ` +
+                `this key is only writable on scope(s): ${allowed.join(", ")}`);
+    }
     /*  set a value at a dotted key in the target scope, creating intermediate maps as needed  */
     set(key, value) {
+        this.assertWritable(key);
         const segments = this.resolveKey(key).split(".");
         const td = this.docs[this.target];
         const next = td.doc.clone();
@@ -508,6 +542,7 @@ export class Config {
     }
     /*  delete a value at a dotted key from the target scope  */
     delete(key) {
+        this.assertWritable(key);
         const td = this.docs[this.target];
         const next = td.doc.clone();
         next.deleteIn(this.resolveKey(key).split("."));
@@ -554,8 +589,12 @@ export default class ConfigCommand {
                 throw new Error(`unknown preset "${type}" (expected: default|vibe|pro|industry)`);
             const cfg = new Config("config", configSchema, this.log, scope);
             cfg.read();
-            for (const [k, val] of Object.entries(preset))
+            const targetKind = scope[scope.length - 1].kind;
+            for (const [k, val] of Object.entries(preset)) {
+                if (!cfg.isWritableOn(k, targetKind))
+                    continue;
                 cfg.set(k, val);
+            }
             cfg.write();
         });
         /*  register CLI sub-command "ase config list"  */

package/dst/ase-hook.js

@@ -0,0 +1,83 @@
+/*
+**  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 { execaSync } from "execa";
+/*  CLI command "ase hook"  */
+export default class HookCommand {
+    log;
+    constructor(log) {
+        this.log = log;
+    }
+    /*  handler for "ase hook session-start"  */
+    doSessionStart() {
+        /*  determine plugin root  */
+        const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT ?? "";
+        if (pluginRoot === "")
+            throw new Error("CLAUDE_PLUGIN_ROOT environment variable is not set");
+        /*  determine path to external files  */
+        const filePkg = path.join(pluginRoot, ".claude-plugin", "plugin.json");
+        const fileMd = path.join(pluginRoot, "meta", "ase-constitution.md");
+        /*  read external files  */
+        const pkg = fs.readFileSync(filePkg, "utf8");
+        let md = fs.readFileSync(fileMd, "utf8");
+        /*  determine own version  */
+        const version = JSON.parse(pkg).version ?? "";
+        /*  read session information  */
+        const stdin = fs.readFileSync(0, "utf8");
+        const input = stdin.trim() !== "" ? JSON.parse(stdin) : {};
+        /*  determine session id  */
+        const sessionId = input.session_id ?? "";
+        /*  determine task id  */
+        const taskId = process.env.ASE_TASK_ID ?? "default";
+        try {
+            execaSync("ase", ["config", `--scope=session:${sessionId}`, "set", "task.id", taskId], { stdio: ["ignore", "ignore", "ignore"] });
+        }
+        catch (_e) {
+            /*  best-effort: ignore failures  */
+        }
+        /*  provide session and task id to Claude Code shell commands  */
+        const envFile = process.env.CLAUDE_ENV_FILE ?? "";
+        if (envFile !== "") {
+            const script = `export ASE_VERSION="${version}"\n` +
+                `export ASE_SESSION_ID="${sessionId}"\n` +
+                `export ASE_TASK_ID="${taskId}"\n`;
+            fs.appendFileSync(envFile, script, "utf8");
+        }
+        /*  prepend ASE information to constitution markdown  */
+        md =
+            `<ase-version>${version}</ase-version>\n` +
+                `<ase-task-id>${taskId}</ase-task-id>\n` +
+                `<ase-session-id>${sessionId}</ase-session-id>\n` +
+                "\n" + md;
+        /*  inject markdown into session context  */
+        process.stdout.write(JSON.stringify({
+            "hookSpecificOutput": {
+                "hookEventName": "SessionStart",
+                "additionalContext": md
+            }
+        }));
+        return 0;
+    }
+    /*  register commands  */
+    register(program) {
+        /*  register CLI top-level command "ase hook"  */
+        const hookCmd = program
+            .command("hook")
+            .description("Claude Code hook entry points")
+            .action(() => {
+            hookCmd.outputHelp();
+            process.exit(1);
+        });
+        /*  register CLI sub-command "ase hook session-start"  */
+        hookCmd
+            .command("session-start")
+            .description("handle Claude Code SessionStart hook event")
+            .action(() => {
+            process.exit(this.doSessionStart());
+        });
+    }
+}

package/dst/ase.1

@@ -26,7 +26,7 @@ The following top-level command-line options exist:
 The following top-level commands exist for configuration handling:
 .RS 0
 .IP \(bu 4
-\fBase config\fR: Manage \fIASE\fR configuration stored in \fB.ase/config.yaml\fR. Without a subcommand, prints usage information. The file is validated against a schema: on read, unknown or invalid entries are warned about and silently dropped from the in-memory view; on set/write, they cause a fatal error. All \fBase config\fR subcommands accept a \fB--scope\fR \fIscope\fR option that selects the scope chain. The \fIscope\fR value is a comma-separated list of scope terms, in any order; each term is one of \fBuser\fR, \fBproject\fR, \fBtask:\fR\fIid\fR, or \fBsession:\fR\fIid\fR (where \fIid\fR matches \fB\[lB]A-Za-z0-9._-\[rB]+\fR). At most one term per kind is allowed. The chain is canonicalized into the fixed inheritance order \fBuser\fR < \fBproject\fR < \fBtask\fR < \fBsession\fR. \fBuser\fR is always implicitly added at the bottom of the chain. \fBproject\fR is implicitly added only when a \fIproject context\fR exists -- i.e. when the current working directory is inside a Git repository, or a \fB.ase\fR directory is found at or above it. Specifying \fBproject\fR explicitly without a project context is an error. Without an explicit \fB--scope\fR, the target defaults to \fBproject\fR when a project context exists, otherwise to \fBuser\fR. Reads cascade from the strongest (rightmost) scope down to the weakest and return the first value that is defined. Writes (\fBset\fR, \fBdelete\fR, \fBedit\fR, \fBinit\fR) are always confined to the strongest (target) scope's own file -- intermediate and weaker scopes are never modified. See \fIFILES\fR below for the resulting paths. Example: \fB--scope task:T1,session:S1\fR yields the chain \fBuser\fR -> \fBproject\fR -> \fBtask:T1\fR -> \fBsession:S1\fR, with \fBsession:S1\fR as the write target.
+\fBase config\fR: Manage \fIASE\fR configuration stored in \fB.ase/config.yaml\fR. Without a subcommand, prints usage information. The file is validated against a schema: on read, unknown or invalid entries are warned about and silently dropped from the in-memory view; on set/write, they cause a fatal error. Recognized keys are grouped under three top-level sections: \fBproject.*\fR (project identity, classification, and artifact globs), \fBagent.*\fR (agent persona and process), and \fBtask.*\fR (currently \fBtask.id\fR, the active task identifier). All \fBase config\fR subcommands accept a \fB--scope\fR \fIscope\fR option that selects the scope chain. The \fIscope\fR value is a comma-separated list of scope terms, in any order; each term is one of \fBuser\fR, \fBproject\fR, \fBtask:\fR\fIid\fR, or \fBsession:\fR\fIid\fR (where \fIid\fR matches \fB\[lB]A-Za-z0-9._-\[rB]+\fR). At most one term per kind is allowed. The chain is canonicalized into the fixed inheritance order \fBuser\fR < \fBproject\fR < \fBtask\fR < \fBsession\fR. \fBuser\fR is always implicitly added at the bottom of the chain. \fBproject\fR is implicitly added only when a \fIproject context\fR exists -- i.e. when the current working directory is inside a Git repository, or a \fB.ase\fR directory is found at or above it. Specifying \fBproject\fR explicitly without a project context is an error. Without an explicit \fB--scope\fR, the target defaults to \fBproject\fR when a project context exists, otherwise to \fBuser\fR. Reads cascade from the strongest (rightmost) scope down to the weakest and return the first value that is defined. Writes (\fBset\fR, \fBdelete\fR, \fBedit\fR, \fBinit\fR) are always confined to the strongest (target) scope's own file -- intermediate and weaker scopes are never modified. See \fIFILES\fR below for the resulting paths. Example: \fB--scope task:T1,session:S1\fR yields the chain \fBuser\fR -> \fBproject\fR -> \fBtask:T1\fR -> \fBsession:S1\fR, with \fBsession:S1\fR as the write target.
 .IP \(bu 4
 \fBase config init\fR \fItype\fR: Initialize \fB.ase/config.yaml\fR with preset values for all recognized keys. The \fItype\fR argument selects the preset: \fBvibe\fR (solo rookie: small black-box prototype, bare code, fully agent-driven, spec-driven, engineer ambition), \fBpro\fR (solo expert: medium white-box product, framework-based, human-controlled, code-driven, artist ambition), or \fBindustry\fR (team crew: large grey-box MVP, framework-based, human-in-the-loop, code-driven, craftsman ambition).
 .IP \(bu 4
@@ -54,18 +54,22 @@ The following top-level commands exist for service management:
 \fBase service stop\fR: Stop the background service via HTTP \fBGET /stop\fR. Exits silently with status 0 on successful stop. If no port is configured or the port is not responding, prints an informational message and exits with status 0.
 .RE 0
 
-.SH "FILES"
+.SH "CONFIGURATION FILES"
 .RS 0
 .IP \(bu 4
-\fB.ase/config.yaml\fR: Per-project \fIASE\fR configuration (scope \fBproject\fR). Read upward from the current working directory. Recognized keys: \fBproject.id\fR (non-empty string, uniqued project id), \fBproject.name\fR (non-empty string, descriptive project name), \fBproject.source.ambition\fR (\fBartist\fR|\fBcraftsman\fR|\fBengineer\fR), \fBproject.source.boxing\fR (\fBwhite\fR|\fBgrey\fR|\fBblack\fR), \fBproject.source.size\fR (\fBsmall\fR|\fBmedium\fR|\fBlarge\fR), \fBproject.source.structure\fR (\fBbare\fR|\fBlibrary\fR|\fBframework\fR), \fBproject.process.actors\fR (\fBperson\fR|\fBteam\fR|\fBcrew\fR), \fBproject.process.control\fR (\fBhuman\fR|\fBhitl\fR|\fBagent\fR), \fBproject.process.drive\fR (\fBspec\fR|\fBcode\fR|\fBtest\fR), and \fBproject.result.target\fR (\fBprototype\fR|\fBmvp\fR|\fBproduct\fR). Agent classification keys: \fBagent.persona.style\fR (\fBwriter\fR|\fBengineer\fR|\fBtelegrapher\fR|\fBcaveman\fR), \fBagent.persona.creativity\fR (\fBnone\fR|\fBlite\fR|\fBfull\fR), and \fBagent.process.autonomy\fR (\fBassistant\fR|\fBhotl\fR|\fBagent\fR).
+\fBuser\fR: \fIper-user configuration directory\fR\fB/config.yaml\fR: Per-user \fIASE\fR configuration (scope \fBuser\fR). The per-user configuration directory is \fB~/Library/Application Support/ase\fR on macOS, \fB%APPDATA%\[rs]ase\fR on Windows, and \fB$XDG_CONFIG_HOME/ase\fR (falling back to \fB~/.config/ase\fR) on Linux and other Unix systems.
 .IP \(bu 4
-\fB.ase/sessions/\fR\fIid\fR\fB/config.yaml\fR: Per-session \fIASE\fR configuration (scope \fBsession:\fR\fIid\fR), located relative to the Git top-level directory. Outside a Git repository, the file is placed under the per-user configuration directory at \fBsessions/\fR\fIid\fR\fB/config.yaml\fR.
+\fBproject\fR: \fB.ase/config.yaml\fR: Per-project \fIASE\fR configuration (scope \fBproject\fR). Read upward from the current working directory.
 .IP \(bu 4
-\fB.ase/tasks/\fR\fIid\fR\fB/config.yaml\fR: Per-task \fIASE\fR configuration (scope \fBtask:\fR\fIid\fR), located relative to the Git top-level directory. Outside a Git repository, the file is placed under the per-user configuration directory at \fBtasks/\fR\fIid\fR\fB/config.yaml\fR.
+\fBtask\fR: \fB.ase/task/\fR\fIid\fR\fB/config.yaml\fR: Per-task \fIASE\fR configuration (scope \fBtask:\fR\fIid\fR), located relative to the Git top-level directory. Outside a Git repository, the file is placed relative to the current working directory.
 .IP \(bu 4
-\fIper-user configuration directory\fR\fB/config.yaml\fR: Per-user \fIASE\fR configuration (scope \fBuser\fR). The per-user configuration directory is \fB~/Library/Application Support/ase\fR on macOS, \fB%APPDATA%\[rs]ase\fR on Windows, and \fB$XDG_CONFIG_HOME/ase\fR (falling back to \fB~/.config/ase\fR) on Linux and other Unix systems.
+\fBsession\fR: \fB~/.ase/session/\fR\fIid\fR\fB/config.yaml\fR: Per-session \fIASE\fR configuration (scope \fBsession:\fR\fIid\fR), located under the user's home directory (independent of any project context).
+.RE 0
+
+.SH "STATE FILES"
+.RS 0
 .IP \(bu 4
-\fB.ase/service.yaml\fR: Per-project service state. Recognized key: \fBport\fR (integer in \fB1024\fR..\fB65535\fR).
+\fB.ase/service.yaml\fR: Per-project service state.
 .IP \(bu 4
 \fB.ase/service.log\fR: Stdout/stderr log of the detached background service.
 .RE 0

package/dst/ase.js

@@ -8,6 +8,7 @@ import { Command, CommanderError, Option } from "commander";
 import Log from "./ase-log.js";
 import ConfigCommand from "./ase-config.js";
 import ServiceCommand from "./ase-service.js";
+import HookCommand from "./ase-hook.js";
 import pkg from "../package.json" with { type: "json" };
 /*  globally initialize logger  */
 const log = new Log("ase", "warning", "-");
@@ -38,6 +39,7 @@ const main = async () => {
     /*  register top-level commands  */
     new ConfigCommand(log).register(program);
     new ServiceCommand(log).register(program);
+    new HookCommand(log).register(program);
     /*  parse program arguments  */
     await program.parseAsync(process.argv);
     /*  gracefully terminate  */

package/package.json

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