@ludecker/aaac 1.0.0 → 1.1.1

package/README.md

@@ -24,7 +24,8 @@ npx @ludecker/aaac@latest init --yes --dir /path/to/your/repo
 
 ## What you get
 
-- `.cursor/aaac/` — ontology, graph, lifecycle, run model, generators config
+- `.cursor/hooks.json` — runtime enforcement (enable in Cursor Settings → Hooks)
+- `.cursor/aaac/` — ontology, graph, lifecycle, run model, enforcement
 - `.cursor/skills/shared/` — full pipeline (discovery → execute → verify → report)
 - `.cursor/agents/` — 13 generic subagent specs
 - `.cursor/commands/` — ~130 generated slash commands
@@ -53,8 +54,8 @@ Authenticate with a registry token in `.npmrc` (used by pnpm, not the `npm` CLI)
 
 ```bash
 pnpm --filter @ludecker/aaac publish --access public --no-git-checks
-git tag aaac-v1.0.0
-git push origin aaac-v1.0.0
+git tag aaac-v1.1.0
+git push origin aaac-v1.1.0
 ```
 
 CI publishes on `aaac-v*` tags via `.github/workflows/publish-aaac.yml` (`NPM_TOKEN` secret).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ludecker/aaac",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Agentic Architecture as Code (AAAC) — installable Cursor agent framework",
   "type": "module",
   "license": "MIT",
@@ -29,10 +29,22 @@
     "src/",
     "templates/"
   ],
+  "devDependencies": {
+    "@playwright/test": "^1.52.0",
+    "vitest": "^3.2.4",
+    "yaml": "^2.8.0"
+  },
   "engines": {
     "node": ">=18"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:node": "node --test tests/log.test.mjs",
+    "test:e2e": "pnpm exec playwright test",
+    "test:e2e:ui": "pnpm exec playwright test --ui"
   }
 }

package/src/cli.mjs

@@ -4,6 +4,7 @@ import path from "path";
 import { parseArgs } from "./lib/paths.mjs";
 import { installAaac, runGenerators } from "./lib/install.mjs";
 import { resolveCursorRoot } from "./lib/paths.mjs";
