@ludecker/aaac 1.0.0 → 1.1.1

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/src/run-engine/verify-website-build.mjs

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+/**
+ * Verify website static assets + production build.
+ * Used by advance-phase on create/update/fix verify completion.
+ *
+ * Usage:
+ *   node verify-website-build.mjs [--run-id <run_id>] [--skip-build]
+ */
+import fs from "fs";
+import path from "path";
+import { spawnSync } from "child_process";
+import { fileURLToPath } from "url";
+import { REPO_ROOT, runDir, isoNow, writeJson } from "./lib.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const WEBSITE_ROOT = path.join(REPO_ROOT, "apps/website");
+const INDEX_HTML = path.join(WEBSITE_ROOT, "index.html");
+
+const args = process.argv.slice(2);
+const runIdIdx = args.indexOf("--run-id");
+const runId = runIdIdx >= 0 ? args[runIdIdx + 1] : null;
+const skipBuild = args.includes("--skip-build");
+
+const results = {
+  status: "pass",
+  checked_at: isoNow(),
+  static_assets: { status: "pass", missing: [] },
+  build: { status: skipBuild ? "skipped" : "pending", command: "pnpm --filter @ludecker/website build" },
+};
+
+function fail(section, detail) {
+  results.status = "fail";
+  if (section === "static_assets") {
+    results.static_assets.status = "fail";
+    results.static_assets.missing.push(detail);
+  } else if (section === "build") {
+    results.build.status = "fail";
+    results.build.detail = detail;
+  }
+  console.error(`[verify-website-build] FAIL ${section}: ${detail}`);
+}
+
+function resolveRootAsset(assetPath) {
+  const rel = assetPath.replace(/^\//, "");
+  const candidates = [
+    path.join(WEBSITE_ROOT, "public", rel),
+    path.join(WEBSITE_ROOT, rel),
+  ];
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+function checkStaticAssets() {
+  if (!fs.existsSync(INDEX_HTML)) {
+    fail("static_assets", `missing index.html at ${INDEX_HTML}`);
+    return;
+  }
+
+  const html = fs.readFileSync(INDEX_HTML, "utf8");
+  const rootRefs = [
+    ...html.matchAll(/\b(?:href|src)="(\/[^"#?]+)"/g),
+  ].map((match) => match[1]);
+
+  const seen = new Set();
+  for (const ref of rootRefs) {
+    if (seen.has(ref) || ref.startsWith("//")) continue;
+    seen.add(ref);
+
+    const resolved = resolveRootAsset(ref);
+    if (!resolved) {
+      fail(
+        "static_assets",
+        `${ref} not found under apps/website/public/ or apps/website/ (Vite dev resolves root paths to project root)`,
+      );
+    }
+  }
+}
+
+function runBuild() {
+  if (skipBuild) return;
+
+  const proc = spawnSync(
+    "pnpm",
+    ["--filter", "@ludecker/website", "build"],
+    {
+      cwd: REPO_ROOT,
+      encoding: "utf8",
+      env: { ...process.env, CI: "1" },
+    },
+  );
+
+  if (proc.status !== 0) {
+    const detail = [proc.stderr, proc.stdout].filter(Boolean).join("\n").trim();
+    results.build.status = "fail";
+    results.build.exit_code = proc.status ?? 1;
+    fail("build", detail || `exit ${proc.status}`);
+    return;
+  }
+
+  results.build.status = "pass";
+  results.build.exit_code = 0;
+}
+
+function writeArtifact() {
+  if (!runId) return;
+
+  const artifactDir = path.join(runDir(runId), "artifacts");
+  fs.mkdirSync(artifactDir, { recursive: true });
+
+  const yaml = [
+    `status: ${results.status}`,
+    `checked_at: ${results.checked_at}`,
+    "static_assets:",
+    `  status: ${results.static_assets.status}`,
+    `  missing: ${JSON.stringify(results.static_assets.missing)}`,
+    "build:",
+    `  status: ${results.build.status}`,
+    `  command: ${JSON.stringify(results.build.command)}`,
+    results.build.exit_code != null ? `  exit_code: ${results.build.exit_code}` : null,
+    results.build.detail ? `  detail: ${JSON.stringify(results.build.detail)}` : null,
+  ]
+    .filter(Boolean)
+    .join("\n");
+
+  fs.writeFileSync(path.join(artifactDir, "verify.yaml"), `${yaml}\n`);
+
+  const manifestPath = path.join(runDir(runId), "run.json");
+  try {
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    manifest.artifacts = manifest.artifacts ?? {};
+    manifest.artifacts.verify = results;
+    manifest.updated_at = isoNow();
+    writeJson(manifestPath, manifest);
+  } catch {
+    // run.json may not exist in standalone invocations
+  }
+}
+
+checkStaticAssets();
+runBuild();
+writeArtifact();
+
+console.log(JSON.stringify({ ok: results.status === "pass", ...results }));
+process.exit(results.status === "pass" ? 0 : 1);

package/templates/cursor/aaac/capabilities/promotion-rules.json

@@ -0,0 +1,64 @@
+{
+  "version": 1,
+  "description": "Evidence-driven capability lifecycle promotion thresholds. State belongs to capability, not provider.",
+  "states": ["experimental", "validated", "trusted", "canonical", "deprecated"],
+  "default_state": "experimental",
+  "thresholds": {
+    "validated": {
+      "min_invocations": 10
+    },
+    "trusted": {
+      "min_invocations": 25,
+      "min_success_rate": 0.8,
+      "max_rollback_rate": 0.05,
+      "max_gate_failure_rate": 0.2
+    },
+    "canonical": {
+      "min_invocations": 100,
+      "min_success_rate": 0.95,
+      "max_rollback_rate": 0.01,
+      "max_gate_failure_rate": 0.1,
+      "manual_approval": true
+    }
+  },
+  "demotion": {
+    "from_trusted": {
+      "min_invocations": 20,
+      "min_success_rate_below": 0.7
+    },
+    "to_deprecated": {
+      "manual_only": true
+    }
+  },
+  "fitness_scoring": {
+    "pass": 100,
+    "warning": 75,
+    "fail": 0
+  },
+  "runtime": {
+    "by_state": {
+      "experimental": {
+        "warn": true,
+        "require_approval_on": ["critical", "protected"]
+      },
+      "validated": {},
+      "trusted": {},
+      "canonical": {},
+      "deprecated": {
+        "block_execute": true
+      }
+    },
+    "evidence_triggers": [
+      {
+        "min_invocations": 5,
+        "min_success_rate_below": 0.5,
+        "action": "require_approval"
+      },
+      {
+        "min_invocations": 10,
+        "min_avg_fitness_below": 60,
+        "action": "require_approval"
+      }
+    ]
+  }
+}