@ludecker/aaac 1.0.0 → 1.1.0

package/src/run-engine/log.mjs

@@ -0,0 +1,343 @@
+#!/usr/bin/env node
+/**
+ * AAAC Run manifest logging — SSOT: observability/telemetry.yaml
+ */
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+import { isoNow } from "./lib.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const AAAC_ROOT = path.resolve(__dirname, "../..");
+
+export const LOG_LEVEL_PRIORITY = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+};
+
+const VALID_LEVELS = new Set(Object.keys(LOG_LEVEL_PRIORITY));
+
+export function normalizeLevel(level) {
+  const normalized = (level ?? "info").toLowerCase();
+  return VALID_LEVELS.has(normalized) ? normalized : "info";
+}
+
+export function getLogLevel() {
+  return normalizeLevel(process.env.LOG_LEVEL);
+}
+
+export function shouldLog(level) {
+  return LOG_LEVEL_PRIORITY[normalizeLevel(level)] >= LOG_LEVEL_PRIORITY[getLogLevel()];
+}
+
+export function recordLog(manifest, opts) {
+  const level = normalizeLevel(opts.level ?? "info");
+  const entry = {
+    at: isoNow(),
+    run_id: manifest.run_id,
+    phase: opts.phase ?? manifest.phase ?? "dispatch",
+    phase_kind: opts.phase_kind ?? manifest.phase_kind ?? "work",
+    skill: opts.skill ?? null,
+    event: opts.event,
+    detail: opts.detail ?? "",
+    level,
+  };
+
+  manifest.log = manifest.log ?? [];
+  manifest.log.push(entry);
+
+  if (shouldLog(level)) {
+    debugPrint(entry);
+  }
+
+  return entry;
+}
+
+export function recordDecision(manifest, opts) {
+  const entry = {
+    at: isoNow(),
+    phase: opts.phase ?? manifest.phase ?? "dispatch",
+    decision: opts.decision,
+    reason: opts.reason,
+    evidence: opts.evidence ?? "",
+  };
+
+  manifest.decisions = manifest.decisions ?? [];
+  manifest.decisions.push(entry);
+
+  if (shouldLog("debug")) {
+    debugPrint({
+      level: "debug",
+      run_id: manifest.run_id,
+      phase: entry.phase,
+      event: "decision",
+      detail: entry.decision,
+      reason: entry.reason,
+      evidence: entry.evidence,
+    });
+  }
+
+  return entry;
+}
+
+export function debugPrint(entry) {
+  const level = normalizeLevel(entry.level ?? "info");
+  const phase = entry.phase ?? "—";
+  const event = entry.event ?? entry.decision ?? "—";
+  const detail = entry.detail ?? entry.reason ?? "";
+  const context = {};
+
+  if (entry.run_id) context.run_id = entry.run_id;
+  if (entry.skill) context.skill = entry.skill;
+  if (entry.phase_kind) context.phase_kind = entry.phase_kind;
+  if (entry.reason && entry.event === "decision") context.reason = entry.reason;
+  if (entry.evidence) context.evidence = entry.evidence;
+
+  const ctxStr = Object.keys(context).length ? ` ${JSON.stringify(context)}` : "";
+  process.stderr.write(`[${level}] [run:${phase}:${event}] ${detail}${ctxStr}\n`);
+}
+
+export function filterLogByLevel(entries, minLevel) {
+  const floor = LOG_LEVEL_PRIORITY[normalizeLevel(minLevel)];
+  return (entries ?? []).filter((e) => {
+    const entryLevel = e.level ? normalizeLevel(e.level) : "info";
+    return LOG_LEVEL_PRIORITY[entryLevel] >= floor;
+  });
+}
+
+export function loadVerbDebugProfiles() {
+  const profilePath = path.join(AAAC_ROOT, "observability", "verb-debug.yaml");
+  try {
+    const raw = fs.readFileSync(profilePath, "utf8");
+    return parseVerbDebugYaml(raw);
+  } catch {
+    return {};
+  }
+}
+
+function parseVerbDebugYaml(raw) {
+  const profiles = {};
+  let current = null;
+  let section = null;
+  let eventPhase = null;
+
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+
+    const profileMatch = trimmed.match(/^([a-z_]+):\s*$/);
+    if (profileMatch && !line.startsWith(" ")) {
+      current = profileMatch[1];
+      profiles[current] = { phases: [], swarm_minimums: {}, description: "" };
+      section = null;
+      eventPhase = null;
+      continue;
+    }
+
+    if (!current) continue;
+
+    if (trimmed === "phases:") {
+      section = "phases";
+      continue;
+    }
+    if (trimmed === "expected_events:") {
+      section = "events";
+      continue;
+    }
+    if (trimmed === "swarm_minimums:") {
+      section = "swarm_minimums";
+      continue;
+    }
+    if (trimmed.startsWith("description:")) {
+      profiles[current].description = trimmed.slice("description:".length).trim();
+      section = null;
+      continue;
+    }
+
+    const listItem = trimmed.match(/^- (.+)$/);
+    if (listItem && section === "phases") {
+      profiles[current].phases.push(listItem[1]);
+      continue;
+    }
+
+    const phaseKey = trimmed.match(/^([a-z_]+):\s*$/);
+    if (phaseKey && section === "events") {
+      eventPhase = phaseKey[1];
+      profiles[current].expected_events = profiles[current].expected_events ?? {};
+      profiles[current].expected_events[eventPhase] = [];
+      continue;
+    }
+
+    if (listItem && section === "events" && eventPhase) {
+      profiles[current].expected_events[eventPhase].push(listItem[1]);
+      continue;
+    }
+
+    const swarmEntry = trimmed.match(/^([a-z_]+):\s*(\d+)$/);
+    if (swarmEntry && section === "swarm_minimums") {
+      profiles[current].swarm_minimums[swarmEntry[1]] = Number(swarmEntry[2]);
+    }
+  }
+
+  return profiles;
+}
+
+export function swarmCountForPhase(log, phase) {
+  const entries = (log ?? []).filter((e) => e.phase === phase);
+  const launches = entries.filter(
+    (e) => e.event === "agent_spawned" || e.event === "task_launch",
+  );
+  if (launches.length) {
+    const last = launches[launches.length - 1];
+    const match = String(last.detail ?? "").match(/count=(\d+)/);
+    return match ? Number(match[1]) : launches.length;
+  }
+  const complete = entries.find((e) => e.event === "phase_complete");
+  if (complete) {
+    const swarmMatch = String(complete.detail ?? "").match(/swarm_count=(\d+)/);
+    if (swarmMatch) return Number(swarmMatch[1]);
+  }
+  return 0;
+}
+
+export function formatTimeline(manifest, { minLevel = "debug" } = {}) {
+  const lines = [];
+  const logs = filterLogByLevel(manifest.log ?? [], minLevel);
+  const decisions = manifest.decisions ?? [];
+
+  const merged = [
+    ...logs.map((e) => ({ ...e, kind: "log" })),
+    ...decisions.map((e) => ({
+      at: e.at,
+      phase: e.phase,
+      event: `decision:${e.decision}`,
+      detail: e.reason,
+      level: "info",
+      kind: "decision",
+      evidence: e.evidence,
+    })),
+  ].sort((a, b) => new Date(a.at) - new Date(b.at));
+
+  for (const entry of merged) {
+    const level = entry.level ?? "info";
+    const skill = entry.skill ? ` skill=${entry.skill}` : "";
+    const evidence = entry.evidence ? ` evidence="${entry.evidence}"` : "";
+    lines.push(
+      `${entry.at} [${level}] ${entry.phase} :: ${entry.event}${skill} — ${entry.detail}${evidence}`,
+    );
+  }
+
+  return lines.join("\n");
+}
+
+export function buildTrace(manifest) {
+  const verb = manifest.verb ?? "unknown";
+  const profiles = loadVerbDebugProfiles();
+  const profile = profiles[verb] ?? null;
+  const log = manifest.log ?? [];
+  const decisions = manifest.decisions ?? [];
+  const sections = [];
+
+  sections.push(`# AAAC trace: ${manifest.run_id}`);
+  sections.push(`Command: /${manifest.command}  Verb: ${verb}  Status: ${manifest.status}`);
+  if (manifest.blocked_reason) sections.push(`Blocked: ${manifest.blocked_reason}`);
+  sections.push("");
+
+  sections.push("## Why did it do this?");
+  for (const d of decisions) {
+    sections.push(`- [${d.phase}] ${d.decision}: ${d.reason}`);
+    if (d.evidence) sections.push(`  evidence: ${d.evidence}`);
+  }
+  if (!decisions.length) sections.push("- (no decisions recorded)");
+  sections.push("");
+
+  sections.push("## Which skill ran?");
+  const skillEvents = log.filter((e) => e.skill || e.event === "skill_loaded");
+  if (skillEvents.length) {
+    for (const e of skillEvents) {
+      sections.push(`- ${e.at} ${e.phase}: ${e.skill ?? e.detail}`);
+    }
+  } else {
+    sections.push("- (no skill_loaded events — infer from phase transitions)");
+    for (const e of log.filter((x) => x.event === "phase_start")) {
+      sections.push(`- phase ${e.phase} started`);
+    }
+  }
+  sections.push("");
+
+  sections.push("## Why was a route chosen?");
+  const routing = decisions.filter((d) =>
+    /route|orchestrator|capability|graph|dispatch/i.test(`${d.decision} ${d.reason}`),
+  );
+  if (routing.length) {
+    for (const d of routing) sections.push(`- ${d.decision}: ${d.reason}`);
+  } else if (manifest.orchestrator) {
+    sections.push(`- orchestrator: ${manifest.orchestrator}`);
+  } else {
+    sections.push("- (see decisions and command registry entry)");
+  }
+  sections.push("");
+
+  sections.push("## Why is the run blocked?");
+  if (manifest.status === "blocked" || manifest.awaiting_approval) {
+    sections.push(`- status=${manifest.status} awaiting_approval=${manifest.awaiting_approval}`);
+    sections.push(`- ${manifest.blocked_reason ?? "gate or swarm incomplete"}`);
+    for (const e of log.filter((x) => x.event === "edit_denied" || x.event === "gate_fail").slice(-5)) {
+      sections.push(`- ${e.at} ${e.event}: ${e.detail}`);
+    }
+  } else if (manifest.status === "running") {
+    sections.push(`- Not blocked. Current phase: ${manifest.phase}`);
+    const minAgents = profile?.swarm_minimums?.[manifest.phase];
+    if (minAgents) {
+      const count = manifest.swarm?.task_launches_this_phase ?? swarmCountForPhase(log, manifest.phase);
+      sections.push(`- Swarm: ${count}/${minAgents} agents this phase`);
+    }
+  } else {
+    sections.push(`- Run ${manifest.status}`);
+  }
+  sections.push("");
+
+  if (profile) {
+    sections.push(`## Verb profile (${verb})`);
+    if (profile.description) sections.push(profile.description);
+    sections.push(`Highlight phases: ${(profile.phases ?? []).join(" → ")}`);
+    for (const [phase, min] of Object.entries(profile.swarm_minimums ?? {})) {
+      const actual = swarmCountForPhase(log, phase);
+      sections.push(`- ${phase}: swarm ${actual}/${min} (${actual >= min ? "ok" : "INCOMPLETE"})`);
+    }
+  }
+
+  sections.push("");
+  sections.push("## Chronological timeline");
+  sections.push(formatTimeline(manifest));
+
+  return sections.join("\n");
+}
+
+export function debugRunSummary(manifest) {
+  const log = manifest.log ?? [];
+  const phase = manifest.phase;
+  const swarmPhase = manifest.swarm?.phase ?? phase;
+  const swarmCount =
+    manifest.swarm?.task_launches_this_phase ?? swarmCountForPhase(log, swarmPhase);
+
+  return {
+    run_id: manifest.run_id,
+    command: manifest.command,
+    verb: manifest.verb,
+    status: manifest.status,
+    phase,
+    phase_kind: manifest.phase_kind,
+    blocked_reason: manifest.blocked_reason,
+    awaiting_approval: manifest.awaiting_approval,
+    completed: manifest.completed ?? [],
+    pending: manifest.pending ?? [],
+    swarm: { phase: swarmPhase, task_launches_this_phase: swarmCount },
+    edit_allowed: manifest.enforcement?.edit_allowed ?? false,
+    last_log_entries: log.slice(-10),
+    decisions_count: (manifest.decisions ?? []).length,
+    log_count: log.length,
+  };
+}

