forjajs 5.1.0 → 5.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (113) hide show
  1. package/CHANGELOG.md +76 -0
  2. package/README.md +37 -4
  3. package/README.pt-BR.md +39 -4
  4. package/dist/apps/cli/src/index.d.ts +0 -1
  5. package/dist/apps/cli/src/index.js +43 -32
  6. package/dist/apps/dashboard/app/api/forja/[...path]/route.js +34 -1
  7. package/dist/apps/dashboard/app/api/forja/capabilities.d.ts +26 -0
  8. package/dist/apps/dashboard/app/api/forja/capabilities.js +39 -0
  9. package/dist/apps/dashboard/app/dashboard-client.jsx +607 -42
  10. package/dist/apps/server/src/forja-nest.module.d.ts +6 -0
  11. package/dist/apps/server/src/forja-nest.module.js +55 -0
  12. package/dist/apps/server/src/main.d.ts +21 -4
  13. package/dist/apps/server/src/main.js +79 -57
  14. package/dist/apps/server/src/task-planning-service.d.ts +29 -0
  15. package/dist/apps/server/src/task-planning-service.js +195 -0
  16. package/dist/apps/server/src/task-runtime-coordinator.d.ts +57 -0
  17. package/dist/apps/server/src/task-runtime-coordinator.js +229 -0
  18. package/dist/bin/forja.js +3 -2
  19. package/dist/lib/agent-evals.d.ts +138 -0
  20. package/dist/lib/agent-evals.js +349 -0
  21. package/dist/lib/cli-output.js +14 -2
  22. package/dist/lib/code-context.d.ts +33 -5
  23. package/dist/lib/code-context.js +70 -5
  24. package/dist/lib/context-builder.d.ts +49 -4
  25. package/dist/lib/context-builder.js +114 -47
  26. package/dist/lib/core/coverage-gate.d.ts +59 -0
  27. package/dist/lib/core/coverage-gate.js +58 -0
  28. package/dist/lib/core/doc-graph.d.ts +38 -0
  29. package/dist/lib/core/doc-graph.js +83 -0
  30. package/dist/lib/core/health.js +286 -5
  31. package/dist/lib/core/journey.js +26 -0
  32. package/dist/lib/core/registry.js +81 -6
  33. package/dist/lib/docs-reference.d.ts +35 -0
  34. package/dist/lib/docs-reference.js +57 -0
  35. package/dist/lib/project-wiring.js +6 -2
  36. package/dist/lib/session-memory.d.ts +38 -0
  37. package/dist/lib/session-memory.js +206 -0
  38. package/dist/lib/spec-trace.d.ts +46 -0
  39. package/dist/lib/spec-trace.js +184 -0
  40. package/dist/packages/adapter-nest/src/index.d.ts +2 -1
  41. package/dist/packages/adapter-nest/src/index.js +59 -1
  42. package/dist/packages/adapter-sqlite/src/index.d.ts +15 -1
  43. package/dist/packages/adapter-sqlite/src/index.js +61 -1
  44. package/dist/packages/context/src/index.d.ts +2 -0
  45. package/dist/packages/context/src/index.js +36 -15
  46. package/dist/packages/contracts/src/index.d.ts +64 -0
  47. package/dist/packages/core/src/index.d.ts +9 -1
  48. package/dist/packages/core/src/index.js +28 -3
  49. package/dist/packages/graph/src/index.js +14 -5
  50. package/dist/packages/mcp/src/index.d.ts +8 -0
  51. package/dist/packages/mcp/src/index.js +12 -1
  52. package/dist/packages/observability/src/index.d.ts +11 -0
  53. package/dist/packages/observability/src/index.js +3 -0
  54. package/dist/packages/orchestration/src/index.d.ts +15 -1
  55. package/dist/packages/orchestration/src/index.js +127 -21
  56. package/dist/packages/planner/src/index.d.ts +7 -1
  57. package/dist/packages/planner/src/index.js +67 -10
  58. package/dist/packages/planner/src/proposal-store.d.ts +30 -0
  59. package/dist/packages/planner/src/proposal-store.js +109 -0
  60. package/dist/packages/policy/src/index.d.ts +9 -16
  61. package/dist/packages/policy/src/index.js +114 -31
  62. package/dist/packages/runtime/src/index.d.ts +16 -2
  63. package/dist/packages/runtime/src/index.js +176 -61
  64. package/dist/scripts/build-smart-context.d.ts +2 -0
  65. package/dist/scripts/build-smart-context.js +12 -3
  66. package/dist/scripts/code-context.d.ts +3 -1
  67. package/dist/scripts/code-context.js +13 -3
  68. package/dist/scripts/coverage-gate.d.ts +2 -0
  69. package/dist/scripts/coverage-gate.js +101 -0
  70. package/dist/scripts/eval-agents.d.ts +11 -0
  71. package/dist/scripts/eval-agents.js +96 -0
  72. package/dist/scripts/gen-commands-doc.d.ts +2 -0
  73. package/dist/scripts/gen-commands-doc.js +18 -0
  74. package/dist/scripts/hook-session-memory.d.ts +9 -0
  75. package/dist/scripts/hook-session-memory.js +20 -0
  76. package/dist/scripts/hook-session-start.js +34 -0
  77. package/dist/scripts/spec-trace.d.ts +10 -0
  78. package/dist/scripts/spec-trace.js +73 -0
  79. package/dist/scripts/sync-universal-memory.js +69 -4
  80. package/dist/scripts/token-benchmark.d.ts +33 -1
  81. package/dist/scripts/token-benchmark.js +179 -5
  82. package/dist/scripts/token-economy.js +3 -1
  83. package/dist/scripts/tools-doctor.d.ts +16 -1
  84. package/dist/scripts/tools-doctor.js +58 -17
  85. package/docs/commands.md +155 -0
  86. package/docs/fluxo.md +11 -7
  87. package/docs/init-project.md +3 -1
  88. package/docs/llm-fit-loop.md +20 -0
  89. package/docs/manual-operacional-cli-sdd-gsd.md +3 -2
  90. package/docs/produto/factsheet-marketing.md +7 -5
  91. package/docs/produto/roteiro-demo.md +14 -5
  92. package/docs/quick-reference.md +3 -3
  93. package/docs/token-optimization.md +10 -6
  94. package/memory/90-decisions/0091-memoria-de-sessao-por-hooks.md +40 -0
  95. package/memory/90-decisions/0092-criterios-de-aceite-ligados-a-testes.md +37 -0
  96. package/memory/90-decisions/0093-avaliacoes-com-agentes-reais.md +40 -0
  97. package/package.json +4 -2
  98. package/specs/avaliacoes-de-agentes/spec.md +52 -0
  99. package/specs/criterios-ligados-a-testes/spec.md +42 -0
  100. package/specs/memoria-de-sessao/spec.md +48 -0
  101. package/specs/v6-agent-runtime-portable/spec.md +83 -0
  102. package/specs/v6-core-consolidation/spec.md +70 -0
  103. package/specs/v6-docs-drift/spec.md +85 -0
  104. package/specs/v6-quality-gates/spec.md +99 -0
  105. package/specs/v6-token-economy/spec.md +84 -0
  106. package/templates/evals/agents/adr.json +25 -0
  107. package/templates/evals/agents/memoria.json +32 -0
  108. package/templates/evals/agents/proxima-acao.json +29 -0
  109. package/templates/evals/agents/spec-nova.json +26 -0
  110. package/templates/evals/agents/teste-do-criterio.json +29 -0
  111. package/templates/project/AGENTS.md +7 -0
  112. package/templates/project/CLAUDE.md +3 -2
  113. package/templates/project/skills/testing/SKILL.md +1 -1
