@rse/ase 0.9.61 → 0.9.63

package/dst/ase-artifact.js

@@ -13,9 +13,9 @@ import { Task } from "./ase-task.js";
 import { writeStdout } from "./ase-stdio.js";
 /*  the recognized artifact kinds, in descending precedence order;
     "othr" is the implicit catch-all and is always resolved last  */
-export const artifactKinds = ["spec", "arch", "code", "docs", "infr", "othr"];
-/*  the five configured kinds (i.e. all kinds except the implicit "othr")  */
-const configuredKinds = ["spec", "arch", "code", "docs", "infr"];
+export const artifactKinds = ["spec", "code", "docs", "infr", "othr"];
+/*  the four configured kinds (i.e. all kinds except the implicit "othr")  */
+const configuredKinds = ["spec", "code", "docs", "infr"];
 /*  reusable functionality: resolve artifact kinds to project-relative
     file lists, driven by the "project.artifact.<kind>" configuration  */
 export class Artifact {
@@ -167,7 +167,7 @@ export class Artifact {
         const all = Artifact.universe();
         const cfg = new Config("config", configSchema, log);
         cfg.read();
-        /*  raw-resolve all five configured kinds  */
+        /*  raw-resolve all four configured kinds  */
         const raw = new Map();
         for (const kind of configuredKinds) {
             const { basedir, files } = Artifact.spec(cfg, kind);
@@ -210,6 +210,17 @@ export class Artifact {
         const { basedir } = Artifact.spec(cfg, kind);
         return basedir === "" ? file : `${basedir}/${file}`;
     }
+    /*  resolve the configured "basedir" of a kind to an absolute path;
+        the implicit "othr" catch-all has no configured "basedir" and is
+        therefore rejected  */
+    static basedir(log, kind) {
+        if (kind === "othr")
+            throw new Error("artifact: kind \"othr\" has no configured basedir");
+        const cfg = new Config("config", configSchema, log);
+        cfg.read();
+        const { basedir } = Artifact.spec(cfg, kind);
+        return path.join(Task.projectRoot(), basedir);
+    }
 }
 /*  CLI command "ase artifact"  */
 export default class ArtifactCommand {
@@ -273,12 +284,12 @@ export class ArtifactMCP {
         mcp.registerTool("ase_artifact_list", {
             title: "ASE artifact list",
             description: "Resolve one or more artifact `kind`s to project-relative file lists. " +
-                "Recognized kinds are `spec`, `arch`, `code`, `docs`, `infr`, and `othr`. " +
+                "Recognized kinds are `spec`, `code`, `docs`, `infr`, and `othr`. " +
                 "Returns an `artifacts` array of `{ kind, files }` objects. " +
                 "If `kind` is omitted or empty, all kinds are resolved.",
             inputSchema: {
                 kind: z.array(z.string()).optional()
-                    .describe("list of artifact kinds (`spec`, `arch`, `code`, `docs`, `infr`, " +
+                    .describe("list of artifact kinds (`spec`, `code`, `docs`, `infr`, " +
                     "`othr`); if omitted or empty, all kinds are resolved")
             },
             outputSchema: {
@@ -306,13 +317,13 @@ export class ArtifactMCP {
             title: "ASE artifact name",
             description: "Resolve a base-relative `filename` within an artifact `kind` to a project-relative path " +
                 "by prefixing it with the kind's configured `basedir`. " +
-                "Recognized kinds are `spec`, `arch`, `code`, `docs`, and `infr` " +
+                "Recognized kinds are `spec`, `code`, `docs`, and `infr` " +
                 "(the implicit `othr` catch-all has no basedir and is rejected). " +
                 "If `kind` is omitted, it defaults to `code`. " +
                 "Returns the resolved path as `name`.",
             inputSchema: {
                 kind: z.string().optional()
-                    .describe("artifact kind (`spec`, `arch`, `code`, `docs`, `infr`); defaults to `code`"),
+                    .describe("artifact kind (`spec`, `code`, `docs`, `infr`); defaults to `code`"),
                 filename: z.string()
                     .describe("base-relative filename within the kind's basedir")
             },

package/dst/ase-config.js

@@ -48,10 +48,9 @@ export const projectClassificationPresets = {
         "project.boxing": "white",
         "project.artifact.task.basedir": ".ase/task",
         "project.artifact.task.files": "*.md",
-        "project.artifact.spec.basedir": "doc/spec",
-        "project.artifact.spec.files": "*.{md,txt}",
-        "project.artifact.arch.basedir": "doc/arch",
-        "project.artifact.arch.files": "*.{md,txt}",
+        "project.artifact.spec.basedir": "docs/specbook",
+        "project.artifact.spec.files": "*.{md,txt,svg,png,jpg}",
+        "project.artifact.spec.schema": "",
         "project.artifact.code.basedir": "src",
         "project.artifact.code.files": "** !**/etc/** !**/{.gitignore,.npmignore,package.json}",
         "project.artifact.docs.basedir": "doc",
@@ -76,8 +75,7 @@ export const configWritableScopes = {
     "project.artifact.task.files": ["user", "project"],
     "project.artifact.spec.basedir": ["user", "project"],
     "project.artifact.spec.files": ["user", "project"],
-    "project.artifact.arch.basedir": ["user", "project"],
-    "project.artifact.arch.files": ["user", "project"],
+    "project.artifact.spec.schema": ["user", "project"],
     "project.artifact.code.basedir": ["user", "project"],
     "project.artifact.code.files": ["user", "project"],
     "project.artifact.docs.basedir": ["user", "project"],
@@ -185,6 +183,13 @@ const artifactSchema = v.optional(v.strictObject({
     basedir: v.optional(v.string()),
     files: v.optional(v.string())
 }));
+/*  schema for the "spec" artifact kind, additionally carrying the
+    SpecBook YAML "schema" configuration file (empty: bundled standard)  */
+const artifactSpecSchema = v.optional(v.strictObject({
+    basedir: v.optional(v.string()),
+    files: v.optional(v.string()),
+    schema: v.optional(v.string())
+}));
 /*  schema for ".ase/config.yaml"  */
 export const configSchema = v.nullish(v.strictObject({
     project: v.optional(v.strictObject({
@@ -192,8 +197,7 @@ export const configSchema = v.nullish(v.strictObject({
         name: v.optional(v.pipe(v.string(), v.minLength(1))),
         boxing: v.optional(v.picklist(projectClassification.boxing)),
         artifact: v.optional(v.strictObject({
-            spec: artifactSchema,
-            arch: artifactSchema,
+            spec: artifactSpecSchema,
             code: artifactSchema,
             docs: artifactSchema,
             infr: artifactSchema,

package/dst/ase-hook.js

@@ -292,6 +292,10 @@ export default class HookCommand {
         const persona = setting("agent.persona", "ASE_PERSONA_STYLE", "engineer");
         const guidance = setting("agent.guidance", "ASE_GUIDANCE_LEVEL", "normal");
         const boxing = setting("project.boxing", "ASE_PROJECT_BOXING", "white");
+        /*  determine the specification base directory and the SpecBook
+            schema configuration (empty: the bundled standard schema)  */
+        const specBasedir = String(cfg.get("project.artifact.spec.basedir") ?? "");
+        const specSchema = String(cfg.get("project.artifact.spec.schema") ?? "");
         /*  determine headless mode  */
         const headless = process.env.ASE_HEADLESS === "true" ? "true" : "false";
         /*  provide ASE information to Anthropic Claude Code CLI shell commands
@@ -303,6 +307,8 @@ export default class HookCommand {
                 `export ASE_USER_ID=${quote([userId])}\n` +
                 `export ASE_PROJECT_ID=${quote([projectId])}\n` +
                 `export ASE_PROJECT_BOXING=${quote([boxing])}\n` +
+                `export ASE_SPEC_BASEDIR=${quote([specBasedir])}\n` +
+                `export ASE_SPEC_SCHEMA=${quote([specSchema])}\n` +
                 `export ASE_TASK_ID=${quote([taskId])}\n` +
                 `export ASE_SESSION_ID=${quote([sessionId])}\n` +
                 `export ASE_HEADLESS=${quote([headless])}\n` +
@@ -325,6 +331,8 @@ export default class HookCommand {
                 `<ase-user-id>${userId}</ase-user-id>\n` +
                 `<ase-project-id>${projectId}</ase-project-id>\n` +
                 `<ase-project-boxing>${boxing}</ase-project-boxing>\n` +
+                `<ase-spec-basedir>${specBasedir}</ase-spec-basedir>\n` +
+                `<ase-spec-schema>${specSchema}</ase-spec-schema>\n` +
                 `<ase-task-id>${taskId}</ase-task-id>\n` +
                 `<ase-session-id>${sessionId}</ase-session-id>\n` +
                 `<ase-headless>${headless}</ase-headless>\n` +

package/dst/ase-service.js

@@ -22,6 +22,7 @@ import { DiagramMCP } from "./ase-diagram.js";
 import { TaskMCP } from "./ase-task.js";
 import { MarkdownMCP } from "./ase-markdown.js";
 import { ArtifactMCP } from "./ase-artifact.js";
+import { SpecMCP } from "./ase-spec.js";
 import { KVMCP } from "./ase-kv.js";
 import { TimestampMCP } from "./ase-timestamp.js";
 import { SleepMCP } from "./ase-sleep.js";
@@ -268,6 +269,7 @@ export default class ServiceCommand {
             new TaskMCP(this.log).register(mcp);
             new MarkdownMCP().register(mcp);
             new ArtifactMCP(this.log).register(mcp);
+            new SpecMCP(this.log).register(mcp);
             new KVMCP().register(mcp);
             new TimestampMCP().register(mcp);
             new SleepMCP().register(mcp);

package/dst/ase-spec.js

@@ -0,0 +1,241 @@
+/*
+**  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 { isScalar } from "yaml";
+import { z } from "zod";
+import sourceCodeError from "source-code-error";
+import { SpecBook, renderDiagnostic, renderVerbose, formats, parseOutputSpec } from "@rse/specbook";
+import { Config, configSchema } from "./ase-config.js";
+import { Task } from "./ase-task.js";
+import { Artifact } from "./ase-artifact.js";
+import { Meta } from "./ase-meta.js";
+import { writeStdout } from "./ase-stdio.js";
+/*  reusable functionality: lint and export the SpecBook-based project
+    specification, located via the "project.artifact.spec.basedir" and
+    "project.artifact.spec.schema" configuration  */
+export class Spec {
+    /*  resolve the YAML schema configuration file: the configured
+        "project.artifact.spec.schema" relative to the project root, or
+        the bundled standard "ase-format-specbook.yaml" plugin meta file
+        if unset or empty  */
+    static configFile(log) {
+        const cfg = new Config("config", configSchema, log);
+        cfg.read();
+        const val = cfg.get("project.artifact.spec.schema");
+        const file = val === undefined ? "" : String(isScalar(val) ? val.value : val);
+        if (file === "")
+            return Meta.resolve("ase-format-specbook.yaml");
+        return path.resolve(Task.projectRoot(), file);
+    }
+    /*  create the SpecBook API instance, routing its verbose processing
+        messages into the info log if requested, else into the debug log  */
+    static api(log, verbose) {
+        return new SpecBook({
+            verbose: (cmd, msg) => log.write(verbose ? "info" : "debug", `specbook: ${cmd}: ${renderVerbose(msg)}`)
+        });
+    }
+    /*  render a diagnostic file path relative to the project root,
+        keeping paths outside the project (like the bundled schema) as-is  */
+    static relativize(file) {
+        const rel = path.relative(Task.projectRoot(), file);
+        if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel))
+            return file;
+        return rel.replace(/\\/g, "/");
+    }
+    /*  lint the specification Markdown files below the "spec" artifact
+        base directory against the schema configuration  */
+    static async lint(log, verbose = false) {
+        const result = await Spec.api(log, verbose).lint({
+            config: Spec.configFile(log),
+            basedir: Artifact.basedir(log, "spec")
+        });
+        return result.diagnostics.map((d) => ({ ...d, file: Spec.relativize(d.file) }));
+    }
+    /*  render a diagnostic as a multi-line message with the affected
+        source snippet (like the verbose SpecBook CLI), falling back to
+        the single-line message when the source file is unreadable or
+        empty (as there is no snippet to show)  */
+    static render(diagnostic, colors) {
+        let code;
+        try {
+            code = fs.readFileSync(path.resolve(Task.projectRoot(), diagnostic.file), "utf8");
+        }
+        catch {
+            return `${renderDiagnostic(diagnostic)}\n`;
+        }
+        if (code === "")
+            return `${renderDiagnostic(diagnostic)}\n`;
+        return sourceCodeError({
+            message: diagnostic.message,
+            filename: diagnostic.file,
+            code,
+            line: diagnostic.line,
+            column: diagnostic.column,
+            colors
+        });
+    }
+    /*  export the specification Markdown files below the "spec" artifact
+        base directory into the requested formats, one buffer per format  */
+    static export(log, formats, verbose = false) {
+        return Spec.api(log, verbose).export({
+            config: Spec.configFile(log),
+            basedir: Artifact.basedir(log, "spec"),
+            formats
+        });
+    }
+}
+/*  CLI command "ase spec"  */
+export default class SpecCommand {
+    log;
+    constructor(log) {
+        this.log = log;
+    }
+    /*  register commands  */
+    register(program) {
+        /*  register CLI top-level command "ase spec"  */
+        const spec = program
+            .command("spec")
+            .description("Lint and export the SpecBook-based project specification")
+            .action(() => {
+            spec.outputHelp();
+            process.exit(1);
+        });
+        /*  register CLI sub-command "ase spec lint"  */
+        spec
+            .command("lint")
+            .description("Lint the specification Markdown files against the SpecBook schema configuration")
+            .option("-v, --verbose", "print verbose processing information and each diagnostic with its affected source snippet")
+            .action(async (opts) => {
+            const diagnostics = await Spec.lint(this.log, opts.verbose === true);
+            for (const diagnostic of diagnostics)
+                await writeStdout(opts.verbose === true ?
+                    Spec.render(diagnostic, process.stdout.isTTY === true) :
+                    `${renderDiagnostic(diagnostic)}\n`);
+            if (diagnostics.length > 0)
+                process.exitCode = 1;
+        });
+        /*  register CLI sub-command "ase spec export"  */
+        spec
+            .command("export")
+            .description("Export the specification Markdown files as JSON, JSON5, YAML, TOON, HTML, PDF, or normalized Markdown")
+            .option("-o, --output <[format:]file>", "output file (\"-\" for stdout, repeatable), with the format inferred " +
+            "from the filename extension unless explicitly prefixed " +
+            "(default: \"index.html\" inside the specification base directory)", (value, previous) => previous.concat(value), new Array())
+            .option("-v, --verbose", "print verbose processing information")
+            .action(async (opts) => {
+            const outputs = (opts.output.length > 0 ? opts.output :
+                [path.join(Artifact.basedir(this.log, "spec"), "index.html")]).map(parseOutputSpec);
+            const distinct = Array.from(new Set(outputs.map(({ format }) => format)));
+            const buffers = await Spec.export(this.log, distinct, opts.verbose === true);
+            for (const { format, output } of outputs) {
+                const data = buffers[distinct.indexOf(format)];
+                if (output === "-")
+                    await writeStdout(data);
+                else {
+                    await fs.promises.writeFile(output, data);
+                    this.log.write("info", `spec: exported specification into "${output}" (${data.length} bytes)`);
+                }
+            }
+        });
+    }
+}
+/*  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 SpecBook tools  */
+export class SpecMCP {
+    log;
+    constructor(log) {
+        this.log = log;
+    }
+    /*  register MCP tools  */
+    register(mcp) {
+        mcp.registerTool("ase_specbook_lint", {
+            title: "ASE SpecBook lint",
+            description: "Lint the SpecBook specification Markdown files of the project (located via the " +
+                "`project.artifact.spec.basedir` configuration) against the SpecBook YAML schema " +
+                "configuration (`project.artifact.spec.schema`, defaulting to the bundled `ase-format-specbook.yaml`). " +
+                "Returns a `diagnostics` array of `{ file, line, column, message }` objects (with " +
+                "project-relative `file`), rendered as bullet points in `text`. With `verbose`, " +
+                "each diagnostic additionally carries a multi-line `snippet` rendering with the " +
+                "affected source lines, which is also used for `text`. An empty array " +
+                "(`text` of `specification valid`) means the specification is valid.",
+            inputSchema: {
+                verbose: z.boolean().optional()
+                    .describe("if true, render each diagnostic with its affected source snippet (default: false)")
+            },
+            outputSchema: {
+                diagnostics: z.array(z.object({
+                    file: z.string().describe("project-relative file path"),
+                    line: z.number().describe("line number (1-based)"),
+                    column: z.number().describe("column number (1-based)"),
+                    message: z.string().describe("diagnostic message"),
+                    snippet: z.string().optional()
+                        .describe("multi-line rendering with the affected source snippet (with `verbose` only)")
+                })).describe("lint diagnostics, empty if the specification is valid")
+            }
+        }, async (args) => {
+            try {
+                const verbose = args.verbose ?? false;
+                const diagnostics = (await Spec.lint(this.log))
+                    .map((d) => verbose ? { ...d, snippet: Spec.render(d, false) } : d);
+                const text = diagnostics.length === 0 ? "specification valid" :
+                    verbose ?
+                        diagnostics.map((d) => d.snippet ?? "").join("").replace(/\n$/, "") :
+                        diagnostics.map((d) => `- ${renderDiagnostic(d)}`).join("\n");
+                return {
+                    structuredContent: { diagnostics },
+                    content: [{ type: "text", text }]
+                };
+            }
+            catch (err) {
+                return mcpToolError(err);
+            }
+        });
+        mcp.registerTool("ase_specbook_export", {
+            title: "ASE SpecBook export",
+            description: "Export the SpecBook specification Markdown files of the project (located via the " +
+                "`project.artifact.spec.basedir` configuration) as JSON, JSON5, YAML, TOON, HTML, PDF, " +
+                "or normalized Markdown. The result is written to the `output` file (a relative path " +
+                "resolves against the project root) if given, else it is returned directly " +
+                "(PDF as a base64-encoded resource). The export fails on any lint diagnostic.",
+            inputSchema: {
+                format: z.enum(formats).optional()
+                    .describe("output format (default: inferred from the `output` file extension, else `json`)"),
+                output: z.string().optional()
+                    .describe("output file path (\"-\" or omitted returns the result directly)")
+            }
+        }, async (args) => {
+            try {
+                /*  an explicit format takes the output as a plain file path, while
+                    otherwise the output is an "[<format>:]<file>" specification  */
+                const spec = args.format !== undefined || args.output === undefined ?
+                    { format: args.format ?? "json", output: args.output } :
+                    parseOutputSpec(args.output);
+                const [data] = await Spec.export(this.log, [spec.format]);
+                if (spec.output !== undefined && spec.output !== "-") {
+                    await fs.promises.writeFile(path.resolve(Task.projectRoot(), spec.output), data);
+                    return { content: [{ type: "text", text: `exported specification into "${spec.output}" (${data.length} bytes)` }] };
+                }
+                else if (spec.format === "pdf")
+                    return {
+                        content: [{
+                                type: "resource",
+                                resource: { uri: "ase:specbook-export.pdf", mimeType: "application/pdf", blob: data.toString("base64") }
+                            }]
+                    };
+                else
+                    return { content: [{ type: "text", text: data.toString("utf8") }] };
+            }
+            catch (err) {
+                return mcpToolError(err);
+            }
+        });
+    }
+}

package/dst/ase.js

@@ -14,6 +14,7 @@ import HookCommand from "./ase-hook.js";
 import StatuslineCommand from "./ase-statusline.js";
 import TaskCommand from "./ase-task.js";
 import ArtifactCommand from "./ase-artifact.js";
+import SpecCommand from "./ase-spec.js";
 import MetaCommand from "./ase-meta.js";
 import CompatCommand from "./ase-compat.js";
 import DiagramCommand from "./ase-diagram.js";
@@ -54,6 +55,7 @@ const main = async () => {
     new StatuslineCommand(log).register(program);
     new TaskCommand(log).register(program);
     new ArtifactCommand(log).register(program);
+    new SpecCommand(log).register(program);
     new MetaCommand(log).register(program);
     new CompatCommand().register(program);
     new DiagramCommand(log).register(program);

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.61",
+    "version":                              "0.9.63",
     "license":                              "Apache-2.0",
     "author": {
         "name":                             "Dr. Ralf S. Engelschall",
@@ -16,11 +16,11 @@
     "type":                                 "module",
     "bin":                                  { "ase": "bin/ase" },
     "devDependencies": {
-        "eslint":                           "10.9.0",
+        "eslint":                           "10.9.1",
         "@eslint/js":                       "10.0.1",
-        "@typescript-eslint/parser":        "8.67.0",
-        "@typescript-eslint/eslint-plugin": "8.67.0",
-        "typescript-eslint":                "8.67.0",
+        "@typescript-eslint/parser":        "8.68.0",
+        "@typescript-eslint/eslint-plugin": "8.68.0",
+        "typescript-eslint":                "8.68.0",
         "eslint-plugin-promise":            "7.3.0",
         "neostandard":                      "0.14.0-next.1",
         "globals":                          "17.11.0",
@@ -30,7 +30,7 @@
         "nodemon":                          "3.1.14",
         "shx":                              "0.4.0",
 
-        "@types/node":                      "26.2.0",
+        "@types/node":                      "26.3.0",
         "@types/luxon":                     "3.7.5",
         "@types/which":                     "3.0.4",
         "@types/update-notifier":           "6.0.8",
@@ -64,8 +64,10 @@
         "write-file-atomic":                "8.0.0",
         "pacote":                           "22.0.0",
         "ofetch":                           "1.5.1",
-        "picomatch":                        "4.0.5",
-        "lru-cache":                        "11.5.2"
+        "picomatch":                        "4.0.7",
+        "lru-cache":                        "11.5.2",
+        "@rse/specbook":                    "1.0.2",
+        "source-code-error":                "1.2.0"
     },
     "allowScripts": {
         "fsevents":                         true

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

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

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

@@ -15,7 +15,7 @@ Workflow
 1.  Set the requested context: <context>$ARGUMENTS</context>.
     The *first* whitespace-separated token of <context/> is the
     comma-separated *aspect set* <aspects/> (a non-empty subset of the
-    aspect ids `A01`...`A20`). The *remaining* tokens are the source
+    aspect ids `A01`...`A21`). The *remaining* tokens are the source
     code files to check.
 
 2.  Use the `Read` tool to read all source code files referenced by
@@ -28,7 +28,7 @@ Workflow
 
 4.  Set <problems/> to empty.
     Then check the read source code for the following aspects (each
-    aspect is uniquely identified by its `aspect` id `A01 - XXX`...`A20
+    aspect is uniquely identified by its `aspect` id `A01 - XXX`...`A21
     - XXX`), but *strictly limited* to those aspects whose id is
     contained in the aspect set <aspects/> -- all other aspects are
     *not* checked and their problems are *never* reported:
@@ -266,6 +266,50 @@ Workflow
         *masks* another bug (e.g., unreachable code after a misplaced
         `return` that skips cleanup logic).
 
+    -   **A21 - DOCUMENTATION**:
+        Check for *incomplete* and for *excessive* code documentation
+        across the following sub-aspects. The yardstick is a *minimal*
+        description: one or two lines stating WHAT the construct does,
+        optimally written in the *idiomatic documentation convention* of
+        the project or the target programming language.
+
+        -   **C1 MISSING-DOCUMENTATION**: functions, methods, classes,
+            interfaces, or modules without any documentation comment
+            describing their purpose -- *private* and *internal*
+            constructs included, not just the public API surface.
+            Exclude trivial constructs whose name already fully conveys
+            the purpose (plain getters/setters, one-line lambdas,
+            delegating overloads) and constructs inheriting the
+            documentation of an overridden or implemented declaration.
+            Propose *adding* those missing comments.
+
+        -   **C2 EXCESSIVE-DOCUMENTATION**: comments going far beyond
+            the minimal description: narrated decision logs ("chose X
+            over Y because ..."), change history ("now uses X instead of
+            Y"), line-by-line explanations of the obvious, or comment
+            blocks substantially longer than the code they describe.
+            Propose *condensing* to a brief 1-2 line description (up to
+            4 lines only for genuinely non-obvious constraints).
+
+        -   **C3 RESTATING-DOCUMENTATION**: comments merely repeating
+            the code or the identifier verbatim without adding any
+            information (e.g., "increment i" above `i++`). Propose
+            *removing* them.
+
+        -   **C4 DRIFTED-DOCUMENTATION**: comments contradicting the
+            code they describe (stale parameter lists, outdated behavior
+            claims). Propose *correcting* the *comment* only -- *never*
+            change the code under this aspect.
+
+        Keep intact comments stating a *constraint the code cannot
+        show* (brief WHY-comments on non-obvious decisions) -- they are
+        neither excessive nor restating.
+
+        Severity guidance: C1 defaults to MEDIUM for non-trivial
+        constructs, else LOW; C2 and C3 default to LOW, escalating to
+        MEDIUM when the noise dominates the file; and C4 defaults to
+        MEDIUM (it actively misleads).
+
     Be conservative - only report clear, well-grounded issues
     that require an actual *code change*. Think twice to avoid
     *false positives*.
@@ -277,7 +321,7 @@ Workflow
 
     For *each* found problem which requires a code change:
 
-    1.  Set <aspect/> to the identifier `A01 - XXX`...`A20 - XXX`,
+    1.  Set <aspect/> to the identifier `A01 - XXX`...`A21 - XXX`,
         indicating the aspect under which the problem was detected.
 
     2.  Set <severity/> to the string `LOW`, `MEDIUM`, or `HIGH`,

package/plugin/etc/stx.conf

@@ -6,8 +6,8 @@
 
 #   [plugin] lint project
 lint
-    markdownlint-cli2 --config etc/markdownlint.yaml meta/*.md skills/**/*.md && \
-    eslint --config etc/eslint.mjs meta skills
+    markdownlint-cli2 --config etc/markdownlint.yaml meta/*.md skills/**/*.md '!meta/ase-format-specbook.md' && \
+    eslint --config etc/eslint.mjs --ignore-pattern meta/ase-format-specbook.md meta skills
 
 #   [plugin] build project
 build : lint
@@ -17,10 +17,12 @@ build : lint
             echo "</purpose>"
         done
     ) >skills/ase-help-intent/data.md
+    specbook describe -p meta   -f raw >meta/ase-format-specbook.md
+    specbook describe -p schema -f raw >meta/ase-format-specbook.yaml
 
 #   [plugin] remove all generated files
 clean
-    true
+    shx rm -f meta/ase-format-specbook.md meta/ase-format-specbook.yaml
 
 #   [plugin] remove all built files
 distclean: clean