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

package/dist/cli/index.js

@@ -2890,6 +2890,28 @@ var init_migrations = __esm({
         ON flow_metrics(project_id, created_at DESC);
       CREATE INDEX IF NOT EXISTS idx_flow_metrics_mode
         ON flow_metrics(mode, created_at DESC);
+    `
+      },
+      {
+        version: 97,
+        // Reuso determinístico (Épico R): cache de artefatos (edits gerados e verdes)
+        // por assinatura de task. Quando a mesma assinatura reaparece, o loop reusa os
+        // edits sem chamar o modelo (~0 tokens). Pairs com src/core/reuse/*.
+        description: "artifact_cache \u2014 reuso determin\xEDstico de edits por task-signature",
+        sql: `
+      CREATE TABLE IF NOT EXISTS artifact_cache (
+        id               TEXT PRIMARY KEY,
+        signature        TEXT NOT NULL,
+        node_id          TEXT,
+        applied_edits    TEXT NOT NULL,
+        approach_summary TEXT,
+        model            TEXT,
+        outcome          TEXT NOT NULL,
+        created_at       INTEGER NOT NULL,
+        UNIQUE(signature, outcome)
+      );
+      CREATE INDEX IF NOT EXISTS idx_artifact_cache_signature
+        ON artifact_cache(signature, created_at DESC);
     `
       }
     ];
@@ -7094,8 +7116,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 {
@@ -7255,9 +7277,11 @@ function defaultSleep(ms) {
 function buildInitialPrompt(node, opts = {}) {
   const repoMapBlock = opts.repoMap && opts.repoMap.length > 0 ? [`Contexto do reposit\xF3rio (refer\xEAncia, n\xE3o reescreva o que j\xE1 existe):`, opts.repoMap, ""] : [];
   const flowBlock = opts.flowContext && opts.flowContext.length > 0 ? [opts.flowContext, ""] : [];
+  const scaffoldBlock = opts.scaffoldHint && opts.scaffoldHint.length > 0 ? [`Scaffold de refer\xEAncia (task semelhante j\xE1 resolvida \u2014 reaproveite o que servir):`, opts.scaffoldHint, ""] : [];
   return [
     ...repoMapBlock,
     ...flowBlock,
+    ...scaffoldBlock,
     `Implemente a task "${node.title}" (id: ${node.id}) seguindo TDD.`,
     "Responda APENAS com um bloco ```json. H\xE1 DOIS mecanismos:",
     '- "edits" (PREFIRA \u2014 economia de token): [{ "path", "oldString", "newString", "replaceAll"? }].',
@@ -7286,8 +7310,25 @@ async function attemptImplementation(deps, options) {
   const sleep2 = deps.sleep ?? defaultSleep;
   let lastResult;
   let lastError;
+  const reuse = options.reuse;
+  if (reuse?.kind === "exact") {
+    const result = await deps.execute({ edits: reuse.edits });
+    if (result.testPassed === true) {
+      log25.info("Reuso exato verde \u2014 0 tokens de modelo", { node: options.node.id, sourceId: reuse.sourceId });
+      return { success: true, attempts: 1, lastResult: result, appliedEdits: reuse.edits, reused: "exact" };
+    }
+    lastResult = result;
+    lastError = result.testOutput;
+    log25.warn("Reuso exato vermelho \u2014 caindo para gera\xE7\xE3o", { node: options.node.id });
+  }
+  const scaffoldHint = reuse?.kind === "scaffold" ? reuse.edits.map((e) => `\u2500\u2500 ${e.path} \u2500\u2500
++ ${e.newString}`).join("\n") : void 0;
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-    const prompt = attempt === 1 || !lastResult ? buildInitialPrompt(options.node, { repoMap: options.repoMap, flowContext: options.flowContext }) : buildRetryPrompt(options.node, lastResult, maxFeedbackChars);
+    const prompt = attempt === 1 || !lastResult ? buildInitialPrompt(options.node, {
+      repoMap: options.repoMap,
+      flowContext: options.flowContext,
+      scaffoldHint
+    }) : buildRetryPrompt(options.node, lastResult, maxFeedbackChars);
     let text;
     try {
       text = await deps.generate(prompt);
@@ -7328,7 +7369,13 @@ async function attemptImplementation(deps, options) {
         oldString: e.oldString,
         newString: e.newString
       }));
-      return { success: true, attempts: attempt, lastResult, appliedEdits };
+      return {
+        success: true,
+        attempts: attempt,
+        lastResult,
+        appliedEdits,
+        ...reuse?.kind === "scaffold" ? { reused: "scaffold" } : {}
+      };
     }
     lastError = lastResult.testOutput;
     log25.warn("Testes vermelhos", { attempt, node: options.node.id });
@@ -8653,6 +8700,97 @@ var init_flow_compact = __esm({
     log28 = createLogger({ layer: "core", source: "flow-compact.ts" });
   }
 });