package/src/run-engine/record-task.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+import path from "path";
+import {
+  loadActiveRun,
+  loadRunManifest,
+  runDir,
+  writeJson,
+  saveActiveRun,
+  isoNow,
+  conversationIdFromHook,
+} 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 allow = () => {
+    console.log(JSON.stringify({ permission: "allow" }));
+    process.exit(0);
+  };
+
+  let hook;
+  try {
+    hook = JSON.parse(input || "{}");
+  } catch {
+    allow();
+  }
+
+  const conversationId = conversationIdFromHook(hook);
+  if (!conversationId) allow();
+
+  const active = loadActiveRun(conversationId);
+  if (!active?.run_id) allow();
+
+  const manifest = loadRunManifest(active.run_id);
+  if (!manifest || manifest.status === "completed") allow();
+  if (manifest.conversation_id && manifest.conversation_id !== conversationId) allow();
+
+  manifest.swarm = manifest.swarm ?? {};
+  manifest.swarm.task_launches_this_phase = (manifest.swarm.task_launches_this_phase ?? 0) + 1;
+  manifest.swarm.phase = manifest.phase;
+  manifest.updated_at = isoNow();
+
+  recordLog(manifest, {
+    event: "agent_spawned",
+    phase: manifest.phase,
+    phase_kind: manifest.phase_kind,
+    detail: `count=${manifest.swarm.task_launches_this_phase}`,
+    level: "debug",
+  });
+
+  writeJson(path.join(runDir(active.run_id), "run.json"), manifest);
+  saveActiveRun(conversationId, { ...active, task_launches_this_phase: manifest.swarm.task_launches_this_phase });
+  allow();
+});