@@ -10,11 +10,14 @@
10
10
  * Uso: npm run token:benchmark
11
11
  */
12
12
  import fs from 'node:fs';
13
+ import os from 'node:os';
13
14
  import path from 'node:path';
15
+ import { spawnSync } from 'node:child_process';
16
+ import Database from 'better-sqlite3';
14
17
  import ContextBuilder from '../lib/context-builder.js';
15
18
  import { fileURLToPath } from 'node:url';
16
19
  import { getDbPath, ensureSchema } from './memory-schema.js';
17
- import { pkgRoot } from '../lib/paths.js';
20
+ import { pkgRoot, script } from '../lib/paths.js';
18
21
  const __dirname = path.dirname(fileURLToPath(import.meta.url));
19
22
  const root = pkgRoot;
20
23
  /**
@@ -49,6 +52,132 @@ function walkMarkdown(dir, out = []) {
49
52
  }
50
53
  return out;
51
54
  }
55
+ /**
56
+ * O projeto de referência sai do banco, não de um nome chutado. O benchmark media
57
+ * 'benchmark-project', que não existe em lugar nenhum: domain e task voltavam só com os nós globais e
58
+ * o relatório anunciava ~99% de "economia" por não ter injetado quase nada (achado da SPEC-057 —
59
+ * medição que não mede é pior que medição nenhuma, porque decide no escuro com ar de número).
60
+ */
61
+ function referenceProject(dbPath) {
62
+ const db = new Database(dbPath, { readonly: true });
63
+ try {
64
+ const row = db.prepare(`
65
+ SELECT p.name AS name, COUNT(n.id) AS nodes
66
+ FROM projects p JOIN memory_nodes n ON n.project_id = p.id
67
+ GROUP BY p.id ORDER BY nodes DESC LIMIT 1
68
+ `).get();
69
+ return row && row.nodes > 0 ? row : null;
70
+ }
71
+ finally {
72
+ db.close();
73
+ }
74
+ }
75
+ /** Nós injetados no pacote. Comparado com o do modo global, diz se o projeto contribuiu com algo. */
76
+ function nodesIn(pack) {
77
+ return (pack.match(/^## 📄 /gm) || []).length;
78
+ }
79
+ /**
80
+ * Termo do modo task: um que existe no projeto (o primeiro domínio indexado, senão o primeiro slug de
81
+ * spec). O termo chutado em inglês que estava aqui antes — 'architecture implementation' — não casa
82
+ * com memória em pt-BR, e o modo task media um pacote sem nenhum nó do projeto.
83
+ */
84
+ function taskKeyword(dbPath, project) {
85
+ const db = new Database(dbPath, { readonly: true });
86
+ try {
87
+ const rows = db.prepare(`
88
+ SELECT n.path AS path FROM memory_nodes n JOIN projects p ON p.id = n.project_id
89
+ WHERE p.name = ? ORDER BY n.path LIMIT 200
90
+ `).all(project);
91
+ for (const row of rows) {
92
+ const domain = /30-domains\/([^/]+)\//.exec(row.path)?.[1];
93
+ if (domain)
94
+ return domain;
95
+ }
96
+ const spec = rows.find((r) => r.path.includes('specs/'));
97
+ return spec ? path.basename(path.dirname(spec.path)) : 'regra';
98
+ }
99
+ finally {
100
+ db.close();
101
+ }
102
+ }
103
+ /**
104
+ * Cenário de referência da SPEC-057 (AC-2): um projeto descartável com 60 nós de ~2,5KB — o volume
105
+ * mínimo que o critério pede — gerado com texto fixo. Fixo porque número de economia que muda entre
106
+ * máquinas ou execuções não é evidência, é ruído.
107
+ *
108
+ * Os três termos cobrem os três caminhos do pack: FTS (casa e devolve `snippet()`), LIKE (substring
109
+ * no meio de palavra, que o porter não casa → janela calculada aqui) e nenhum (só globais).
110
+ */
111
+ const REF_PROJECT = 'ref-spec-057';
112
+ const REF_NODES = 60;
113
+ const REF_KEYWORDS = ['pagamentos', 'pagament', 'pagamentosavancado', 'termo-inexistente'];
114
+ function refNodeBody(i, termo) {
115
+ let body = `# Nota ${i} de ${termo}\n\n`;
116
+ for (let s = 0; s < 6; s++) {
117
+ body += `## Seção ${s}\n\n`;
118
+ body += `Este nó documenta a regra de ${termo} aplicada ao fluxo de pedidos: o agregado valida o ` +
119
+ `invariante, o repositório persiste e a apresentação traduz o resultado. O recálculo de ${termo} ` +
120
+ `usa duas casas decimais e publica evento com o identificador idempotente da tentativa anterior, ` +
121
+ `o que evita duplicidade no consumidor a jusante.\n\n`;
122
+ body += '- item de lista com contexto suficiente para ocupar uma linha inteira\n- outro item\n';
123
+ }
124
+ return body;
125
+ }
126
+ function referenceScenario() {
127
+ const ws = fs.mkdtempSync(path.join(os.tmpdir(), 'forja-ref-'));
128
+ try {
129
+ const proj = path.join(ws, 'projects', REF_PROJECT);
130
+ const write = (rel, body) => {
131
+ const abs = path.join(proj, rel);
132
+ fs.mkdirSync(path.dirname(abs), { recursive: true });
133
+ fs.writeFileSync(abs, body);
134
+ };
135
+ for (let i = 0; i < REF_NODES; i++) {
136
+ write(path.join('memory', '30-domains', `dom${i % 6}`, `nota-${i}.md`), refNodeBody(i, i % 3 === 0 ? 'pagamentos' : 'cobranca'));
137
+ }
138
+ write(path.join('docs', 'guia-pagamentosavancado.md'), refNodeBody(900, 'pagamentosavancado'));
139
+ const sync = spawnSync(process.execPath, [script('bin/forja'), 'sync:universal'], {
140
+ cwd: root,
141
+ encoding: 'utf8',
142
+ env: { ...process.env, FORJA_WORKSPACE: ws },
143
+ });
144
+ if (sync.status !== 0)
145
+ throw new Error(`sync do cenário de referência falhou: ${sync.stderr || sync.stdout}`);
146
+ const builder = new ContextBuilder(proj, path.join(ws, 'memory', 'sqlite', 'universal.db'));
147
+ try {
148
+ return REF_KEYWORDS.map((keyword) => {
149
+ const trecho = builder.build('task', REF_PROJECT, keyword);
150
+ const integral = builder.build('task', REF_PROJECT, keyword, { full: true });
151
+ const a = estimateTokens(trecho.length);
152
+ const b = estimateTokens(integral.length);
153
+ return { keyword, nodes: nodesIn(trecho), trecho: a, integral: b, corte: b === 0 ? 0 : Math.round(((b - a) / b) * 100) };
154
+ });
155
+ }
156
+ finally {
157
+ builder.close();
158
+ }
159
+ }
160
+ finally {
161
+ fs.rmSync(ws, { recursive: true, force: true });
162
+ }
163
+ }
164
+ function referenceScenarioReport(rows) {
165
+ console.log(`Cenário de referência SPEC-057 — ${REF_NODES} nós gerados, trecho FTS5 vs conteúdo integral\n`);
166
+ if (!rows) {
167
+ console.warn(' não foi possível medir\n');
168
+ return;
169
+ }
170
+ for (const r of rows) {
171
+ console.log(` "${r.keyword}"`.padEnd(28) + `${String(r.nodes).padStart(3)} nós · trecho ${String(r.trecho).padStart(6)} vs integral ${String(r.integral).padStart(6)} tokens · −${r.corte}%`);
172
+ }
173
+ // O AC-2 olha o termo que casa: é para ele que o `snippet()` existe. O termo sem casamento entra na
174
+ // tabela como controle — ali o pacote é só o global, e a redução diz respeito à política de cabeça.
175
+ const fts = rows.find((r) => r.keyword === 'pagamentos');
176
+ if (fts)
177
+ console.log(`\n Meta AC-2 (≥ 50% no termo que casa): −${fts.corte}% → ${fts.corte >= 50 ? '✅' : '❌'}\n`);
178
+ else
179
+ console.log('');
180
+ }
52
181
  /**
53
182
  * Executar benchmark
54
183
  */
@@ -56,12 +185,29 @@ async function benchmark() {
56
185
  console.log('Token Economy Benchmark\n');
57
186
  ensureSchema({ silent: true });
58
187
  const dbPath = getDbPath();
59
- const project = 'benchmark-project';
60
188
  if (!fs.existsSync(dbPath)) {
61
189
  console.warn('Database not found at:', dbPath);
62
190
  console.log(' Run: npm run memory:db:init');
63
191
  process.exit(1);
64
192
  }
193
+ // O cenário de referência da SPEC-057 vem antes: não depende de projeto indexado e é o número
194
+ // reproduzível (mesma fixture, qualquer máquina) que a evidência do AC-2 cita.
195
+ let refRows = null;
196
+ try {
197
+ refRows = referenceScenario();
198
+ }
199
+ catch (e) {
200
+ console.warn(` medir o cenário de referência falhou: ${e.message}`);
201
+ }
202
+ referenceScenarioReport(refRows);
203
+ const ref = referenceProject(dbPath);
204
+ if (!ref) {
205
+ console.warn('Nenhum projeto indexado no banco — os modos domain/task do SEU projeto ficaram de fora.');
206
+ console.log(' Rode dentro de um projeto: forja sync:universal\n');
207
+ return;
208
+ }
209
+ const project = ref.name;
210
+ console.log(`Projeto indexado: ${project} (${ref.nodes} nós)\n`);
65
211
  const builder = new ContextBuilder(root, dbPath);
66
212
  try {
67
213
  // 1. Simular contexto "antigo" (sem smart context)
@@ -96,10 +242,13 @@ async function benchmark() {
96
242
  console.log(` Cost: $${baselineCost}\n`);
97
243
  // 2. Testar 3 modos de contexto inteligente
98
244
  const modes = ['global', 'domain', 'task'];
245
+ const keywordTask = taskKeyword(dbPath, project);
99
246
  const results = [];
247
+ let globalNodes = 0;
248
+ let excerptAxis = null;
100
249
  for (const mode of modes) {
101
250
  console.log(`Scenario: ${mode.toUpperCase()} Mode\n`);
102
- const keyword = mode === 'task' ? 'architecture implementation' : '';
251
+ const keyword = mode === 'task' ? keywordTask : '';
103
252
  const start = Date.now();
104
253
  let context = '';
105
254
  try {
@@ -115,11 +264,30 @@ async function benchmark() {
115
264
  const tokens = estimateTokens(size);
116
265
  const cost = (tokens * 0.00001).toFixed(5);
117
266
  const savings = (((baselineTokens - tokens) / baselineTokens) * 100).toFixed(1);
267
+ const nodes = nodesIn(context);
268
+ if (mode === 'global')
269
+ globalNodes = nodes;
118
270
  console.log(` Size: ${formatBytes(size)}`);
119
271
  console.log(` Tokens: ${tokens.toLocaleString()}`);
272
+ console.log(` Nodes: ${nodes}`);
120
273
  console.log(` Time: ${duration}ms`);
121
274
  console.log(` Cost: $${cost}`);
122
- console.log(` Savings: ${savings}% (vs baseline)\n`);
275
+ console.log(` Savings: ${savings}% (vs baseline)`);
276
+ // Sem isto o relatório anuncia economia por não ter injetado nada: se domain/task não trazem um
277
+ // nó a mais que global, o projeto não entrou no pacote e o número não mede o que diz medir.
278
+ if (mode !== 'global' && nodes <= globalNodes) {
279
+ console.log(` ⚠️ nenhum nó do projeto além dos globais — economia vazia, não conte este número`);
280
+ }
281
+ console.log('');
282
+ // Eixo SPEC-057: o mesmo pacote com o conteúdo integral de cada nó (--full-context) vs o trecho
283
+ // casado que o FTS devolve. É a redução que o corte de trecho compra, medida no projeto real.
284
+ if (mode === 'task') {
285
+ const integral = estimateTokens(builder.build(mode, project, keyword, { full: true }).length);
286
+ const corte = integral === 0 ? 0 : Math.round(((integral - tokens) / integral) * 100);
287
+ console.log(` Trecho vs integral (SPEC-057): ${tokens.toLocaleString()} vs ${integral.toLocaleString()} tokens → −${corte}%`);
288
+ console.log(` Meta AC-2: ≥ 50% → ${corte >= 50 ? '✅' : '❌'}\n`);
289
+ excerptAxis = { trecho: tokens, integral, corte };
290
+ }
123
291
  results.push({
124
292
  mode,
125
293
  size,
@@ -146,6 +314,12 @@ async function benchmark() {
146
314
  console.log(` Tokens: ${bestMode.tokens.toLocaleString()}`);
147
315
  console.log(` Cost: $${bestMode.cost.toFixed(5)}`);
148
316
  console.log(` Savings: ${bestMode.savings.toFixed(1)}%\n`);
317
+ if (excerptAxis) {
318
+ console.log(`Trecho vs integral (SPEC-057, modo task em ${project})`);
319
+ console.log(` Com snippet FTS5: ${excerptAxis.trecho.toLocaleString()} tokens`);
320
+ console.log(` Conteúdo integral: ${excerptAxis.integral.toLocaleString()} tokens`);
321
+ console.log(` Redução: −${excerptAxis.corte}% (meta AC-2: ≥ 50%)\n`);
322
+ }
149
323
  // 4. Cálculo de ROI
150
324
  const monthlyRequests = 1000;
151
325
  const savedCostPerMonth = (baselineTokens - avgTokens) * 0.00001 * monthlyRequests;
@@ -179,4 +353,4 @@ async function benchmark() {
179
353
  if (import.meta.url === `file://${process.argv[1]}`) {
180
354
  benchmark().catch(console.error);
181
355
  }
182
- export { benchmark, estimateTokens };
356
+ export { benchmark, estimateTokens, formatBytes, walkMarkdown, nodesIn, referenceProject, referenceScenario, referenceScenarioReport, taskKeyword, };
@@ -45,7 +45,9 @@ function projectMode(projectRoot) {
45
45
  say('Para cada domínio: ler o mapa (context.md) vs ler todo o código da fatia.\n');
46
46
  const rows = [];
47
47
  for (const domain of domains) {
48
- const pack = buildContextPack({ projectRoot, domain, includeCode: true });
48
+ // `full: true` de propósito: este eixo mede o custo de ler a fatia INTEIRA no frio. Com o
49
+ // orçamento da SPEC-057 ligado, mediríamos o pacote cortado e o −61% viraria ficção.
50
+ const pack = buildContextPack({ projectRoot, domain, includeCode: true, full: true });
49
51
  const economy = pack.codeTokens === 0 ? '—' : `−${Math.round(((pack.codeTokens - pack.mapTokens) / pack.codeTokens) * 100)}%`;
50
52
  rows.push({ domínio: domain, mapa_tok: pack.mapTokens, código_tok: pack.codeTokens, mapa_vs_código: economy });
51
53
  say(`■ ${domain}`);
@@ -17,4 +17,19 @@
17
17
  *
18
18
  * Uso: forja tools:doctor
19
19
  */
20
- export {};
20
+ export interface ToolState {
21
+ readonly name: string;
22
+ readonly role: string;
23
+ readonly gate: string;
24
+ readonly install: string;
25
+ readonly ok: boolean;
26
+ readonly version: string | null;
27
+ }
28
+ export interface ProjectWiring {
29
+ readonly status: 'ok' | 'warn' | 'fail';
30
+ readonly checks: readonly {
31
+ id: string;
32
+ status: string;
33
+ detail: string;
34
+ }[];
35
+ }
@@ -21,6 +21,7 @@ import { spawnSync } from 'node:child_process';
21
21
  import fs from 'node:fs';
22
22
  import path from 'node:path';
23
23
  import { runChecks, worstStatus, bucketFor, BUCKET_LABEL } from '../lib/core/health.js';
24
+ import { emitError, emitOk } from '../lib/cli-output.js';
24
25
  import { COMMANDS } from '../lib/core/registry.js';
25
26
  import { checkProjectWiring } from '../lib/project-wiring.js';
26
27
  import { isInsideFrameworkRepo } from '../lib/workspace.js';
@@ -64,10 +65,18 @@ const TOOLS = [
64
65
  function detect(cmd, args) {
65
66
  const res = spawnSync(cmd, args, { encoding: 'utf8' });
66
67
  if (res.error && res.error.code === 'ENOENT')
67
- return { ok: false };
68
+ return { ok: false, version: null };
68
69
  const version = (res.stdout || res.stderr || '').trim().split('\n')[0] || 'instalado';
69
70
  return { ok: true, version };
70
71
  }
72
+ /** Sondar e imprimir eram uma coisa só; o ramo `--json` precisa do resultado sem o texto. */
73
+ function detectTools() {
74
+ return TOOLS.map((tool) => {
75
+ const [cmd, args] = tool.probe;
76
+ const { ok, version } = detect(cmd, args);
77
+ return { name: tool.name, role: tool.role, gate: tool.gate, install: tool.install, ok, version };
78
+ });
79
+ }
71
80
  const TAG = {
72
81
  ok: 'OK ',
73
82
  warn: 'AVISO',
@@ -91,43 +100,51 @@ function printCore(results) {
91
100
  console.log('');
92
101
  }
93
102
  }
94
- function printTools() {
103
+ function printTools(tools) {
95
104
  console.log(`— ${BUCKET_LABEL.optional} — potencializam o harness, nunca travam (ADR-0018)\n`);
96
105
  let installed = 0;
97
- for (const tool of TOOLS) {
98
- const [cmd, args] = tool.probe;
99
- const { ok, version } = detect(cmd, args);
100
- if (ok)
106
+ for (const tool of tools) {
107
+ if (tool.ok)
101
108
  installed += 1;
102
- console.log(`${ok ? TAG.ok : 'FALTA'} ${tool.name.padEnd(13)} ${ok ? version : '(ausente)'}`);
109
+ console.log(`${tool.ok ? TAG.ok : 'FALTA'} ${tool.name.padEnd(13)} ${tool.ok ? tool.version : '(ausente)'}`);
103
110
  console.log(` papel: ${tool.role}`);
104
111
  console.log(` gate: ${tool.gate}`);
105
- if (!ok)
112
+ if (!tool.ok)
106
113
  console.log(` instalar: ${tool.install}`);
107
114
  console.log('');
108
115
  }
109
- console.log(`${installed}/${TOOLS.length} ferramentas disponíveis.`);
116
+ console.log(`${installed}/${tools.length} ferramentas disponíveis.`);
110
117
  console.log('Ferramentas ausentes apenas desativam seus gates — o fluxo nunca trava por elas.\n');
111
118
  }
112
119
  /** Num projeto (fora do repo do framework): a IA, os hooks e o MCP estão ligados a ele? */
113
- function printProject() {
120
+ function collectProject() {
114
121
  const cwd = process.cwd();
115
122
  if (isInsideFrameworkRepo(cwd) || !fs.existsSync(path.join(cwd, 'AGENTS.md')))
116
123
  return null;
117
- console.log('Projeto — a IA enxerga o Forja aqui? (forja project:wire --check)\n');
118
124
  const checks = checkProjectWiring(cwd, { commands: COMMANDS });
119
- for (const c of checks)
125
+ return { status: checks.some((c) => c.status === 'fail') ? 'fail' : checks.some((c) => c.status === 'warn') ? 'warn' : 'ok', checks };
126
+ }
127
+ function printProject(project) {
128
+ if (project === null)
129
+ return null;
130
+ console.log('Projeto — a IA enxerga o Forja aqui? (forja project:wire --check)\n');
131
+ for (const c of project.checks)
120
132
  console.log(`${TAG[c.status]} ${c.id.padEnd(13)} ${c.detail}`);
121
133
  console.log('');
122
- return checks.some((c) => c.status === 'fail') ? 'fail' : checks.some((c) => c.status === 'warn') ? 'warn' : 'ok';
134
+ return project.status;
123
135
  }
124
136
  async function main() {
125
- console.log('\nForja doctor\n');
137
+ const asJson = process.argv.includes('--json');
126
138
  const core = await runChecks();
139
+ const tools = detectTools();
140
+ const project = collectProject();
141
+ if (asJson)
142
+ emitJson(core, project, tools);
143
+ console.log('\nForja doctor\n');
127
144
  printCore(core);
128
- const project = printProject();
129
- printTools();
130
- if (project === 'fail') {
145
+ const projectVerdict = printProject(project);
146
+ printTools(tools);
147
+ if (projectVerdict === 'fail') {
131
148
  console.log('Projeto desconectado da IA — corrija com: forja project:wire');
132
149
  process.exit(1);
133
150
  }
@@ -147,4 +164,28 @@ async function main() {
147
164
  }
148
165
  console.log('Núcleo saudável.');
149
166
  }
167
+ /**
168
+ * O registry anuncia `tools:doctor [--json]` e o script ignorava a flag: quem pedia JSON recebia o
169
+ * texto humano de volta. Mesmo contrato do ADR-0082 (um objeto no stdout, diagnóstico no stderr) e
170
+ * os mesmos exit codes do ramo de texto — 1 para núcleo quebrado ou projeto desconectado.
171
+ */
172
+ function emitJson(core, project, tools) {
173
+ if (project?.status === 'fail')
174
+ return emitError('Projeto desconectado da IA — corrija com: forja project:wire', { code: 'PROJECT_UNWIRED' });
175
+ const criticas = core.filter((r) => r.status === 'fail' && r.severity === 'critical');
176
+ if (criticas.length > 0) {
177
+ return emitError(`Núcleo quebrado — ${criticas.length} ${criticas.length === 1 ? 'falha' : 'falhas'} crítica(s)`, {
178
+ code: 'CORE_UNHEALTHY',
179
+ detail: criticas.map((r) => `${r.id}: ${r.fix || 'sem correção automática'}`).join('\n'),
180
+ });
181
+ }
182
+ return emitOk({
183
+ verdict: worstStatus(core),
184
+ core: core.map((r) => ({ id: r.id, status: r.status, severity: r.severity ?? null, detail: r.detail ?? null, fix: r.fix ?? null })),
185
+ ...(project === null ? {} : { project: { status: project.status, checks: project.checks } }),
186
+ tools,
187
+ toolsAvailable: tools.filter((tool) => tool.ok).length,
188
+ toolsTotal: tools.length,
189
+ });
190
+ }
150
191
  main();
@@ -0,0 +1,155 @@
1
+ # Referência de comandos
2
+
3
+ > Gerado por `forja docs:gen` a partir de `lib/core/registry.ts` — **não edite à mão.**
4
+ > 106 comandos · 34 skills distribuídas aos projetos gerados.
5
+
6
+ ## workspace
7
+
8
+ | Comando | O que faz | Uso | Tier | Gates |
9
+ |---|---|---|---|---|
10
+ | `forja workspace:init` | Cria a estrutura base do workspace (~/forja-workspace) | `forja workspace:init` | core | — |
11
+ | `forja project:new` | Cria projeto no workspace e registra ficha em 30-projects/ | `forja project:new <nome> [-- --ai claude,copilot --skip-backend] [--template <nome>]` | core | workspace |
12
+ | `forja setup` | Rotina de primeiro uso: workspace:init + sync:universal, atrás de confirmação | `forja setup [--yes]` | core | — |
13
+ | `forja project:list` | Lista projetos do workspace | `forja project:list` | advanced | — |
14
+ | `forja project:upgrade` | Traz peças novas de scaffold e religa a IA num projeto (ou --all) — aditivo; --apply aplica | `forja project:upgrade [--apply] [--project <path> \| --all] [--json]` | advanced | — |
15
+ | `forja workspace:project:check` | Valida padrões em um projeto do workspace | `forja workspace:project:check` | advanced | workspace |
16
+ | `forja project:templates` | Lista os boilerplates: quais são templates validados (project:new --template) e quais são referência | `forja project:templates [--json]` | advanced | — |
17
+ | `forja project:wire` | Conecta o projeto à inteligência do Forja: instruções nativas, hooks, sub-agents e MCP | `forja project:wire [--check] [--ai claude,codex,gemini,copilot] [--json]` | advanced | — |
18
+
19
+ ## sdd
20
+
21
+ | Comando | O que faz | Uso | Tier | Gates |
22
+ |---|---|---|---|---|
23
+ | `forja spec:new` | Cria specs/<slug>/spec.md a partir do template | `forja spec:new <slug>` | core | — |
24
+ | `forja spec:plan` | Deriva plan.md de uma spec | `forja spec:plan <slug>` | core | — |
25
+ | `forja spec:tasks` | Decompõe plan.md em tasks.md | `forja spec:tasks <slug>` | core | — |
26
+ | `forja spec:trace` | Critérios de aceite × testes que os citam (SPEC-NNN AC-N): cobertos, sem teste e órfãos | `forja spec:trace [slug] [--strict] [--json]` | advanced | — |
27
+ | `forja spec:check` | Valida completude da spec (gate de governança) | `forja spec:check [slug] [--json]` | core | — |
28
+ | `forja spec:set-status` | Atualiza o status de um artefato SDD | `forja spec:set-status` | advanced | — |
29
+
30
+ ## gsd
31
+
32
+ | Comando | O que faz | Uso | Tier | Gates |
33
+ |---|---|---|---|---|
34
+ | `forja status` | Retrato único do estado: workspace, sprint, corrida, specs, runs, handoffs | `forja status [--json]` | core | workspace-warn |
35
+ | `forja next` | A próxima ação recomendada + o comando exato para executá-la | `forja next [--json]` | core | workspace-warn |
36
+ | `forja orchestrate` | Abre uma corrida: a cadeia SDD/GSD como máquina de estados guardada por gates | `forja orchestrate "<objetivo>" --slug <slug>` | core | — |
37
+ | `forja orchestrate:status` | O estado da corrida: etapas feitas, aberta, gates e vereditos | `forja orchestrate:status <slug>` | core | — |
38
+ | `forja orchestrate:advance` | Roda o gate da etapa aberta; verde → abre a próxima; vermelho → trava com o parecer | `forja orchestrate:advance <slug>` | core | — |
39
+ | `forja gsd:plan` | Cria runbook GSD em .context/ | `forja gsd:plan` | advanced | — |
40
+ | `forja gsd:handoff` | Registra handoff GSD padronizado (ADR-0005) | `forja gsd:handoff` | advanced | — |
41
+ | `forja gsd:check` | Valida gates básicos do runbook GSD | `forja gsd:check` | advanced | — |
42
+ | `forja hermes:handoff` | Registra handoff ADR-0005 bruto via agent-router | `forja hermes:handoff` | advanced | — |
43
+ | `forja agent:route` | Roteia/inspeciona handoffs (agent-router) | `forja agent:route <append\|list [--open] [--mine\|--project <nome>] [--to <papel>]\|show\|done\|in_progress\|cancel\|archive\|schema> [args]` | advanced | — |
44
+ | `forja sprint:start` | Inicia sprint | `forja sprint:start` | advanced | — |
45
+ | `forja sprint:status` | Status da sprint atual | `forja sprint:status` | advanced | — |
46
+ | `forja sprint:complete` | Encerra sprint | `forja sprint:complete` | advanced | — |
47
+
48
+ ## design
49
+
50
+ | Comando | O que faz | Uso | Tier | Gates |
51
+ |---|---|---|---|---|
52
+ | `forja design:check` | Valida brief visual antes do handoff | `forja design:check` | advanced | — |
53
+ | `forja design:select` | Sugere referências design-md por superfície | `forja design:select` | advanced | — |
54
+
55
+ ## code
56
+
57
+ | Comando | O que faz | Uso | Tier | Gates |
58
+ |---|---|---|---|---|
59
+ | `forja code:check` | Valida índice codegraph (worktree + freshness) | `forja code:check` | advanced | — |
60
+ | `forja code:impact` | Chamadores + blast radius de um símbolo | `forja code:impact` | advanced | — |
61
+ | `forja graph:sync` | Indexa arquivos rastreáveis do workspace no GraphLoop por checksum | `forja graph:sync` | advanced | workspace-warn |
62
+ | `forja drift:check` | Reindexa e sinaliza relações verified que a extração atual não reproduz mais (SPEC-030). --domain <d> restringe; --all roda por projeto do workspace | `forja drift:check [--domain <d>] [--all]` | advanced | workspace-warn |
63
+ | `forja adr:list` | Lista ADRs (memory/90-decisions/) com status, via Engineering Graph (SPEC-032) | `forja adr:list` | advanced | workspace-warn |
64
+ | `forja adr:show` | Mostra uma ADR: status, arquivo, constraints (SPEC-032) | `forja adr:show` | advanced | workspace-warn |
65
+ | `forja adr:impact` | Componentes/documentos alcançáveis a partir de uma ADR, via GraphLoop.impact (SPEC-032) | `forja adr:impact` | advanced | workspace-warn |
66
+ | `forja adr:graph` | Subgrafo (JSON) de nós ADR/SPEC + vizinhança (SPEC-032) | `forja adr:graph` | advanced | workspace-warn |
67
+ | `forja architecture:compile` | ADRs (## Constraints) → .context/architecture/constitution.json (SPEC-033) | `forja architecture:compile` | advanced | — |
68
+ | `forja architecture:check` | Verifica o código real contra a Architecture Constitution compilada (SPEC-033) | `forja architecture:check` | advanced | workspace-warn |
69
+ | `forja architecture:status` | Resumo da Constitution: regras active/proposed, última compilação (SPEC-033) | `forja architecture:status` | advanced | — |
70
+ | `forja architecture:explain` | Explica uma regra da Constitution: ADR de origem, severidade, texto original (SPEC-033) | `forja architecture:explain` | advanced | — |
71
+ | `forja architecture:approve` | Promove uma regra proposed a active via ApprovalLedger (SPEC-033) | `forja architecture:approve` | advanced | — |
72
+ | `forja risk:assess` | Score de risco 0-100 (7 fatores) sobre o diff de um ref (default: working tree) (SPEC-034) | `forja risk:assess` | advanced | workspace-warn |
73
+ | `forja risk:explain` | Reexibe um assessment de risco já calculado, com todos os fatores (SPEC-034) | `forja risk:explain` | advanced | — |
74
+ | `forja evidence:show` | View agregada de evidência de um run: intent, agente, testes, aprovações (SPEC-035) | `forja evidence:show` | advanced | workspace-warn |
75
+ | `forja engineer` | Façade: contexto + ADRs relevantes + architecture:check + risco + fluxo recomendado | `forja engineer "<objetivo>" [--ref <ref>] [--role <role>] [--json]` | core | workspace-warn |
76
+ | `forja agent:register` | Registra/atualiza um agente (role/provider/model/capabilities/domains) (SPEC-036) | `forja agent:register <id> --role <role> [--provider <p>] [--model <m>] [--capabilities <c1,c2>] [--domains <d1,d2>] [--max-files <n>] [--max-cost-usd <n>]` | advanced | workspace-warn |
77
+ | `forja agent:list` | Lista agentes registrados, com trustLevel se já pontuados (SPEC-036) | `forja agent:list` | advanced | workspace-warn |
78
+ | `forja agent:show` | Detalhe de um agente registrado (SPEC-036) | `forja agent:show` | advanced | workspace-warn |
79
+ | `forja agent:score` | Computa e persiste trustLevel/autonomyLevel a partir de Observation reais (SPEC-036) | `forja agent:score <id> [--domain <d>]` | advanced | workspace-warn |
80
+ | `forja agent:history` | Observations de um agente, mais recentes primeiro (SPEC-036) | `forja agent:history` | advanced | workspace-warn |
81
+ | `forja agent:recommend` | Ranking de agentes registrados por adequação a um papel/domínio — informação, não atribuição (SPEC-037) | `forja agent:recommend --role <role> [--domain <d>]` | advanced | workspace-warn |
82
+ | `forja agent:monitor` | Compara comportamento recente de um agente contra a linha de base histórica — informação, não bloqueio (SPEC-040) | `forja agent:monitor <id> [--window-hours <n>]` | advanced | workspace-warn |
83
+ | `forja incident:record` | Grava um incidente no Engineering Graph (SPEC-041) | `forja incident:record --title <t> [--description <d>]` | advanced | workspace-warn |
84
+ | `forja incident:list` | Incidentes registrados, mais recentes primeiro (SPEC-041) | `forja incident:list` | advanced | workspace-warn |
85
+ | `forja incident:similar` | Sugere incidentes parecidos por palavra-chave — sugestão, nunca aplicação automática (SPEC-041) | `forja incident:similar` | advanced | workspace-warn |
86
+ | `forja simulate` | Testa+arquitetura+risco de um ref num worktree isolado, nunca promove | `forja simulate <ref> [--command "npm test"] [--json]` | advanced | workspace-warn |
87
+ | `forja provenance:record` | Extrai proveniência (arquivo↔agente) de um RuntimeRun já persistido (SPEC-039) | `forja provenance:record` | advanced | workspace-warn |
88
+ | `forja blame` | Histórico de proveniência de um arquivo — granularidade de arquivo, não linha (SPEC-039) | `forja blame` | advanced | workspace-warn |
89
+ | `forja sbom` | AI-SBOM: relatório de proveniência agregado por agente (SPEC-039) | `forja sbom` | advanced | workspace-warn |
90
+ | `forja code:context` | Pacote de contexto mínimo de um domínio: o mapa (context.md), + código com --code (ADR-0009) | `forja code:context <domínio> [termo] [--code] [--full] [--project <path>]` | advanced | — |
91
+ | `forja code:index` | Inicializa índice codegraph | `forja code:index` | advanced | — |
92
+ | `forja code:sync` | Sincroniza índice codegraph | `forja code:sync` | advanced | — |
93
+ | `forja code:status` | Status do índice codegraph | `forja code:status` | advanced | — |
94
+ | `forja code:query` | Consulta o índice codegraph | `forja code:query` | advanced | — |
95
+
96
+ ## memoria
97
+
98
+ | Comando | O que faz | Uso | Tier | Gates |
99
+ |---|---|---|---|---|
100
+ | `forja sync:universal` | Reindexa a memória universal (SQLite FTS5) | `forja sync:universal` | core | workspace-warn |
101
+ | `forja query:universal` | Busca FTS5 na memória universal | `forja query:universal "<termo>"` | core | workspace-warn |
102
+ | `forja memory:compress` | Arquiva runs antigos e compacta memória de projeto | `forja memory:compress` | advanced | — |
103
+ | `forja memory:vacuum` | Comprime e limpa memória (archive + VACUUM) | `forja memory:vacuum` | advanced | — |
104
+ | `forja memory:schema` | Garante schema do SQLite de memória | `forja memory:schema` | advanced | — |
105
+ | `forja memory:extract` | Extrai conhecimento global da memória | `forja memory:extract` | advanced | — |
106
+ | `forja memory:audit` | Coerência mapa↔código: mapa não cita código morto (falha) + módulo sem mapa (aviso). SPEC-017 | `forja memory:audit` | advanced | — |
107
+
108
+ ## contexto
109
+
110
+ | Comando | O que faz | Uso | Tier | Gates |
111
+ |---|---|---|---|---|
112
+ | `forja context:smart` | Gera smart-context (3 modos: global \| domain \| task) | `forja context:smart [--mode global\|domain\|task] [--domain <d>] [--task <termo>] [--keyword <k>] [--project <nome>] [--full-context]` | core | workspace-warn |
113
+ | `forja context:budget` | Orçamento de tokens do contexto | `forja context:budget` | advanced | — |
114
+ | `forja context:sprint` | Pacote de contexto da sprint | `forja context:sprint` | advanced | — |
115
+ | `forja agent:brief` | Brief de contexto para um agente | `forja agent:brief` | advanced | — |
116
+ | `forja catalog:assets` | Catálogo de assets do repo | `forja catalog:assets` | advanced | — |
117
+ | `forja catalog:manifests` | Catálogo de manifests | `forja catalog:manifests` | advanced | — |
118
+ | `forja token:benchmark` | Benchmark de consumo de tokens | `forja token:benchmark` | advanced | — |
119
+ | `forja token:economy` | Economia de token: eixos arquitetura + memória; --project mede seus domínios reais | `forja token:economy [--project <path>] [--json]` | advanced | — |
120
+ | `forja benchmark:context` | Benchmark JSON determinístico de baseline, contexto mínimo, checksum e cache | `forja benchmark:context` | advanced | — |
121
+
122
+ ## llm
123
+
124
+ | Comando | O que faz | Uso | Tier | Gates |
125
+ |---|---|---|---|---|
126
+ | `forja llm:profiles:init` | Cria perfis de adapters LLM no workspace | `forja llm:profiles:init` | advanced | workspace |
127
+ | `forja llm:doctor` | Verifica adapters LLM configurados sem usar credenciais | `forja llm:doctor` | advanced | workspace |
128
+ | `forja llm:probe` | Executa probe seguro de disponibilidade dos adapters LLM | `forja llm:probe` | advanced | workspace |
129
+ | `forja llm:recommend` | Recomenda perfil LLM por papel, tarefa e evidência local | `forja llm:recommend [--role <papel>] [--task <tarefa>] [--json]` | advanced | workspace |
130
+ | `forja llm:run` | Executa um perfil LLM e registra observação normalizada. --engineer "<objetivo>" monta o contexto pelo façade | `forja llm:run [--profile <perfil>] [--task <caminho>] [--prompt <texto>] [--engineer "<objetivo>"] [--context <caminho>...] [--output-schema <arquivo>] [--validation <arquivo>] [--resume <id>] [--json]` | advanced | workspace |
131
+ | `forja llm:sessions` | Lista/mostra sessões LLM registradas (o SESSION_ID de llm:run --resume) — somente leitura (SPEC-048) | `forja llm:sessions <list\|show> [id] [--json]` | advanced | workspace |
132
+ | `forja llm:eval` | Avalia execuções LLM com métricas determinísticas | `forja llm:eval [--scope <escopo>] [--id <id>] [--json]` | advanced | workspace |
133
+ | `forja eval:agents` | Avalia agentes reais (Claude, Codex) numa suíte de tarefas do Forja, em projeto descartável — custa | `forja eval:agents --agent claude\|codex [--case a,b] [--model m] [--budget-usd n] [--timeout s] [--keep] [--list] [--json]` | advanced | — |
134
+ | `forja cost:economy` | Custo real acumulado (USD) das execuções LLM registradas, por modelo — tabela de preço local | `forja cost:economy [--json]` | advanced | workspace |
135
+
136
+ ## governanca
137
+
138
+ | Comando | O que faz | Uso | Tier | Gates |
139
+ |---|---|---|---|---|
140
+ | `forja project:check` | Standards check do framework (pre-commit) | `forja project:check` | core | — |
141
+ | `forja tools:doctor` | Raio-x do núcleo (gate, exit 1) + ferramentas de processo | `forja tools:doctor [--json]` | core | — |
142
+ | `forja hook:session-start` | Hook SessionStart: briefing de specs, handoffs e saúde do núcleo para a IA | `forja hook:session-start` | advanced | — |
143
+ | `forja hook:user-prompt` | Hook UserPromptSubmit: injeta o contexto da spec citada no prompt | `forja hook:user-prompt` | advanced | — |
144
+ | `forja hook:session-memory` | Hook Stop/PreCompact: grava o checkpoint da sessão em memory/60-runs/sessions/ | `forja hook:session-memory` | advanced | — |
145
+ | `forja demo:autonomy` | Executa a prova offline de autonomia supervisionada com Git worktree real | `forja demo:autonomy` | advanced | — |
146
+ | `forja demo:workspace` | Cria um workspace isolado e rotulado para demonstração do produto | `forja demo:workspace [--path <diretório>] [--json]` | advanced | — |
147
+ | `forja release:check` | Gate do tarball: instala limpo e prova que o pacote funciona (ADR-0024). --publish para o modo estrito | `forja release:check [--publish]` | advanced | — |
148
+ | `forja project:smoke` | Gate do projeto gerado: gera isolado e prova que é coerente. --full instala e builda o backend; --ai <lista> valida as instruções nativas | `forja project:smoke [--full] [--ai claude,copilot,gemini,codex] [--template <nome>]` | advanced | — |
149
+ | `forja check:all` | Roda a bateria inteira de gates e dá um veredito (SPEC-020). --full inclui tarball e build | `forja check:all [--full] [--with-architecture] [--with-drift]` | advanced | — |
150
+ | `forja project:dashboard` | Gera dashboard estático de status | `forja project:dashboard` | advanced | — |
151
+ | `forja audit:sync` | Projeta a trilha de auditoria (.jsonl) numa tabela consultável (SPEC-014) | `forja audit:sync` | advanced | — |
152
+ | `forja audit:query` | Consulta a auditoria: --failed, --cmd <x>, --since 7d | `forja audit:query [--failed] [--cmd <comando>] [--gate <gate>] [--since <janela>]` | advanced | — |
153
+ | `forja docs:gen` | Regenera docs/commands.md a partir do registry — a referência completa de comandos (SPEC-055) | `forja docs:gen` | advanced | — |
154
+ | `forja quality:coverage` | Roda a suíte com a cobertura nativa do Node e cobra o piso versionado (SPEC-056) — exit 2 abaixo do piso | `forja quality:coverage [--json]` | advanced | — |
155
+ | `forja governance:dashboard` | Gera um painel HTML estático de governança (gates, SDD, auditoria) — leitura, sem servidor | `forja governance:dashboard` | advanced | — |
package/docs/fluxo.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # Fluxo do 2-projeto-agents — mapa operacional
2
2
 
3
3
  **Princípio:** CLI-first. Todo o ciclo roda por linha de comando. O dashboard web
4
- (`npm run dashboard`, porta 7777) é **visão opcional read-only** — nunca é gate de
5
- spec, handoff, sprint ou entrega.
4
+ (`npm run dashboard:api` + `npm run dashboard:dev`, app na porta 3001) é **visão opcional
5
+ read-only** — nunca é gate de spec, handoff, sprint ou entrega.
6
6
 
7
7
  As 3 capacidades externas (ADR-0016) entram em pontos específicos do ciclo, sem mudar
8
8
  o pipeline SDD+GSD existente:
@@ -35,7 +35,7 @@ flowchart LR
35
35
  end
36
36
 
37
37
  ENTREGA(["✅ Entrega"])
38
- VISAO["👁 dashboard 7777 (opcional)"]
38
+ VISAO["👁 dashboard 3001 (opcional)"]
39
39
 
40
40
  IDEIA --> E1
41
41
  E6 --> ENTREGA
@@ -54,7 +54,7 @@ flowchart LR
54
54
  codegraph product sdd-arch tasks worker governance
55
55
  ai-eng (ref) spec:new spec:plan+ADR spec:tasks codegraph MCP spec:check
56
56
  harness (time) handoffs project:check
57
- ──────────────► 👁 dashboard 7777 (opcional, read-only)
57
+ ──────────────► 👁 dashboard 3001 (opcional, read-only)
58
58
  ```
59
59
 
60
60
  ---
@@ -95,9 +95,13 @@ então *opera* esses agentes pelos handoffs existentes — harness desenha, GSD
95
95
 
96
96
  ## Front (opcional)
97
97
 
98
- O dashboard sobe com `npm run dashboard` em `http://127.0.0.1:7777` e oferece uma visão
99
- read-only de specs, handoffs e agentes (`/api/health`, `/api/specs`, `/api/handoffs`,
100
- `/api/agents`). É conveniência de leitura — se não subir, **o fluxo segue 100% pela CLI**.
98
+ O dashboard sobe em dois terminais — `npm run dashboard:api` (API em `127.0.0.1:3000`) e
99
+ `npm run dashboard:dev` (app em `http://localhost:3001`) — e oferece cinco abas read-only:
100
+ Visão, Rastreio, Custo, Gates e Operação. A leitura passa por `POST /api/capabilities/:id/execute`
101
+ (só capacidades que o servidor declara sem escrita nem efeito colateral), `GET /api/graph/query`,
102
+ `GET /api/control-plane/metrics`, `GET /api/observability/observations` e `GET /api/approvals`.
103
+ É conveniência de leitura — se não subir, **o fluxo segue 100% pela CLI**. Tokens e roteiro:
104
+ `docs/produto/roteiro-demo.md`.
101
105
 
102
106
  Ver também: `docs/cli-first-operacao.md` (comandos), `docs/capacidades-externas.md`
103
107
  (detalhe das 3 capacidades), `AGENTS.md` (papéis), ADR-0016.
@@ -39,7 +39,9 @@ O workspace é resolvido por: `FORJA_WORKSPACE` → `workspaceRoot` em `~/.forja
39
39
  - `AGENTS.md` com o bloco do Forja (lido por Codex, Copilot agent e Gemini).
40
40
  - `CLAUDE.md` e `GEMINI.md` importando o `AGENTS.md`; `.github/copilot-instructions.md`.
41
41
  - `.claude/settings.json`: hooks `forja hook:session-start` (briefing da sessão) e
42
- `forja hook:user-prompt` (anexa a spec citada), mais a permissão `Bash(forja *)`.
42
+ `forja hook:user-prompt` (anexa a spec citada), `forja hook:session-memory` nos eventos `Stop` e
43
+ `PreCompact` (checkpoint da sessão em `memory/60-runs/sessions/`, ADR-0091), mais a permissão
44
+ `Bash(forja *)`.
43
45
  - `.claude/agents/`: orchestrator, product, sdd-architect, context-engineer, governance, marketing.
44
46
  - `.mcp.json`: servidor `forja mcp:start` (e `codegraph`, se instalado); o mesmo servidor em
45
47
  `.codex/config.toml` (Codex), `.gemini/settings.json` (Gemini) e `.vscode/mcp.json` (Copilot).
@@ -168,6 +168,26 @@ workspace. `forja llm:doctor` confere se a CLI instalada oferece as flags de som
168
168
  elas, o perfil fica incompatível em vez de rodar com permissões que o Forja não pediu. Retomada
169
169
  (`--resume`) continua só em Codex e Claude.
170
170
 
171
+ ## Avaliar agentes reais no método do Forja (SPEC-054, ADR-0093)
172
+
173
+ `llm:eval` agrega execuções do `llm:run`. Para saber se um agente **segue o Forja** num projeto
174
+ conectado, use a suíte de tarefas:
175
+
176
+ ```bash
177
+ forja eval:agents --list # os casos (templates/evals/agents/*.json)
178
+ forja eval:agents --agent claude # todos os casos; teto de US$ 1,00 por caso
179
+ forja eval:agents --agent codex --case adr,memoria
180
+ forja eval:agents --agent claude --model sonnet --budget-usd 0.5 --json
181
+ ```
182
+
183
+ Cada caso cria um workspace e um projeto descartáveis, aplica a semente, roda o agente e corrige de
184
+ forma determinística (arquivo criado e conteúdo, comando executado, resposta, critério coberto pelo
185
+ `spec:trace`, comando que passa, arquivos inalterados). É a única exceção ao modo somente leitura:
186
+ o agente escreve, mas só ali (Codex com `-s workspace-write`; Claude com `acceptEdits`, lista fechada
187
+ de comandos e `--max-budget-usd`). O resultado vai para `<workspace>/.context/agent-evals.jsonl` e é
188
+ comparado com a execução anterior do mesmo agente e modelo. **Custa**: cada caso é uma sessão real.
189
+ Exit 0 = tudo passou, 2 = algum caso falhou.
190
+
171
191
  ## Métricas e recomendação por custo/latência (SPEC-049)
172
192
 
173
193
  `llm:eval` acrescenta às métricas do relatório: