@rse/ase 0.0.8 → 0.0.10

package/dst/ase-config.js

@@ -4,6 +4,7 @@
 **  Licensed under GPL 3.0 <https://spdx.org/licenses/GPL-3.0-only>
 */
 import path from "node:path";
+import os from "node:os";
 import fs from "node:fs";
 import readline from "node:readline/promises";
 import { Document, parseDocument, isMap, isScalar } from "yaml";
@@ -20,13 +21,22 @@ export const projectClassification = {
     },
     process: {
         actors: ["person", "team", "crew"],
-        control: ["human", "hitl", "agent"],
         drive: ["spec", "code", "test"]
     },
     result: {
         target: ["prototype", "mvp", "product"]
     }
 };
+/*  agent classification taxonomy  */
+export const agentClassification = {
+    persona: {
+        style: ["writer", "engineer", "telegrapher", "caveman"],
+        creativity: ["none", "lite", "full"]
+    },
+    process: {
+        autonomy: ["assistant", "hotl", "agent"]
+    }
+};
 /*  classification presets  */
 export const projectClassificationPresets = {
     vibe: {
@@ -37,9 +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"
+        "project.result.target": "prototype",
+        "agent.persona.style": "writer",
+        "agent.persona.creativity": "full",
+        "agent.process.autonomy": "agent"
     },
     pro: {
         "project.id": "example",
@@ -49,9 +61,31 @@ 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.result.target": "product",
+        "agent.persona.style": "engineer",
+        "agent.persona.creativity": "none",
+        "agent.process.autonomy": "assistant"
+    },
+    default: {
+        "project.id": "example",
+        "project.name": "Example Project",
+        "project.source.ambition": "artist",
+        "project.source.boxing": "white",
+        "project.source.size": "medium",
+        "project.source.structure": "framework",
+        "project.process.actors": "person",
+        "project.process.drive": "code",
+        "project.result.target": "product",
+        "project.artifact.build": "{etc/**,README.md,AGENTS.md,LICENSE.txt,package.json}",
+        "project.artifact.code": "src/**/*",
+        "project.artifact.docs": "doc/user/**/*.md",
+        "project.artifact.spec": "doc/spec/**/*.md",
+        "project.artifact.arch": "doc/arch/**/*.md",
+        "agent.persona.style": "engineer",
+        "agent.persona.creativity": "none",
+        "agent.process.autonomy": "assistant",
+        "task.id": "default"
     },
     industry: {
         "project.id": "example",
@@ -61,11 +95,87 @@ 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"
+        "project.result.target": "mvp",
+        "agent.persona.style": "engineer",
+        "agent.persona.creativity": "none",
+        "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  */
+const parseScopeTerm = (value) => {
+    if (value === "user")
+        return { kind: "user" };
+    else if (value === "project")
+        return { kind: "project" };
+    const m = /^(session|task):([A-Za-z0-9._-]+)$/.exec(value);
+    if (m !== null)
+        return { kind: m[1], id: m[2] };
+    throw new Error(`invalid --scope term "${value}" ` +
+        "(expected: \"user\", \"project\", \"task:<id>\", or \"session:<id>\")");
+};
+/*  detect whether a project context exists, i.e. either we are inside
+    a Git working tree or a ".ase" directory is present at or above cwd  */
+const hasProjectContext = () => {
+    try {
+        const result = execaSync("git", ["rev-parse", "--show-toplevel"], { stderr: "ignore" });
+        if (result.stdout.trim() !== "")
+            return true;
+    }
+    catch {
+        /*  not inside a Git working tree  */
+    }
+    let dir = fs.realpathSync(process.cwd());
+    for (;;) {
+        if (fs.existsSync(path.join(dir, ".ase")))
+            return true;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return false;
+        dir = parent;
+    }
+};
+/*  parse a raw "--scope" option value into a canonical Scope chain;
+    accepts a comma-separated list of terms in any order. The "user"
+    term is always implicitly added at the bottom of the chain; the
+    "project" term is implicitly added only when a project context
+    exists (Git repository or ".ase" directory at or above cwd), and
+    an explicit "project" term requires that same context  */
+const parseScope = (value) => {
+    const projectActive = hasProjectContext();
+    const input = (value === undefined || value === "") ?
+        (projectActive ? "project" : "user") :
+        value.trim();
+    if (input === "")
+        throw new Error("invalid --scope: value must not be empty");
+    const terms = input.split(",").map((s) => parseScopeTerm(s.trim()));
+    const seen = new Set();
+    for (const t of terms) {
+        if (seen.has(t.kind))
+            throw new Error(`invalid --scope: duplicate term of kind "${t.kind}"`);
+        seen.add(t.kind);
+    }
+    if (seen.has("project") && !projectActive)
+        throw new Error("invalid --scope: \"project\" requires a project context " +
+            "(a Git repository or a \".ase\" directory at or above the current directory)");
+    if (!seen.has("project") && projectActive)
+        terms.unshift({ kind: "project" });
+    if (!seen.has("user"))
+        terms.unshift({ kind: "user" });
+    terms.sort((a, b) => scopeRank(a.kind) - scopeRank(b.kind));
+    terms.unshift({ kind: "default" });
+    return terms;
+};
 /*  schema for ".ase/config.yaml"  */
 export const configSchema = v.nullish(v.strictObject({
     project: v.optional(v.strictObject({
@@ -79,31 +189,100 @@ 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({
+        persona: v.optional(v.strictObject({
+            style: v.optional(v.picklist(agentClassification.persona.style)),
+            creativity: v.optional(v.picklist(agentClassification.persona.creativity))
+        })),
+        process: v.optional(v.strictObject({
+            autonomy: v.optional(v.picklist(agentClassification.process.autonomy))
         }))
+    })),
+    task: v.optional(v.strictObject({
+        id: v.optional(v.pipe(v.string(), v.minLength(1)))
     }))
 }));
-/*  encapsulate read/write access to a project-local ".ase/<name>.yaml" file  */
+/*  encapsulate read/write access to a stack of "<name>.yaml" configuration files,
+    each associated with a scope term; reads cascade along user < project < task < session,
+    writes are confined to the target (strongest) scope term  */
 export class Config {
+    /*  public state  */
     filename;
-    doc;
+    /*  private state  */
+    name;
+    scope;
     schema;
     log;
-    constructor(name, schema, log) {
-        const rel = path.join(".ase", `${name}.yaml`);
-        const cwd = process.cwd();
-        const top = this.gitToplevel();
-        const found = top !== null ?
-            this.findUpward(cwd, top, rel) :
-            (fs.existsSync(path.join(cwd, rel)) ? path.join(cwd, rel) : null);
-        this.filename = found ?? path.join(top ?? cwd, rel);
-        this.doc = new Document();
+    docs;
+    target;
+    /*  creation  */
+    constructor(name, schema, log, scope = [{ kind: "project" }]) {
+        if (scope.length === 0)
+            throw new Error("invalid scope: chain must not be empty");
+        this.name = name;
+        this.scope = scope[0].kind === "default" ? scope : [{ kind: "default" }, ...scope];
         this.schema = schema ?? null;
         this.log = log;
+        const tgt = this.scope[this.scope.length - 1];
+        this.filename = this.resolveFilename(name, tgt);
+        this.docs = [{ scope: tgt, filename: this.filename, doc: new Document() }];
+        this.target = 0;
+    }
+    /*  render a scope term as a short textual label  */
+    static scopeLabel(term) {
+        if (term.kind === "default" || term.kind === "user" || term.kind === "project")
+            return term.kind;
+        return `${term.kind}:${term.id}`;
+    }
+    /*  resolve the per-OS user-scope base directory  */
+    userConfigDir() {
+        if (process.platform === "darwin")
+            /*  macOS  */
+            return path.join(os.homedir(), "Library", "Application Support", "ase");
+        else if (process.platform === "win32")
+            /*  Windows  */
+            return path.join(process.env.APPDATA ?? os.homedir(), "ase");
+        else {
+            /*  Linux  */
+            const xdg = process.env.XDG_CONFIG_HOME;
+            const base = xdg !== undefined && xdg !== "" ? xdg : path.join(os.homedir(), ".config");
+            return path.join(base, "ase");
+        }
+    }
+    /*  resolve the configuration filename based on the selected scope term  */
+    resolveFilename(name, term) {
+        if (term.kind === "default")
+            throw new Error("internal error: \"default\" scope has no filename");
+        if (term.kind === "user")
+            return path.join(this.userConfigDir(), `${name}.yaml`);
+        else if (term.kind === "project") {
+            const rel = path.join(".ase", `${name}.yaml`);
+            const cwd = process.cwd();
+            const top = this.gitToplevel();
+            const found = top !== null ?
+                this.findUpward(cwd, top, rel) :
+                (fs.existsSync(path.join(cwd, rel)) ? path.join(cwd, rel) : null);
+            return found ?? path.join(top ?? cwd, rel);
+        }
+        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  */
@@ -135,31 +314,67 @@ export class Config {
             return null;
         }
     }
-    /*  read configuration file into memory  */
+    /*  read the full scope chain into memory; the requested mode applies
+        to the target scope only, inherited scopes are always lenient  */
     read(mode = "lenient") {
-        const text = fs.existsSync(this.filename) ? fs.readFileSync(this.filename, "utf8") : "";
-        this.doc = parseDocument(text);
-        if (this.doc.errors.length > 0) {
-            const msg = `invalid YAML in ${this.filename}: ${this.doc.errors[0].message}`;
-            if (mode === "strict")
-                throw new Error(msg);
-            this.log.write("warning", msg);
-            this.doc = new Document();
+        const chain = this.scope;
+        const docs = [];
+        for (let i = 0; i < chain.length; i++) {
+            const sc = chain[i];
+            if (sc.kind === "default") {
+                const doc = new Document();
+                doc.contents = doc.createNode({});
+                const preset = projectClassificationPresets.default;
+                for (const [k, val] of Object.entries(preset)) {
+                    const segments = k.split(".");
+                    for (let j = 1; j < segments.length; j++) {
+                        const prefix = segments.slice(0, j);
+                        const node = doc.getIn(prefix, true);
+                        if (node === undefined)
+                            doc.setIn(prefix, doc.createNode({}));
+                    }
+                    doc.setIn(segments, doc.createNode(val));
+                }
+                docs.push({ scope: sc, filename: "", doc });
+                continue;
+            }
+            const filename = this.resolveFilename(this.name, sc);
+            const isTarget = (i === chain.length - 1);
+            const perDocMode = isTarget ? mode : "lenient";
+            const text = fs.existsSync(filename) ? fs.readFileSync(filename, "utf8") : "";
+            let doc = parseDocument(text);
+            if (doc.errors.length > 0) {
+                const msg = `invalid YAML in ${filename}: ${doc.errors[0].message}`;
+                if (perDocMode === "strict")
+                    throw new Error(msg);
+                this.log.write("warning", msg);
+                doc = new Document();
+            }
+            docs.push({ scope: sc, filename, doc });
+        }
+        this.docs = docs;
+        this.target = docs.length - 1;
+        for (let i = 0; i < docs.length; i++) {
+            const isTarget = (i === this.target);
+            const perDocMode = isTarget ? mode : "lenient";
+            this.validateDoc(docs[i].doc, docs[i].filename, perDocMode);
         }
-        this.validate(mode);
     }
-    /*  write in-memory configuration back to file  */
+    /*  write in-memory configuration back to the target scope's file  */
     write() {
-        this.validate("strict");
-        fs.mkdirSync(path.dirname(this.filename), { recursive: true });
-        fs.writeFileSync(this.filename, this.doc.toString({ indent: 4 }), "utf8");
+        const td = this.docs[this.target];
+        if (td.scope.kind === "default")
+            throw new Error("internal error: \"default\" scope is not writable");
+        this.validateDoc(td.doc, td.filename, "strict");
+        fs.mkdirSync(path.dirname(td.filename), { recursive: true });
+        fs.writeFileSync(td.filename, td.doc.toString({ indent: 4 }), "utf8");
     }
-    /*  validate in-memory configuration against the optional schema  */
-    validate(mode = "strict") {
+    /*  validate a single YAML document against the optional schema  */
+    validateDoc(doc, filename, mode = "strict") {
         if (this.schema === null)
             return;
         for (;;) {
-            const result = v.safeParse(this.schema, this.doc.toJS());
+            const result = v.safeParse(this.schema, doc.toJS());
             if (result.success)
                 return;
             if (mode === "strict") {
@@ -167,15 +382,15 @@ export class Config {
                     const dotPath = (i.path ?? []).map((p) => String(p.key)).join(".");
                     return dotPath ? `${dotPath}: ${i.message}` : i.message;
                 }).join("; ");
-                throw new Error(`invalid configuration in ${this.filename}: ${issues}`);
+                throw new Error(`invalid configuration in ${filename}: ${issues}`);
             }
             let progressed = false;
             for (const i of result.issues) {
                 const segs = (i.path ?? []).map((p) => String(p.key));
                 const dotPath = segs.join(".");
-                this.log.write("warning", `invalid entry in ${this.filename}: ${dotPath ? `${dotPath}: ` : ""}${i.message}`);
+                this.log.write("warning", `invalid entry in ${filename}: ${dotPath ? `${dotPath}: ` : ""}${i.message}`);
                 if (segs.length > 0) {
-                    this.doc.deleteIn(segs);
+                    doc.deleteIn(segs);
                     progressed = true;
                 }
                 else
@@ -228,16 +443,84 @@ export class Config {
             throw new Error(`ambiguous key "${key}" matches: ${matches.map((m) => m.join(".")).join(", ")}`);
         return matches[0].join(".");
     }
-    /*  retrieve a value at a dotted key, or the root contents if no key given  */
+    /*  retrieve the effective value at a dotted key (strongest scope wins),
+        or the target scope's root contents if no key is given  */
     get(key) {
         if (key === undefined)
-            return this.doc.contents;
-        return this.doc.getIn(this.resolveKey(key).split("."));
+            return this.docs[this.target].doc.contents;
+        const segs = this.resolveKey(key).split(".");
+        for (let i = this.docs.length - 1; i >= 0; i--) {
+            const v = this.docs[i].doc.getIn(segs);
+            if (v !== undefined)
+                return v;
+        }
+        return undefined;
+    }
+    /*  retrieve the effective value together with the scope it came from  */
+    getWithOrigin(key) {
+        const segs = this.resolveKey(key).split(".");
+        for (let i = this.docs.length - 1; i >= 0; i--) {
+            const v = this.docs[i].doc.getIn(segs);
+            if (v !== undefined)
+                return { value: v, scope: this.docs[i].scope };
+        }
+        return undefined;
+    }
+    /*  enumerate the effective leaf entries across the full scope chain;
+        each returned entry identifies the originating scope  */
+    entries() {
+        const keys = new Set();
+        const walk = (node, prefix) => {
+            if (isMap(node))
+                for (const item of node.items) {
+                    const k = [...prefix, String(item.key)];
+                    if (isMap(item.value))
+                        walk(item.value, k);
+                    else if (isScalar(item.value))
+                        keys.add(k.join("."));
+                    else
+                        throw new Error(`key "${k.join(".")}" has unsupported node type`);
+                }
+        };
+        for (const d of this.docs)
+            walk(d.doc.contents, []);
+        const result = [];
+        for (const k of keys) {
+            const segs = k.split(".");
+            for (let i = this.docs.length - 1; i >= 0; i--) {
+                const v = this.docs[i].doc.getIn(segs);
+                if (v !== undefined) {
+                    result.push({ key: k, value: v, scope: this.docs[i].scope });
+                    break;
+                }
+            }
+        }
+        result.sort((a, b) => a.key.localeCompare(b.key));
+        return result;
     }
-    /*  set a value at a dotted key, creating intermediate maps as needed  */
+    /*  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 next = this.doc.clone();
+        const td = this.docs[this.target];
+        const next = td.doc.clone();
         for (let i = 1; i < segments.length; i++) {
             const prefix = segments.slice(0, i);
             const node = next.getIn(prefix, true);
@@ -247,27 +530,29 @@ export class Config {
                 next.setIn(prefix, next.createNode({}));
         }
         next.setIn(segments, value);
-        const saved = this.doc;
-        this.doc = next;
+        const saved = td.doc;
+        td.doc = next;
         try {
-            this.validate("strict");
+            this.validateDoc(td.doc, td.filename, "strict");
         }
         catch (err) {
-            this.doc = saved;
+            td.doc = saved;
             throw err;
         }
     }
-    /*  delete a value at a dotted key  */
+    /*  delete a value at a dotted key from the target scope  */
     delete(key) {
-        const next = this.doc.clone();
+        this.assertWritable(key);
+        const td = this.docs[this.target];
+        const next = td.doc.clone();
         next.deleteIn(this.resolveKey(key).split("."));
-        const saved = this.doc;
-        this.doc = next;
+        const saved = td.doc;
+        td.doc = next;
         try {
-            this.validate("strict");
+            this.validateDoc(td.doc, td.filename, "strict");
         }
         catch (err) {
-            this.doc = saved;
+            td.doc = saved;
             throw err;
         }
     }
@@ -283,7 +568,11 @@ export default class ConfigCommand {
         /*  register CLI top-level command "ase config"  */
         const configCmd = program
             .command("config")
-            .description("Manage ASE configuration")
+            .option("--scope <scope>", "configuration scope chain: comma-separated list of \"user\", \"project\", " +
+            "\"task:<id>\", and/or \"session:<id>\" terms (e.g. \"task:N,session:M\"); " +
+            "\"user\" is always implicitly included and \"project\" is implicitly " +
+            "included whenever a project context (Git repo or upward \".ase\" directory) exists")
+            .description("manage ASE configuration")
             .action((_opts, cmd) => {
             cmd.outputHelp();
             process.exit(1);
@@ -291,52 +580,50 @@ export default class ConfigCommand {
         /*  register CLI sub-command "ase config init"  */
         configCmd
             .command("init")
-            .description("Initialize configuration with preset values (vibe|pro|industry)")
-            .argument("<type>", "Preset type (vibe|pro|industry)")
-            .action((type) => {
+            .description("initialize configuration with preset values (default|vibe|pro|industry)")
+            .argument("<type>", "Preset type (default|vibe|pro|industry)")
+            .action((type, _opts, cmd) => {
+            const scope = parseScope(cmd.optsWithGlobals().scope);
             const preset = projectClassificationPresets[type];
             if (preset === undefined)
-                throw new Error(`unknown preset "${type}" (expected: vibe|pro|industry)`);
-            const cfg = new Config("config", configSchema, this.log);
+                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"  */
         configCmd
             .command("list")
-            .description("List all configured values as flat dotted keys")
-            .action(() => {
-            const cfg = new Config("config", configSchema, this.log);
+            .description("list all configured values as flat dotted keys")
+            .action((_opts, cmd) => {
+            const scope = parseScope(cmd.optsWithGlobals().scope);
+            const cfg = new Config("config", configSchema, this.log, scope);
             cfg.read();
             const table = new Table({
-                head: ["KEY", "VALUE"],
+                head: ["KEY", "VALUE", "SCOPE"],
                 chars: { "mid": "", "left-mid": "", "mid-mid": "", "right-mid": "" },
                 style: { head: ["blue"] }
             });
-            const list = (node, prefix) => {
-                if (isMap(node))
-                    for (const item of node.items) {
-                        const k = prefix ? `${prefix}.${item.key}` : String(item.key);
-                        if (isMap(item.value))
-                            list(item.value, k);
-                        else if (!isScalar(item.value))
-                            throw new Error(`key "${k}" has unsupported node type`);
-                        else
-                            table.push([k, String(item.value.value)]);
-                    }
-            };
-            list(cfg.get(), "");
+            for (const e of cfg.entries()) {
+                const v = isScalar(e.value) ? e.value.value : e.value;
+                table.push([e.key, String(v), Config.scopeLabel(e.scope)]);
+            }
             process.stdout.write(`${table.toString()}\n`);
         });
         /*  register CLI sub-command "ase config edit"  */
         configCmd
             .command("edit")
-            .description("Edit configuration file with $EDITOR")
-            .action(async () => {
+            .description("edit configuration file with $EDITOR")
+            .action(async (_opts, cmd) => {
+            const scope = parseScope(cmd.optsWithGlobals().scope);
             const editor = process.env.EDITOR ?? process.env.VISUAL ?? "vi";
-            const cfg = new Config("config", configSchema, this.log);
+            const cfg = new Config("config", configSchema, this.log, scope);
             fs.mkdirSync(path.dirname(cfg.filename), { recursive: true });
             if (!fs.existsSync(cfg.filename))
                 fs.writeFileSync(cfg.filename, "", "utf8");
@@ -364,10 +651,11 @@ export default class ConfigCommand {
         /*  register CLI sub-command "ase config get"  */
         configCmd
             .command("get")
-            .description("Print the value at a dotted configuration key")
-            .argument("<key>", "Configuration key (dotted path)")
-            .action((key) => {
-            const cfg = new Config("config", configSchema, this.log);
+            .description("print 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.read();
             const val = cfg.get(key);
             if (val === undefined)
@@ -379,11 +667,12 @@ export default class ConfigCommand {
         /*  register CLI sub-command "ase config set"  */
         configCmd
             .command("set")
-            .description("Set the value at a dotted configuration key")
-            .argument("<key>", "Configuration key (dotted path)")
-            .argument("<value>", "Configuration value")
-            .action((key, value) => {
-            const cfg = new Config("config", configSchema, this.log);
+            .description("set the value at a dotted configuration key")
+            .argument("<key>", "configuration key (dotted path)")
+            .argument("<value>", "configuration value")
+            .action((key, value, _opts, cmd) => {
+            const scope = parseScope(cmd.optsWithGlobals().scope);
+            const cfg = new Config("config", configSchema, this.log, scope);
             cfg.read();
             cfg.set(key, value);
             cfg.write();

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,13 +26,13 @@ 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.
+\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
 \fBase config edit\fR: Open \fB.ase/config.yaml\fR in the editor defined by the \fB$EDITOR\fR or \fB$VISUAL\fR environment variable (falling back to \fBvi\fR). The file and its parent directory are created if missing. After the editor exits, the file is re-read and schema warnings are reported.
 .IP \(bu 4
-\fBase config list\fR: List all configured values as flat dotted keys, rendered as a two-column table of \fBkey\fR and \fBvalue\fR.
+\fBase config list\fR: List all effective configured values across the scope inheritance chain, rendered as a three-column table of \fBkey\fR, \fBvalue\fR, and \fBorigin\fR. The \fBorigin\fR column identifies the scope (\fBuser\fR, \fBproject\fR, \fBtask:\fR\fIid\fR, or \fBsession:\fR\fIid\fR) that supplied each value. For overlapping keys only the value from the strongest scope is shown.
 .IP \(bu 4
 \fBase config get\fR \fIkey\fR: Print the value at the given dotted \fIkey\fR. Fails with an error if \fIkey\fR does not resolve to a leaf value.
 .IP \(bu 4
@@ -54,12 +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. 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).
+\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/service.yaml\fR: Per-project service state. Recognized key: \fBport\fR (integer in \fB1024\fR..\fB65535\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
+\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
+\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.
 .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.8",
+    "version":                              "0.0.10",
     "license":                              "GPL-3.0-only",
     "author": {
         "name":                             "Dr. Ralf S. Engelschall",