@ludecker/aaac 1.0.0 → 1.1.0

package/templates/cursor/aaac/observability/verb-debug.yaml

@@ -0,0 +1,170 @@
+# AAAC verb-specific debug profiles — expected phases and log events
+
+version: 1
+
+create:
+  description: Create verbs — discover → investigate_lite → plan → gates → execute → verify → report.
+  phases:
+    - discover
+    - investigate_lite
+    - plan
+    - validate
+    - impact_analysis
+    - dependency_graph
+    - fitness_functions
+    - rollback
+    - execute
+    - verify
+    - report
+  swarm_minimums:
+    discover: 4
+  expected_events:
+    discover:
+      - command_parsed
+      - run_created
+      - graph_resolved
+      - phase_start
+      - agent_spawned
+      - phase_complete
+    investigate_lite:
+      - phase_start
+      - skill_loaded
+      - phase_complete
+    plan:
+      - phase_start
+      - skill_loaded
+      - phase_complete
+    validate:
+      - phase_start
+      - gate_pass
+      - phase_complete
+    execute:
+      - phase_start
+      - execute_start
+      - edit_allowed
+      - execute_complete
+      - phase_complete
+
+update:
+  description: Update verbs mirror create — discover → investigate_lite → plan → gates → execute.
+  phases:
+    - discover
+    - investigate_lite
+    - plan
+    - validate
+    - impact_analysis
+    - dependency_graph
+    - fitness_functions
+    - rollback
+    - execute
+    - verify
+    - report
+  swarm_minimums:
+    discover: 4
+  expected_events:
+    discover:
+      - command_parsed
+      - run_created
+      - graph_resolved
+      - phase_start
+      - agent_spawned
+      - phase_complete
+    investigate_lite:
+      - phase_start
+      - skill_loaded
+      - phase_complete
+    plan:
+      - phase_start
+      - skill_loaded
+      - phase_complete
+    validate:
+      - phase_start
+      - gate_pass
+      - phase_complete
+    execute:
+      - phase_start
+      - execute_start
+      - edit_allowed
+      - execute_complete
+      - phase_complete
+
+fix:
+  description: Fix verbs — investigate_swarm → root_cause → plan → gates → execute → verify_fix swarm.
+  phases:
+    - discover
+    - investigate_swarm
+    - root_cause
+    - plan
+    - validate
+    - impact_analysis
+    - dependency_graph
+    - fitness_functions
+    - rollback
+    - execute
+    - verify
+    - report
+  swarm_minimums:
+    discover: 4
+    investigate_swarm: 7
+    verify: 3
+  expected_events:
+    discover:
+      - command_parsed
+      - run_created
+      - graph_resolved
+      - phase_start
+      - agent_spawned
+      - phase_complete
+    investigate_swarm:
+      - phase_start
+      - agent_spawned
+      - skill_loaded
+      - phase_complete
+    root_cause:
+      - phase_start
+      - skill_loaded
+      - phase_complete
+    verify:
+      - phase_start
+      - agent_spawned
+      - phase_complete
+    execute:
+      - phase_start
+      - execute_start
+      - edit_allowed
+      - edit_denied
+      - execute_complete
+      - phase_complete
+
+check:
+  description: Check verbs — readonly discover → gates → report (no execute).
+  phases:
+    - discover
+    - validate
+    - impact_analysis
+    - dependency_graph
+    - fitness_functions
+    - report
+  swarm_minimums:
+    discover: 4
+    check_swarm: 3
+  expected_events:
+    discover:
+      - command_parsed
+      - run_created
+      - graph_resolved
+      - phase_start
+      - agent_spawned
+      - phase_complete
+    validate:
+      - phase_start
+      - gate_pass
+      - phase_complete
+    report:
+      - phase_start
+      - skill_loaded
+      - phase_complete
+  readonly: true
+  notes: >-
+    Orchestrator runs check_swarm (3 explore agents) during discover.
+    Edits always denied — no execute phase.

package/templates/cursor/aaac/ontology.json

@@ -122,6 +122,13 @@
     "requirements": 0.8,
     "scope": 0.8
   },
