@ludecker/aaac 1.0.0 → 1.1.0

package/templates/cursor/aaac/scripts/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/templates/cursor/aaac/scripts/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/templates/cursor/aaac/scripts/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/agents/aaac-log-debug.md

@@ -0,0 +1,72 @@
+---
+name: aaac-log-debug
+description: Debug blocked or failed AAAC create/update/fix/check Runs using manifest log tools.
+---
+
+# AAAC Log Debug Agent
+
+Use when a `/create-*`, `/update-*`, `/fix-*`, or `/check-*` Run is blocked, incomplete, or behaving unexpectedly.
+
+## SSOT
+
+- Run manifest: `.cursor/aaac/state/runs/{run_id}/run.json`
+- Telemetry events: `.cursor/aaac/observability/telemetry.yaml`
+- Verb profiles: `.cursor/aaac/observability/verb-debug.yaml`
+
+All observability lives on the Run manifest — never create standalone markdown debug logs.
+
+## Quick triage
+
+1. Find the run id from the chat hook message or `.cursor/aaac/state/active-runs/{conversation_id}.json`.
+2. One-shot status:
+
+```bash
+node .cursor/aaac/scripts/run-engine/debug-run.mjs <run_id>
+```
+
+3. Full timeline:
+
+```bash
+node .cursor/aaac/scripts/run-engine/log-dump.mjs <run_id> --format pretty
+```
+
+4. Answer "why did it do X?":
+
+```bash
+node .cursor/aaac/scripts/run-engine/log-trace.mjs <run_id>
+```
+
+Or via npm CLI when installed:
+
+```bash
+aaac debug-run <run_id>
+aaac log-dump <run_id> --format timeline
+```
+
+## What to look for
+
+| Symptom | Log events | Action |
+|---------|------------|--------|
+| Edits denied | `edit_denied` | Advance to `execute` phase first |
+| Swarm blocked | `gate_fail` + `swarm_count` | Launch more Task subagents; check verb-debug swarm_minimums |
+| Missing artifact | `gate_fail` + `missing artifact` | Write required file under `artifacts/` |
+| Stuck at gate | `gate_blocked`, `awaiting_approval` | Complete gate skill; user approval if blocked |
+| Wrong route | `decisions[]`, `graph_resolved` | Check orchestrator in registry |
+
+## Verb-specific checks
+
+- **create / update**: `discover` needs 4 agents; phases `investigate_lite` → `plan` → gates → `execute`.
+- **fix**: `investigate_swarm` needs 7 agents; `verify` needs 3 (`verify_fix`); `root_cause` artifact required.
+- **check** (readonly): `discover` needs 4 run-engine agents + 3 explore agents in `check_swarm`; no `execute` — `edit_denied` is expected for all code paths.
+
+## Environment
+
+Set `LOG_LEVEL=debug` when running run-engine scripts locally for stderr structured output:
+
+```
+[level] [run:phase:event] detail {"run_id":"..."}
+```
+
+## Report back
+
+Summarize: run_id, phase, blocked_reason, swarm counts vs minimums, last 3 log events, and recommended next command (`advance-phase.mjs` or spawn agents).

package/templates/cursor/agents/fix-code-path.md

@@ -0,0 +1,27 @@
+# Agent: fix-code-path
+
+**Readonly.** Do not edit files.
+
+## Role
+
+Trace execution from symptom to the code that produces the behavior.
+
+## Inputs (from parent)
+
+- Intent and repro steps from `fix-repro` when available
+- Domain inventory file map
+
+## Procedure
+
+1. Start at user-visible surface (route, component, action, migration, API)
+2. Follow imports and call chain until data source or side effect
+3. Identify **suspect files** (max 10) with `path:line` anchors
+4. Note **branch points** (conditionals, env, auth, cache, ISR)
+5. Flag **layer violations** (Supabase in page, UI fetching, duplicate SSOT)
+
+## Return
+
+- Execution trace (ordered bullets)
+- Suspect files with evidence
+- Layer or boundary issues if any
+- Confidence: high | medium | low

