@mcp-graph-workflow/agent-graph-flow 0.5.0 → 0.7.0

package/dist/cli/index.js

@@ -7094,8 +7094,8 @@ var init_implementation_executor = __esm({
     };
     defaultRunner = (command, cwd) => {
       try {
-        const output17 = execSync(command, { cwd, encoding: "utf8", stdio: "pipe" });
-        return { exitCode: 0, output: output17 };
+        const output18 = execSync(command, { cwd, encoding: "utf8", stdio: "pipe" });
+        return { exitCode: 0, output: output18 };
       } catch (err) {
         const e = err;
         return {
@@ -14578,13 +14578,13 @@ function pruneOrphanWorktrees(options) {
     }
   }
   try {
-    const output17 = execSync("git worktree prune --verbose", execOpts).toString();
+    const output18 = 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: output17 });
+      log46.debug("shadow-branch:prune-ok", { reapedBranches, reapedWorktrees, output: output18 });
     }
-    return { pruned: true, reapedBranches, reapedWorktrees, output: output17 };
+    return { pruned: true, reapedBranches, reapedWorktrees, output: output18 };
   } catch (err) {
     const error = String(err);
     log46.debug("shadow-branch:prune-failed", { error });
@@ -14655,6 +14655,181 @@ ${count} skill(s).`);
   return cmd;
 }
 
+// src/cli/commands/principles-cmd.ts
+init_esm_shims();
+
+// src/core/doctrine/principles.ts
+init_esm_shims();
+var PRINCIPLES = Object.freeze([
+  // ── Promessa (o filtro de toda decisão) ──────────────────
+  {
+    id: "three-pillars",
+    title: "Tr\xEAs pilares",
+    category: "promise",
+    statement: "R\xE1pido \xB7 best-practice SWE \xB7 custo de token brutalmente baixo. O que n\xE3o serve aos tr\xEAs, n\xE3o entra.",
+    rationale: "Uma promessa \xFAnica alinha cada decis\xE3o de produto; remove ambiguidade sobre o que merece existir."
+  },
+  // ── TDD ──────────────────────────────────────────────────
+  {
+    id: "tdd-red-green-refactor",
+    title: "TDD Red \u2192 Green \u2192 Refactor",
+    category: "tdd",
+    statement: "Sem teste, sem c\xF3digo. Escreva o teste que falha (Red), fa\xE7a passar (Green), ent\xE3o refatore.",
+    rationale: "O teste primeiro define o contrato e elimina retrabalho \u2014 o anti-vibe-coding por excel\xEAncia."
+  },
+  {
+    id: "ac-as-contract",
+    title: "AC como contrato",
+    category: "tdd",
+    statement: "Crit\xE9rios de aceita\xE7\xE3o Given/When/Then s\xE3o o contrato; o DoD precisa passar antes de `done`.",
+    rationale: "AC test\xE1vel transforma inten\xE7\xE3o em verifica\xE7\xE3o objetiva \u2014 nada \xE9 'pronto' por opini\xE3o."
+  },
+  // ── Clean Code ───────────────────────────────────────────
+  {
+    id: "clean-functions",
+    title: "Fun\xE7\xF5es pequenas e reveladoras",
+    category: "clean-code",
+    statement: "Fun\xE7\xF5es fazem uma coisa, num s\xF3 n\xEDvel de abstra\xE7\xE3o, com nomes que revelam inten\xE7\xE3o.",
+    rationale: "C\xF3digo que se l\xEA como prosa reduz alucina\xE7\xE3o do agente e custo de manuten\xE7\xE3o."
+  },
+  {
+    id: "typed-errors",
+    title: "Erros tipados",
+    category: "clean-code",
+    statement: "Nunca lance string crua; use erros tipados e trate falhas explicitamente.",
+    rationale: "Erros classific\xE1veis permitem retry inteligente e diagn\xF3sticos \u2014 n\xE3o silenciam o sistema."
+  },
+  {
+    id: "no-magic",
+    title: "Sem m\xE1gica, sem `any`",
+    category: "clean-code",
+    statement: "Sem n\xFAmeros m\xE1gicos, sem `any`; tipos estritos e constantes nomeadas.",
+    rationale: "Tipos s\xE3o contexto de m\xE1quina \u2014 elevam o agent-readiness e barram regress\xF5es em compila\xE7\xE3o."
+  },
+  // ── XP ───────────────────────────────────────────────────
+  {
+    id: "atomic-decomposition",
+    title: "Decomposi\xE7\xE3o at\xF4mica",
+    category: "xp",
+    statement: "Cada task \xE9 complet\xE1vel em \u22642h; epics viram tasks at\xF4micas antes de implementar.",
+    rationale: "Pequenos passos verific\xE1veis mant\xEAm o ciclo curto e o custo previs\xEDvel."
+  },
+  {
+    id: "anti-one-shot",
+    title: "Anti-one-shot",
+    category: "xp",
+    statement: "Nunca gere um sistema inteiro num prompt; decomponha e itere.",
+    rationale: "Gera\xE7\xE3o one-shot infla tokens e esconde defeitos \u2014 o oposto da disciplina incremental."
+  },
+  {
+    id: "code-detachment",
+    title: "Code detachment",
+    category: "xp",
+    statement: "Se a IA errou, explique o erro via prompt e regenere \u2014 n\xE3o edite o resultado \xE0 m\xE3o.",
+    rationale: "Mant\xE9m o agente como autor respons\xE1vel e preserva a rastreabilidade no grafo."
+  },
+  // ── Lean / Theory of Constraints ─────────────────────────
+  {
+    id: "wip-one",
+    title: "WIP = 1",
+    category: "lean",
+    statement: "No m\xE1ximo uma task `in_progress` por vez.",
+    rationale: "Lei de Little: cycle_time = WIP / throughput \u2014 menos WIP, menos cycle time."
+  },
+  {
+    id: "pull-not-push",
+    title: "Pull, n\xE3o push",
+    category: "lean",
+    statement: "`next` puxa a pr\xF3xima task desbloqueada; nunca empurre para `in_progress`.",
+    rationale: "Sistema pull respeita o gargalo (TOC) e evita ac\xFAmulo de WIP."
+  },
+  // ── Flow / economia de token (a fórmula do dono no centro) ─
+  {
+    id: "token-economy-lambda-flow",
+    title: "Hipofrontalidade: \u03BB_flow",
+    category: "flow",
+    statement: "\u03BB_flow = \u03BB_base + (\u03B1 \xB7 \u03A6(t)). \u03A6 (\xEDndice de flow, EMA com histerese) governa a agressividade do esquecimento; o decaimento e^{-\u03BB\xB7d} dilui a vizinhan\xE7a do grafo \u2014 cortando tokens de contexto sem perder invariantes.",
+    rationale: "O diferencial do projeto: um controlador determin\xEDstico de esquecimento corta o custo de contexto sem sumariza\xE7\xE3o por LLM."
+  },
+  {
+    id: "repo-map-ranked",
+    title: "Repo-map ranqueado",
+    category: "flow",
+    statement: "Injete s\xEDmbolos ranqueados por PageRank num budget ~1k tokens, focados na task.",
+    rationale: "Contexto de entrada m\xEDnimo e relevante \u2014 corte de token sem perder sinal."
+  },
+  {
+    id: "compact-feedback",
+    title: "Feedback compacto no retry",
+    category: "flow",
+    statement: "No retry, realimente s\xF3 a sa\xEDda de teste que falhou (truncada), pedindo fix incremental.",
+    rationale: "Menos tokens por itera\xE7\xE3o e menos escala\xE7\xF5es que re-geram do zero."
+  }
+]);
+function listPrinciples() {
+  return PRINCIPLES;
+}
+function getPrinciple(id) {
+  return PRINCIPLES.find((p) => p.id === id);
+}
+function principlesByCategory(category) {
+  return PRINCIPLES.filter((p) => p.category === category);
+}
+function listCategories() {
+  const seen = [];
+  for (const p of PRINCIPLES) {
+    if (!seen.includes(p.category)) seen.push(p.category);
+  }
+  return seen;
+}
+
+// src/cli/commands/principles-cmd.ts
+function output17(msg) {
+  process.stdout.write(msg + "\n");
+}
+var CATEGORY_LABEL = {
+  promise: "Promessa",
+  tdd: "TDD",
+  "clean-code": "Clean Code",
+  xp: "XP",
+  lean: "Lean / TOC",
+  flow: "Flow / economia de token"
+};
+function principlesCommand() {
+  const cmd = new Command("principles").description(
+    "O credo de engenharia da CLI: Clean Code \xB7 XP \xB7 TDD \xB7 Lean + \u03BB_flow (economia de token)"
+  );
+  cmd.command("list", { isDefault: true }).description("Lista os princ\xEDpios agrupados por categoria").option("-c, --category <cat>", "Filtra por categoria (promise|tdd|clean-code|xp|lean|flow)").action((opts) => {
+    const cats = opts.category ? [opts.category] : listCategories();
+    for (const cat of cats) {
+      const items = principlesByCategory(cat);
+      if (items.length === 0) {
+        output17(`(categoria desconhecida: ${cat})`);
+        continue;
+      }
+      output17(`
+${CATEGORY_LABEL[cat] ?? cat}`);
+      for (const p of items) output17(`  \u2022 ${p.title.padEnd(28)} ${p.statement}`);
+    }
+    output17(`
+${listPrinciples().length} princ\xEDpios \xB7 use 'principles show <id>' para detalhes.`);
+  });
+  cmd.command("show <id>").description("Detalha um princ\xEDpio (t\xEDtulo, categoria, statement, rationale)").action((id) => {
+    const p = getPrinciple(id);
+    if (!p) {
+      output17(`Princ\xEDpio desconhecido: ${id}. Tente 'principles list'.`);
+      process.exitCode = 1;
+      return;
+    }
+    output17(`${p.title}  [${CATEGORY_LABEL[p.category] ?? p.category}]`);
+    output17(`
+  ${p.statement}`);
+    output17(`
+  Por qu\xEA: ${p.rationale}`);
+  });
+  return cmd;
+}
+
 // src/cli/index.ts
 var program = new Command();
 program.name("agent-graph-flow").description(PROMISE).version(VERSION, "-v, --version");
@@ -14677,6 +14852,7 @@ program.addCommand(doctorCommand());
 program.addCommand(gcCommand());
 program.addCommand(skillCommand());
 program.addCommand(profileCommand());
+program.addCommand(principlesCommand());
 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.5.0",
+  "version": "0.7.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",