+  "complexity_ref": "aaac/complexity.yaml",
+  "complexity_strategy": {
+    "optimization": "capability_per_complexity",
+    "default_verb_when_ambiguous": "update",
+    "mutating_verbs": ["create", "update", "fix"],
+    "priority": ["reuse", "extend", "modify", "create"]
+  },
   "object_maturity": {
     "function": "evolving",
     "component": "evolving",
@@ -214,6 +221,8 @@
     "create-form": "create-component",
     "update-page": "update-component",
     "review-flow": "review-workflow",
-    "update-flow": "update-workflow"
+    "update-flow": "update-workflow",
+    "module-fix": "fix-module",
+    "bug-fix": "fix-bug"
   }
 }

package/templates/cursor/aaac/run/RUN.md

@@ -2,6 +2,8 @@
 
 **Every AAAC command executes within a Run.** There is no standalone lifecycle execution or standalone logging.
 
+**Hook enforcement:** [.cursor/hooks.json](../../hooks.json) + [enforcement.json](../enforcement.json) block code edits until `execute`. Registry: [runtime-registry.json](../runtime-registry.json).
+
 Schema: [schema.json](schema.json)
 
 ## Create Run (dispatch step 2.5 — after graph resolve, before orchestrator)

package/templates/cursor/aaac/run/schema.json

@@ -71,6 +71,15 @@
     "rollback",
     "report"
   ],
+  "plan_complexity_fields": [
+    "requirement_map",
+    "complexity_score",
+    "complexity_breakdown",
+    "reuse",
+    "modify",
+    "create",
+    "rejected_alternatives"
+  ],
   "resume": {
     "read_manifest": "state/runs/{run_id}/run.json",
     "continue_from": "phase field when status running or blocked with user approval"

package/templates/cursor/aaac/scripts/generate-runtime-registry.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+/** Emit .cursor/aaac/runtime-registry.json from ontology + lifecycle — SSOT for hooks */
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const aaac = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+);
+
+const ontology = JSON.parse(
+  fs.readFileSync(path.join(aaac, "ontology.json"), "utf8"),
+);
+const lifecycle = JSON.parse(
+  fs.readFileSync(path.join(aaac, "lifecycle/lifecycle.json"), "utf8"),
+);
+const phases = JSON.parse(
+  fs.readFileSync(path.join(aaac, "lifecycle/phases.json"), "utf8"),
+);
+const gates = JSON.parse(
+  fs.readFileSync(path.join(aaac, "governance/gates.json"), "utf8"),
+);
+
+function composeRuntimePhases(verbDef) {
+  const work = verbDef.work_phases ?? [];
+  if (!verbDef.gate_stack) return work;
+  const gatePhases = gates.stacks[verbDef.gate_stack] ?? [];
+  const executeIdx = work.indexOf("execute");
+  if (executeIdx === -1) {
+    const reportIdx = work.indexOf("report");
+    if (reportIdx <= 0) {
+      return work.length <= 1
+        ? [...work, ...gatePhases]
+        : [...work.slice(0, -1), ...gatePhases, work[work.length - 1]];
+    }
+    return [...work.slice(0, reportIdx), ...gatePhases, ...work.slice(reportIdx)];
+  }
+  return [...work.slice(0, executeIdx), ...gatePhases, ...work.slice(executeIdx)];
+}
+
+const gatePhases = {};
+for (const [id, def] of Object.entries(phases.phases ?? {})) {
+  if (def.gate) gatePhases[id] = true;
+}
+
+const commands = {};
+const aliases = { ...(ontology.command_aliases ?? {}) };
+
+for (const [cmd, entry] of Object.entries(ontology.command_overrides ?? {})) {
+  if (entry.alias) continue;
+  let pending;
+  let gate_stack = null;
+  if (lifecycle.workflows?.[cmd]) {
+    pending = composeRuntimePhases(lifecycle.workflows[cmd]);
+    gate_stack = lifecycle.workflows[cmd].gate_stack ?? null;
+  } else {
+    const verb = cmd.split("-")[0];
+    const verbDef = lifecycle.verbs?.[verb];
+    if (verbDef) {
+      pending = composeRuntimePhases(verbDef);
+      gate_stack = verbDef.gate_stack ?? null;
+    }
+  }
+  if (!pending) continue;
+  commands[cmd] = {
+    verb: cmd.split("-")[0],
+    object: cmd.includes("-") ? cmd.split("-").slice(1).join("-") : null,
+    orchestrator: entry.orchestrator ?? entry.resolver ?? null,
+    resolver: entry.resolver ?? null,
+    pending,
+    gate_stack,
+  };
+}
+
+for (const verb of Object.keys(ontology.verbs ?? {})) {
+  for (const object of Object.keys(ontology.objects ?? {})) {
+    const cmd = `${verb}-${object}`;
+    if (commands[cmd]) continue;
+    if (
+      (ontology.invalid_pairs ?? []).some(([v, o]) => v === verb && o === object)
+    ) {
+      continue;
+    }
+    const verbDef = lifecycle.verbs?.[verb];
+    if (!verbDef) continue;
+    commands[cmd] = {
+      verb,
+      object,
+      orchestrator: verb === "check" ? "verb-check" : `verb-${verb}`,
+      pending: composeRuntimePhases(verbDef),
+      gate_stack: verbDef.gate_stack ?? null,
+    };
+  }
+}
+
+for (const [alias, canonical] of Object.entries(aliases)) {
+  if (commands[canonical] && !commands[alias]) {
+    commands[alias] = { ...commands[canonical], alias_of: canonical };
+  }
+}
+
+const out = {
+  version: 1,
+  generated_at: new Date().toISOString(),
+  aliases,
+  gate_phases: gatePhases,
+  commands,
+};
+
+fs.writeFileSync(
+  path.join(aaac, "runtime-registry.json"),
+  `${JSON.stringify(out, null, 2)}\n`,
+);
+console.log(`Wrote runtime-registry.json (${Object.keys(commands).length} commands)`);