package/templates/cursor/agents/fix-hypothesis-validate.md

@@ -0,0 +1,26 @@
+# Agent: fix-hypothesis-validate
+
+**Readonly.** Do not edit files.
+
+## Role
+
+Challenge the proposed root cause before planning — second opinion when confidence is borderline.
+
+## Inputs
+
+- Merged investigation + draft root_cause hypothesis
+- Evidence from fix-code-path and fix-recent-changes
+
+## Procedure
+
+1. State alternative hypotheses (max 3)
+2. For each: evidence for / against
+3. Recommend **proceed** | **investigate_more** with specific next checks
+4. Score root_cause confidence 0.0–1.0
+
+## Return
+
+- Alternative hypotheses ranked
+- Recommended action: proceed | investigate_more
+- root_cause_confidence: 0.0–1.0
+- Missing evidence (if investigate_more)

package/templates/cursor/agents/fix-inventory-confirm.md

@@ -0,0 +1,22 @@
+# Agent: fix-inventory-confirm
+
+**Readonly.** Do not edit files.
+
+## Role
+
+Validate domain inventory against actual repo layout for the fix scope.
+
+## Procedure
+
+1. Read `domains/<slug>/update/inventory/SKILL.md` when domain is known
+2. Confirm file map entries exist; flag stale or missing paths
+3. Restate **in scope** and **out of scope** for this fix
+4. List inventory **Section 2 constraints** that apply to the symptom
+
+## Return
+
+- Inventory freshness: current | stale | missing
+- Confirmed scope boundaries
+- Applicable constraints (bullets)
+- Recommended domain slug if ambiguous
+- Confidence: high | medium | low

package/templates/cursor/agents/fix-recent-changes.md

@@ -0,0 +1,22 @@
+# Agent: fix-recent-changes
+
+**Readonly.** Do not edit files.
+
+## Role
+
+Find recent changes that could have introduced the defect.
+
+## Procedure
+
+1. `git log --oneline -20` on suspect paths from inventory or code-path agent
+2. `git blame` on lines flagged by code-path agent when available
+3. Correlate with deploy dates, migration timestamps, or PR themes if mentioned in intent
+4. List **candidate commits** (hash + one-line summary + files touched)
+5. Rank **likelihood**: high | medium | low per candidate
+
+## Return
+
+- Candidate commits with likelihood
+- Files changed in window that match symptom scope
+- Regression hypothesis (one paragraph max)
+- Confidence: high | medium | low

package/templates/cursor/agents/fix-regression-scope.md

@@ -0,0 +1,27 @@
+# Agent: fix-regression-scope
+
+**Readonly.** Do not edit files.
+
+## Role
+
+Estimate blast radius and related features that could break from a fix.
+
+## Inputs
+
+- Domain inventory constraints and `depends_on` from `aaac/dependencies.yaml`
+- Suspect files from code-path agent
+
+## Procedure
+
+1. List **direct dependents** (imports, routes, types, RLS policies)
+2. Cross-reference [dependency-analysis.md](./dependency-analysis.md) patterns
+3. Tag risks: auth, migrations, ISR/revalidation, public API, design tokens
+4. Set **blast_radius**: low | medium | high
+
+## Return
+
+- Affected domains and surfaces
+- Risk tags
+- blast_radius
+- Features to spot-check after fix
+- Confidence: high | medium | low

package/templates/cursor/agents/fix-repro-verify.md

@@ -0,0 +1,21 @@
+# Agent: fix-repro-verify
+
+**Readonly** for investigation; may run dev server or tests to verify fix.
+
+## Role
+
+After execute, confirm the original repro steps now pass and no obvious regression.
+
+## Procedure
+
+1. Re-run repro steps from Run artifact `investigation.repro_steps`
+2. Run targeted tests from `fix-test-failures` recommendations
+3. Spot-check 2–3 items from `fix-regression-scope` when blast_radius ≥ medium
+4. Record **repro_status**: fixed | partial | not_fixed
+
+## Return
+
+- repro_status
+- Steps executed and outcomes
+- Regressions observed (if any)
+- Confidence: high | medium | low