@mcp-graph-workflow/agent-graph-flow 0.8.0 → 0.9.0

package/dist/cli/index.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import * as path17 from 'path';
-import path17__default, { join, isAbsolute, dirname, resolve, relative } from 'path';
+import path17__default, { join, basename, isAbsolute, dirname, resolve, relative } from 'path';
 import { fileURLToPath } from 'url';
 import { z } from 'zod/v4';
 import * as fs from 'fs';
-import fs__default, { existsSync, rmSync, readFileSync, mkdirSync, writeFileSync, statSync, lstatSync, readdirSync, unlinkSync, copyFileSync } from 'fs';
+import fs__default, { existsSync, rmSync, writeFileSync, readFileSync, mkdirSync, statSync, lstatSync, readdirSync, unlinkSync, copyFileSync } from 'fs';
 import { AsyncLocalStorage } from 'async_hooks';
 import Database2 from 'better-sqlite3';
 import { randomUUID, randomBytes, createHash } from 'crypto';
@@ -7116,8 +7116,8 @@ var init_implementation_executor = __esm({
     };
     defaultRunner = (command, cwd) => {
       try {
-        const output18 = execSync(command, { cwd, encoding: "utf8", stdio: "pipe" });
-        return { exitCode: 0, output: output18 };
+        const output20 = execSync(command, { cwd, encoding: "utf8", stdio: "pipe" });
+        return { exitCode: 0, output: output20 };
       } catch (err) {
         const e = err;
         return {
@@ -9261,7 +9261,7 @@ function InteractiveApp({ dashboard, port, asyncPort, liveRunner, skillCommands
     process.stdout.isTTY ? "banner" : "dashboard"
   );
   const [input, setInput] = useState("");
-  const [log48, setLog] = useState([]);
+  const [log50, setLog] = useState([]);
   const [running, setRunning] = useState(false);
   const [elapsedMs, setElapsedMs] = useState(0);
   const [showHelp, setShowHelp] = useState(false);
@@ -9346,7 +9346,7 @@ ${skill.body}` : `Skill n\xE3o encontrada: ${parsed.cmd}`);
   }
   return /* @__PURE__ */ jsxs(Box, { flexDirection: "column", children: [
     /* @__PURE__ */ jsx(App, { model: dashboard }),
-    log48.length > 0 && /* @__PURE__ */ jsx(Box, { flexDirection: "column", marginTop: 1, borderStyle: "single", paddingX: 1, children: log48.map((line, i) => /* @__PURE__ */ jsx(Text, { children: line }, i)) }),
+    log50.length > 0 && /* @__PURE__ */ jsx(Box, { flexDirection: "column", marginTop: 1, borderStyle: "single", paddingX: 1, children: log50.map((line, i) => /* @__PURE__ */ jsx(Text, { children: line }, i)) }),
     showHelp && /* @__PURE__ */ jsxs(Box, { flexDirection: "column", marginTop: 1, borderStyle: "round", paddingX: 1, children: [
       /* @__PURE__ */ jsx(Text, { bold: true, children: "Comandos:" }),
       COMMANDS.map((c) => /* @__PURE__ */ jsxs(Text, { children: [
@@ -14746,13 +14746,13 @@ function pruneOrphanWorktrees(options) {
     }
   }
   try {
-    const output18 = execSync("git worktree prune --verbose", execOpts).toString();
+    const output20 = execSync("git worktree prune --verbose", execOpts).toString();
     if (reapedBranches > 0 || reapedWorktrees > 0) {
       log46.info("shadow-branch:prune-ok", { reapedBranches, reapedWorktrees, ttlMs });
     } else {
-      log46.debug("shadow-branch:prune-ok", { reapedBranches, reapedWorktrees, output: output18 });
+      log46.debug("shadow-branch:prune-ok", { reapedBranches, reapedWorktrees, output: output20 });
     }
-    return { pruned: true, reapedBranches, reapedWorktrees, output: output18 };
+    return { pruned: true, reapedBranches, reapedWorktrees, output: output20 };
   } catch (err) {
     const error = String(err);
     log46.debug("shadow-branch:prune-failed", { error });
@@ -14998,6 +14998,470 @@ ${listPrinciples().length} princ\xEDpios \xB7 use 'principles show <id>' para de
   return cmd;
 }
 
+// src/cli/commands/generate-prd-cmd.ts
+init_esm_shims();
+init_resolve_adapter();
+init_model_client();
+
+// src/core/prd/generate-prd.ts
+init_esm_shims();
+init_errors();
+function buildPrdPrompt(description) {
+  return [
+    `Voc\xEA \xE9 um Product Manager s\xEAnior. Escreva um PRD em Markdown para o produto descrito abaixo,`,
+    `pronto para ser importado num grafo de execu\xE7\xE3o (epics \u2192 tasks \u2192 crit\xE9rios de aceita\xE7\xE3o).`,
+    "",
+    `Descri\xE7\xE3o do produto:`,
+    description.trim(),
+    "",
+    `Estruture com EXATAMENTE estas se\xE7\xF5es (Markdown, headings ##):`,
+    `## Objetivo`,
+    `## Usu\xE1rios`,
+    `## Requisitos  (lista de epics; cada um com um id curto)`,
+    `## Crit\xE9rios de Aceita\xE7\xE3o  (Given/When/Then por requisito \u2014 test\xE1veis)`,
+    `## Constraints  (t\xE9cnicas e de neg\xF3cio)`,
+    `## Riscos`,
+    "",
+    `Seja espec\xEDfico e conciso. Cada AC deve ser verific\xE1vel por um teste automatizado.`
+  ].join("\n");
+}
+async function generatePrd(description, deps) {
+  if (description.trim().length === 0) {
+    throw new ValidationError("Descri\xE7\xE3o vazia \u2014 forne\xE7a o que deve ser constru\xEDdo para gerar o PRD.", []);
+  }
+  return deps.generate(buildPrdPrompt(description));
+}
+
+// src/cli/commands/generate-prd-cmd.ts
+init_extract();
+init_prd_to_graph();
+function output18(msg) {
+  process.stdout.write(msg + "\n");
+}
+function generatePrdCommand() {
+  return new Command("generate-prd").description("Gera um PRD.md a partir de uma descri\xE7\xE3o (via modelo); --import j\xE1 vira grafo").argument("<descricao>", "O que deve ser constru\xEDdo").option("-d, --dir <dir>", "Diret\xF3rio do projeto", process.cwd()).option("-o, --out <file>", "Arquivo de sa\xEDda do PRD", "PRD.md").option("--import", "Importa o PRD gerado para o grafo de execu\xE7\xE3o", false).option("--model <id>", "Modelo fixo; 'auto' usa o tier-router", "auto").action(async (descricao, opts) => {
+    const config = opts.model === "auto" ? { mode: "auto" } : { mode: "pinned", modelId: opts.model };
+    const resolved = resolveModelAdapter();
+    const client = new TieredModelClient(resolved.adapter, config);
+    output18(`[generate-prd] ${client.modelFor("plan")} via ${resolved.kind === "api" ? "API HTTP" : "CLI"} \u2192 gerando PRD\u2026`);
+    const md = await generatePrd(descricao, {
+      generate: async (prompt) => (await client.run("plan", prompt)).text
+    });
+    const outPath = join(opts.dir, opts.out);
+    writeFileSync(outPath, md, "utf8");
+    output18(`\u2713 PRD gravado em ${outPath} (${md.length} chars)`);
+    if (opts.import) {
+      const store2 = openStoreOrFail(opts.dir);
+      try {
+        if (!store2.getProject()) store2.initProject(basename(opts.dir));
+        const entities = extractEntities(md);
+        const graph = convertToGraph(entities, outPath);
+        store2.bulkInsert(graph.nodes, graph.edges);
+        store2.recordImport?.(outPath, graph.nodes.length, graph.edges.length);
+        output18(`\u2713 Importado: ${graph.nodes.length} n\xF3s, ${graph.edges.length} arestas`);
+      } finally {
+        store2.close();
+      }
+    } else {
+      output18(`Dica: rode 'import-prd ${opts.out}' ou repita com --import.`);
+    }
+  });
+}
+
+// src/cli/commands/build-cmd.ts
+init_esm_shims();
+
+// src/core/orchestrator/run-delivery.ts
+init_esm_shims();
+
+// src/core/orchestrator/orchestrator.ts
+init_esm_shims();
+function nextDeliveryAction(state) {
+  if (state.totalNodes === 0 || !state.hasRequirements) {
+    return { action: "import_prd", reason: "Grafo sem PRD \u2014 importe requisitos primeiro." };
+  }
+  if (state.oversizedCount > 0) {
+    return {
+      action: "decompose",
+      reason: `${state.oversizedCount} epic(s)/task(s) L/XL sem subtasks \u2014 decompor antes de implementar.`
+    };
+  }
+  if (state.readyTasks > 0 || state.inProgress > 0) {
+    return {
+      action: "implement",
+      reason: `${state.readyTasks} pronta(s), ${state.inProgress} em andamento \u2014 implementar (TDD).`
+    };
+  }
+  if (state.doneRatio >= 1) {
+    return { action: "done", reason: "Todas as tasks conclu\xEDdas \u2014 entrega completa." };
+  }
+  if (state.allBlocked) {
+    return { action: "escalate", reason: "Todas as tasks restantes est\xE3o bloqueadas \u2014 interven\xE7\xE3o humana." };
+  }
+  return { action: "escalate", reason: "Sem tasks acion\xE1veis \u2014 escalando para o humano." };
+}
+
+// src/core/orchestrator/run-delivery.ts
+async function runDelivery(getState, handlers, options) {
+  const actions = [];
+  for (let step = 0; step < options.maxSteps; step++) {
+    if (options.signal?.aborted === true) {
+      return { steps: step, stopped: "aborted", actions };
+    }
+    const decision = nextDeliveryAction(getState());
+    options.onStep?.(decision);
+    if (decision.action === "done") {
+      return { steps: step, stopped: "done", actions };
+    }
+    if (decision.action === "escalate") {
+      return { steps: step, stopped: "escalation", actions };
+    }
+    actions.push(decision.action);
+    if (decision.action === "import_prd") await handlers.importPrd();
+    else if (decision.action === "decompose") await handlers.decompose();
+    else await handlers.implement();
+  }
+  return { steps: options.maxSteps, stopped: "budget", actions };
+}
+
+// src/core/orchestrator/delivery-state.ts
+init_esm_shims();
+init_next_task();
+init_decompose();
+var TASK_TYPES = /* @__PURE__ */ new Set(["task", "subtask"]);
+var REQUIREMENT_TYPES = /* @__PURE__ */ new Set(["epic", "requirement"]);
+var EMPTY_STATE = {
+  totalNodes: 0,
+  hasRequirements: false,
+  oversizedCount: 0,
+  readyTasks: 0,
+  inProgress: 0,
+  allBlocked: false,
+  doneRatio: 0
+};
+function deriveDeliveryState(store2) {
+  if (!store2.getProject()) return { ...EMPTY_STATE };
+  const stats = store2.getStats();
+  const doc = store2.toGraphDocument();
+  const hasRequirements = doc.nodes.some((n) => REQUIREMENT_TYPES.has(n.type));
+  const oversizedCount = detectLargeTasks(doc).length;
+  const tasks = doc.nodes.filter((n) => TASK_TYPES.has(n.type));
+  const done = tasks.filter((t) => t.status === "done").length;
+  const inProgress = tasks.filter((t) => t.status === "in_progress").length;
+  const doneRatio = tasks.length > 0 ? done / tasks.length : 0;
+  const next = findNextTask(doc);
+  const actionable = next !== null && !("warning" in next);
+  const allBlocked = next !== null && "warning" in next && next.warning === "all_tasks_blocked";
+  return {
+    totalNodes: stats.totalNodes,
+    hasRequirements,
+    oversizedCount,
+    readyTasks: actionable ? 1 : 0,
+    inProgress,
+    allBlocked,
+    doneRatio
+  };
+}
+
+// src/cli/commands/build-cmd.ts
+init_extract();
+init_prd_to_graph();
+
+// src/core/planner/auto-decompose.ts
+init_esm_shims();
+init_xp_sizing();
+init_id();
+
+// src/core/planner/smart-decompose.ts
+init_esm_shims();
+init_id();
+init_logger();
+
+// src/core/planner/invest-validator.ts
+init_esm_shims();
+
+// src/core/planner/smart-decompose.ts
+var log48 = createLogger({ layer: "core", source: "smart-decompose.ts" });
+var INTEGRATION_KEYWORDS2 = [
+  "api",
+  "endpoint",
+  "database",
+  "db",
+  "persiste",
+  "persists",
+  "saves",
+  "sync",
+  "indexa",
+  "indexes",
+  "fetch",
+  "request",
+  "response",
+  "query",
+  "http",
+  "rest",
+  "graphql",
+  "grpc",
+  "webhook"
+];
+var E2E_KEYWORDS2 = [
+  "page",
+  "navega",
+  "navigates",
+  "click",
+  "clicks",
+  "form",
+  "browser",
+  "redirect",
+  "ui",
+  "dashboard",
+  "tab",
+  "button",
+  "modal",
+  "toast",
+  "screen",
+  "display",
+  "render",
+  "shows",
+  "visible"
+];
+function inferTestType2(acText) {
+  const lower = acText.toLowerCase();
+  if (E2E_KEYWORDS2.some((kw) => lower.includes(kw))) return "e2e";
+  if (INTEGRATION_KEYWORDS2.some((kw) => lower.includes(kw))) return "integration";
+  return "unit";
+}
+function acToTitle(ac, index) {
+  const truncated = ac.length > 60 ? ac.slice(0, 60).replace(/\s\S*$/, "...") : ac;
+  return `Subtask ${index + 1}: ${truncated}`;
+}
+function estimateFromTestType(testType) {
+  switch (testType) {
+    case "unit":
+      return 30;
+    case "integration":
+      return 60;
+    case "e2e":
+      return 90;
+  }
+}
+function smartDecompose(store2, nodeId) {
+  const node = store2.getNodeById(nodeId);
+  if (!node) {
+    log48.warn("smart-decompose:node_not_found", { nodeId });
+    return null;
+  }
+  const doc = store2.toGraphDocument();
+  const acChildNodes = doc.nodes.filter(
+    (n) => n.type === "acceptance_criteria" && n.parentId === nodeId
+  );
+  const acTexts = [
+    ...node.acceptanceCriteria ?? [],
+    ...acChildNodes.map((n) => n.title)
+  ];
+  if (acTexts.length === 0) {
+    log48.info("smart-decompose:no_ac", { nodeId });
+    return null;
+  }
+  const subtaskIds = [];
+  const subtasks = acTexts.map((ac, i) => {
+    subtaskIds.push(generateId("sub"));
+    const testType = inferTestType2(ac);
+    return {
+      title: acToTitle(ac, i),
+      type: "subtask",
+      acceptanceCriteria: [ac],
+      estimateMinutes: estimateFromTestType(testType),
+      suggestedTestType: testType
+    };
+  });
+  const edges = [];
+  for (let i = 1; i < subtaskIds.length; i++) {
+    edges.push({
+      from: subtaskIds[i],
+      to: subtaskIds[i - 1],
+      relation: "depends_on"
+    });
+  }
+  log48.info("smart-decompose:ok", {
+    nodeId,
+    subtasks: subtasks.length,
+    edges: edges.length,
+    testTypes: subtasks.map((s) => s.suggestedTestType)
+  });
+  return {
+    parentId: nodeId,
+    subtasks,
+    edges,
+    rationale: `Decomposed "${node.title}" into ${subtasks.length} subtasks (1 per AC). Test types: ${subtasks.map((s) => s.suggestedTestType).join(", ")}.`
+  };
+}
+
+// src/core/planner/auto-decompose.ts
+init_logger();
+init_time();
+var log49 = createLogger({ layer: "core", source: "auto-decompose.ts" });
+function persistDecomposition(store2, result) {
+  const createdNodeIds = [];
+  const provisionalToReal = /* @__PURE__ */ new Map();
+  const plannerIds = Array.from(
+    new Set(result.edges.flatMap((e) => [e.from, e.to]))
+  );
+  result.subtasks.forEach((sub, index) => {
+    const realId = generateId("sub");
+    createdNodeIds.push(realId);
+    if (plannerIds[index]) provisionalToReal.set(plannerIds[index], realId);
+    const timestamp = now();
+    const node = {
+      id: realId,
+      type: "subtask",
+      title: sub.title,
+      status: "backlog",
+      priority: 3,
+      parentId: result.parentId,
+      acceptanceCriteria: sub.acceptanceCriteria,
+      estimateMinutes: sub.estimateMinutes,
+      createdAt: timestamp,
+      updatedAt: timestamp
+    };
+    store2.insertNode(node);
+  });
+  let createdEdgeCount = 0;
+  for (const edge of result.edges) {
+    const from = provisionalToReal.get(edge.from);
+    const to = provisionalToReal.get(edge.to);
+    if (!from || !to) continue;
+    const realEdge = {
+      id: generateId("edge"),
+      from,
+      to,
+      relationType: "depends_on",
+      createdAt: now()
+    };
+    try {
+      store2.insertEdge(realEdge);
+      createdEdgeCount++;
+    } catch (err) {
+      log49.warn("auto-decompose:edge_insert_failed", {
+        from,
+        to,
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+  log49.info("auto-decompose:persisted", {
+    parentId: result.parentId,
+    subtasks: createdNodeIds.length,
+    edges: createdEdgeCount
+  });
+  return { createdNodeIds, createdEdgeCount };
+}
+var LARGE_XP_THRESHOLD3 = 4;
+function autoDecomposeLarge(store2, options = {}) {
+  const maxSubtasks = options.maxSubtasks ?? 8;
+  const minAcs = options.minAcs ?? 2;
+  const doc = store2.toGraphDocument();
+  const decomposed = [];
+  const skipped = [];
+  for (const node of doc.nodes) {
+    if (node.type !== "task") continue;
+    const ord = XP_SIZE_ORDER[node.xpSize ?? ""] ?? 0;
+    if (ord < LARGE_XP_THRESHOLD3) {
+      continue;
+    }
+    const hasChildren = doc.nodes.some((n) => n.parentId === node.id);
+    if (hasChildren) {
+      skipped.push({ parentId: node.id, reason: "has_children" });
+      continue;
+    }
+    const acChildren = doc.nodes.filter(
+      (n) => n.type === "acceptance_criteria" && n.parentId === node.id
+    );
+    const acCount = (node.acceptanceCriteria?.length ?? 0) + acChildren.length;
+    if (acCount < minAcs) {
+      skipped.push({ parentId: node.id, reason: "insufficient_acs" });
+      continue;
+    }
+    if (acCount > maxSubtasks) {
+      skipped.push({ parentId: node.id, reason: "too_many_acs" });
+      continue;
+    }
+    const resultValue = smartDecompose(store2, node.id);
+    if (!resultValue) {
+      skipped.push({ parentId: node.id, reason: "decompose_failed" });
+      continue;
+    }
+    const persisted = persistDecomposition(store2, resultValue);
+    decomposed.push({ parentId: node.id, subtaskIds: persisted.createdNodeIds });
+  }
+  log49.info("auto-decompose:scan_complete", {
+    decomposed: decomposed.length,
+    skipped: skipped.length
+  });
+  return { decomposed, skipped };
+}
+
+// src/cli/commands/build-cmd.ts
+init_autopilot_loop();
+init_store_port();
+init_live_implement();
+init_token_ledger();
+function output19(msg) {
+  process.stdout.write(msg + "\n");
+}
+function importPrdFile(store2, dir, prdPath) {
+  const path22 = prdPath ?? join(dir, "PRD.md");
+  if (!existsSync(path22)) {
+    throw new Error(`PRD n\xE3o encontrado em ${path22}. Rode 'generate-prd "<descri\xE7\xE3o>"' ou passe --prd <arquivo>.`);
+  }
+  if (!store2.getProject()) store2.initProject(basename(dir));
+  const entities = extractEntities(readFileSync(path22, "utf8"));
+  const graph = convertToGraph(entities, path22);
+  store2.bulkInsert(graph.nodes, graph.edges);
+  output19(`  \u2713 importado: ${graph.nodes.length} n\xF3s, ${graph.edges.length} arestas`);
+}
+function buildCommand() {
+  return new Command("build").description("Orquestra a entrega: PRD \u2192 grafo \u2192 decomp\xF5e \u2192 autopilot \u2192 entrega (m\xE1quina de estados)").option("-d, --dir <dir>", "Diret\xF3rio do projeto", process.cwd()).option("--prd <file>", "Caminho do PRD a importar (default: PRD.md)").option("--max <n>", "Teto de passos do orquestrador (cost-runaway)", "20").option("--live", "Implementa com o modelo real (autopilot --live)", false).option("--test-cmd <cmd>", "Comando de teste no --live", "npm test").action(async (opts) => {
+    const store2 = openStoreOrFail(opts.dir);
+    const ledger = new TokenLedger();
+    try {
+      const maxSteps = Math.max(1, parseInt(opts.max, 10) || 20);
+      const live = opts.live ? buildLiveImplement({ store: store2, dir: opts.dir, testCmd: opts.testCmd, retries: 2, ledger, onLog: output19 }) : null;
+      const handlers = {
+        importPrd: async () => importPrdFile(store2, opts.dir, opts.prd),
+        decompose: async () => {
+          const report2 = autoDecomposeLarge(store2);
+          output19(`  \u2713 decompostas ${report2.decomposed.length} epic(s) em subtasks`);
+        },
+        implement: async () => {
+          const port = makeStorePort(store2);
+          const implement = live ? live.implement : void 0;
+          const result = await runAutopilot(port, {
+            maxIterations: 1,
+            implement,
+            onStep: (s) => output19(`  ${s.action === "done" ? "\u2713" : s.action === "escalated" ? "\u26A0" : "\u2192"} ${s.title} [${s.action}] ${s.detail}`)
+          });
+          if (result.stopped === "escalation") throw new Error("autopilot escalou \u2014 interven\xE7\xE3o necess\xE1ria");
+        }
+      };
+      output19(`[build] orquestrando (max ${maxSteps} passos${opts.live ? ", --live" : ""})\u2026
+`);
+      const report = await runDelivery(() => deriveDeliveryState(store2), handlers, {
+        maxSteps,
+        onStep: (s) => output19(`\xBB ${s.action}: ${s.reason}`)
+      });
+      const t = ledger.totals();
+      output19(`
+Resumo: ${report.steps} passo(s), parou em '${report.stopped}'. Tokens: ${t.total}.`);
+      if (report.stopped === "escalation") process.exitCode = 1;
+    } catch (err) {
+      output19(`erro: ${err instanceof Error ? err.message : String(err)}`);
+      process.exitCode = 1;
+    } finally {
+      store2.close();
+    }
+  });
+}
+
 // src/cli/index.ts
 var program = new Command();
 program.name("agent-graph-flow").description(PROMISE).version(VERSION, "-v, --version");
@@ -15021,6 +15485,8 @@ program.addCommand(gcCommand());
 program.addCommand(skillCommand());
 program.addCommand(profileCommand());
 program.addCommand(principlesCommand());
+program.addCommand(generatePrdCommand());
+program.addCommand(buildCommand());
 function shouldLaunchTui() {
   const noArgs = process.argv.length <= 2;
   const isTty = Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-graph-workflow/agent-graph-flow",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Agente SWE autônomo, local-first e token-frugal: PRD → grafo de execução persistente, TDD obrigatório, custo de token brutalmente baixo. AGPL v3.",
   "type": "module",
   "main": "dist/index.js",

package/src/skills/any/orchestrate-delivery.md

@@ -0,0 +1,53 @@
+---
+name: orchestrate-delivery
+description: Skill mestre — orquestra a entrega end-to-end (dir vazio → PRD → grafo → autopilot → entrega) com economia brutal de token
+category: any
+phases: [ANALYZE, PLAN, IMPLEMENT, VALIDATE]
+---
+
+# orchestrate-delivery
+
+A skill mestre que conduz um produto do zero à entrega, **orquestrando as demais
+skills e comandos** por uma máquina de estados determinística (`nextDeliveryAction`)
+— sem gastar tokens decidindo o que fazer.
+
+## Quando usar
+
+- Diretório vazio: "construa um kanban do zero".
+- Quando você quer **um comando** que vá de PRD a software testado.
+
+## Fluxo (determinístico)
+
+```
+estado do grafo → nextDeliveryAction →
+  vazio/sem PRD        → import_prd   (generate-prd → import-prd)
+  epics L/XL           → decompose    (decompose / auto-subtasks)
+  tasks prontas        → implement    (autopilot --live, TDD)
+  todas done           → done         (entrega completa)
+  todas bloqueadas     → escalate     (intervenção humana)
+```
+
+O comando `build` executa este loop (`runDelivery`) com teto de passos
+(cost-runaway) e cancelamento (Esc). `generate-prd "<descrição>"` cria o PRD.
+
+## Economia de token (peça central)
+
+- **λ_flow** (`λ_flow = λ_base + α·Φ(t)`) dilui o contexto do grafo por
+  esquecimento determinístico.
+- **Reuso determinístico**: tasks já resolvidas reaplicam edits cacheados por
+  assinatura — **0 token de modelo** (não re-raciocina).
+- **repo-map ranqueado** (~1k tok) + **feedback compacto** no retry.
+- **exec-policy** barra comandos perigosos; **interrupt** (Esc) corta turnos.
+
+## Disciplina (inegociável)
+
+TDD Red→Green→Refactor · WIP=1 · pull-não-push · DoD antes de `done` ·
+decomposição atômica (≤2h) · anti-one-shot · code-detachment. Veja `principles`.
+
+## Comandos
+
+```bash
+mcp-graph-agent generate-prd "um kanban com colunas e cards" --import
+mcp-graph-agent build --live --max 20        # orquestra até entregar
+mcp-graph-agent principles                    # o credo de engenharia
+```