package/templates/cursor/aaac/scripts/run-engine/advance-phase.mjs

@@ -0,0 +1,192 @@
+#!/usr/bin/env node
+/**
+ * Advance Run to next phase. Validates swarm counts + required artifacts.
+ * Usage: node advance-phase.mjs <run_id> <completed_phase> [--force]
+ */
+import fs from "fs";
+import path from "path";
+import {
+  loadRegistry,
+  loadEnforcement,
+  loadRunManifest,
+  runDir,
+  isoNow,
+  phaseKind,
+  isEditPhase,
+  isGatePhase,
+  writeJson,
+  saveActiveRun,
+} from "./lib.mjs";
+import { recordLog } from "./log.mjs";
+
+const runId = process.argv[2];
+const completedPhase = process.argv[3];
+const force = process.argv.includes("--force");
+
+if (!runId || !completedPhase) {
+  console.error("Usage: advance-phase.mjs <run_id> <completed_phase> [--force]");
+  process.exit(1);
+}
+
+const registry = loadRegistry();
+const enforcement = loadEnforcement();
+const manifestPath = path.join(runDir(runId), "run.json");
+const manifest = loadRunManifest(runId);
+
+if (!manifest) {
+  console.error(`Run not found: ${runId}`);
+  process.exit(1);
+}
+
+if (manifest.phase !== completedPhase) {
+  console.error(
+    `Phase mismatch: current=${manifest.phase} completed=${completedPhase}`,
+  );
+  process.exit(1);
+}
+
+const minAgents =
+  completedPhase === "verify" &&
+  (enforcement.fix_commands?.includes(manifest.command) || manifest.verb === "fix")
+    ? enforcement.swarm_min_agents?.verify_fix
+    : enforcement.swarm_min_agents?.[completedPhase];
+const launches = manifest.swarm?.task_launches_this_phase ?? 0;
+if (minAgents && launches < minAgents && !force) {
+  recordLog(manifest, {
+    event: "gate_fail",
+    phase: completedPhase,
+    phase_kind: manifest.phase_kind,
+    detail: `swarm incomplete: ${launches}/${minAgents} agents`,
+    level: "warn",
+  });
+  manifest.updated_at = isoNow();
+  writeJson(manifestPath, manifest);
+  console.error(
+    `Swarm incomplete: phase ${completedPhase} requires ${minAgents} Task agents, got ${launches}. Launch parallel Task subagents first.`,
+  );
+  process.exit(2);
+}
+
+const requiredArtifacts = enforcement.phase_artifacts?.[completedPhase] ?? [];
+for (const rel of requiredArtifacts) {
+  const artifactPath = path.join(runDir(runId), rel);
+  if (!fs.existsSync(artifactPath)) {
+    recordLog(manifest, {
+      event: "gate_fail",
+      phase: completedPhase,
+      phase_kind: manifest.phase_kind,
+      detail: `missing artifact: ${rel}`,
+      level: "warn",
+    });
+    manifest.updated_at = isoNow();
+    writeJson(manifestPath, manifest);
+    console.error(`Missing artifact: ${rel} (required before leaving ${completedPhase})`);
+    process.exit(2);
+  }
+}
+
+const now = isoNow();
+const completedIsGate = isGatePhase(completedPhase, registry);
+
+if (completedIsGate) {
+  recordLog(manifest, {
+    event: "gate_pass",
+    phase: completedPhase,
+    phase_kind: "gate",
+    detail: "gate phase completed",
+    level: "info",
+  });
+  manifest.gates = manifest.gates ?? { stack: null, results: {} };
+  manifest.gates.results[completedPhase] = "pass";
+}
+
+if (completedPhase === "execute") {
+  recordLog(manifest, {
+    event: "execute_complete",
+    phase: completedPhase,
+    phase_kind: "work",
+    detail: "execute phase completed",
+    level: "info",
+  });
+}
+
+manifest.completed.push(completedPhase);
+recordLog(manifest, {
+  event: "phase_complete",
+  phase: completedPhase,
+  phase_kind: manifest.phase_kind,
+  detail: minAgents ? `swarm_count=${launches}` : "ok",
+  level: "info",
+});
+
+const nextPhase = manifest.pending.shift() ?? null;
+if (!nextPhase) {
+  manifest.status = "completed";
+  manifest.phase = "report";
+  manifest.enforcement.edit_allowed = false;
+  recordLog(manifest, {
+    event: "run_completed",
+    phase: "report",
+    phase_kind: "work",
+    detail: "all phases completed",
+    level: "info",
+  });
+} else {
+  manifest.phase = nextPhase;
+  manifest.phase_kind = phaseKind(nextPhase, registry);
+  manifest.swarm = { task_launches_this_phase: 0, phase: nextPhase };
+  manifest.enforcement.edit_allowed = isEditPhase(nextPhase, enforcement);
+
+  recordLog(manifest, {
+    event: "phase_start",
+    phase: nextPhase,
+    phase_kind: manifest.phase_kind,
+    detail: "advanced",
+    level: "info",
+  });
+
+  if (nextPhase === "execute") {
+    recordLog(manifest, {
+      event: "execute_start",
+      phase: nextPhase,
+      phase_kind: "work",
+      detail: "edit phase unlocked",
+      level: "info",
+    });
+  }
+
+  if (isGatePhase(nextPhase, registry)) {
+    recordLog(manifest, {
+      event: "gate_blocked",
+      phase: nextPhase,
+      phase_kind: "gate",
+      detail: "awaiting gate evaluation",
+      level: "debug",
+    });
+  }
+}
+
+manifest.updated_at = now;
+writeJson(manifestPath, manifest);
+
+saveActiveRun(manifest.conversation_id ?? null, {
+  run_id: runId,
+  conversation_id: manifest.conversation_id ?? null,
+  command: manifest.command,
+  phase: manifest.phase,
+  status: manifest.status,
+  task_launches_this_phase: 0,
+  edit_allowed: manifest.enforcement.edit_allowed,
+  started_at: manifest.created_at,
+});
+
+console.log(
+  JSON.stringify({
+    ok: true,
+    run_id: runId,
+    completed: completedPhase,
+    phase: manifest.phase,
+    status: manifest.status,
+    edit_allowed: manifest.enforcement.edit_allowed,
+  }),
+);