package/src/run-engine/stop-check.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+import path from "path";
+import {
+  loadActiveRun,
+  loadRunManifest,
+  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", () => {
+  let hook = {};
+  try {
+    hook = JSON.parse(input || "{}");
+  } catch {
+    process.exit(0);
+  }
+
+  const conversationId = conversationIdFromHook(hook);
+  if (!conversationId) process.exit(0);
+
+  const active = loadActiveRun(conversationId);
+  if (!active?.run_id) process.exit(0);
+
+  const manifest = loadRunManifest(active.run_id);
+  if (!manifest || manifest.status === "completed") process.exit(0);
+
+  const remaining = [manifest.phase, ...(manifest.pending ?? [])].filter(Boolean);
+
+  recordLog(manifest, {
+    event: "run_incomplete",
+    phase: manifest.phase,
+    phase_kind: manifest.phase_kind,
+    detail: `stop hook: status=${manifest.status} remaining=${remaining.join("→")}`,
+    level: "warn",
+  });
+  manifest.updated_at = isoNow();
+  writeJson(path.join(runDir(active.run_id), "run.json"), manifest);
+
+  console.log(
+    JSON.stringify({
+      followup_message: [
+        `AAAC Run ${active.run_id} incomplete (this chat). Phase: ${manifest.phase}.`,
+        `Remaining: ${remaining.join(" → ")}`,
+        `Advance: node .cursor/aaac/scripts/run-engine/advance-phase.mjs ${active.run_id} ${manifest.phase}`,
+        `Debug: node .cursor/aaac/scripts/run-engine/debug-run.mjs ${active.run_id}`,
+      ].join("\n"),
+    }),
+  );
+});

