stealthos-cli 0.1.0-alpha.3 → 0.1.0-alpha.4

package/ai/server/aios-server.mjs

@@ -0,0 +1,2134 @@
+#!/usr/bin/env node
+// AI OS — MCP Server (stdio, pure Node, zero deps)
+// Speaks JSON-RPC 2.0 over stdin/stdout per the Model Context Protocol.
+// Optional HTTP mode: --http [--port N]
+//
+// Usage:
+//   node server/aios-server.mjs                 # MCP stdio (default)
+//   node server/aios-server.mjs --http          # HTTP server on port 47781 (auto-fallback)
+//   node server/aios-server.mjs --http --port 8080
+
+import { readFile, readdir, stat, writeFile, mkdir, appendFile } from "node:fs/promises";
+import { existsSync, statSync, readFileSync, readdirSync } from "node:fs";
+import { join, dirname, resolve, relative, sep, normalize } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { spawn } from "node:child_process";
+import { createServer } from "node:http";
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import readline from "node:readline";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// ---------- StealthOS multi-tenant resolution (ADR-0012) ----------
+// MODE:
+//   'embedded' (default) — knowledge base & project state both in <project>/.ai/
+//   'hybrid'             — knowledge base in ~/.stealthos/, project state in ~/.stealthos/projects/<hash>/
+const STEALTHOS_MODE = (process.env.STEALTHOS_MODE || "embedded").toLowerCase();
+const STEALTHOS_HOME = process.env.STEALTHOS_HOME || join(homedir(), ".stealthos");
+
+// PROJECT_ROOT: where the user's code lives. In embedded mode, derived from server location.
+// In hybrid mode, the server is in ~/.stealthos/ and the project is wherever the MCP client launched us.
+const PROJECT_ROOT = STEALTHOS_MODE === "hybrid"
+  ? (process.env.STEALTHOS_PROJECT_DIR || process.cwd())
+  : resolve(__dirname, "..", "..");
+
+function computeProjectHash(absPath) {
+  return createHash("sha256").update(normalize(resolve(absPath)), "utf8").digest("hex").slice(0, 12);
+}
+const PROJECT_HASH = computeProjectHash(PROJECT_ROOT);
+
+// KB_DIR — Knowledge base (canonical OS: rules, workflows, manifest, ROUTER, hooks, blueprints, templates)
+const KB_DIR = STEALTHOS_MODE === "hybrid" ? STEALTHOS_HOME : join(PROJECT_ROOT, ".ai");
+
+// PROJECT_STATE_DIR — Project-specific state (runtime, memory, snapshots, context, artifacts, specs, architecture)
+const PROJECT_STATE_DIR = STEALTHOS_MODE === "hybrid"
+  ? join(STEALTHOS_HOME, "projects", PROJECT_HASH)
+  : join(PROJECT_ROOT, ".ai");
+
+// Legacy alias — AI_DIR is kept for code that pre-dates the split.
+// In embedded mode it equals both KB_DIR and PROJECT_STATE_DIR.
+// In hybrid mode it points to KB_DIR for backward-compat reads (knowledge base ops).
+const AI_DIR = KB_DIR;
+
+// ---------- Runtime v0.1 (optional, lazy) ----------
+// Imports the compiled TS runtime from ./dist/index.mjs if available.
+// If absent (build not run yet), daemon continues with the 12 base tools only.
+let runtime = null;
+let runtimeLoadError = null;
+const RUNTIME_DIST_PATH = join(__dirname, "dist", "index.mjs");
+try {
+  if (existsSync(RUNTIME_DIST_PATH)) {
+    runtime = await import(pathToFileURL(RUNTIME_DIST_PATH).href);
+  }
+} catch (e) {
+  runtimeLoadError = String(e && e.message ? e.message : e);
+  process.stderr.write(`[aios] Runtime v0.1 dist failed to load: ${runtimeLoadError}\n`);
+}
+
+// ---------- Args ----------
+const args = process.argv.slice(2);
+const HTTP_MODE = args.includes("--http");
+const portIdx = args.indexOf("--port");
+const REQUESTED_PORT = portIdx > -1 ? parseInt(args[portIdx + 1], 10) : 47781;
+
+// ---------- Utility: safe path ----------
+// Resolves a relative path to its absolute form, restricted to the AI OS allowlist.
+// Mode-aware (ADR-0012): in 'hybrid', knowledge-base paths resolve to KB_DIR (~/.stealthos/)
+// and project-state paths to PROJECT_STATE_DIR (~/.stealthos/projects/<hash>/).
+// In 'embedded', everything resolves under PROJECT_ROOT/.ai/ as before.
+const PROJECT_STATE_PREFIXES = ["memory", "runtime", "snapshots", "context", "artifacts", "specs", "architecture", "product"];
+
+function safeResolve(rel) {
+  const clean = rel.replace(/^[\/\\]+/, "");
+
+  // Project files (always under user's cwd, regardless of mode)
+  const projectFileMatches =
+    clean === "CLAUDE.md" || clean === "GEMINI.md" || clean === "GPT.md" || clean === "AGENTS.md" ||
+    clean === ".claude" || clean.startsWith(".claude/") || clean.startsWith(".claude\\") ||
+    clean.startsWith(".ai/scripts/") || clean.startsWith(".ai\\scripts\\");
+  if (projectFileMatches) {
+    const baseAbs = resolve(PROJECT_ROOT);
+    const abs = resolve(baseAbs, clean);
+    if (!abs.startsWith(baseAbs)) throw new Error("Path traversal blocked");
+    return abs;
+  }
+
+  // Determine base: project-state prefix → PROJECT_STATE_DIR; else → KB_DIR
+  const firstSeg = clean.split(/[\/\\]/)[0];
+  const baseRaw = PROJECT_STATE_PREFIXES.includes(firstSeg) ? PROJECT_STATE_DIR : KB_DIR;
+  // resolve(base) normalizes separators so startsWith() works on Windows even if env var used /
+  const base = resolve(baseRaw);
+  const abs = resolve(base, clean);
+  if (!abs.startsWith(base)) throw new Error("Path traversal blocked");
+  return abs;
+}
+
+async function readDoc(rel) {
+  const abs = safeResolve(rel);
+  return await readFile(abs, "utf8");
+}
+
+async function listDir(rel) {
+  const abs = safeResolve(rel);
+  const entries = await readdir(abs, { withFileTypes: true });
+  return entries.map((e) => ({ name: e.name, type: e.isDirectory() ? "dir" : "file" }));
+}
+
+// ---------- Router parser ----------
+let routerCache = null;
+async function parseRouter() {
+  if (routerCache) return routerCache;
+  const txt = await readFile(join(AI_DIR, "ROUTER.md"), "utf8");
+  const routes = [];
+  // Pattern: heading "### Title" followed by **Triggers**: list and **Load**: code block
+  const sections = txt.split(/\n###\s+/).slice(1);
+  for (const sec of sections) {
+    const lines = sec.split("\n");
+    const title = lines[0].trim();
+    const triggersMatch = sec.match(/\*\*Triggers\*\*:\s*(.+)/);
+    const loadMatch = sec.match(/\*\*Load\*\*:\s*\n```\n([\s\S]*?)\n```/);
+    if (!triggersMatch || !loadMatch) continue;
+    const triggers = triggersMatch[1]
+      .split(",")
+      .map((s) => s.trim().replace(/^`|`$/g, "").toLowerCase())
+      .filter(Boolean);
+    const files = loadMatch[1]
+      .split("\n")
+      .map((s) => s.trim())
+      .filter(Boolean);
+    routes.push({ title, triggers, files });
+  }
+  routerCache = routes;
+  return routes;
+}
+
+function normalizeQuery(q) {
+  return String(q || "").toLowerCase();
+}
+
+async function routeQuery(query) {
+  const routes = await parseRouter();
+  const q = normalizeQuery(query);
+  const matched = [];
+  const files = new Set();
+  for (const r of routes) {
+    for (const t of r.triggers) {
+      if (t && q.includes(t)) {
+        matched.push({ route: r.title, trigger: t });
+        for (const f of r.files) files.add(f);
+        break;
+      }
+    }
+  }
+  // Always include CORE
+  const CORE = [
+    ".ai/INDEX.md",
+    ".ai/CONTRACT.md",
+    ".ai/ROUTER.md",
+    ".ai/rules/dont.md",
+    ".ai/rules/behavior.md",
+    ".ai/memory/project-context.md",
+  ];
+  for (const f of CORE) files.add(f);
+  return { core: CORE, matched, files: [...files] };
+}
+
+// ---------- Classifier ----------
+function classifyTask(query) {
+  const q = normalizeQuery(query);
+
+  // Trivial signals: short, factual, no action verbs
+  const len = q.length;
+  const wordCount = q.split(/\s+/).length;
+  const isQuestion = /^(qual|quais|como|o que|onde|quando|por que|por quê|when|what|where|why|how)\b/.test(q) || q.endsWith("?");
+  const isLookup = /(lista|listar|mostra|mostrar|mostre|ler|show|read|describe|cite|cita)/.test(q);
+  const hasEditVerbs = /(adiciona|adicionar|cria|criar|modifica|modificar|altera|alterar|refator|implementa|implementar|build|criar?|adicionar?|escreva|fix|corrige|corrigir|add|create|update|change|implement)/.test(q);
+  const hasArchKeywords = /(arquitetura|architecture|adr|trade.?off|microservi|escala|sharding|schema migration|api contract|breaking change)/.test(q);
+  const hasMultiFile = /(em todos|all files|cross-?module|atravessa|toda a app|toda aplicação|toda a base)/.test(q);
+
+  let cls = "trivial";
+  const reasons = [];
+
+  if (hasArchKeywords || hasMultiFile) {
+    cls = "complex";
+    if (hasArchKeywords) reasons.push("contém palavra-chave arquitetural");
+    if (hasMultiFile) reasons.push("escopo cross-module aparente");
+  } else if (hasEditVerbs) {
+    cls = "simple";
+    reasons.push("verbo de edição presente");
+  } else if (isQuestion || isLookup) {
+    cls = "trivial";
+    reasons.push("pergunta/lookup");
+  } else if (len > 280 || wordCount > 50) {
+    cls = "simple";
+    reasons.push("tamanho do prompt sugere tarefa não-trivial");
+  }
+
+  return { classification: cls, reasons, wordCount, length: len };
+}
+
+// ---------- Lint runner ----------
+async function runLint() {
+  return new Promise((resolveProm) => {
+    const isWin = process.platform === "win32";
+    const cmd = isWin ? "powershell" : "bash";
+    const scriptPs = join(PROJECT_ROOT, ".ai", "scripts", "lint-os.ps1");
+    const scriptSh = join(PROJECT_ROOT, ".ai", "scripts", "lint-os.sh");
+    const script = isWin ? scriptPs : (existsSync(scriptSh) ? scriptSh : scriptPs);
+    const argsRun = isWin
+      ? ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", script, "-TargetPath", PROJECT_ROOT]
+      : [script];
+    const child = spawn(cmd, argsRun, { cwd: PROJECT_ROOT });
+    let out = "";
+    let err = "";
+    child.stdout.on("data", (d) => (out += d));
+    child.stderr.on("data", (d) => (err += d));
+    child.on("close", (code) => {
+      resolveProm({ exitCode: code, stdout: out, stderr: err });
+    });
+    child.on("error", (e) => resolveProm({ exitCode: -1, stdout: "", stderr: String(e) }));
+  });
+}
+
+async function runDetectStack(targetPath) {
+  return new Promise((resolveProm) => {
+    const isWin = process.platform === "win32";
+    const cmd = isWin ? "powershell" : "bash";
+    const scriptPs = join(PROJECT_ROOT, ".ai", "scripts", "detect-stack.ps1");
+    const scriptSh = join(PROJECT_ROOT, ".ai", "scripts", "detect-stack.sh");
+    const script = isWin ? scriptPs : (existsSync(scriptSh) ? scriptSh : scriptPs);
+    const argsRun = isWin
+      ? ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", script, "-TargetPath", targetPath]
+      : [script, "--target", targetPath];
+    const child = spawn(cmd, argsRun, { cwd: PROJECT_ROOT });
+    let out = "";
+    let err = "";
+    child.stdout.on("data", (d) => (out += d));
+    child.stderr.on("data", (d) => (err += d));
+    child.on("close", (code) => {
+      resolveProm({ exitCode: code, stdout: out, stderr: err });
+    });
+    child.on("error", (e) => resolveProm({ exitCode: -1, stdout: "", stderr: String(e) }));
+  });
+}
+
+// ---------- Memory search ----------
+async function searchMemory(query, maxResults = 20) {
+  const memDir = join(PROJECT_STATE_DIR, "memory");
+  const files = await readdir(memDir);
+  const q = normalizeQuery(query);
+  const results = [];
+  for (const f of files) {
+    const abs = join(memDir, f);
+    const st = await stat(abs).catch(() => null);
+    if (!st || !st.isFile()) continue;
+    if (!f.endsWith(".md")) continue;
+    const content = await readFile(abs, "utf8");
+    const lines = content.split("\n");
+    lines.forEach((line, idx) => {
+      if (line.toLowerCase().includes(q)) {
+        results.push({ file: `.ai/memory/${f}`, line: idx + 1, text: line.trim() });
+      }
+    });
+  }
+  return results.slice(0, maxResults);
+}
+
+// ---------- CORE bundle ----------
+async function getCoreBundle() {
+  const CORE = [
+    ".ai/INDEX.md",
+    ".ai/CONTRACT.md",
+    ".ai/ROUTER.md",
+    ".ai/rules/dont.md",
+    ".ai/rules/behavior.md",
+    ".ai/memory/project-context.md",
+  ];
+  const out = [];
+  for (const f of CORE) {
+    try {
+      const content = await readDoc(f);
+      out.push(`<file path="${f}">\n${content}\n</file>`);
+    } catch (e) {
+      out.push(`<file path="${f}" error="${e.message}"/>`);
+    }
+  }
+  return out.join("\n\n");
+}
+
+async function getManifest() {
+  const m = await readFile(join(AI_DIR, "manifest.json"), "utf8");
+  return JSON.parse(m);
+}
+
+async function getSummary() {
+  try {
+    return await readFile(join(PROJECT_STATE_DIR, "memory", "_summary.md"), "utf8");
+  } catch {
+    return "(_summary.md ainda não foi gerado — rode /compact-memory)";
+  }
+}
+
+// ---------- Audit validator ----------
+function validateAudit(text) {
+  const required = ["Files touched:", "Memory updated:", "Validations:", "Decisions:", "Open items:"];
+  const missing = required.filter((k) => !text.includes(k));
+  return {
+    valid: missing.length === 0,
+    missing,
+    hasHeader: text.includes("[OS Audit]"),
+  };
+}
+
+// ---------- Tools registry ----------
+const TOOLS = [
+  {
+    name: "aios_get_core_bundle",
+    description: "Retorna o pacote CORE do AI OS (INDEX + CONTRACT + ROUTER + rules/dont + rules/behavior + memory/project-context). Use no início de cada sessão como atalho a 6 reads.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  },
+  {
+    name: "aios_route_query",
+    description: "Dado o texto da tarefa do usuário, retorna a lista determinística de arquivos a carregar (CORE + conditional matched pelo ROUTER.md).",
+    inputSchema: {
+      type: "object",
+      properties: { query: { type: "string", description: "Texto/intent da tarefa." } },
+      required: ["query"],
+    },
+  },
+  {
+    name: "aios_classify_task",
+    description: "Classifica uma tarefa como trivial | simple | complex usando heurística baseada em verbos e escopo.",
+    inputSchema: {
+      type: "object",
+      properties: { query: { type: "string" } },
+      required: ["query"],
+    },
+  },
+  {
+    name: "aios_read",
+    description: "Lê um arquivo do AI OS (.ai/, CLAUDE.md, GEMINI.md, GPT.md, .claude/, scripts/). Path traversal bloqueado.",
+    inputSchema: {
+      type: "object",
+      properties: { path: { type: "string", description: "Caminho relativo ao project root." } },
+      required: ["path"],
+    },
+  },
+  {
+    name: "aios_list",
+    description: "Lista o conteúdo de um diretório do AI OS.",
+    inputSchema: {
+      type: "object",
+      properties: { path: { type: "string" } },
+      required: ["path"],
+    },
+  },
+  {
+    name: "aios_search_memory",
+    description: "Busca substring em todos os arquivos de .ai/memory/. Retorna trechos com arquivo e linha.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string" },
+        max_results: { type: "number", default: 20 },
+      },
+      required: ["query"],
+    },
+  },
+  {
+    name: "aios_get_summary",
+    description: "Retorna .ai/memory/_summary.md (resumo rotativo dos últimos 90 dias).",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  },
+  {
+    name: "aios_get_manifest",
+    description: "Retorna .ai/manifest.json — fonte da verdade estrutural.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  },
+  {
+    name: "aios_lint",
+    description: "Roda o lint do OS (manifest + links + frontmatter). Retorna stdout/stderr/exit code.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  },
+  {
+    name: "aios_detect_stack",
+    description: "Inspeciona um diretório de projeto e detecta linguagens, frameworks, infra, CI, smells.",
+    inputSchema: {
+      type: "object",
+      properties: { target_path: { type: "string", description: "Caminho absoluto do projeto a inspecionar." } },
+      required: ["target_path"],
+    },
+  },
+  {
+    name: "aios_validate_audit",
+    description: "Valida se um bloco [OS Audit] tem todos os campos obrigatórios.",
+    inputSchema: {
+      type: "object",
+      properties: { text: { type: "string" } },
+      required: ["text"],
+    },
+  },
+  {
+    name: "aios_health",
+    description: "Health check do daemon. Retorna versão, uptime, project root, .ai/ status.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  },
+  {
+    name: "aios_analyze_project",
+    description: "Roda o Project State Engine: detecta stack, mapeia módulos (AST via ts-morph), constrói grafo de dependências, detecta smells. Persiste .ai/context/project-state.{json,md}. Requer Runtime v0.1 compilado (dist/index.mjs).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        scan_dirs: {
+          type: "array",
+          items: { type: "string" },
+          description: "Diretórios relativos ao project root para escanear. Padrão: ['.ai/server/src', 'src', 'lib', 'app', 'packages'].",
+        },
+        write: { type: "boolean", description: "Persistir arquivos em .ai/context/. Padrão: true." },
+      },
+    },
+  },
+  {
+    name: "aios_build_context_package",
+    description: "Gera um Context Package otimizado: stack + módulos relevantes (YAML-blocks) + decisões/erros/issues do memory + smells. Substitui dump de arquivos brutos.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        intent: { type: "string", description: "Descrição da tarefa para guiar a seleção de módulos relevantes." },
+        max_modules: { type: "number", description: "Limite de módulos no pacote. Padrão: 12." },
+        write: { type: "boolean", description: "Persistir em .ai/context/packages/<slug>.md. Padrão: true." },
+      },
+    },
+  },
+  {
+    name: "aios_snapshot",
+    description: "Cria snapshot do estado atual: project-state + hashes SHA-256 dos arquivos rastreados (.ai, .claude, CLAUDE.md, GEMINI.md, GPT.md) + memory snapshot. Salva em .ai/snapshots/<id>/.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        label: { type: "string", description: "Rótulo curto para o snapshot (ex.: 'pre-v01-refactor')." },
+      },
+      required: ["label"],
+    },
+  },
+  {
+    name: "aios_snapshot_list",
+    description: "Lista todos os snapshots existentes em .ai/snapshots/ (mais novos primeiro).",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  },
+  {
+    name: "aios_snapshot_diff",
+    description: "Compara dois snapshots: arquivos adicionados/removidos/alterados, módulos, delta de smells.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        a: { type: "string", description: "ID do snapshot base." },
+        b: { type: "string", description: "ID do snapshot comparado." },
+      },
+      required: ["a", "b"],
+    },
+  },
+  {
+    name: "aios_run_workflow",
+    description: "Executa um workflow determinístico declarado em .ai/workflows/<name>.json. Workflow encadeia chamadas a tools primitivas com tratamento de erro por step. Use isso em vez de chamar tools individuais quando houver um workflow registrado (init, sync, work). Retorna relatório de execução com status por step.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: {
+          type: "string",
+          description: "Nome do workflow (ex.: 'init', 'sync', 'work'). Mapeia para .ai/workflows/<name>.json.",
+        },
+        input: {
+          type: "object",
+          description: "Valores substituídos em ${input.X} dentro dos args dos steps. Ex.: { intent: 'refactor auth module' }.",
+          additionalProperties: true,
+        },
+      },
+      required: ["name"],
+    },
+  },
+  {
+    name: "aios_list_workflows",
+    description: "Lista os workflows disponíveis em .ai/workflows/ com id, versão, descrição e número de steps.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  },
+  {
+    name: "aios_state_get",
+    description: "Lê estado operacional do AI OS de .ai/runtime/state.json. Sem path → retorna state completo. Com path → retorna sub-valor por dotted path (ex.: 'lifecycle.phase', 'identity.maturity').",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Dotted path opcional. Ex.: 'lifecycle.phase'." },
+      },
+    },
+  },
+  {
+    name: "aios_state_set",
+    description: "Atualiza um campo do state.json por dotted path. Atualiza updated_at automaticamente. Use para mudanças avulsas; para phase/mode use aios_state_advance.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Dotted path (ex.: 'rotating.active_focus')." },
+        value: { description: "Valor a atribuir (qualquer tipo JSON)." },
+      },
+      required: ["path", "value"],
+    },
+  },
+  {
+    name: "aios_state_advance",
+    description: "Atalho para avançar lifecycle: muda state.lifecycle.phase e/ou state.lifecycle.mode. Pelo menos um dos dois é obrigatório. Reporta diff.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        phase: { enum: ["discovery", "planning", "implementation", "stabilization", "production"] },
+        mode: { enum: ["readonly", "analysis", "execution", "validation"] },
+      },
+    },
+  },
+  {
+    name: "aios_state_reset",
+    description: "Recria state.json com baseline (lifecycle=discovery/analysis, identity vazia, listas vazias). DESTRUTIVO: workflow_history é perdido. Use só em reset deliberado.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  },
+  {
+    name: "aios_compile_runtime_context",
+    description: "Project State Compiler (ADR-0007). Consolida state.json + project-state + últimas decisions + top-N módulos + memory rotating num único JSON otimizado (.ai/runtime/runtime-context.json, target ≤4000 tokens). Use no início do /work em vez de carregar tudo separado.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        max_modules: { type: "number", description: "Limite de módulos a incluir. Default 10." },
+        max_decisions: { type: "number", description: "Limite de ADRs recentes. Default 5." },
+        write: { type: "boolean", description: "Persistir em runtime-context.json. Default true." },
+      },
+    },
+  },
+  {
+    name: "aios_detect_drift",
+    description: "Documentation Drift Detection (ADR-0007). Compara estado atual com último snapshot: módulos sem spec referenciada, specs sem código, módulos órfãos. Retorna severity tiers (info|warning).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        since_snapshot: { type: "string", description: "ID do snapshot base. Default: snapshot mais recente." },
+      },
+    },
+  },
+  {
+    name: "aios_get_context",
+    description: "Atalho para Context Layers (ADR-0007). Devolve só o tier pedido: 'core' (INDEX+CONTRACT+ROUTER+rules+memory), 'working' (state+project-state resumo+rotating memory+top decisions), 'deep' (working+full project-state+full memory+all decisions).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        layer: { enum: ["core", "working", "deep"], description: "Tier de contexto." },
+        focus: { type: "string", description: "Tema/intent opcional para priorização." },
+      },
+      required: ["layer"],
+    },
+  },
+  {
+    name: "aios_artifact_list",
+    description: "Lista artefatos do AI OS (specs, snapshots, packages, ADRs, RFCs) com metadata. Filtros opcionais por tipo/status.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        type: { enum: ["ADR", "RFC", "PRD", "SDD", "RUNBOOK", "TASK", "BRD", "snapshot", "package", "workflow"] },
+        status: { type: "string", description: "Filtro de status (ex.: 'accepted' para ADRs)." },
+      },
+    },
+  },
+  {
+    name: "aios_resume_workflow",
+    description: "Retoma um workflow pausado (status:'paused'). Use o execution_id devolvido por aios_run_workflow + forneça user_input para o pause point.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        execution_id: { type: "string" },
+        user_input: { description: "Resposta do usuário ao prompt da pausa. Qualquer tipo JSON." },
+      },
+      required: ["execution_id"],
+    },
+  },
+  {
+    name: "aios_list_paused_executions",
+    description: "Lista execuções pausadas em .ai/runtime/paused-executions/ (TTL default 30 min).",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  },
+  {
+    name: "aios_cancel_paused_execution",
+    description: "Cancela e remove uma execução pausada.",
+    inputSchema: {
+      type: "object",
+      properties: { execution_id: { type: "string" } },
+      required: ["execution_id"],
+    },
+  },
+  {
+    name: "aios_confidence_get",
+    description: "Lê Confidence System (ADR-0009). Sem categoria → retorna toda a tabela; com categoria → só ela.",
+    inputSchema: {
+      type: "object",
+      properties: { category: { type: "string" } },
+    },
+  },
+  {
+    name: "aios_confidence_set",
+    description: "Registra/atualiza confiança em uma categoria. level deve ser low|medium|high. reason recomendado (ajuda a entender em revisão).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        category: { type: "string", description: "Ex.: 'architecture', 'modules', 'telemetry', 'decisions', 'domain'." },
+        level: { enum: ["low", "medium", "high"] },
+        reason: { type: "string" },
+      },
+      required: ["category", "level"],
+    },
+  },
+  {
+    name: "aios_confidence_assess",
+    description: "Heurística que olha state + project-state + drift e PROPÕE níveis de confidence + sugestão de maturity. NÃO aplica — usuário/LLM decide via aios_confidence_set / aios_state_set.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  },
+  {
+    name: "aios_list_blueprints",
+    description: "Lista os structural blueprints disponíveis em .ai/blueprints/ (web, saas, crm, mobile, game, ai-platform, telemetry, realtime). Cada blueprint declara folders, modules, packages e integrations recomendados.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  },
+  {
+    name: "aios_get_blueprint",
+    description: "Retorna o blueprint completo (parseado) para o id informado. Use depois de aios_list_blueprints.",
+    inputSchema: {
+      type: "object",
+      properties: { name: { type: "string" } },
+      required: ["name"],
+    },
+  },
+  {
+    name: "aios_compose_structure",
+    description: "Composition Engine (ADR-0010). Recebe lista de tipos (ex.: ['saas','telemetry','realtime']), resolve 'extends' transitivo, faz union semântica (dedup) de folders/modules/packages/integrations, merge de constraints (mais restritivo vence), e retorna estrutura final pronta para scaffolding.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        types: {
+          type: "array",
+          items: { type: "string" },
+          description: "IDs de blueprints a compor (ex.: ['saas','telemetry']).",
+        },
+      },
+      required: ["types"],
+    },
+  },
+];
+
+const START_TIME = Date.now();
+
+function requireRuntime(toolName) {
+  if (!runtime) {
+    const hint = runtimeLoadError
+      ? `Reason: ${runtimeLoadError}`
+      : "Run: cd .ai/server && npm install && npm run build";
+    throw new Error(
+      `Tool ${toolName} requires Runtime v0.1 (dist/index.mjs). ${hint}`,
+    );
+  }
+  return runtime;
+}
+
+const HANDLERS = {
+  "aios_get_core_bundle": async () => await getCoreBundle(),
+  "aios_route_query": async ({ query }) => await routeQuery(query),
+  "aios_classify_task": async ({ query }) => classifyTask(query),
+  "aios_read": async ({ path }) => await readDoc(path),
+  "aios_list": async ({ path }) => await listDir(path),
+  "aios_search_memory": async ({ query, max_results }) => await searchMemory(query, max_results || 20),
+  "aios_get_summary": async () => await getSummary(),
+  "aios_get_manifest": async () => await getManifest(),
+  "aios_lint": async () => await runLint(),
+  "aios_detect_stack": async ({ target_path }) => await runDetectStack(target_path),
+  "aios_validate_audit": async ({ text }) => validateAudit(text),
+  "aios_health": async () => ({
+    status: "ok",
+    version: (await getManifest().catch(() => ({}))).version || "unknown",
+    uptime_seconds: Math.floor((Date.now() - START_TIME) / 1000),
+    mode: STEALTHOS_MODE,
+    stealthos_home: STEALTHOS_HOME,
+    project_root: PROJECT_ROOT,
+    project_hash: PROJECT_HASH,
+    kb_dir: KB_DIR,
+    kb_exists: existsSync(KB_DIR),
+    project_state_dir: PROJECT_STATE_DIR,
+    project_state_exists: existsSync(PROJECT_STATE_DIR),
+    pid: process.pid,
+    node: process.version,
+    platform: process.platform,
+    runtime_v0_1: !!runtime,
+    runtime_load_error: runtimeLoadError,
+    runtime_dist_path: RUNTIME_DIST_PATH,
+  }),
+  "aios_analyze_project": async ({ scan_dirs, write } = {}) => {
+    const rt = requireRuntime("aios_analyze_project");
+    return await rt.analyzer.analyzeProject(PROJECT_ROOT, {
+      scanDirs: scan_dirs,
+      write: write !== false,
+    });
+  },
+  "aios_build_context_package": async ({ intent, max_modules, write } = {}) => {
+    const rt = requireRuntime("aios_build_context_package");
+    return await rt.packager.buildContextPackage(PROJECT_ROOT, {
+      intent: intent || "",
+      maxModules: max_modules,
+      write: write !== false,
+    });
+  },
+  "aios_snapshot": async ({ label } = {}) => {
+    const rt = requireRuntime("aios_snapshot");
+    if (!label) throw new Error("aios_snapshot requires 'label' argument");
+    return await rt.snapshot.createSnapshot(PROJECT_ROOT, { label });
+  },
+  "aios_snapshot_list": async () => {
+    const rt = requireRuntime("aios_snapshot_list");
+    return await rt.snapshot.listSnapshots(PROJECT_ROOT);
+  },
+  "aios_snapshot_diff": async ({ a, b } = {}) => {
+    const rt = requireRuntime("aios_snapshot_diff");
+    if (!a || !b) throw new Error("aios_snapshot_diff requires 'a' and 'b' snapshot IDs");
+    return await rt.snapshot.diffSnapshots(PROJECT_ROOT, a, b);
+  },
+  "aios_run_workflow": async ({ name, input = {} } = {}) => {
+    if (!name) throw new Error("aios_run_workflow requires 'name'");
+    return await runWorkflow(name, input);
+  },
+  "aios_list_workflows": async () => await listWorkflows(),
+  "aios_state_get": async ({ path } = {}) => await stateGet(path),
+  "aios_state_set": async ({ path, value } = {}) => {
+    if (!path) throw new Error("aios_state_set requires 'path'");
+    return await stateSet(path, value);
+  },
+  "aios_state_advance": async ({ phase, mode } = {}) => {
+    if (!phase && !mode) throw new Error("aios_state_advance requires 'phase' or 'mode'");
+    return await stateAdvance(phase, mode);
+  },
+  "aios_state_reset": async () => await stateReset(),
+  "aios_compile_runtime_context": async ({ max_modules, max_decisions, write } = {}) =>
+    await compileRuntimeContext({
+      maxModules: max_modules || 10,
+      maxDecisions: max_decisions || 5,
+      write: write !== false,
+    }),
+  "aios_detect_drift": async ({ since_snapshot } = {}) => await detectDrift(since_snapshot),
+  "aios_get_context": async ({ layer, focus } = {}) => {
+    if (!layer) throw new Error("aios_get_context requires 'layer'");
+    return await getContextLayer(layer, focus);
+  },
+  "aios_artifact_list": async ({ type, status } = {}) => await artifactList(type, status),
+  "aios_resume_workflow": async ({ execution_id, user_input } = {}) => {
+    if (!execution_id) throw new Error("aios_resume_workflow requires 'execution_id'");
+    return await resumeWorkflow(execution_id, user_input);
+  },
+  "aios_list_paused_executions": async () => await listPausedExecutions(),
+  "aios_cancel_paused_execution": async ({ execution_id } = {}) => {
+    if (!execution_id) throw new Error("aios_cancel_paused_execution requires 'execution_id'");
+    return await cancelPausedExecution(execution_id);
+  },
+  "aios_confidence_get": async ({ category } = {}) => await confidenceGet(category),
+  "aios_confidence_set": async ({ category, level, reason } = {}) => {
+    if (!category || !level) throw new Error("aios_confidence_set requires 'category' and 'level'");
+    return await confidenceSet(category, level, reason);
+  },
+  "aios_confidence_assess": async () => await confidenceAssess(),
+  "aios_list_blueprints": async () => await listBlueprints(),
+  "aios_get_blueprint": async ({ name } = {}) => {
+    if (!name) throw new Error("aios_get_blueprint requires 'name'");
+    return await getBlueprint(name);
+  },
+  "aios_compose_structure": async ({ types } = {}) => {
+    if (!Array.isArray(types) || types.length === 0) {
+      throw new Error("aios_compose_structure requires 'types' as non-empty array");
+    }
+    return await composeStructure(types);
+  },
+};
+
+// ---------- Workflow Engine (Fase 1 — ADR-0005, estendido em ADR-0006) ----------
+const WORKFLOWS_DIR = join(KB_DIR, "workflows");
+const RUNTIME_DIR = join(PROJECT_STATE_DIR, "runtime");
+const STATE_PATH = join(RUNTIME_DIR, "state.json");
+
+// Mapeamento guarantee → tools provedoras (ADR-0006 + ADR-0007)
+const GUARANTEE_PROVIDERS = {
+  snapshot_created: ["aios_snapshot"],
+  state_updated: ["aios_state_set", "aios_state_advance", "aios_state_reset"],
+  context_compiled: ["aios_build_context_package"],
+  lint_clean: ["aios_lint"],
+  stack_detected: ["aios_detect_stack"],
+  project_analyzed: ["aios_analyze_project"],
+  core_loaded: ["aios_get_core_bundle"],
+  memory_searched: ["aios_search_memory"],
+  query_routed: ["aios_route_query"],
+  task_classified: ["aios_classify_task"],
+  runtime_context_compiled: ["aios_compile_runtime_context"],
+  drift_checked: ["aios_detect_drift"],
+};
+
+function resolveTemplateValue(str, ctx) {
+  if (typeof str !== "string" || !str.includes("${")) return str;
+  return str.replace(/\$\{([^}]+)\}/g, (_, expr) => {
+    // Support: input.X, timestamp, state.X, input.X || 'fallback'
+    const parts = expr.split("||").map((p) => p.trim());
+    for (const part of parts) {
+      const lit = part.match(/^['"](.*)['"]$/);
+      if (lit) return lit[1];
+      const segs = part.split(".");
+      let val = ctx;
+      let ok = true;
+      for (const s of segs) {
+        if (val == null || !(s in val)) { ok = false; break; }
+        val = val[s];
+      }
+      if (ok && val !== "" && val != null) return String(val);
+    }
+    return "";
+  });
+}
+
+function resolveArgs(args, ctx) {
+  const out = {};
+  for (const [k, v] of Object.entries(args || {})) {
+    if (typeof v === "string") out[k] = resolveTemplateValue(v, ctx);
+    else if (Array.isArray(v)) out[k] = v.map((x) => (typeof x === "string" ? resolveTemplateValue(x, ctx) : x));
+    else if (v && typeof v === "object") out[k] = resolveArgs(v, ctx);
+    else out[k] = v;
+  }
+  return out;
+}
+
+async function loadWorkflow(name) {
+  // Restrict name to safe chars
+  if (!/^[a-z][a-z0-9_-]{0,32}$/.test(name)) {
+    throw new Error(`Invalid workflow name: ${name}`);
+  }
+  const wfPath = join(WORKFLOWS_DIR, `${name}.json`);
+  if (!existsSync(wfPath)) {
+    throw new Error(`Workflow not found: ${name} (expected at ${wfPath})`);
+  }
+  const raw = await readFile(wfPath, "utf8");
+  const wf = JSON.parse(raw);
+  if (!wf.id || !Array.isArray(wf.steps)) {
+    throw new Error(`Invalid workflow ${name}: missing id or steps[]`);
+  }
+  return wf;
+}
+
+// ADR-0008: paused executions
+const PAUSED_DIR = join(RUNTIME_DIR, "paused-executions");
+const PAUSE_TTL_MS = 30 * 60 * 1000; // 30 min
+
+function expandSteps(steps, ctx) {
+  // Expand branches inline; recursive
+  const out = [];
+  for (const step of steps || []) {
+    if (Array.isArray(step.branches)) {
+      let chosen = null;
+      for (const br of step.branches) {
+        if (br.default) { if (!chosen) chosen = br; continue; }
+        if (evalBranchCondition(br.when, ctx)) { chosen = br; break; }
+      }
+      if (chosen && Array.isArray(chosen.steps)) {
+        out.push(...expandSteps(chosen.steps, ctx));
+      }
+      continue;
+    }
+    out.push(step);
+  }
+  return out;
+}
+
+function evalBranchCondition(expr, ctx) {
+  if (!expr || typeof expr !== "string") return false;
+  // Supported: <path> == <literal> | <path> != <literal> | <literal> in <path>
+  const opMatch = expr.match(/^(.+?)\s+(==|!=|in)\s+(.+)$/);
+  if (!opMatch) return false;
+  const [, leftRaw, op, rightRaw] = opMatch;
+  const parseLiteralOrPath = (raw) => {
+    const s = raw.trim();
+    const litStr = s.match(/^['"](.*)['"]$/);
+    if (litStr) return litStr[1];
+    if (s === "true") return true;
+    if (s === "false") return false;
+    if (s === "null") return null;
+    if (/^-?\d+(\.\d+)?$/.test(s)) return Number(s);
+    // dotted path lookup
+    const segs = s.split(".");
+    let val = ctx;
+    for (const seg of segs) {
+      if (val == null || typeof val !== "object") return undefined;
+      val = val[seg];
+    }
+    return val;
+  };
+  const left = parseLiteralOrPath(leftRaw);
+  const right = parseLiteralOrPath(rightRaw);
+  if (op === "==") return left === right;
+  if (op === "!=") return left !== right;
+  if (op === "in") {
+    if (Array.isArray(right)) return right.includes(left);
+    if (typeof right === "string") return right.includes(String(left));
+    return false;
+  }
+  return false;
+}
+
+async function ensurePausedDir() {
+  if (!existsSync(PAUSED_DIR)) await mkdir(PAUSED_DIR, { recursive: true });
+}
+
+async function savePausedExecution(execution) {
+  await ensurePausedDir();
+  const file = join(PAUSED_DIR, `${execution.execution_id}.json`);
+  await writeFile(file, JSON.stringify(execution, null, 2), "utf8");
+  return file;
+}
+
+async function runWorkflow(name, input) {
+  const wf = await loadWorkflow(name);
+  const startIso = new Date().toISOString();
+  const report = {
+    workflow: wf.id,
+    version: wf.version || "unknown",
+    started_at: startIso,
+    input,
+    safety: wf.safety || null,
+    declared_guarantees: Array.isArray(wf.guarantees) ? wf.guarantees : [],
+    steps: [],
+    status: "running",
+  };
+  let stateSnapshot = null;
+  try { stateSnapshot = await loadState(); } catch (_) { stateSnapshot = null; }
+  const ctx = {
+    input: input || {},
+    timestamp: startIso.replace(/[:.]/g, "-"),
+    state: stateSnapshot,
+    resumed_input: null,
+  };
+  // Expand branches up front
+  const expandedSteps = expandSteps(wf.steps, ctx);
+  return await executeStepsFrom(wf, expandedSteps, 0, ctx, report);
+}
+
+async function executeStepsFrom(wf, steps, startIdx, ctx, report) {
+  const toolsExecutedOk = new Set(report._toolsOk || []);
+  for (let i = startIdx; i < steps.length; i++) {
+    const step = steps[i];
+    // Pause-for-input (Fase 4 / ADR-0008)
+    if (step.pause_for && (step.pause_for.when || "before") === "before") {
+      return await pauseExecution(wf, steps, i, ctx, report, toolsExecutedOk, "before");
+    }
+    const stepStart = Date.now();
+    const stepReport = {
+      id: step.id,
+      tool: step.tool,
+      status: "pending",
+      duration_ms: 0,
+    };
+    try {
+      const handler = HANDLERS[step.tool];
+      if (!handler) throw new Error(`Unknown tool in workflow: ${step.tool}`);
+      const resolved = resolveArgs(step.args || {}, ctx);
+      const result = await handler(resolved);
+      stepReport.status = "ok";
+      stepReport.duration_ms = Date.now() - stepStart;
+      const preview = typeof result === "string" ? result : JSON.stringify(result);
+      stepReport.result_preview = preview.slice(0, 400);
+      stepReport.result_length = preview.length;
+      toolsExecutedOk.add(step.tool);
+    } catch (e) {
+      stepReport.status = "error";
+      stepReport.duration_ms = Date.now() - stepStart;
+      stepReport.error = String(e && e.message ? e.message : e);
+      report.steps.push(stepReport);
+      if (step.on_error !== "continue") {
+        report.status = "aborted";
+        report.finished_at = new Date().toISOString();
+        await recordWorkflowHistory(report);
+        return report;
+      }
+      continue;
+    }
+    report.steps.push(stepReport);
+    if (step.pause_for && step.pause_for.when === "after") {
+      return await pauseExecution(wf, steps, i + 1, ctx, report, toolsExecutedOk, "after");
+    }
+  }
+  // Validate guarantees (ADR-0006)
+  const metGuarantees = [];
+  const unmetGuarantees = [];
+  for (const g of report.declared_guarantees) {
+    const providers = GUARANTEE_PROVIDERS[g] || [];
+    const satisfied = providers.some((t) => toolsExecutedOk.has(t));
+    (satisfied ? metGuarantees : unmetGuarantees).push(g);
+  }
+  report.guarantees_met = metGuarantees;
+  report.unmet_guarantees = unmetGuarantees;
+  report.status = unmetGuarantees.length > 0 ? "ok_with_warnings" : "ok";
+  report.finished_at = new Date().toISOString();
+  delete report._toolsOk;
+  await recordWorkflowHistory(report);
+  return report;
+}
+
+async function pauseExecution(wf, steps, nextIndex, ctx, report, toolsExecutedOk, when) {
+  const execution_id = `exec-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  const pauseStep = steps[when === "before" ? nextIndex : nextIndex - 1];
+  const persisted = {
+    execution_id,
+    workflow: wf.id,
+    version: wf.version,
+    paused_at: new Date().toISOString(),
+    expires_at: new Date(Date.now() + PAUSE_TTL_MS).toISOString(),
+    next_step_index: nextIndex,
+    steps,
+    ctx_minus_state: { input: ctx.input, timestamp: ctx.timestamp, resumed_input: ctx.resumed_input },
+    report: { ...report, _toolsOk: [...toolsExecutedOk] },
+    pause_info: {
+      step_id: pauseStep.id,
+      when,
+      reason: pauseStep.pause_for.reason,
+      prompt: pauseStep.pause_for.prompt,
+      expected_input: pauseStep.pause_for.expected_input || null,
+    },
+  };
+  await savePausedExecution(persisted);
+  return {
+    status: "paused",
+    execution_id,
+    workflow: wf.id,
+    paused_at: persisted.paused_at,
+    expires_at: persisted.expires_at,
+    pause_info: persisted.pause_info,
+    steps_completed: report.steps.length,
+    resume_instruction: `Call aios_resume_workflow({execution_id:"${execution_id}", user_input: <answer>}).`,
+  };
+}
+
+async function resumeWorkflow(execution_id, user_input) {
+  await ensurePausedDir();
+  const file = join(PAUSED_DIR, `${execution_id}.json`);
+  if (!existsSync(file)) throw new Error(`Paused execution not found: ${execution_id}`);
+  const raw = await readFile(file, "utf8");
+  const persisted = JSON.parse(raw);
+  if (new Date(persisted.expires_at).getTime() < Date.now()) {
+    return { status: "expired", execution_id, expired_at: persisted.expires_at };
+  }
+  // Reload state (may have changed)
+  let stateSnapshot = null;
+  try { stateSnapshot = await loadState(); } catch (_) { stateSnapshot = null; }
+  const ctx = {
+    ...persisted.ctx_minus_state,
+    state: stateSnapshot,
+    resumed_input: user_input ?? null,
+  };
+  const report = persisted.report;
+  // Remove paused file
+  try { await readFile(file, "utf8"); } catch (_) { /* ignore */ }
+  try { (await import("node:fs/promises")).unlink(file); } catch (_) { /* ignore */ }
+  return await executeStepsFrom(
+    { id: persisted.workflow, version: persisted.version, guarantees: report.declared_guarantees },
+    persisted.steps,
+    persisted.next_step_index,
+    ctx,
+    report,
+  );
+}
+
+async function listPausedExecutions() {
+  await ensurePausedDir();
+  const entries = await readdir(PAUSED_DIR).catch(() => []);
+  const out = [];
+  for (const f of entries) {
+    if (!f.endsWith(".json")) continue;
+    try {
+      const raw = await readFile(join(PAUSED_DIR, f), "utf8");
+      const e = JSON.parse(raw);
+      out.push({
+        execution_id: e.execution_id,
+        workflow: e.workflow,
+        paused_at: e.paused_at,
+        expires_at: e.expires_at,
+        expired: new Date(e.expires_at).getTime() < Date.now(),
+        pause_info: e.pause_info,
+      });
+    } catch (_) { /* skip */ }
+  }
+  return { count: out.length, paused: out };
+}
+
+async function cancelPausedExecution(execution_id) {
+  const file = join(PAUSED_DIR, `${execution_id}.json`);
+  if (!existsSync(file)) return { cancelled: false, reason: "not_found" };
+  try {
+    const fsp = await import("node:fs/promises");
+    await fsp.unlink(file);
+    return { cancelled: true, execution_id };
+  } catch (e) {
+    return { cancelled: false, error: String(e.message || e) };
+  }
+}
+
+// ---------- Fase 5 (ADR-0009): Confidence System ----------
+async function ensureConfidenceBlock(state) {
+  if (!state.confidence) state.confidence = { default_level: "medium", categories: {} };
+  if (!state.confidence.categories) state.confidence.categories = {};
+  if (!state.confidence.default_level) state.confidence.default_level = "medium";
+  return state;
+}
+
+async function confidenceGet(category) {
+  const state = await loadState();
+  await ensureConfidenceBlock(state);
+  if (!category) {
+    return {
+      default_level: state.confidence.default_level,
+      categories: state.confidence.categories,
+      count: Object.keys(state.confidence.categories).length,
+    };
+  }
+  const entry = state.confidence.categories[category];
+  if (!entry) {
+    return {
+      category,
+      level: state.confidence.default_level,
+      reason: "default (no explicit entry)",
+      explicit: false,
+    };
+  }
+  return { category, ...entry, explicit: true };
+}
+
+async function confidenceSet(category, level, reason) {
+  if (!["low", "medium", "high"].includes(level)) {
+    throw new Error(`Invalid level: ${level} (must be low|medium|high)`);
+  }
+  const state = await loadState();
+  await ensureConfidenceBlock(state);
+  const prev = state.confidence.categories[category];
+  state.confidence.categories[category] = {
+    level,
+    reason: reason || null,
+    updated_at: new Date().toISOString(),
+  };
+  await saveState(state);
+  return {
+    category,
+    previous: prev || null,
+    current: state.confidence.categories[category],
+  };
+}
+
+// ---------- Fase 6 (ADR-0010): Structural Blueprints + Composition Engine ----------
+const BLUEPRINTS_DIR = join(KB_DIR, "blueprints");
+
+async function listBlueprints() {
+  if (!existsSync(BLUEPRINTS_DIR)) return { count: 0, blueprints: [] };
+  const entries = await readdir(BLUEPRINTS_DIR, { withFileTypes: true });
+  const out = [];
+  for (const e of entries) {
+    if (!e.isFile() || !e.name.endsWith(".json") || e.name.startsWith("_")) continue;
+    try {
+      const raw = await readFile(join(BLUEPRINTS_DIR, e.name), "utf8");
+      const bp = JSON.parse(raw);
+      out.push({
+        id: bp.id,
+        description: bp.description,
+        extends: bp.extends || [],
+        modules_count: Array.isArray(bp.modules) ? bp.modules.length : 0,
+        folders_count: Array.isArray(bp.folders) ? bp.folders.length : 0,
+        file: e.name,
+      });
+    } catch (err) {
+      out.push({ id: e.name.replace(/\.json$/, ""), error: String(err.message || err), file: e.name });
+    }
+  }
+  return { count: out.length, blueprints: out };
+}
+
+async function loadBlueprint(name) {
+  if (!/^[a-z][a-z0-9_-]{0,32}$/.test(name)) {
+    throw new Error(`Invalid blueprint name: ${name}`);
+  }
+  const file = join(BLUEPRINTS_DIR, `${name}.json`);
+  if (!existsSync(file)) throw new Error(`Blueprint not found: ${name}`);
+  const raw = await readFile(file, "utf8");
+  const bp = JSON.parse(raw);
+  if (!bp.id || !Array.isArray(bp.folders) || !Array.isArray(bp.modules)) {
+    throw new Error(`Invalid blueprint ${name}: missing id/folders/modules`);
+  }
+  return bp;
+}
+
+async function getBlueprint(name) {
+  const bp = await loadBlueprint(name);
+  return { blueprint: bp };
+}
+
+async function resolveExtendsTransitive(types, visited = new Set()) {
+  const ordered = [];
+  for (const t of types) {
+    if (visited.has(t)) continue;
+    visited.add(t);
+    let bp;
+    try { bp = await loadBlueprint(t); } catch (e) {
+      ordered.push({ id: t, error: String(e.message || e) });
+      continue;
+    }
+    if (Array.isArray(bp.extends) && bp.extends.length > 0) {
+      const parents = await resolveExtendsTransitive(bp.extends, visited);
+      ordered.push(...parents);
+    }
+    ordered.push(bp);
+  }
+  return ordered;
+}
+
+function mergeConstraints(base, override) {
+  // Mais restritivo vence (menor número geralmente; para booleans true vence)
+  const out = { ...base };
+  for (const [k, v] of Object.entries(override || {})) {
+    if (out[k] === undefined) { out[k] = v; continue; }
+    if (typeof v === "number" && typeof out[k] === "number") {
+      // Para limites: menor vence; para "max_*" é menor; aqui assumimos limits
+      out[k] = Math.min(out[k], v);
+    } else if (typeof v === "boolean") {
+      out[k] = out[k] || v;
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+async function composeStructure(types) {
+  const resolved = await resolveExtendsTransitive(types);
+  const valid = resolved.filter((bp) => !bp.error);
+  const errors = resolved.filter((bp) => bp.error);
+
+  const foldersSet = new Set();
+  const modulesSet = new Set();
+  const packagesSet = new Set();
+  const integrationsSet = new Set();
+  let constraints = {
+    max_module_dependencies: 5,
+    max_file_lines: 500,
+    max_folder_depth: 4,
+    max_modules_before_split: 20,
+    require_module_readme: true,
+    require_module_index: true,
+    forbid_global_singletons: true,
+    forbid_circular_module_deps: true,
+  };
+  const notes = [];
+
+  for (const bp of valid) {
+    for (const f of bp.folders || []) foldersSet.add(f);
+    for (const m of bp.modules || []) modulesSet.add(m);
+    for (const p of bp.packages_recommended || []) packagesSet.add(p);
+    for (const i of bp.integrations_recommended || []) integrationsSet.add(i);
+    if (bp.constraints_overrides) {
+      constraints = mergeConstraints(constraints, bp.constraints_overrides);
+    }
+    if (bp.notes) notes.push({ from: bp.id, note: bp.notes });
+  }
+
+  return {
+    requested_types: types,
+    types_resolved: valid.map((bp) => bp.id),
+    errors: errors.length > 0 ? errors : undefined,
+    folders: [...foldersSet].sort(),
+    modules: [...modulesSet].sort(),
+    packages_recommended: [...packagesSet].sort(),
+    integrations_recommended: [...integrationsSet].sort(),
+    constraints,
+    notes,
+    next_step_hint: "Estrutura sugerida — adapte ao seu contexto. Princípios: ver .ai/rules/structure-canon.md. Limites: .ai/rules/structural-constraints.md.",
+  };
+}
+
+async function confidenceAssess() {
+  const state = await loadState();
+  await ensureConfidenceBlock(state);
+  const projectState = safeReadJson(join(PROJECT_STATE_DIR, "context", "project-state.json"));
+  const adrs = await listAdrs(50);
+  const totalModules = projectState && Array.isArray(projectState.modules)
+    ? projectState.modules.length : 0;
+  const smellsCount = projectState && Array.isArray(projectState.smells)
+    ? projectState.smells.length : 0;
+  const adrCount = adrs.length;
+  const syncCount = (state.workflow_history || []).filter((h) => h.workflow === "sync").length;
+
+  // Suggested maturity
+  let suggestedMaturity = "empty";
+  if (state.identity?.project_name && adrCount <= 2) suggestedMaturity = "minimal";
+  if (adrCount >= 3 && adrCount <= 9 && totalModules > 0) suggestedMaturity = "partial";
+  if (adrCount >= 10 && totalModules > 10 && syncCount >= 3) suggestedMaturity = "mature";
+
+  // Suggested confidence levels (heuristic)
+  const suggestions = {};
+  suggestions.decisions = {
+    level: adrCount >= 10 ? "high" : adrCount >= 3 ? "medium" : "low",
+    reason: `${adrCount} ADRs registrados`,
+  };
+  suggestions.architecture = {
+    level: existsSync(join(PROJECT_STATE_DIR, "architecture", "containers.md")) ? "high" : "medium",
+    reason: "presença de architecture/containers.md C4 L2",
+  };
+  suggestions.modules = {
+    level: totalModules > 10 && smellsCount === 0 ? "high"
+      : totalModules > 0 ? "medium" : "low",
+    reason: `${totalModules} módulos, ${smellsCount} smells`,
+  };
+  suggestions.domain = {
+    level: existsSync(join(PROJECT_STATE_DIR, "product", "vision.md")) ? "medium" : "low",
+    reason: "presença de product/vision.md",
+  };
+  suggestions.telemetry = {
+    level: "low",
+    reason: "sem instrumentação detectada (heurística default)",
+  };
+
+  return {
+    current_maturity: state.identity?.maturity || "unknown",
+    suggested_maturity: suggestedMaturity,
+    suggested_confidence: suggestions,
+    apply_hint: "Use aios_confidence_set({category, level, reason}) e/ou aios_state_set({path:'identity.maturity', value}) para aplicar.",
+    inputs: {
+      adrs_count: adrCount,
+      modules_count: totalModules,
+      smells_count: smellsCount,
+      sync_runs: syncCount,
+    },
+  };
+}
+
+// ---------- Runtime State helpers (ADR-0006) ----------
+const DEFAULT_STATE = {
+  $schema: "./state.schema.json",
+  version: "1.0.0",
+  updated_at: new Date(0).toISOString(),
+  identity: { project_name: null, maturity: "empty", stack: [] },
+  lifecycle: { phase: "discovery", mode: "analysis" },
+  persistent: { architecture_decisions_refs: [], rules_refs: [] },
+  rotating: { ttl_days: 30, active_focus: null, recent_errors: [], open_questions: [] },
+  workflow_history: [],
+};
+
+const MAX_WORKFLOW_HISTORY = 20;
+
+async function ensureRuntimeDir() {
+  if (!existsSync(RUNTIME_DIR)) await mkdir(RUNTIME_DIR, { recursive: true });
+}
+
+async function loadState() {
+  await ensureRuntimeDir();
+  if (!existsSync(STATE_PATH)) {
+    await writeFile(STATE_PATH, JSON.stringify(DEFAULT_STATE, null, 2), "utf8");
+    return JSON.parse(JSON.stringify(DEFAULT_STATE));
+  }
+  const raw = await readFile(STATE_PATH, "utf8");
+  return JSON.parse(raw);
+}
+
+async function saveState(state) {
+  await ensureRuntimeDir();
+  state.updated_at = new Date().toISOString();
+  await writeFile(STATE_PATH, JSON.stringify(state, null, 2), "utf8");
+  return state;
+}
+
+function getByPath(obj, path) {
+  if (!path) return obj;
+  const segs = path.split(".");
+  let val = obj;
+  for (const s of segs) {
+    if (val == null || typeof val !== "object") return undefined;
+    val = val[s];
+  }
+  return val;
+}
+
+function setByPath(obj, path, value) {
+  const segs = path.split(".");
+  let parent = obj;
+  for (let i = 0; i < segs.length - 1; i++) {
+    if (parent[segs[i]] == null || typeof parent[segs[i]] !== "object") {
+      parent[segs[i]] = {};
+    }
+    parent = parent[segs[i]];
+  }
+  parent[segs[segs.length - 1]] = value;
+  return obj;
+}
+
+async function stateGet(path) {
+  const state = await loadState();
+  if (!path) return state;
+  const val = getByPath(state, path);
+  if (val === undefined) {
+    throw new Error(`State path not found: ${path}`);
+  }
+  return { path, value: val };
+}
+
+async function stateSet(path, value) {
+  const state = await loadState();
+  const prev = getByPath(state, path);
+  setByPath(state, path, value);
+  await saveState(state);
+  return { path, previous: prev === undefined ? null : prev, current: value, updated_at: state.updated_at };
+}
+
+async function stateAdvance(phase, mode) {
+  const state = await loadState();
+  const diff = {};
+  if (phase) {
+    diff.phase = { from: state.lifecycle?.phase, to: phase };
+    if (!state.lifecycle) state.lifecycle = {};
+    state.lifecycle.phase = phase;
+  }
+  if (mode) {
+    diff.mode = { from: state.lifecycle?.mode, to: mode };
+    if (!state.lifecycle) state.lifecycle = {};
+    state.lifecycle.mode = mode;
+  }
+  await saveState(state);
+  return { diff, lifecycle: state.lifecycle, updated_at: state.updated_at };
+}
+
+async function stateReset() {
+  const fresh = JSON.parse(JSON.stringify(DEFAULT_STATE));
+  fresh.updated_at = new Date().toISOString();
+  await ensureRuntimeDir();
+  await writeFile(STATE_PATH, JSON.stringify(fresh, null, 2), "utf8");
+  return { reset: true, state: fresh };
+}
+
+async function recordWorkflowHistory(report) {
+  try {
+    const state = await loadState();
+    if (!Array.isArray(state.workflow_history)) state.workflow_history = [];
+    state.workflow_history.unshift({
+      workflow: report.workflow,
+      started_at: report.started_at,
+      finished_at: report.finished_at,
+      status: report.status,
+      guarantees_met: report.guarantees_met || [],
+      unmet_guarantees: report.unmet_guarantees || [],
+    });
+    state.workflow_history = state.workflow_history.slice(0, MAX_WORKFLOW_HISTORY);
+    await saveState(state);
+  } catch (_) {
+    // history is best-effort; don't break workflow on history write failure
+  }
+}
+
+// ---------- Fase 3 (ADR-0007): State Compiler + Drift + Context Layers + Artifact Index ----------
+const RUNTIME_CONTEXT_PATH = join(RUNTIME_DIR, "runtime-context.json");
+const ARTIFACTS_INDEX_PATH = join(PROJECT_STATE_DIR, "artifacts", "index.json");
+
+function estimateTokens(str) {
+  // ~4 chars per token rough approximation
+  return Math.ceil((str || "").length / 4);
+}
+
+function safeReadJson(absPath) {
+  try {
+    if (!existsSync(absPath)) return null;
+    return JSON.parse(readFileSync(absPath, "utf8"));
+  } catch (_) {
+    return null;
+  }
+}
+
+function safeReadText(absPath, maxChars = 4000) {
+  try {
+    if (!existsSync(absPath)) return null;
+    const txt = readFileSync(absPath, "utf8");
+    return txt.length > maxChars ? txt.slice(0, maxChars) + "\n…[truncated]" : txt;
+  } catch (_) {
+    return null;
+  }
+}
+
+async function listAdrs(limit) {
+  const dir = join(PROJECT_STATE_DIR, "specs", "ADR");
+  if (!existsSync(dir)) return [];
+  const entries = await readdir(dir);
+  const adrs = entries
+    .filter((n) => n.startsWith("ADR-") && n.endsWith(".md"))
+    .sort()
+    .reverse();
+  const out = [];
+  for (const name of adrs.slice(0, limit || 5)) {
+    const txt = readFileSync(join(dir, name), "utf8");
+    const idMatch = txt.match(/^id:\s*(\S+)/m);
+    const slugMatch = txt.match(/^slug:\s*(\S+)/m);
+    const statusMatch = txt.match(/^status:\s*(\S+)/m);
+    const titleMatch = txt.match(/^#\s+(.+)$/m);
+    out.push({
+      file: name,
+      id: idMatch?.[1] || name,
+      slug: slugMatch?.[1] || null,
+      status: statusMatch?.[1] || null,
+      title: titleMatch?.[1] || null,
+    });
+  }
+  return out;
+}
+
+async function compileRuntimeContext({ maxModules, maxDecisions, write }) {
+  const state = await loadState();
+  const projectState = safeReadJson(join(PROJECT_STATE_DIR, "context", "project-state.json"));
+  const manifest = safeReadJson(join(AI_DIR, "manifest.json"));
+  const adrs = await listAdrs(maxDecisions);
+
+  // Top modules by edges count (most connected = most relevant)
+  let topModules = [];
+  if (projectState && Array.isArray(projectState.modules)) {
+    topModules = [...projectState.modules]
+      .map((m) => ({
+        path: m.path || m.file || null,
+        kind: m.kind || null,
+        edges_in: m.edges_in || 0,
+        edges_out: m.edges_out || 0,
+        connectivity: (m.edges_in || 0) + (m.edges_out || 0),
+      }))
+      .sort((a, b) => b.connectivity - a.connectivity)
+      .slice(0, maxModules);
+  }
+
+  // Fase 5 (ADR-0009): low confidence flags
+  const lowConfidenceFlags = [];
+  const cats = state.confidence?.categories || {};
+  for (const [name, entry] of Object.entries(cats)) {
+    if (entry?.level === "low") {
+      lowConfidenceFlags.push({ category: name, reason: entry.reason || null });
+    }
+  }
+
+  const compiled = {
+    $schema: "runtime-context-v1",
+    compiled_at: new Date().toISOString(),
+    os_version: manifest?.version || "unknown",
+    identity: state.identity || {},
+    lifecycle: state.lifecycle || {},
+    rotating: state.rotating || {},
+    low_confidence_flags: lowConfidenceFlags.slice(0, 3),
+    persistent: {
+      architecture_decisions_refs: state.persistent?.architecture_decisions_refs || [],
+      rules_refs: state.persistent?.rules_refs || [],
+      recent_adrs: adrs,
+    },
+    project_state: projectState
+      ? {
+          source_hash: projectState.source_hash || projectState.hash || null,
+          stack: projectState.stack || null,
+          total_files: projectState.total_files || null,
+          total_modules: Array.isArray(projectState.modules) ? projectState.modules.length : null,
+          total_edges: projectState.total_edges || null,
+          smells_count: Array.isArray(projectState.smells) ? projectState.smells.length : 0,
+          top_modules: topModules,
+        }
+      : null,
+    recent_workflow_history: (state.workflow_history || []).slice(0, 5),
+  };
+
+  const serialized = JSON.stringify(compiled, null, 2);
+  const estimated = estimateTokens(serialized);
+  compiled.estimated_tokens = estimated;
+
+  if (write) {
+    await ensureRuntimeDir();
+    await writeFile(RUNTIME_CONTEXT_PATH, JSON.stringify(compiled, null, 2), "utf8");
+  }
+  return {
+    path: write ? RUNTIME_CONTEXT_PATH : null,
+    estimated_tokens: estimated,
+    over_budget: estimated > 4000,
+    summary: {
+      identity: compiled.identity,
+      lifecycle: compiled.lifecycle,
+      modules: compiled.project_state?.total_modules,
+      top_modules_count: topModules.length,
+      adrs_count: adrs.length,
+    },
+    runtime_context: compiled,
+  };
+}
+
+async function detectDrift(sinceSnapshot) {
+  const projectState = safeReadJson(join(PROJECT_STATE_DIR, "context", "project-state.json"));
+  if (!projectState) {
+    return { error: "project-state.json not found. Run aios_analyze_project first.", drift: [] };
+  }
+
+  // Pick snapshot
+  const snapshotsDir = join(PROJECT_STATE_DIR, "snapshots");
+  let chosenSnapshotId = sinceSnapshot;
+  if (!chosenSnapshotId && existsSync(snapshotsDir)) {
+    const entries = await readdir(snapshotsDir, { withFileTypes: true });
+    const snapshots = entries.filter((e) => e.isDirectory()).map((e) => e.name).sort().reverse();
+    chosenSnapshotId = snapshots[0] || null;
+  }
+  if (!chosenSnapshotId) {
+    return { error: "no snapshot available. Run aios_snapshot first.", drift: [] };
+  }
+
+  // Snapshot v0.1 grava como 'state.json'; aceitar ambos os nomes
+  const snapStatePath = existsSync(join(snapshotsDir, chosenSnapshotId, "project-state.json"))
+    ? join(snapshotsDir, chosenSnapshotId, "project-state.json")
+    : join(snapshotsDir, chosenSnapshotId, "state.json");
+  const snapState = safeReadJson(snapStatePath);
+  if (!snapState) {
+    return {
+      error: `snapshot ${chosenSnapshotId} has no state.json/project-state.json`,
+      snapshot_id: chosenSnapshotId,
+      drift: [],
+    };
+  }
+
+  // Compare module paths
+  const currentPaths = new Set((projectState.modules || []).map((m) => m.path || m.file).filter(Boolean));
+  const prevPaths = new Set((snapState.modules || []).map((m) => m.path || m.file).filter(Boolean));
+  const added = [...currentPaths].filter((p) => !prevPaths.has(p));
+  const removed = [...prevPaths].filter((p) => !currentPaths.has(p));
+  const persisted = [...currentPaths].filter((p) => prevPaths.has(p));
+
+  // Specs that mention modules
+  const specsDir = join(PROJECT_STATE_DIR, "specs");
+  const specMentions = new Set();
+  if (existsSync(specsDir)) {
+    const collect = (dir) => {
+      const entries = readdirSync(dir, { withFileTypes: true });
+      for (const e of entries) {
+        const p = join(dir, e.name);
+        if (e.isDirectory()) collect(p);
+        else if (e.isFile() && e.name.endsWith(".md") && !e.name.startsWith("_")) {
+          const txt = safeReadText(p, 50000) || "";
+          for (const mod of currentPaths) {
+            if (txt.includes(mod)) specMentions.add(mod);
+          }
+        }
+      }
+    };
+    try { collect(specsDir); } catch (_) { /* ignore */ }
+  }
+
+  const orphanModules = [...currentPaths].filter((p) => !specMentions.has(p));
+
+  return {
+    snapshot_id: chosenSnapshotId,
+    severity: "info",
+    summary: {
+      modules_added_since_snapshot: added.length,
+      modules_removed_since_snapshot: removed.length,
+      modules_persisted: persisted.length,
+      orphan_modules_no_spec_reference: orphanModules.length,
+    },
+    modules_added: added.slice(0, 30),
+    modules_removed: removed.slice(0, 30),
+    orphan_modules: orphanModules.slice(0, 30),
+    note: "Heurística MVP: hash+path+spec text search. Severity 'info' por default; Fase 4+ pode aprofundar com AST diff.",
+  };
+}
+
+async function getContextLayer(layer, focus) {
+  if (layer === "core") {
+    return await getCoreBundle();
+  }
+  if (layer === "working") {
+    const state = await loadState();
+    const projectState = safeReadJson(join(PROJECT_STATE_DIR, "context", "project-state.json"));
+    const adrs = await listAdrs(3);
+    const summary = safeReadText(join(PROJECT_STATE_DIR, "memory", "_summary.md"), 2000);
+    return {
+      layer: "working",
+      focus: focus || null,
+      identity: state.identity,
+      lifecycle: state.lifecycle,
+      rotating: state.rotating,
+      project_state_summary: projectState
+        ? {
+            source_hash: projectState.source_hash || null,
+            stack: projectState.stack || null,
+            total_modules: Array.isArray(projectState.modules) ? projectState.modules.length : null,
+          }
+        : null,
+      recent_adrs: adrs,
+      memory_summary_preview: summary ? summary.slice(0, 1500) : null,
+    };
+  }
+  if (layer === "deep") {
+    const state = await loadState();
+    const projectState = safeReadJson(join(PROJECT_STATE_DIR, "context", "project-state.json"));
+    const adrs = await listAdrs(20);
+    const memoryDir = join(PROJECT_STATE_DIR, "memory");
+    const memoryFiles = {};
+    if (existsSync(memoryDir)) {
+      const entries = await readdir(memoryDir, { withFileTypes: true });
+      for (const e of entries) {
+        if (e.isFile() && e.name.endsWith(".md")) {
+          memoryFiles[e.name] = safeReadText(join(memoryDir, e.name), 8000);
+        }
+      }
+    }
+    return {
+      layer: "deep",
+      focus: focus || null,
+      state,
+      project_state: projectState,
+      adrs,
+      memory_files: memoryFiles,
+    };
+  }
+  throw new Error(`Unknown layer: ${layer} (use 'core', 'working' or 'deep')`);
+}
+
+async function artifactList(typeFilter, statusFilter) {
+  const items = [];
+
+  const specsBase = join(PROJECT_STATE_DIR, "specs");
+  const specTypes = ["ADR", "RFC", "PRD", "SDD", "RUNBOOKS", "TASKS", "BRD"];
+  for (const t of specTypes) {
+    const dir = join(specsBase, t);
+    if (!existsSync(dir)) continue;
+    const entries = await readdir(dir);
+    for (const f of entries) {
+      if (!f.endsWith(".md") || f.startsWith("_")) continue;
+      const txt = safeReadText(join(dir, f), 4000) || "";
+      const idMatch = txt.match(/^id:\s*(\S+)/m);
+      const statusMatch = txt.match(/^status:\s*(\S+)/m);
+      const titleMatch = txt.match(/^#\s+(.+)$/m);
+      const normalizedType = t.replace(/S$/, "");
+      items.push({
+        type: normalizedType,
+        file: `${t}/${f}`,
+        id: idMatch?.[1] || f,
+        status: statusMatch?.[1] || null,
+        title: titleMatch?.[1] || null,
+      });
+    }
+  }
+
+  // Snapshots
+  const snapshotsDir = join(PROJECT_STATE_DIR, "snapshots");
+  if (existsSync(snapshotsDir)) {
+    const entries = await readdir(snapshotsDir, { withFileTypes: true });
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      items.push({
+        type: "snapshot",
+        file: `snapshots/${e.name}`,
+        id: e.name,
+        status: null,
+        title: e.name,
+      });
+    }
+  }
+
+  // Packages
+  const packagesDir = join(PROJECT_STATE_DIR, "context", "packages");
+  if (existsSync(packagesDir)) {
+    const entries = await readdir(packagesDir);
+    for (const f of entries) {
+      if (!f.endsWith(".md")) continue;
+      items.push({
+        type: "package",
+        file: `context/packages/${f}`,
+        id: f.replace(/\.md$/, ""),
+        status: null,
+        title: f,
+      });
+    }
+  }
+
+  // Workflows
+  if (existsSync(WORKFLOWS_DIR)) {
+    const entries = await readdir(WORKFLOWS_DIR);
+    for (const f of entries) {
+      if (!f.endsWith(".json") || f.startsWith("_")) continue;
+      const wf = safeReadJson(join(WORKFLOWS_DIR, f)) || {};
+      items.push({
+        type: "workflow",
+        file: `workflows/${f}`,
+        id: wf.id || f,
+        status: wf.version || null,
+        title: wf.description || null,
+      });
+    }
+  }
+
+  let filtered = items;
+  if (typeFilter) filtered = filtered.filter((i) => i.type === typeFilter);
+  if (statusFilter) filtered = filtered.filter((i) => i.status === statusFilter);
+
+  // Write index if no filter (canonical full index)
+  if (!typeFilter && !statusFilter) {
+    try {
+      const artifactsDir = join(PROJECT_STATE_DIR, "artifacts");
+      if (!existsSync(artifactsDir)) await mkdir(artifactsDir, { recursive: true });
+      const indexBlob = {
+        compiled_at: new Date().toISOString(),
+        count: items.length,
+        items,
+      };
+      await writeFile(ARTIFACTS_INDEX_PATH, JSON.stringify(indexBlob, null, 2), "utf8");
+    } catch (_) { /* best-effort */ }
+  }
+
+  return { count: filtered.length, total: items.length, items: filtered };
+}
+
+async function listWorkflows() {
+  if (!existsSync(WORKFLOWS_DIR)) return { workflows: [] };
+  const entries = await readdir(WORKFLOWS_DIR, { withFileTypes: true });
+  const out = [];
+  for (const e of entries) {
+    if (!e.isFile() || !e.name.endsWith(".json") || e.name.startsWith("_")) continue;
+    try {
+      const raw = await readFile(join(WORKFLOWS_DIR, e.name), "utf8");
+      const wf = JSON.parse(raw);
+      out.push({
+        id: wf.id,
+        version: wf.version,
+        description: wf.description,
+        steps: Array.isArray(wf.steps) ? wf.steps.length : 0,
+        file: e.name,
+      });
+    } catch (err) {
+      out.push({ id: e.name.replace(/\.json$/, ""), error: String(err.message || err), file: e.name });
+    }
+  }
+  return { workflows: out };
+}
+
+// ---------- MCP Prompts (ADR-0010) ----------
+// Expõe os 3 workflows canônicos (init/sync/work) como MCP Prompts.
+// Em IDEs que suportam o primitivo Prompts (Claude Code, Cursor recente),
+// aparecem nativamente no autocomplete `/` — funcionam apenas conectando o MCP.
+// Híbrido: cada prompt retorna instrução para a LLM chamar `aios_run_workflow`
+// + contexto enriquecido (state.identity, ROUTER hint, suggested intent).
+
+const PROMPT_WORKFLOWS = ["init", "sync", "work"];
+
+async function listMcpPrompts() {
+  const prompts = [];
+  for (const name of PROMPT_WORKFLOWS) {
+    const wfPath = join(WORKFLOWS_DIR, `${name}.json`);
+    if (!existsSync(wfPath)) continue;
+    try {
+      const wf = JSON.parse(await readFile(wfPath, "utf8"));
+      prompts.push({
+        name,
+        title: `/${name}`,
+        description: wf.description || `Run the ${name} workflow.`,
+        arguments: [
+          {
+            name: "intent",
+            description:
+              name === "work"
+                ? "Descrição da tarefa a executar (recomendado)."
+                : "Intent opcional para contextualizar a execução.",
+            required: name === "work",
+          },
+        ],
+      });
+    } catch (_) {
+      // skip malformed
+    }
+  }
+  return prompts;
+}
+
+async function buildRouterHint(intent) {
+  if (!intent || typeof intent !== "string") return null;
+  try {
+    const routes = await parseRouter();
+    const q = normalizeQuery(intent);
+    const matched = [];
+    const files = new Set();
+    for (const r of routes) {
+      for (const t of r.triggers) {
+        if (t && q.includes(t)) {
+          matched.push(r.title);
+          for (const f of r.files) files.add(f);
+          break;
+        }
+      }
+    }
+    if (matched.length === 0) return null;
+    return { matched_routes: matched, conditional_files: [...files] };
+  } catch (_) {
+    return null;
+  }
+}
+
+async function getMcpPrompt(name, args = {}) {
+  if (!PROMPT_WORKFLOWS.includes(name)) {
+    throw new Error(`Unknown prompt: ${name}`);
+  }
+  const wf = await loadWorkflow(name);
+  const intent = typeof args.intent === "string" ? args.intent.trim() : "";
+
+  // Coleta contexto enriquecido (best-effort: nunca falha o prompt)
+  let identity = null;
+  let lifecycle = null;
+  let maturity = null;
+  try {
+    const state = await loadState();
+    identity = state.identity || null;
+    lifecycle = state.lifecycle || null;
+    maturity = state.identity?.maturity || null;
+  } catch (_) { /* state ausente é ok */ }
+
+  const routerHint = await buildRouterHint(intent);
+
+  // Monta os argumentos da tool conforme convenção do workflow engine
+  const toolArgs = { name };
+  const input = {};
+  if (intent) input.intent = intent;
+  if (Object.keys(input).length > 0) toolArgs.input = input;
+
+  // Texto principal: instrução pra LLM + contexto compacto
+  const lines = [];
+  lines.push(`# /${name} — AI OS workflow (v${wf.version || "?"})`);
+  lines.push("");
+  lines.push(wf.description || "");
+  lines.push("");
+  lines.push("## Ação");
+  lines.push("Chame a tool MCP `aios_run_workflow` com estes argumentos:");
+  lines.push("");
+  lines.push("```json");
+  lines.push(JSON.stringify(toolArgs, null, 2));
+  lines.push("```");
+
+  if (Array.isArray(wf.guarantees) && wf.guarantees.length > 0) {
+    lines.push("");
+    lines.push("## Garantias do workflow");
+    for (const g of wf.guarantees) lines.push(`- ${g}`);
+  }
+
+  if (identity || lifecycle || maturity) {
+    lines.push("");
+    lines.push("## Contexto do projeto (state.json)");
+    const ctxObj = {};
+    if (identity) ctxObj.identity = identity;
+    if (lifecycle) ctxObj.lifecycle = lifecycle;
+    if (maturity) ctxObj.maturity = maturity;
+    lines.push("```json");
+    lines.push(JSON.stringify(ctxObj, null, 2));
+    lines.push("```");
+  }
+
+  if (routerHint) {
+    lines.push("");
+    lines.push("## ROUTER hint (intent → arquivos condicionais)");
+    lines.push("```json");
+    lines.push(JSON.stringify(routerHint, null, 2));
+    lines.push("```");
+  }
+
+  lines.push("");
+  lines.push(
+    "> Após chamar `aios_run_workflow`, siga `rules/execution-flow.md`: emita `OS:loaded(...)` na primeira linha, classifique a tarefa, e termine com bloco `[OS Audit]`.",
+  );
+
+  return {
+    description: wf.description || `Run the ${name} workflow.`,
+    messages: [
+      {
+        role: "user",
+        content: { type: "text", text: lines.join("\n") },
+      },
+    ],
+  };
+}
+
+// ---------- MCP JSON-RPC handler ----------
+async function handleRpc(msg) {
+  const { method, id, params } = msg;
+  try {
+    if (method === "initialize") {
+      return {
+        jsonrpc: "2.0",
+        id,
+        result: {
+          protocolVersion: "2024-11-05",
+          capabilities: { tools: {}, prompts: {} },
+          serverInfo: { name: "ai-os", version: "1.2.0" },
+        },
+      };
+    }
+    if (method === "tools/list") {
+      return { jsonrpc: "2.0", id, result: { tools: TOOLS } };
+    }
+    if (method === "tools/call") {
+      const handler = HANDLERS[params.name];
+      if (!handler) throw new Error(`Unknown tool: ${params.name}`);
+      const result = await handler(params.arguments || {});
+      const text = typeof result === "string" ? result : JSON.stringify(result, null, 2);
+      return { jsonrpc: "2.0", id, result: { content: [{ type: "text", text }] } };
+    }
+    if (method === "prompts/list") {
+      const prompts = await listMcpPrompts();
+      return { jsonrpc: "2.0", id, result: { prompts } };
+    }
+    if (method === "prompts/get") {
+      const result = await getMcpPrompt(params?.name, params?.arguments || {});
+      return { jsonrpc: "2.0", id, result };
+    }
+    if (method === "notifications/initialized") return null; // notif, no reply
+    if (method === "ping") return { jsonrpc: "2.0", id, result: {} };
+    throw new Error(`Method not found: ${method}`);
+  } catch (e) {
+    return { jsonrpc: "2.0", id, error: { code: -32000, message: e.message } };
+  }
+}
+
+// ---------- Transports ----------
+function startStdio() {
+  const rl = readline.createInterface({ input: process.stdin });
+  rl.on("line", async (line) => {
+    if (!line.trim()) return;
+    let msg;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      return;
+    }
+    const resp = await handleRpc(msg);
+    if (resp) process.stdout.write(JSON.stringify(resp) + "\n");
+  });
+  process.stderr.write(`[aios] MCP server up (stdio) — mode: ${STEALTHOS_MODE}, project: ${PROJECT_ROOT}\n`);
+  if (STEALTHOS_MODE === "hybrid") {
+    process.stderr.write(`[aios] KB: ${KB_DIR}, project state: ${PROJECT_STATE_DIR}\n`);
+  }
+}
+
+async function tryListen(server, port, attempts = 5) {
+  return new Promise((resolveProm, rejectProm) => {
+    let tries = 0;
+    function tryPort(p) {
+      server.once("error", (err) => {
+        if (err.code === "EADDRINUSE" && tries < attempts) {
+          tries++;
+          const next = p + 1;
+          process.stderr.write(`[aios] Port ${p} busy, trying ${next}\n`);
+          tryPort(next);
+        } else {
+          rejectProm(err);
+        }
+      });
+      server.listen(p, "127.0.0.1", () => resolveProm(p));
+    }
+    tryPort(port);
+  });
+}
+
+async function startHttp() {
+  const server = createServer(async (req, res) => {
+    if (req.method === "GET" && req.url === "/health") {
+      const h = await HANDLERS["aios_health"]({});
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify(h, null, 2));
+      return;
+    }
+    if (req.method === "POST" && req.url === "/rpc") {
+      let body = "";
+      req.on("data", (d) => (body += d));
+      req.on("end", async () => {
+        let msg;
+        try {
+          msg = JSON.parse(body);
+        } catch {
+          res.writeHead(400);
+          res.end('{"error":"invalid json"}');
+          return;
+        }
+        const resp = await handleRpc(msg);
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(resp || {}));
+      });
+      return;
+    }
+    if (req.method === "GET" && req.url === "/tools") {
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify(TOOLS, null, 2));
+      return;
+    }
+    res.writeHead(404);
+    res.end("Not found");
+  });
+
+  try {
+    const port = await tryListen(server, REQUESTED_PORT, 10);
+    // Write port to runtime file
+    const runtimeDir = join(PROJECT_STATE_DIR, ".runtime");
+    await mkdir(runtimeDir, { recursive: true });
+    await writeFile(join(runtimeDir, "port"), String(port));
+    await writeFile(join(runtimeDir, "daemon.pid"), String(process.pid));
+    process.stderr.write(`[aios] HTTP server listening on http://127.0.0.1:${port}\n`);
+    process.stderr.write(`[aios] Endpoints: GET /health, GET /tools, POST /rpc\n`);
+  } catch (e) {
+    process.stderr.write(`[aios] HTTP start failed: ${e.message}\n`);
+    process.exit(1);
+  }
+}
+
+// ---------- Boot ----------
+if (HTTP_MODE) {
+  await startHttp();
+} else {
+  startStdio();
+}
+
+// Graceful shutdown
+process.on("SIGINT", () => process.exit(0));
+process.on("SIGTERM", () => process.exit(0));