package/templates/cursor/aaac/scripts/run-engine/debug-run.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+/** One-shot Run status. Usage: debug-run.mjs <run_id> [--json] */
+import { loadRunManifest } from "./lib.mjs";
+import { debugRunSummary } from "./log.mjs";
+
+const runId = process.argv[2];
+const asJson = process.argv.includes("--json");
+
+if (!runId) {
+  console.error("Usage: debug-run.mjs <run_id> [--json]");
+  process.exit(1);
+}
+
+const manifest = loadRunManifest(runId);
+if (!manifest) {
+  console.error(`Run not found: ${runId}`);
+  process.exit(1);
+}
+
+const summary = debugRunSummary(manifest);
+
+if (asJson) {
+  console.log(JSON.stringify(summary, null, 2));
+  process.exit(0);
+}
+
+console.log(`Run: ${summary.run_id}`);
+console.log(`Command: /${summary.command}  verb=${summary.verb}  status=${summary.status}`);
+console.log(`Phase: ${summary.phase} (${summary.phase_kind})  edit_allowed=${summary.edit_allowed}`);
+if (summary.blocked_reason) console.log(`Blocked: ${summary.blocked_reason}`);
+console.log(`Completed: ${summary.completed.join(" → ") || "(none)"}`);
+console.log(`Pending: ${summary.pending.join(" → ") || "(none)"}`);
+console.log(`Swarm: phase=${summary.swarm.phase} count=${summary.swarm.task_launches_this_phase}`);
+console.log(`Log: ${summary.log_count} entries  Decisions: ${summary.decisions_count}`);
+console.log("--- last 10 log entries ---");
+for (const e of summary.last_log_entries) {
+  console.log(`${e.at} ${e.phase} :: ${e.event} — ${e.detail}`);
+}