+function norm2(text) {
+  return text.trim().toLowerCase().replace(/\s+/g, " ");
+}
+function normSorted(items) {
+  return (items ?? []).map(norm2).filter((s) => s.length > 0).sort();
+}
+function computeTaskSignature(input) {
+  const canonical = {
+    title: norm2(input.title),
+    type: norm2(input.type ?? "task"),
+    ac: normSorted(input.acceptanceCriteria),
+    tags: normSorted(input.tags)
+  };
+  return createHash("sha256").update(JSON.stringify(canonical)).digest("hex");
+}
+var init_task_signature = __esm({
+  "src/core/reuse/task-signature.ts"() {
+    init_esm_shims();
+  }
+});
+
+// src/core/reuse/artifact-cache.ts
+function recordArtifact(db, row) {
+  db.prepare(
+    `INSERT OR IGNORE INTO artifact_cache
+       (id, signature, node_id, applied_edits, approach_summary, model, outcome, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`
+  ).run(
+    row.id,
+    row.signature,
+    row.nodeId ?? null,
+    JSON.stringify(row.appliedEdits),
+    row.approachSummary ?? null,
+    row.model ?? null,
+    row.outcome,
+    row.createdAt
+  );
+}
+function parseEdits(json) {
+  try {
+    const parsed = JSON.parse(json);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+function queryBySignature(db, signature) {
+  const rows = db.prepare(
+    `SELECT id, signature, node_id, applied_edits, approach_summary, model, outcome, created_at
+       FROM artifact_cache
+       WHERE signature = ?
+       ORDER BY created_at DESC`
+  ).all(signature);
+  return rows.map((r) => ({
+    id: r.id,
+    signature: r.signature,
+    nodeId: r.node_id ?? void 0,
+    appliedEdits: parseEdits(r.applied_edits),
+    approachSummary: r.approach_summary ?? void 0,
+    model: r.model ?? void 0,
+    outcome: r.outcome,
+    createdAt: r.created_at
+  }));
+}
+var init_artifact_cache = __esm({
+  "src/core/reuse/artifact-cache.ts"() {
+    init_esm_shims();
+  }
+});
+
+// src/core/reuse/resolve-reuse.ts
+function resolveReuse(db, signature, deps = {}, options = {}) {
+  const exact = queryBySignature(db, signature).find((r) => r.outcome === "success");
+  if (exact && exact.appliedEdits.length > 0) {
+    return { kind: "exact", edits: exact.appliedEdits, sourceId: exact.id };
+  }
+  const threshold = options.scaffoldThreshold ?? DEFAULT_SCAFFOLD_THRESHOLD;
+  const neighbor = deps.findNeighbor?.(signature);
+  if (neighbor && neighbor.similarity >= threshold && neighbor.edits.length > 0) {
+    return { kind: "scaffold", edits: neighbor.edits, sourceId: neighbor.sourceId, similarity: neighbor.similarity };
+  }
+  return { kind: "none" };
+}
+var DEFAULT_SCAFFOLD_THRESHOLD;
+var init_resolve_reuse = __esm({
+  "src/core/reuse/resolve-reuse.ts"() {
+    init_esm_shims();
+    init_artifact_cache();
+    DEFAULT_SCAFFOLD_THRESHOLD = 0.85;
+  }
+});
 
 // src/cli/shared/live-implement.ts
 function buildLiveImplement(options) {
@@ -8689,6 +8827,17 @@ function buildLiveImplement(options) {
         `  [flow] \u03A6=${flow.flow.phi.toFixed(2)} \u03BB=${flow.flow.lambda.toFixed(2)} podados=${flow.flow.prunedCount} pinados=${flow.flow.pinnedCount} \u2192 ${flow.flow.tokensSaved} tok economizados`
       );
     }
+    const fullNode = store2.getNodeById?.(node.id);
+    const signature = computeTaskSignature({
+      title: node.title,
+      acceptanceCriteria: fullNode?.acceptanceCriteria,
+      type: fullNode?.type,
+      tags: fullNode?.tags
+    });
+    const reuse = resolveReuse(store2.getDb(), signature);
+    if (reuse.kind !== "none") {
+      onLog?.(`  [reuse] ${reuse.kind} (sig ${signature.slice(0, 8)}\u2026) \u2192 ${reuse.kind === "exact" ? "0 tok se verde" : "scaffold no prompt"}`);
+    }
     const outcome = await attemptImplementation(
       {
         generate: async (prompt) => {
@@ -8704,8 +8853,9 @@ function buildLiveImplement(options) {
         },
         execute: (plan) => executePlan(plan, { workspaceDir: dir, defaultTestCommand: testCmd, runCommand: guardedRunner })
       },
-      { node, maxAttempts, repoMap, flowContext }
+      { node, maxAttempts, repoMap, flowContext, reuse }
     );
+    if (outcome.reused === "exact") onLog?.(`  [reuse] exact verde \u2014 0 tokens de modelo`);
     const files = outcome.lastResult?.applied.length ?? 0;
     const task = ledger.byTask(node.id);
     onLog?.(
@@ -8729,6 +8879,21 @@ function buildLiveImplement(options) {
       });
     } catch {
     }
+    if (outcome.success && outcome.appliedEdits && outcome.appliedEdits.length > 0) {
+      try {
+        recordArtifact(store2.getDb(), {
+          id: generateId("art"),
+          signature,
+          nodeId: node.id,
+          appliedEdits: outcome.appliedEdits,
+          approachSummary: buildApproachSummary(outcome.lastResult?.applied ?? [], []),
+          model: client.modelFor("implement"),
+          outcome: "success",
+          createdAt: Date.now()
+        });
+      } catch {
+      }
+    }
     return outcome.success;
   };
   return { implement, repoSymbolCount: repoSymbols.length };
@@ -8748,6 +8913,9 @@ var init_live_implement = __esm({
     init_flow_compact();
     init_episodic_outcomes_store();
     init_id();
+    init_task_signature();
+    init_resolve_reuse();
+    init_artifact_cache();
     REPO_MAP_TOKEN_BUDGET = 1e3;
   }
 });
@@ -9856,15 +10024,15 @@ function meanPoolAndNormalize(data, validTokens, dim) {
       embedding[dVar] += data[tVar * dim + dVar];
     }
   }
-  let norm2 = 0;
+  let norm3 = 0;
   for (let dVar = 0; dVar < dim; dVar++) {
     embedding[dVar] /= validTokens;
-    norm2 += embedding[dVar] * embedding[dVar];
+    norm3 += embedding[dVar] * embedding[dVar];
   }
-  norm2 = Math.sqrt(norm2);
-  if (norm2 > 0) {
+  norm3 = Math.sqrt(norm3);
+  if (norm3 > 0) {
     for (let dVar = 0; dVar < dim; dVar++) {
-      embedding[dVar] /= norm2;
+      embedding[dVar] /= norm3;
     }
   }
   return embedding;
@@ -14578,13 +14746,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 +14823,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 +15020,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.6.0",
+  "version": "0.8.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",