package/templates/cursor/aaac/complexity.yaml

@@ -0,0 +1,98 @@
+# Complexity governance — SSOT for create / update / fix (code-changing verbs)
+# Policy: .cursor/policies/minimal-complexity.md
+# Scored in plan; validated at validate gate; enforced at fitness_functions gate.
+
+version: 1
+
+mutating_verbs: [create, update, fix]
+
+optimization:
+  target: "maximum outcome / minimum structure"
+  default_verb_when_ambiguous: update
+
+strategy_priority:
+  - reuse_existing
+  - extend_existing
+  - modify_existing
+  - create_new
+
+scoring:
+  description: Sum weights for every net-new artifact in the plan (not edits to existing files).
+  weights:
+    new_file: 1
+    new_component: 1
+    new_function: 1
+    new_hook: 1
+    new_module: 3
+    new_service: 5
+    new_api_endpoint: 2
+    new_table: 3
+    new_migration: 2
+    new_state_machine: 4
+    new_queue_or_bus: 5
+    new_abstraction_layer: 4
+    new_orchestrator: 4
+    new_skill: 2
+    new_dependency: 2
+
+thresholds:
+  fix: 5
+  update: 8
+  create: 12
+
+yagni:
+  rule: Future requirements do not exist unless the user stated them.
+  reject_without_user_evidence:
+    - maybe later
+    - might need
+    - future-proof
+    - future proof
+    - scalability
+    - extensibility
+    - plugin system
+    - event bus
+    - generic framework
+    - abstraction layer
+    - for flexibility
+    - potential use case
+
+plan_artifact:
+  path: Run.artifacts.plan
+  required_for_verbs: [create, update, fix]
+  required_fields:
+    requirement_map:
+      description: Each stated requirement mapped to satisfying artifacts
+      item_shape:
+        requirement: string
+        satisfies_with: list
+    complexity_score: number
+    complexity_breakdown: object
+    reuse:
+      description: Existing artifacts to reuse or extend (preferred)
+      type: list
+    modify:
+      description: Existing artifacts to change in place
+      type: list
+    create:
+      description: Net-new artifacts — each must cite requirement_map entry
+      item_shape:
+        artifact: string
+        kind: string
+        requirement_ref: string
+        why_not_reuse: string
+    rejected_alternatives:
+      description: Higher-complexity options considered and rejected
+      type: list
+
+gate_rules:
+  validate:
+    fail_when:
+      - missing required plan fields for mutating verb
+      - create entry without requirement_ref or why_not_reuse
+      - yagni phrase in plan without user intent evidence
+  fitness_functions:
+    function: minimal_complexity
+    fail_when:
+      - complexity_score above threshold for verb
+      - speculative create not justified
+    blocking: true