+import { runEngineScript } from "./lib/run-engine-paths.mjs";
 
 function printHelp() {
   console.log(`@ludecker/aaac — Agentic Architecture as Code
@@ -15,7 +16,9 @@ Usage:
 
 Commands:
   init      Copy AAAC kernel into .cursor/ and docs/ (default)
-  generate  Regenerate graph.yaml and commands from ontology
+  generate    Regenerate graph.yaml and commands from ontology
+  log-dump    Print Run manifest log + decisions
+  debug-run   One-shot Run status summary
 
 Options:
   --dir <path>   Target project directory (default: cwd)
@@ -89,10 +92,11 @@ AAAC installed.
   docs/        → ${docsDest}
 
 Next steps:
-  1. Open the project in Cursor
-  2. Create ${options.docsRoot}/master_rules.md and ${options.docsRoot}/architecture.md if missing
-  3. Try /review-architecture or /check-architecture
-  4. Read ${options.docsRoot}/agentic_architecture.md — Part 2 for adding domains
+  1. Enable Cursor Hooks (Settings → Hooks) and restart Cursor
+  2. Open the project in Cursor
+  3. Create ${options.docsRoot}/master_rules.md and ${options.docsRoot}/architecture.md if missing
+  4. Try /review-architecture or /check-architecture
+  5. Read ${options.docsRoot}/agentic_architecture.md — Part 2 for adding domains
 
 Regenerate after ontology changes:
   pnpm dlx @ludecker/aaac@latest generate
@@ -108,6 +112,28 @@ function cmdGenerate(args) {
   console.log("Done.");
 }
 
+function cmdLogDump(args, argv) {
+  const targetDir = args.dir ? path.resolve(args.dir) : process.cwd();
+  const passthrough = argv.filter((a) => a !== "log-dump" && a !== "--dir");
+  const runIdx = passthrough.findIndex((a) => !a.startsWith("-"));
+  if (runIdx === -1) {
+    console.error("Usage: aaac log-dump <run_id> [--level debug] [--format timeline|json|pretty] [--dir <path>]");
+    process.exit(1);
+  }
+  runEngineScript("log-dump.mjs", passthrough.slice(runIdx), targetDir);
+}
+
+function cmdDebugRun(args, argv) {
+  const targetDir = args.dir ? path.resolve(args.dir) : process.cwd();
+  const passthrough = argv.filter((a) => a !== "debug-run" && a !== "--dir");
+  const runIdx = passthrough.findIndex((a) => !a.startsWith("-"));
+  if (runIdx === -1) {
+    console.error("Usage: aaac debug-run <run_id> [--json] [--dir <path>]");
+    process.exit(1);
+  }
+  runEngineScript("debug-run.mjs", passthrough.slice(runIdx), targetDir);
+}
+
 async function main() {
   const argv = process.argv.slice(2);
   if (argv.includes("--help") || argv.includes("-h")) {
@@ -126,6 +152,14 @@ async function main() {
     cmdGenerate(args);
     return;
   }
+  if (sub === "log-dump") {
+    cmdLogDump(args, argv);
+    return;
+  }
+  if (sub === "debug-run") {
+    cmdDebugRun(args, argv);
+    return;
+  }
 
   console.error(`Unknown command: ${sub}`);
   printHelp();

package/src/generators/generate-commands.mjs

@@ -34,6 +34,105 @@ const invalid = new Set(invalid_pairs.map(([v, o]) => `${v}-${o}`));
 
 const KEEP_EXTRA = new Set(projectConfig.manual_commands ?? []);
 
+const CONTENT_WRITER_CANONICAL = "write-article";
+const FIX_MODULE_CANONICAL = "fix-module";
+
+function isFixCommand(cmd, entry) {
+  const canonical = entry?.alias ?? cmd;
+  return (
+    canonical === FIX_MODULE_CANONICAL ||
+    canonical === "fix-bug" ||
+    cmd === "module-fix" ||
+    cmd === "bug-fix"
+  );
+}
+
+function writeFixCmd(cmd, entry = null) {
+  const canonical = entry?.alias ?? cmd;
+  const isBug = canonical === "fix-bug" || cmd === "bug-fix";
+  const resolver = isBug ? "fix-bug-by-slug" : "fix-domain-by-slug";
+  const domainRequired = isBug
+    ? "Domain slug **recommended** (`cms`, `ui`, `database`, `aaac`)."
+    : "**Domain slug required** (`cms`, `ui`, `database`, `aaac`).";
+  const aliasLine =
+    cmd !== canonical
+      ? `\n\n> Alias → \`/${canonical}\`. See [${canonical}.md](${canonical}.md).\n`
+      : isBug
+        ? "\n\nAliases: `/bug-fix` → same command.\n"
+        : "\n\nAliases: `/module-fix` → same command.\n";
+  const body = `# ${cmd}
+
+AAAC: \`/${cmd} <domain> "<intent>"\`
+
+**Layer:** ${isBug ? "product" : "code"}  
+**Repair something broken** a **${isBug ? "bug" : "module"}** — full fix swarm (discovery + 7-agent investigate_swarm + root cause + gates + repro verify).${aliasLine}
+
+## Dispatch
+
+1. [.cursor/aaac/dispatch.md](../aaac/dispatch.md)
+2. [.cursor/aaac/graph.yaml](../aaac/graph.yaml) — **\`${canonical}\`**
+3. resolver **\`${resolver}\`** → \`cms-fix-bug\` | \`ui-fix-bug\` | \`database-fix-bug\` | \`aaac-fix-bug\`
+4. [investigation/SKILL.md](../skills/shared/investigation/SKILL.md) Mode A + domain \`fix_mode\`
+
+${domainRequired}
+
+## Swarm (mandatory)
+
+| Phase | Agents | Parallel |
+|-------|--------|----------|
+| discover | discovery-inventory, discovery-boundaries, discovery-ssot | 4–6 |
+| investigate_swarm | fix-repro, fix-code-path, fix-recent-changes, fix-test-failures, fix-regression-scope, fix-runtime-evidence, fix-inventory-confirm | **7** |
+| root_cause | parent + optional fix-hypothesis-validate | 0–1 |
+| verify | fix-repro-verify, unit-test-run, fallow-check-changed | **3** |
+
+Contract: [${canonical}.yaml](../aaac/contracts/commands/${canonical}.yaml)
+
+## Example
+
+\`\`\`text
+/${cmd} cms "Getting Started nav missing published guides"
+/${cmd} ui "DocsNav section state lost on route change"
+\`\`\`
+`;
+  fs.writeFileSync(path.join(commandsDir, `${cmd}.md`), body);
+}
+
+function isContentWriter(cmd, entry) {
+  const canonical = entry?.alias ?? cmd;
+  return canonical === CONTENT_WRITER_CANONICAL;
+}
+
+function writeContentWriterCmd(cmd, entry = null) {
+  const aliasLine =
+    cmd !== CONTENT_WRITER_CANONICAL
+      ? `\n\n> Alias → \`/${CONTENT_WRITER_CANONICAL}\`. See [write-article.md](write-article.md).\n`
+      : "";
+  const body = `# ${cmd}
+
+CMS writer — research swarm + agents, any \`article_type\`, persist to Supabase.${aliasLine}
+
+## Syntax
+
+\`\`\`text
+/${CONTENT_WRITER_CANONICAL} <type>, <title> [flags]
+\`\`\`
+
+Types: \`article\`, \`guide\`, \`skill\`, \`tool\`, \`command\`, \`subagent\`, \`diagram\`
+
+Flags: \`--publish\`, \`--dry-run\`, \`--update\`, \`--tags "a, b"\`
+
+## Dispatch
+
+1. [.cursor/aaac/dispatch.md](../aaac/dispatch.md)
+2. [.cursor/aaac/graph.yaml](../aaac/graph.yaml) — **\`${CONTENT_WRITER_CANONICAL}\`**
+3. Run workflow \`write-article\` → [domains/content/write/orchestrator](../domains/content/write/orchestrator/SKILL.md)
+4. [write-article skill](../skills/write-article/SKILL.md)
+
+Full reference: [write-article.md](write-article.md)
+`;
+  fs.writeFileSync(path.join(commandsDir, `${cmd}.md`), body);
+}
+
 const EXCEPTION_CMD = {
   "fix-bug": {
     layer: "product",
@@ -43,6 +142,10 @@ const EXCEPTION_CMD = {
     layer: "system",
     description: "production incident investigation",
   },
+  "publish-aaac": {
+    layer: "product",
+    description: "npm publish @ludecker/aaac with init smoke test and git tag",
+  },
 };
 
 function objectMeta(object, cmd) {
@@ -63,7 +166,9 @@ function orchestratorHint(cmd, entry) {
     const fallback =
       cmd === "fix-bug"
         ? " — unknown slug → `verb-fix` + object `feature`"
-        : "";
+        : cmd === "fix-module"
+          ? " — unknown slug → `verb-fix` + object `module`"
+          : "";
     return `resolver \`${entry.resolver}\`${fallback}`;
   }
   const verb = cmd.split("-")[0];
@@ -74,6 +179,7 @@ function orchestratorHint(cmd, entry) {
     "review-incident",
     "test-function",
     "release-app",
+    "aaac-publish",
     "write-article",
   ]);
   if (cmd === "update-architecture" || (orch && dedicated.has(orch))) {
@@ -85,7 +191,7 @@ function orchestratorHint(cmd, entry) {
 }
 
 function domainLine(cmd) {
-  if (cmd === "review-incident" || cmd.endsWith("-function")) {
+  if (cmd === "review-incident" || cmd.endsWith("-function") || cmd === "publish-aaac") {
     return "Domain optional.";
   }
   if (cmd.endsWith("-domain") || cmd.endsWith("-module")) {
@@ -95,6 +201,14 @@ function domainLine(cmd) {
 }
 
 function writeCmd(cmd, entry = null) {
+  if (isContentWriter(cmd, entry)) {
+    writeContentWriterCmd(cmd, entry);
+    return;
+  }
+  if (isFixCommand(cmd, entry)) {
+    writeFixCmd(cmd, entry);
+    return;
+  }
   const parts = cmd.split("-");
   const verb = parts[0];
   let object = parts.slice(1).join("-");
@@ -108,7 +222,9 @@ function writeCmd(cmd, entry = null) {
     ? ` (alias \`${cmd}\` → \`${entry.alias}\`)`
     : "";
   const domainArg =
-    cmd === "review-incident" || cmd.endsWith("-function") ? "" : " <domain>";
+    cmd === "review-incident" || cmd.endsWith("-function") || cmd === "publish-aaac"
+      ? ""
+      : " <domain>";
   const layerLine = layer ? `**Layer:** ${layer}  \n` : "";
   const body = `# ${cmd}
 
@@ -130,6 +246,7 @@ ${domainLine(cmd)}
 const written = new Set();
 
 for (const [cmd, entry] of Object.entries(command_overrides)) {
+  if (KEEP_EXTRA.has(`${cmd}.md`)) continue;
   writeCmd(cmd, entry);
   written.add(cmd);
 }

package/src/generators/generate-graph.mjs

@@ -148,6 +148,13 @@ const governanceGateStacksBlock = Object.entries(gates.stacks ?? {})
   .map(([name, phases]) => `  ${name}: [${phases.join(", ")}]`)
   .join("\n");
 
+const commandWorkflowsBlock = Object.entries(lifecycle.workflows ?? {})
+  .map(([cmd, def]) => {
+    const phases = composeRuntimePhases(def);
+    return `  ${cmd}: [${phases.join(", ")}]`;
+  })
+  .join("\n");
+
 const layerComment = Object.entries(data.layers ?? {})
   .sort((a, b) => a[1].order - b[1].order)
   .map(([name, L]) => `#   ${name}: ${L.objects.join(", ")}`)
@@ -207,6 +214,10 @@ ${governanceGateStacksBlock}
 verb_runtime:
 ${verbRuntimeBlock}
 
+# Exception commands — not verb×object; use for Run.pending when command matches
+command_workflows:
+${commandWorkflowsBlock}
+
 confidence:
 ${confidenceBlock}
 
@@ -220,6 +231,7 @@ ${maturityRulesBlock}
 lifecycle: aaac/lifecycle/lifecycle.json
 lifecycle_phases: aaac/lifecycle/phases.json
 governance_gates: aaac/governance/gates.json
+complexity: aaac/complexity.yaml
 run: aaac/run/schema.json
 capabilities: aaac/capabilities/registry.json
 dependencies: aaac/dependencies.yaml
@@ -240,3 +252,8 @@ if (tail.includes(INJECT_MARKER)) {
 const out = `${header}${commandsBlock}\n\n${tail}\n`;
 fs.writeFileSync(path.join(aaac, "graph.yaml"), out);
 console.log("Wrote graph.yaml");
+
+const registryScript = path.join(aaac, "scripts", "generate-runtime-registry.mjs");
+if (fs.existsSync(registryScript)) {
+  execSync(`${process.execPath} "${registryScript}"`, { stdio: "inherit" });
+}

package/src/lib/install.mjs

@@ -55,6 +55,7 @@ export function installAaac({
   copyDirRecursive(cursorSrc, cursorDest);
   ensureDir(path.join(cursorDest, "commands"));
   ensureDir(path.join(aaacDest, "state", "runs"));
+  ensureDir(path.join(aaacDest, "state", "active-runs"));
 
   const docsDest = path.join(resolvedTarget, docsRoot);
   ensureDir(docsDest);

package/src/lib/run-engine-paths.mjs

@@ -0,0 +1,33 @@
+import fs from "fs";
+import path from "path";
+import { spawnSync } from "child_process";
+import { fileURLToPath } from "url";
+
+const packageRoot = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+
+export function resolveRunEngineScript(scriptName, targetDir = process.cwd()) {
+  const projectScript = path.join(
+    targetDir,
+    ".cursor",
+    "aaac",
+    "scripts",
+    "run-engine",
+    scriptName,
+  );
+  if (fs.existsSync(projectScript)) return projectScript;
+  const bundled = path.join(packageRoot, "src", "run-engine", scriptName);
+  if (fs.existsSync(bundled)) return bundled;
+  throw new Error(`Run engine script not found: ${scriptName}`);
+}
+
+export function runEngineScript(scriptName, argv, targetDir = process.cwd()) {
+  const scriptPath = resolveRunEngineScript(scriptName, targetDir);
+  const result = spawnSync(process.execPath, [scriptPath, ...argv], {
+    stdio: "inherit",
+    cwd: targetDir,
+    env: process.env,
+  });
+  if (result.status !== 0) {
+    process.exit(result.status ?? 1);
+  }
+}