package/templates/cursor/aaac/scripts/run-engine/gate-write.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+/** preToolUse — deny code edits outside execute phase for THIS chat only. */
+import path from "path";
+import {
+  loadActiveRun,
+  loadRunManifest,
+  loadEnforcement,
+  isEditPhase,
+  isArtifactPath,
+  conversationIdFromHook,
+  runDir,
+  writeJson,
+  isoNow,
+} from "./lib.mjs";
+import { recordLog } from "./log.mjs";
+
+let input = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (c) => (input += c));
+process.stdin.on("end", () => {
+  const deny = (userMessage, agentMessage, detail) => {
+    console.log(JSON.stringify({ permission: "deny", user_message: userMessage, agent_message: agentMessage }));
+    process.exit(0);
+  };
+  const allow = () => {
+    console.log(JSON.stringify({ permission: "allow" }));
+    process.exit(0);
+  };
+
+  const persistEditEvent = (manifest, runId, event, detail) => {
+    recordLog(manifest, {
+      event,
+      phase: manifest.phase,
+      phase_kind: manifest.phase_kind,
+      detail,
+      level: "debug",
+    });
+    manifest.updated_at = isoNow();
+    writeJson(path.join(runDir(runId), "run.json"), manifest);
+  };
+
+  let hook;
+  try {
+    hook = JSON.parse(input || "{}");
+  } catch {
+    allow();
+  }
+
+  const toolName = hook.tool_name ?? hook.toolName ?? "";
+  if (!/^(Write|StrReplace|Delete|EditNotebook|ApplyPatch)$/i.test(toolName)) allow();
+
+  const conversationId = conversationIdFromHook(hook);
+  if (!conversationId) allow();
+
+  const active = loadActiveRun(conversationId);
+  if (!active?.run_id || active.status === "completed") allow();
+
+  const manifest = loadRunManifest(active.run_id);
+  if (!manifest || manifest.status === "completed") allow();
+  if (manifest.conversation_id && manifest.conversation_id !== conversationId) allow();
+
+  const enforcement = loadEnforcement();
+  const filePath =
+    hook.tool_input?.path ?? hook.toolInput?.path ?? hook.tool_input?.file_path ?? hook.arguments?.path ?? "";
+
+  if (filePath && isArtifactPath(filePath, enforcement)) {
+    persistEditEvent(manifest, active.run_id, "edit_allowed", `artifact path: ${filePath}`);
+    allow();
+  }
+
+  if (manifest.awaiting_approval || manifest.status === "blocked") {
+    persistEditEvent(manifest, active.run_id, "edit_denied", `blocked at gate: ${manifest.blocked_reason ?? "approval"}`);
+    deny(`AAAC Run ${active.run_id} blocked at gate.`, `Run blocked. Run: ${active.run_id}`);
+  }
+
+  if (isEditPhase(manifest.phase, enforcement)) {
+    persistEditEvent(manifest, active.run_id, "edit_allowed", `${toolName} in phase ${manifest.phase}`);
+    allow();
+  }
+  if (enforcement.artifact_write_phases?.includes(manifest.phase) && filePath) {
+    persistEditEvent(manifest, active.run_id, "edit_allowed", `artifact_write phase ${manifest.phase}`);
+    allow();
+  }
+
+  persistEditEvent(
+    manifest,
+    active.run_id,
+    "edit_denied",
+    `${toolName} blocked in phase ${manifest.phase}${filePath ? `: ${filePath}` : ""}`,
+  );
+  deny(
+    `AAAC: edits blocked in phase "${manifest.phase}" (this chat). Run: ${active.run_id}`,
+    `Cannot ${toolName} during "${manifest.phase}". Chat ${conversationId}. Advance phase first.`,
+  );
+});