package/templates/cursor/aaac/contracts/commands/fix-bug.yaml

@@ -1,12 +1,13 @@
 name: fix-bug
-purpose: Repair broken behavior in a domain
+purpose: Repair broken behavior in a domain (alias of fix-module workflow)
 inputs:
   domain:
     required: false
+    enum: [cms, ui, database, aaac]
   intent:
     required: true
 outputs:
-  findings:
+  investigation:
     type: markdown
     required: true
   root_cause:
@@ -24,9 +25,15 @@ outputs:
     type: markdown
     required: true
 lifecycle_verb: fix
+workflow: fix-bug
 success_criteria:
-  - deep investigation and root_cause before plan
+  - discovery swarm completed (4-6 agents)
+  - fix investigation swarm completed (7 parallel agents)
+  - root_cause confidence at least 0.7
+  - repro_status fixed after execute
   - impact_analysis proceed yes or rollback defined
 failure_conditions:
+  - skip discovery or investigate_swarm phase
   - root_cause confidence below 0.7
   - symptom patch without root cause frame
+  - repro_status not_fixed while claiming success

package/templates/cursor/aaac/contracts/commands/fix-module.yaml

@@ -0,0 +1,41 @@
+name: fix-module
+purpose: Repair broken behavior in a bounded domain module
+inputs:
+  domain:
+    required: true
+    enum: [cms, ui, database, aaac]
+  intent:
+    required: true
+outputs:
+  investigation:
+    type: markdown
+    required: true
+  root_cause:
+    type: markdown
+    required: true
+  plan:
+    type: markdown
+    required: true
+  implementation:
+    type: code_changes
+  verification:
+    type: markdown
+    required: true
+  report:
+    type: markdown
+    required: true
+lifecycle_verb: fix
+workflow: fix-module
+success_criteria:
+  - discovery swarm completed (4-6 agents)
+  - fix investigation swarm completed (7 parallel agents)
+  - root_cause confidence at least 0.7
+  - repro_status fixed after execute
+  - domain inventory Section 3 synced after execute
+  - complexity_score at most 5
+failure_conditions:
+  - skip discovery or investigate_swarm phase
+  - plan or execute before root_cause artifact
+  - symptom patch without root cause frame
+  - repro_status not_fixed while claiming success
+  - domain slug missing for resolver commands

