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.
- package/CHANGELOG.md +76 -0
- package/README.md +37 -4
- package/README.pt-BR.md +39 -4
- package/dist/apps/cli/src/index.d.ts +0 -1
- package/dist/apps/cli/src/index.js +43 -32
- package/dist/apps/dashboard/app/api/forja/[...path]/route.js +34 -1
- package/dist/apps/dashboard/app/api/forja/capabilities.d.ts +26 -0
- package/dist/apps/dashboard/app/api/forja/capabilities.js +39 -0
- package/dist/apps/dashboard/app/dashboard-client.jsx +607 -42
- package/dist/apps/server/src/forja-nest.module.d.ts +6 -0
- package/dist/apps/server/src/forja-nest.module.js +55 -0
- package/dist/apps/server/src/main.d.ts +21 -4
- package/dist/apps/server/src/main.js +79 -57
- package/dist/apps/server/src/task-planning-service.d.ts +29 -0
- package/dist/apps/server/src/task-planning-service.js +195 -0
- package/dist/apps/server/src/task-runtime-coordinator.d.ts +57 -0
- package/dist/apps/server/src/task-runtime-coordinator.js +229 -0
- package/dist/bin/forja.js +3 -2
- package/dist/lib/agent-evals.d.ts +138 -0
- package/dist/lib/agent-evals.js +349 -0
- package/dist/lib/cli-output.js +14 -2
- package/dist/lib/code-context.d.ts +33 -5
- package/dist/lib/code-context.js +70 -5
- package/dist/lib/context-builder.d.ts +49 -4
- package/dist/lib/context-builder.js +114 -47
- package/dist/lib/core/coverage-gate.d.ts +59 -0
- package/dist/lib/core/coverage-gate.js +58 -0
- package/dist/lib/core/doc-graph.d.ts +38 -0
- package/dist/lib/core/doc-graph.js +83 -0
- package/dist/lib/core/health.js +286 -5
- package/dist/lib/core/journey.js +26 -0
- package/dist/lib/core/registry.js +81 -6
- package/dist/lib/docs-reference.d.ts +35 -0
- package/dist/lib/docs-reference.js +57 -0
- package/dist/lib/project-wiring.js +6 -2
- package/dist/lib/session-memory.d.ts +38 -0
- package/dist/lib/session-memory.js +206 -0
- package/dist/lib/spec-trace.d.ts +46 -0
- package/dist/lib/spec-trace.js +184 -0
- package/dist/packages/adapter-nest/src/index.d.ts +2 -1
- package/dist/packages/adapter-nest/src/index.js +59 -1
- package/dist/packages/adapter-sqlite/src/index.d.ts +15 -1
- package/dist/packages/adapter-sqlite/src/index.js +61 -1
- package/dist/packages/context/src/index.d.ts +2 -0
- package/dist/packages/context/src/index.js +36 -15
- package/dist/packages/contracts/src/index.d.ts +64 -0
- package/dist/packages/core/src/index.d.ts +9 -1
- package/dist/packages/core/src/index.js +28 -3
- package/dist/packages/graph/src/index.js +14 -5
- package/dist/packages/mcp/src/index.d.ts +8 -0
- package/dist/packages/mcp/src/index.js +12 -1
- package/dist/packages/observability/src/index.d.ts +11 -0
- package/dist/packages/observability/src/index.js +3 -0
- package/dist/packages/orchestration/src/index.d.ts +15 -1
- package/dist/packages/orchestration/src/index.js +127 -21
- package/dist/packages/planner/src/index.d.ts +7 -1
- package/dist/packages/planner/src/index.js +67 -10
- package/dist/packages/planner/src/proposal-store.d.ts +30 -0
- package/dist/packages/planner/src/proposal-store.js +109 -0
- package/dist/packages/policy/src/index.d.ts +9 -16
- package/dist/packages/policy/src/index.js +114 -31
- package/dist/packages/runtime/src/index.d.ts +16 -2
- package/dist/packages/runtime/src/index.js +176 -61
- package/dist/scripts/build-smart-context.d.ts +2 -0
- package/dist/scripts/build-smart-context.js +12 -3
- package/dist/scripts/code-context.d.ts +3 -1
- package/dist/scripts/code-context.js +13 -3
- package/dist/scripts/coverage-gate.d.ts +2 -0
- package/dist/scripts/coverage-gate.js +101 -0
- package/dist/scripts/eval-agents.d.ts +11 -0
- package/dist/scripts/eval-agents.js +96 -0
- package/dist/scripts/gen-commands-doc.d.ts +2 -0
- package/dist/scripts/gen-commands-doc.js +18 -0
- package/dist/scripts/hook-session-memory.d.ts +9 -0
- package/dist/scripts/hook-session-memory.js +20 -0
- package/dist/scripts/hook-session-start.js +34 -0
- package/dist/scripts/spec-trace.d.ts +10 -0
- package/dist/scripts/spec-trace.js +73 -0
- package/dist/scripts/sync-universal-memory.js +69 -4
- package/dist/scripts/token-benchmark.d.ts +33 -1
- package/dist/scripts/token-benchmark.js +179 -5
- package/dist/scripts/token-economy.js +3 -1
- package/dist/scripts/tools-doctor.d.ts +16 -1
- package/dist/scripts/tools-doctor.js +58 -17
- package/docs/commands.md +155 -0
- package/docs/fluxo.md +11 -7
- package/docs/init-project.md +3 -1
- package/docs/llm-fit-loop.md +20 -0
- package/docs/manual-operacional-cli-sdd-gsd.md +3 -2
- package/docs/produto/factsheet-marketing.md +7 -5
- package/docs/produto/roteiro-demo.md +14 -5
- package/docs/quick-reference.md +3 -3
- package/docs/token-optimization.md +10 -6
- package/memory/90-decisions/0091-memoria-de-sessao-por-hooks.md +40 -0
- package/memory/90-decisions/0092-criterios-de-aceite-ligados-a-testes.md +37 -0
- package/memory/90-decisions/0093-avaliacoes-com-agentes-reais.md +40 -0
- package/package.json +4 -2
- package/specs/avaliacoes-de-agentes/spec.md +52 -0
- package/specs/criterios-ligados-a-testes/spec.md +42 -0
- package/specs/memoria-de-sessao/spec.md +48 -0
- package/specs/v6-agent-runtime-portable/spec.md +83 -0
- package/specs/v6-core-consolidation/spec.md +70 -0
- package/specs/v6-docs-drift/spec.md +85 -0
- package/specs/v6-quality-gates/spec.md +99 -0
- package/specs/v6-token-economy/spec.md +84 -0
- package/templates/evals/agents/adr.json +25 -0
- package/templates/evals/agents/memoria.json +32 -0
- package/templates/evals/agents/proxima-acao.json +29 -0
- package/templates/evals/agents/spec-nova.json +26 -0
- package/templates/evals/agents/teste-do-criterio.json +29 -0
- package/templates/project/AGENTS.md +7 -0
- package/templates/project/CLAUDE.md +3 -2
- 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' ?
|
|
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)
|
|
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
|
-
|
|
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
|
|
98
|
-
|
|
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}/${
|
|
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
|
|
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
|
-
|
|
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
|
|
134
|
+
return project.status;
|
|
123
135
|
}
|
|
124
136
|
async function main() {
|
|
125
|
-
|
|
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
|
|
129
|
-
printTools();
|
|
130
|
-
if (
|
|
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();
|
package/docs/commands.md
ADDED
|
@@ -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
|
|
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
|
|
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
|
|
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
|
|
99
|
-
|
|
100
|
-
|
|
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.
|
package/docs/init-project.md
CHANGED
|
@@ -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),
|
|
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).
|
package/docs/llm-fit-loop.md
CHANGED
|
@@ -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:
|