package/templates/cursor/aaac/contracts/skills/investigation.yaml

@@ -1,9 +1,22 @@
 name: investigation
-purpose: Deep investigation for fix paths and incidents
+purpose: Deep investigation swarm for fix paths and incidents
 outputs:
+  investigation_frame:
+    type: object
+    required: true
   findings:
     type: list
     required: true
+  repro_steps:
+    type: list
+    required: true
+  repro_confirmed:
+    type: string
+    required: true
+    enum: [yes, partial, no]
+  suspect_files:
+    type: list
+    required: true
   risks:
     type: list
     required: true
@@ -14,4 +27,12 @@ outputs:
     type: object
     required: true
     fields: [architecture, requirements, scope]
+swarm:
+  fix_path:
+    prerequisite: discovery
+    agents: 7
+    parallel: mandatory
+  incident_path:
+    agents: 4
+    parallel: mandatory
 readonly: true

package/templates/cursor/aaac/contracts/skills/planning.yaml

@@ -0,0 +1,17 @@
+name: planning
+purpose: Plan mutating changes with complexity score and requirement map before execute
+applies_to_verbs: [create, update, fix]
+outputs:
+  plan:
+    type: object
+    required_for_verbs: [create, update, fix]
+    required_fields:
+      - requirement_map
+      - complexity_score
+      - complexity_breakdown
+      - reuse
+      - modify
+      - create
+      - rejected_alternatives
+    store_at: Run.artifacts.plan
+readonly: true

package/templates/cursor/aaac/contracts/skills/validation.yaml

@@ -1,5 +1,6 @@
 name: validation
-purpose: Confidence gates before execute
+purpose: Confidence and complexity gates before execute (mutating verbs)
+applies_to_verbs: [create, update, fix]
 outputs:
   validation:
     type: enum
@@ -8,6 +9,13 @@ outputs:
   scores:
     type: object
     required: true
+  complexity:
+    type: object
+    required_for_verbs: [create, update, fix]
+    fields:
+      score: number
+      threshold: number
+      pass: boolean
   clarification_questions:
     type: list
     required_when: validation fail