forjajs 4.0.1 → 4.1.1
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 +170 -7
- package/DOC-MAP.md +1 -0
- package/README.md +10 -2
- package/README.pt-BR.md +3 -0
- package/dist/apps/cli/src/index.d.ts +18 -1
- package/dist/apps/cli/src/index.js +161 -26
- package/dist/apps/cli/src/params.d.ts +44 -0
- package/dist/apps/cli/src/params.js +123 -0
- package/dist/bin/forja.js +234 -13
- package/dist/bin/init-project.js +11 -62
- package/dist/lib/cli-output.d.ts +29 -0
- package/dist/lib/cli-output.js +39 -0
- package/dist/lib/core/checks.d.ts +1 -1
- package/dist/lib/core/health.d.ts +9 -0
- package/dist/lib/core/health.js +9 -0
- package/dist/lib/core/project-smoke.d.ts +6 -2
- package/dist/lib/core/project-smoke.js +83 -7
- package/dist/lib/core/registry.d.ts +38 -571
- package/dist/lib/core/registry.js +174 -25
- package/dist/lib/core/release.d.ts +1 -571
- package/dist/lib/core/release.js +0 -3
- package/dist/lib/handoffs-index.d.ts +16 -0
- package/dist/lib/handoffs-index.js +29 -0
- package/dist/lib/llm/claude-output.d.ts +8 -0
- package/dist/lib/llm/claude-output.js +54 -0
- package/dist/lib/llm/context.d.ts +22 -0
- package/dist/lib/llm/context.js +39 -0
- package/dist/lib/llm/session.d.ts +6 -1
- package/dist/lib/llm/session.js +12 -2
- package/dist/lib/multi-ai-instructions.d.ts +28 -0
- package/dist/lib/multi-ai-instructions.js +83 -0
- package/dist/lib/orchestrate.d.ts +5 -0
- package/dist/lib/orchestrate.js +18 -0
- package/dist/lib/specs-index.d.ts +20 -0
- package/dist/lib/specs-index.js +51 -0
- package/dist/lib/sprint-index.d.ts +15 -0
- package/dist/lib/sprint-index.js +34 -0
- package/dist/lib/status-model.d.ts +64 -0
- package/dist/lib/status-model.js +180 -0
- package/dist/packages/evals/src/index.d.ts +2 -0
- package/dist/packages/evals/src/index.js +21 -0
- package/dist/packages/llm/src/index.d.ts +24 -3
- package/dist/packages/llm/src/index.js +51 -5
- package/dist/scripts/cost-economy.js +12 -10
- package/dist/scripts/drift-check.d.ts +2 -0
- package/dist/scripts/drift-check.js +57 -1
- package/dist/scripts/engineer.js +7 -4
- package/dist/scripts/forja-setup.d.ts +14 -0
- package/dist/scripts/forja-setup.js +58 -0
- package/dist/scripts/forja-status.d.ts +11 -0
- package/dist/scripts/forja-status.js +70 -0
- package/dist/scripts/hook-session-start.js +20 -46
- package/dist/scripts/llm-fit.js +113 -8
- package/dist/scripts/project-smoke.js +13 -3
- package/dist/scripts/simulate.js +18 -6
- package/dist/scripts/token-economy.js +34 -28
- package/dist/scripts/tools-doctor.js +14 -6
- package/docs/2x/CLI-CAPABILITIES.md +34 -10
- package/docs/agent-operating-contract.md +3 -1
- package/docs/cli-first-operacao.md +17 -0
- package/docs/contrato-saida-cli.md +79 -0
- package/docs/llm-evolution.md +2 -1
- package/docs/llm-fit-loop.md +74 -2
- package/docs/publishing.md +13 -16
- package/docs/quick-reference.md +13 -0
- package/docs/roadmap-v4.1.md +199 -0
- package/memory/90-decisions/0082-contrato-saida-cli.md +95 -0
- package/memory/90-decisions/0083-mcp-cobertura-declarativa.md +103 -0
- package/memory/90-decisions/0084-drift-sentinel-fecha.md +79 -0
- package/memory/90-decisions/0085-adaptador-claude-paridade.md +85 -0
- package/package.json +4 -1
- package/specs/cli-intuitiva-v1/plan.md +169 -0
- package/specs/cli-intuitiva-v1/spec.md +163 -0
- package/specs/cli-intuitiva-v1/tasks.md +224 -0
- package/specs/contrato-saida-cli/plan.md +162 -0
- package/specs/contrato-saida-cli/spec.md +157 -0
- package/specs/contrato-saida-cli/tasks.md +153 -0
- package/specs/drift-sentinel/spec.md +17 -8
- package/specs/forja-status-caminho-feliz/plan.md +149 -0
- package/specs/forja-status-caminho-feliz/spec.md +158 -0
- package/specs/forja-status-caminho-feliz/tasks.md +175 -0
- package/specs/llm-adaptador-claude/plan.md +117 -0
- package/specs/llm-adaptador-claude/spec.md +144 -0
- package/specs/llm-adaptador-claude/tasks.md +100 -0
- package/specs/llm-benchmark-recomendacao/plan.md +121 -0
- package/specs/llm-benchmark-recomendacao/spec.md +141 -0
- package/specs/llm-benchmark-recomendacao/tasks.md +88 -0
- package/specs/llm-contexto-e-sessoes/plan.md +143 -0
- package/specs/llm-contexto-e-sessoes/spec.md +139 -0
- package/specs/llm-contexto-e-sessoes/tasks.md +127 -0
- package/specs/mcp-cobertura-nucleo/plan.md +158 -0
- package/specs/mcp-cobertura-nucleo/spec.md +161 -0
- package/specs/mcp-cobertura-nucleo/tasks.md +169 -0
- package/specs/projeto-gerado-confiavel/plan.md +148 -0
- package/specs/projeto-gerado-confiavel/spec.md +142 -0
- package/specs/projeto-gerado-confiavel/tasks.md +139 -0
package/dist/scripts/llm-fit.js
CHANGED
|
@@ -10,9 +10,10 @@ import { ObservabilityRecorder } from "../packages/observability/src/index.js";
|
|
|
10
10
|
import { SqliteMigrationRunner, SqliteObservationStore, SqliteJsonRepository } from "../packages/adapter-sqlite/src/index.js";
|
|
11
11
|
import { getWorkspaceContextDir, getWorkspaceDbDir, getWorkspaceDbPath } from "../lib/workspace.js";
|
|
12
12
|
import { computeCostUsd, isPriceStale, loadPricingTable, lookupPrice, STALE_PRICE_MAX_AGE_DAYS } from "../lib/core/model-pricing.js";
|
|
13
|
-
import { buildContextPrompt } from "../lib/llm/context.js";
|
|
13
|
+
import { buildContextPrompt, buildEngineerBlock } from "../lib/llm/context.js";
|
|
14
14
|
import { normalizeCodexResult } from "../lib/llm/codex-output.js";
|
|
15
|
-
import {
|
|
15
|
+
import { normalizeClaudeResult } from "../lib/llm/claude-output.js";
|
|
16
|
+
import { LlmSessionStore, RESUME_PROVIDERS, validSessionId } from "../lib/llm/session.js";
|
|
16
17
|
import { prepareValidation, validateLlmResponse } from "../lib/llm/validation.js";
|
|
17
18
|
const profilePath = () => path.join(getWorkspaceContextDir(), 'llm-profiles.json');
|
|
18
19
|
function usage() {
|
|
@@ -82,6 +83,13 @@ function doctor(name) {
|
|
|
82
83
|
features = { outputSchema: !help.error && help.status === 0 && help.stdout.includes('--output-schema'),
|
|
83
84
|
resume: !resumeHelp.error && resumeHelp.status === 0 && ['--json', '--config'].every((flag) => resumeHelp.stdout.includes(flag)) };
|
|
84
85
|
}
|
|
86
|
+
else if (available && value.provider === 'claude') {
|
|
87
|
+
// SPEC-050 — o `claude` CLI oferece --resume nativo; schema não (validação é local, Ajv).
|
|
88
|
+
const help = spawnSync(value.command, ['--help'], { encoding: 'utf8', timeout: 10_000, shell: false });
|
|
89
|
+
const helpOk = !help.error && help.status === 0;
|
|
90
|
+
compatible = helpOk && ['--output-format', '--print'].every((flag) => help.stdout.includes(flag));
|
|
91
|
+
features = { resume: helpOk && help.stdout.includes('--resume'), outputSchema: false };
|
|
92
|
+
}
|
|
85
93
|
return { name: profileName, provider: value.provider, model: value.model, enabled: value.enabled, executable: value.command, available, compatible,
|
|
86
94
|
features, modelAccess: 'not-probed', detail: errorCode ?? (probe.status === 0 ? String(probe.stdout).trim().split('\n')[0] : String(probe.stderr).trim().split('\n')[0]), pricing };
|
|
87
95
|
});
|
|
@@ -98,7 +106,7 @@ function doctor(name) {
|
|
|
98
106
|
async function run() {
|
|
99
107
|
const input = flags(process.argv.slice(3));
|
|
100
108
|
for (const [key, values] of input) {
|
|
101
|
-
if (!['--profile', '--prompt', '--task', '--context', '--resume', '--output-schema', '--validation'].includes(key))
|
|
109
|
+
if (!['--profile', '--prompt', '--task', '--context', '--resume', '--output-schema', '--validation', '--engineer'].includes(key))
|
|
102
110
|
throw new Error(`Opção não suportada: ${key}`);
|
|
103
111
|
if (key !== '--context' && values.length !== 1)
|
|
104
112
|
throw new Error(`Opção repetida: ${key}`);
|
|
@@ -106,11 +114,31 @@ async function run() {
|
|
|
106
114
|
if (input.has('--prompt') && input.has('--task'))
|
|
107
115
|
throw new Error('Use --prompt ou --task, não ambos.');
|
|
108
116
|
const name = option(input, '--profile');
|
|
109
|
-
const
|
|
117
|
+
const objective = option(input, '--engineer');
|
|
118
|
+
// Sem --prompt/--task, o próprio objetivo do --engineer vira o prompt.
|
|
119
|
+
const prompt = option(input, '--prompt')
|
|
120
|
+
?? (option(input, '--task') ? fs.readFileSync(path.resolve(option(input, '--task')), 'utf8') : undefined)
|
|
121
|
+
?? objective;
|
|
110
122
|
if (!name || !prompt)
|
|
111
123
|
usage();
|
|
112
124
|
const selected = profile(name);
|
|
113
|
-
|
|
125
|
+
// SPEC-048: --engineer monta o contexto pelo façade e o embute no prompt. Falha do façade =
|
|
126
|
+
// falha ANTES do provedor — nunca mandar um prompt sem o contexto pedido.
|
|
127
|
+
const engineerRefs = [];
|
|
128
|
+
let promptWithEngineer = prompt;
|
|
129
|
+
if (objective !== undefined) {
|
|
130
|
+
try {
|
|
131
|
+
const block = buildEngineerBlock(objective);
|
|
132
|
+
promptWithEngineer = `${block.text}\n\n${prompt}`;
|
|
133
|
+
engineerRefs.push(block.ref);
|
|
134
|
+
}
|
|
135
|
+
catch (error) {
|
|
136
|
+
const detail = error instanceof Error && 'detail' in error ? error.detail : String(error);
|
|
137
|
+
console.log(JSON.stringify({ profile: name, exitCode: 1, errorCode: 'ENGINEER_FAILED', stderr: detail }, null, 2));
|
|
138
|
+
process.exit(1);
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
const context = buildContextPrompt(promptWithEngineer, input.get('--context') ?? []);
|
|
114
142
|
const prepared = prepareValidation(option(input, '--output-schema'), option(input, '--validation'));
|
|
115
143
|
const resume = option(input, '--resume');
|
|
116
144
|
const fullPrompt = prepared.schemaText === undefined ? context.prompt : `${context.prompt}\n\nResponda somente JSON conforme este JSON Schema:\n${prepared.schemaText}`;
|
|
@@ -122,14 +150,18 @@ async function run() {
|
|
|
122
150
|
if (resume !== undefined)
|
|
123
151
|
sessions.require(resume, selected, process.cwd());
|
|
124
152
|
const raw = await runLlm(execution, process.cwd(), selected.timeoutMs);
|
|
125
|
-
let result = selected.provider === 'codex'
|
|
153
|
+
let result = selected.provider === 'codex'
|
|
154
|
+
? normalizeCodexResult(raw)
|
|
155
|
+
: selected.provider === 'claude'
|
|
156
|
+
? normalizeClaudeResult(raw)
|
|
157
|
+
: raw;
|
|
126
158
|
if (result.sessionId !== undefined && (!validSessionId(result.sessionId) || (resume !== undefined && result.sessionId !== resume))) {
|
|
127
159
|
result = { ...result, exitCode: result.exitCode || 1, errorCode: 'SESSION_MISMATCH', sessionId: undefined };
|
|
128
160
|
}
|
|
129
161
|
const sessionId = result.errorCode === 'SESSION_MISMATCH' ? undefined : result.sessionId ?? resume;
|
|
130
162
|
const validation = await validateLlmResponse(prepared, result.stdout, process.cwd(), result.exitCode === 0);
|
|
131
163
|
const recorder = new ObservabilityRecorder(store);
|
|
132
|
-
const refs = [...context.refs, ...[prepared.schemaPath, prepared.manifestPath].filter((value) => value !== undefined)];
|
|
164
|
+
const refs = [...engineerRefs, ...context.refs, ...[prepared.schemaPath, prepared.manifestPath].filter((value) => value !== undefined)];
|
|
133
165
|
const model = `${selected.provider}:${selected.model}`;
|
|
134
166
|
const inputTokens = result.usage?.inputTokens ?? Math.ceil(Buffer.byteLength(fullPrompt) / 4);
|
|
135
167
|
const outputTokens = result.usage?.outputTokens ?? Math.ceil(Buffer.byteLength(result.stdout) / 4);
|
|
@@ -140,7 +172,7 @@ async function run() {
|
|
|
140
172
|
console.warn(`Aviso: preço desconhecido para ${model} — custo desta execução não computado. Rode \`forja llm:doctor\` ou adicione uma entrada em lib/core/model-pricing.json.`);
|
|
141
173
|
const observation = await recorder.record({ traceId: `llm:${name}:${randomUUID()}`, model, inputHash: createHash('sha256').update(fullPrompt).digest('hex'), contextRefs: refs, inputTokens, outputTokens, durationMs: result.durationMs, cost: costUsd, tools: [selected.command], commands: [selected.command], outcome: result.exitCode === 0 ? 'succeeded' : 'failed', validationStatus: validation.status, errorCode: result.errorCode ?? validation.errorCode });
|
|
142
174
|
repository.put('llm_validation', observation.id, { ...validation, observationId: observation.id, cwd: fs.realpathSync(process.cwd()) }, observation.updatedAt);
|
|
143
|
-
if (selected.provider
|
|
175
|
+
if (RESUME_PROVIDERS.has(selected.provider) && sessionId !== undefined)
|
|
144
176
|
sessions.save(sessionId, selected, process.cwd(), observation.id);
|
|
145
177
|
const exitCode = result.exitCode || (validation.status === 'rejected' ? 2 : 0);
|
|
146
178
|
console.log(JSON.stringify({ profile: name, model: observation.model, exitCode, executionExitCode: result.exitCode, durationMs: result.durationMs,
|
|
@@ -184,6 +216,77 @@ async function evaluate() {
|
|
|
184
216
|
db.close();
|
|
185
217
|
}
|
|
186
218
|
}
|
|
219
|
+
/**
|
|
220
|
+
* SPEC-048 — `llm:sessions list|show`. Somente leitura sobre `llm_session`: torna descobrível o
|
|
221
|
+
* `SESSION_ID` que `llm:run --resume` exige. Não usa `flags()` (subcomandos são posicionais).
|
|
222
|
+
*/
|
|
223
|
+
function cmdSessions() {
|
|
224
|
+
const args = process.argv.slice(3);
|
|
225
|
+
const json = args.includes('--json');
|
|
226
|
+
const positionals = args.filter((a) => !a.startsWith('--'));
|
|
227
|
+
const sub = positionals[0] ?? 'list';
|
|
228
|
+
if (sub !== 'list' && sub !== 'show') {
|
|
229
|
+
console.error('Uso: forja llm:sessions <list|show> [id] [--json]');
|
|
230
|
+
process.exit(1);
|
|
231
|
+
}
|
|
232
|
+
const { db, store } = storage();
|
|
233
|
+
try {
|
|
234
|
+
const repository = new SqliteJsonRepository(db);
|
|
235
|
+
const sessions = new LlmSessionStore(repository);
|
|
236
|
+
if (sub === 'list') {
|
|
237
|
+
const all = sessions.all();
|
|
238
|
+
if (json) {
|
|
239
|
+
console.log(JSON.stringify(all, null, 2));
|
|
240
|
+
return;
|
|
241
|
+
}
|
|
242
|
+
if (all.length === 0) {
|
|
243
|
+
console.log('Nenhuma sessão registrada neste workspace.');
|
|
244
|
+
return;
|
|
245
|
+
}
|
|
246
|
+
console.log(`\n${all.length} sessão(ões) — mais recente primeiro. Use o id em \`llm:run --resume <id>\`.\n`);
|
|
247
|
+
for (const s of all)
|
|
248
|
+
console.log(` ${s.id.padEnd(40)} ${path.basename(s.cwd).padEnd(24)} ${s.updatedAt} obs:${s.observationId}`);
|
|
249
|
+
return;
|
|
250
|
+
}
|
|
251
|
+
// show <id>
|
|
252
|
+
const id = positionals[1];
|
|
253
|
+
if (!id) {
|
|
254
|
+
console.error('Uso: forja llm:sessions show <id> [--json]');
|
|
255
|
+
process.exit(1);
|
|
256
|
+
}
|
|
257
|
+
const session = sessions.find(id);
|
|
258
|
+
if (!session) {
|
|
259
|
+
console.error(`Sessão não encontrada: ${id}`);
|
|
260
|
+
process.exit(1);
|
|
261
|
+
}
|
|
262
|
+
const observation = store.list().find((o) => o.id === session.observationId);
|
|
263
|
+
const validation = repository.get('llm_validation', session.observationId);
|
|
264
|
+
const payload = {
|
|
265
|
+
session,
|
|
266
|
+
observation: observation
|
|
267
|
+
? { model: observation.model ?? null, outcome: observation.outcome ?? null, validationStatus: observation.validationStatus ?? null, durationMs: observation.durationMs ?? null }
|
|
268
|
+
: null,
|
|
269
|
+
validation: validation ? { status: validation.status ?? null, checks: (validation.checks ?? []).map((c) => c.name) } : null,
|
|
270
|
+
};
|
|
271
|
+
if (json) {
|
|
272
|
+
console.log(JSON.stringify(payload, null, 2));
|
|
273
|
+
return;
|
|
274
|
+
}
|
|
275
|
+
console.log(`\nSessão ${session.id}`);
|
|
276
|
+
console.log(` projeto: ${session.cwd}`);
|
|
277
|
+
console.log(` atualizada: ${session.updatedAt}`);
|
|
278
|
+
console.log(` observação: ${session.observationId}`);
|
|
279
|
+
if (payload.observation)
|
|
280
|
+
console.log(` → ${payload.observation.model} · ${payload.observation.outcome} · validação ${payload.observation.validationStatus} · ${payload.observation.durationMs}ms`);
|
|
281
|
+
if (payload.validation)
|
|
282
|
+
console.log(` → validação: ${payload.validation.status}${payload.validation.checks.length ? ` (checks: ${payload.validation.checks.join(', ')})` : ''}`);
|
|
283
|
+
if (!payload.observation && !payload.validation)
|
|
284
|
+
console.log(' (sem observação/validação vinculada — sessão pode ser de outra versão)');
|
|
285
|
+
}
|
|
286
|
+
finally {
|
|
287
|
+
db.close();
|
|
288
|
+
}
|
|
289
|
+
}
|
|
187
290
|
async function main() {
|
|
188
291
|
const command = process.argv[2];
|
|
189
292
|
if (command === 'profiles:init') {
|
|
@@ -201,6 +304,8 @@ async function main() {
|
|
|
201
304
|
await run();
|
|
202
305
|
else if (command === 'eval')
|
|
203
306
|
await evaluate();
|
|
307
|
+
else if (command === 'sessions')
|
|
308
|
+
cmdSessions();
|
|
204
309
|
else
|
|
205
310
|
usage();
|
|
206
311
|
}
|
|
@@ -13,11 +13,21 @@
|
|
|
13
13
|
*/
|
|
14
14
|
import { runProjectSmoke, worstStatus } from "../lib/core/project-smoke.js";
|
|
15
15
|
const TAG = { ok: 'OK ', warn: 'AVISO', fail: 'FALHA', skipped: '— ' };
|
|
16
|
+
function parseAi(argv) {
|
|
17
|
+
const i = argv.indexOf('--ai');
|
|
18
|
+
if (i < 0 || argv[i + 1] === undefined)
|
|
19
|
+
return undefined;
|
|
20
|
+
const list = argv[i + 1].split(',').map((s) => s.trim()).filter(Boolean);
|
|
21
|
+
return list.length ? list : undefined;
|
|
22
|
+
}
|
|
16
23
|
async function main() {
|
|
17
24
|
const full = process.argv.includes('--full');
|
|
18
|
-
|
|
19
|
-
console.log(
|
|
20
|
-
|
|
25
|
+
const ai = parseAi(process.argv.slice(2));
|
|
26
|
+
console.log(`\nForja project smoke${full ? ' (tier --full)' : ''}${ai ? ` (--ai ${ai.join(',')})` : ''}\n`);
|
|
27
|
+
console.log(ai
|
|
28
|
+
? `Gerando um projeto só-memória + instruções nativas (${ai.join(', ')}) num diretório isolado.\n`
|
|
29
|
+
: `Gerando um projeto num diretório isolado${full ? ' e buildando o backend — isto leva minutos' : ''}.\n`);
|
|
30
|
+
const results = await runProjectSmoke({ full, ai });
|
|
21
31
|
for (const r of results) {
|
|
22
32
|
console.log(`${TAG[r.status]} ${r.id.padEnd(16)} ${r.detail}`);
|
|
23
33
|
if (r.fix)
|
package/dist/scripts/simulate.js
CHANGED
|
@@ -30,6 +30,7 @@ import { GitGraphDocumentSource } from "../packages/adapter-git/src/index.js";
|
|
|
30
30
|
import { GraphIndexer, GraphLoop } from "../packages/graph/src/index.js";
|
|
31
31
|
import { SqliteGraphStore, SqliteMigrationRunner } from "../packages/adapter-sqlite/src/index.js";
|
|
32
32
|
import { buildRiskInput, changedFiles } from "../lib/core/risk-collect.js";
|
|
33
|
+
import { emitOk, emitError, emitRejected } from "../lib/cli-output.js";
|
|
33
34
|
const CONSTITUTION_PATH = '.context/architecture/constitution.json';
|
|
34
35
|
function repoRoot() {
|
|
35
36
|
return process.env.FORJA_GRAPH_ROOT ?? process.cwd();
|
|
@@ -87,7 +88,10 @@ async function cmdSimulate(args) {
|
|
|
87
88
|
const testCommand = commandIndex === -1 ? 'npm test' : args[commandIndex + 1];
|
|
88
89
|
const ref = args.filter((arg, index) => arg !== '--json' && (commandIndex === -1 || (index !== commandIndex && index !== commandIndex + 1)))[0];
|
|
89
90
|
if (!ref) {
|
|
90
|
-
|
|
91
|
+
const usage = 'Uso: forja simulate <ref> [--command "npm test"] [--json]';
|
|
92
|
+
if (json)
|
|
93
|
+
emitError(usage); // termina o processo
|
|
94
|
+
console.error(usage);
|
|
91
95
|
process.exitCode = 1;
|
|
92
96
|
return;
|
|
93
97
|
}
|
|
@@ -99,6 +103,7 @@ async function cmdSimulate(args) {
|
|
|
99
103
|
const worktreeRoot = path.join(tempBase, 'worktree');
|
|
100
104
|
const runId = randomUUID();
|
|
101
105
|
const session = await sandbox.create({ runId, root: worktreeRoot });
|
|
106
|
+
let report;
|
|
102
107
|
try {
|
|
103
108
|
await sandbox.prepare(session.id);
|
|
104
109
|
const [executable, ...cmdArgs] = testCommand.split(' ');
|
|
@@ -106,11 +111,7 @@ async function cmdSimulate(args) {
|
|
|
106
111
|
const testResult = { exitCode: execution.exitCode, durationMs: execution.durationMs, passed: execution.exitCode === 0 };
|
|
107
112
|
const { architectureCheck, risk } = await assessWorktree(worktreeRoot, paths);
|
|
108
113
|
const recommendation = recommendationFor(testResult.passed, architectureCheck, risk);
|
|
109
|
-
|
|
110
|
-
if (json)
|
|
111
|
-
console.log(JSON.stringify(report, null, 2));
|
|
112
|
-
else
|
|
113
|
-
printText(report);
|
|
114
|
+
report = { ref, changedFiles: paths, testCommand, testResult, architectureCheck, risk, recommendation };
|
|
114
115
|
}
|
|
115
116
|
finally {
|
|
116
117
|
// best-effort — reject() pode já ter deixado a sessão num estado terminal se execute() lançou,
|
|
@@ -121,6 +122,17 @@ async function cmdSimulate(args) {
|
|
|
121
122
|
await sandbox.destroy(session.id).catch((error) => { console.error(`simulate: aviso — destroy do sandbox falhou: ${error instanceof Error ? error.message : String(error)}`); });
|
|
122
123
|
fs.rmSync(tempBase, { recursive: true, force: true });
|
|
123
124
|
}
|
|
125
|
+
// Fora do try/finally: o cleanup do sandbox já rodou, então as saídas que terminam o processo
|
|
126
|
+
// (emit*) são seguras. `discard` = o gate do simulate dizendo "não promova" → rejected/exit 2
|
|
127
|
+
// (ADR-0082).
|
|
128
|
+
if (json) {
|
|
129
|
+
if (report.recommendation === 'discard')
|
|
130
|
+
emitRejected({ ...report }); // termina o processo
|
|
131
|
+
emitOk({ ...report }); // termina o processo
|
|
132
|
+
}
|
|
133
|
+
printText(report);
|
|
134
|
+
if (report.recommendation === 'discard')
|
|
135
|
+
process.exitCode = 2;
|
|
124
136
|
}
|
|
125
137
|
function printText(report) {
|
|
126
138
|
console.log(`simulate ${report.ref}`);
|
|
@@ -21,6 +21,11 @@ import fs from 'node:fs';
|
|
|
21
21
|
import path from 'node:path';
|
|
22
22
|
import { fileURLToPath } from 'node:url';
|
|
23
23
|
import { domainsOf, buildContextPack } from "../lib/code-context.js";
|
|
24
|
+
import { emitOk } from "../lib/cli-output.js";
|
|
25
|
+
const JSON_MODE = process.argv.includes('--json');
|
|
26
|
+
/** No modo `--json` o stdout é só o objeto final (ADR-0082); o texto de análise é suprimido. */
|
|
27
|
+
const say = (line = '') => { if (!JSON_MODE)
|
|
28
|
+
console.log(line); };
|
|
24
29
|
const __filename = fileURLToPath(import.meta.url);
|
|
25
30
|
const root = path.resolve(path.dirname(__filename), '..');
|
|
26
31
|
/**
|
|
@@ -29,26 +34,28 @@ const root = path.resolve(path.dirname(__filename), '..');
|
|
|
29
34
|
*/
|
|
30
35
|
function projectMode(projectRoot) {
|
|
31
36
|
const domains = domainsOf(projectRoot);
|
|
32
|
-
|
|
37
|
+
say(`\nToken economy — eixo memória nos domínios de ${projectRoot} (ADR-0009)\n`);
|
|
33
38
|
if (!domains.length) {
|
|
34
|
-
|
|
39
|
+
say(`Nenhum domínio em ${path.join(projectRoot, 'memory/30-domains')}. Rode dentro de um projeto gerado.`);
|
|
40
|
+
if (JSON_MODE)
|
|
41
|
+
emitOk({ rows: [] });
|
|
35
42
|
return;
|
|
36
43
|
}
|
|
37
|
-
|
|
44
|
+
say('Para cada domínio: ler o mapa (context.md) vs ler todo o código da fatia.\n');
|
|
38
45
|
const rows = [];
|
|
39
46
|
for (const domain of domains) {
|
|
40
47
|
const pack = buildContextPack({ projectRoot, domain, includeCode: true });
|
|
41
48
|
const economy = pack.codeTokens === 0 ? '—' : `−${Math.round(((pack.codeTokens - pack.mapTokens) / pack.codeTokens) * 100)}%`;
|
|
42
49
|
rows.push({ domínio: domain, mapa_tok: pack.mapTokens, código_tok: pack.codeTokens, mapa_vs_código: economy });
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
50
|
+
say(`■ ${domain}`);
|
|
51
|
+
say(` mapa (context.md): ${String(pack.mapTokens).padStart(5)} tok`);
|
|
52
|
+
say(` código da fatia: ${String(pack.codeTokens).padStart(5)} tok (${pack.code.length} arq.)`);
|
|
53
|
+
say(` o mapa custa ${economy} do código — é o resumo que substitui a leitura da árvore\n`);
|
|
47
54
|
}
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
if (
|
|
51
|
-
|
|
55
|
+
say('O mapa é o resumo do domínio: lê-lo custa uma fração de ler a fatia inteira. Essa é a');
|
|
56
|
+
say('economia da memória, medida no SEU projeto. (Sem mapa? rode `forja memory:audit`.)\n');
|
|
57
|
+
if (JSON_MODE)
|
|
58
|
+
emitOk({ rows });
|
|
52
59
|
}
|
|
53
60
|
const CLEAN = 'boilerplates/06-clean-arch/backend/src/modules/orders';
|
|
54
61
|
const CLEAN_CTX = 'boilerplates/06-clean-arch/memory/30-domains/orders/context.md';
|
|
@@ -113,28 +120,27 @@ if (projIdx >= 0) {
|
|
|
113
120
|
projectMode(path.resolve(process.argv[projIdx + 1] || process.cwd()));
|
|
114
121
|
process.exit(0);
|
|
115
122
|
}
|
|
116
|
-
|
|
117
|
-
|
|
123
|
+
say('\nToken economy — o custo do CONTEXTO por cenário (ADR-0027, ADR-0009)\n');
|
|
124
|
+
say('Token ≈ bytes/4. Não mede o custo de gerar do zero (custo único); mede o regime permanente.\n');
|
|
118
125
|
const out = [];
|
|
119
126
|
for (const s of SCENARIOS) {
|
|
120
127
|
const a = sum(s.a.files);
|
|
121
128
|
const b = sum(s.b.files);
|
|
122
129
|
out.push({ eixo: s.axis, cenário: s.name, [s.a.label]: a, [s.b.label]: b, a_vs_b: pct(a, b) });
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
130
|
+
say(`■ [${s.axis}] ${s.name}`);
|
|
131
|
+
say(` ${s.question}`);
|
|
132
|
+
say(` ${s.a.label.padEnd(18)} ${String(a).padStart(5)} tok (${s.a.files.length} arq.)`);
|
|
133
|
+
say(` ${s.b.label.padEnd(18)} ${String(b).padStart(5)} tok (${s.b.files.length} arq.)`);
|
|
134
|
+
say(` ${s.a.label} vs ${s.b.label}: ${pct(a, b)}\n`);
|
|
128
135
|
}
|
|
129
136
|
const arch = out[1]; // mudar a regra, clean vs flat
|
|
130
137
|
const mem = out[2]; // frio vs quente
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
if (
|
|
139
|
-
|
|
140
|
-
}
|
|
138
|
+
say('Veredito (derivado dos números):');
|
|
139
|
+
say(` • EIXO ARQUITETURA: numa feature pequena, camadas custam MAIS token (${arch.a_vs_b} para`);
|
|
140
|
+
say(` a mudança isolada). "Clean Architecture economiza tokens" não se sustenta nessa escala —`);
|
|
141
|
+
say(` a justificativa das camadas é isolamento e testabilidade, não token.`);
|
|
142
|
+
say(` • EIXO MEMÓRIA: o mapa (context.md) faz o contexto mínimo custar ${mem.a_vs_b} vs varrer`);
|
|
143
|
+
say(` a fatia no frio. É AQUI que a economia mora — e ela COMPÕE: o scaffold é custo único,`);
|
|
144
|
+
say(` o mapa economiza a cada tarefa futura. Depois do projeto levantado, a memória paga de volta.\n`);
|
|
145
|
+
if (JSON_MODE)
|
|
146
|
+
emitOk({ rows: out });
|
|
@@ -18,7 +18,7 @@
|
|
|
18
18
|
* Uso: node scripts/tools-doctor.mjs
|
|
19
19
|
*/
|
|
20
20
|
import { spawnSync } from 'node:child_process';
|
|
21
|
-
import { runChecks, worstStatus } from "../lib/core/health.js";
|
|
21
|
+
import { runChecks, worstStatus, bucketFor, BUCKET_LABEL } from "../lib/core/health.js";
|
|
22
22
|
const TOOLS = [
|
|
23
23
|
{
|
|
24
24
|
name: 'codegraph',
|
|
@@ -71,15 +71,23 @@ const TAG = {
|
|
|
71
71
|
};
|
|
72
72
|
function printCore(results) {
|
|
73
73
|
console.log('Núcleo — o que impede o framework de trabalhar (SPEC-009)\n');
|
|
74
|
-
for (const
|
|
75
|
-
|
|
76
|
-
if (
|
|
77
|
-
|
|
74
|
+
for (const bucket of ['blocking', 'first-run']) {
|
|
75
|
+
const group = results.filter((r) => bucketFor(r.id) === bucket);
|
|
76
|
+
if (group.length === 0)
|
|
77
|
+
continue;
|
|
78
|
+
console.log(`— ${BUCKET_LABEL[bucket]} —`);
|
|
79
|
+
for (const r of group) {
|
|
80
|
+
console.log(`${TAG[r.status]} ${r.id.padEnd(13)} ${r.detail}`);
|
|
81
|
+
if (r.fix)
|
|
82
|
+
console.log(` corrigir: ${r.fix}`);
|
|
83
|
+
}
|
|
84
|
+
if (bucket === 'first-run')
|
|
85
|
+
console.log(' (ou rode tudo de uma vez: forja setup)');
|
|
78
86
|
console.log('');
|
|
79
87
|
}
|
|
80
88
|
}
|
|
81
89
|
function printTools() {
|
|
82
|
-
console.log(
|
|
90
|
+
console.log(`— ${BUCKET_LABEL.optional} — potencializam o harness, nunca travam (ADR-0018)\n`);
|
|
83
91
|
let installed = 0;
|
|
84
92
|
for (const tool of TOOLS) {
|
|
85
93
|
const [cmd, args] = tool.probe;
|
|
@@ -1,8 +1,10 @@
|
|
|
1
1
|
# CLI como adaptador do Capability Registry
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
O CLI unifica os comandos abaixo com o registry executável. O comando legado continua disponível
|
|
4
|
+
como alias; a lógica roda por um handler injetado no adaptador, não por uma implementação
|
|
5
|
+
paralela. O mapeamento argv↔payload é **declarativo** (`spec.params` em `apps/cli/src/index.ts`,
|
|
6
|
+
`parseArgv`/`argvFor` em `apps/cli/src/params.ts`); um teste de round-trip força os dois sentidos
|
|
7
|
+
a fecharem (SPEC-046, [ADR-0083](../../memory/90-decisions/0083-mcp-cobertura-declarativa.md)).
|
|
6
8
|
|
|
7
9
|
| Comando legado | Capability | Input | Observação |
|
|
8
10
|
| --- | --- | --- | --- |
|
|
@@ -12,6 +14,23 @@ por uma implementação paralela no CLI.
|
|
|
12
14
|
| `spec:check [feature]` | `spec.validate` | `{ feature? }` | valida uma spec ou todas |
|
|
13
15
|
| `sprint:status [project]` | `sprint.status` | `{ project? }` | consulta a sprint atual |
|
|
14
16
|
| `gsd:handoff <phase> <slug> [context]` | `handoff.create` | `{ phase, slug, context? }` | grava handoff local governado |
|
|
17
|
+
| `spec:new <slug>` | `spec.create` | `{ slug }` | escreve `specs/<slug>/spec.md` |
|
|
18
|
+
| `spec:plan <slug>` | `spec.plan` | `{ slug }` | escreve `plan.md` |
|
|
19
|
+
| `spec:tasks <slug>` | `spec.tasks` | `{ slug }` | escreve `tasks.md` |
|
|
20
|
+
| `code:context <domain> [--code]` | `code.context` | `{ domain?, code? }` | pacote de contexto mínimo |
|
|
21
|
+
| `query:universal <query>` | `memory.query` | `{ query }` | busca FTS5 na memória universal |
|
|
22
|
+
| `engineer "<obj>" [--ref r] [--role x]` | `engineering.facade` | `{ objective, ref?, role? }` | façade de engenharia |
|
|
23
|
+
| `risk:assess [ref]` | `risk.assess` | `{ ref? }` | score de risco 0-100 |
|
|
24
|
+
| `orchestrate:status <slug>` | `orchestrate.status` | `{ slug }` | estado da corrida |
|
|
25
|
+
| `orchestrate:advance <slug>` | `orchestrate.advance` | `{ slug }` | roda o gate da etapa (write) |
|
|
26
|
+
| `drift:check [--domain d]` | `drift.check` | `{ domain? }` | reindexa + sinaliza drift |
|
|
27
|
+
| `status` | `forja.status` | `{}` | retrato do estado |
|
|
28
|
+
| `next` | `forja.next` | `{}` | próxima ação recomendada |
|
|
29
|
+
|
|
30
|
+
**Fora da cobertura**, por desenho ([ADR-0083](../../memory/90-decisions/0083-mcp-cobertura-declarativa.md)):
|
|
31
|
+
`orchestrate` (start), `llm:*` (contrato de privacidade próprio, ADR-0081),
|
|
32
|
+
`project:new`/`sprint:start`/`sprint:complete`/`workspace:init`/`setup` (mutação fora do fluxo
|
|
33
|
+
SDD), `memory:*` de escrita, `architecture:approve` (governança).
|
|
15
34
|
|
|
16
35
|
## Descoberta e execução
|
|
17
36
|
|
|
@@ -21,15 +40,20 @@ forja capabilities:describe code.impact --json
|
|
|
21
40
|
forja capability:execute code.impact --input '{"symbol":"CapabilityRegistry","depth":2}' --json
|
|
22
41
|
```
|
|
23
42
|
|
|
24
|
-
Os
|
|
43
|
+
Os comandos-capability também aceitam `--json` no CLI. Desde SPEC-046, essa saída segue o
|
|
44
|
+
**contrato de saída** ([ADR-0082](../../memory/90-decisions/0082-contrato-saida-cli.md),
|
|
45
|
+
[`docs/contrato-saida-cli.md`](../contrato-saida-cli.md)) — não o `ExecutionResult` cru:
|
|
25
46
|
|
|
26
47
|
```bash
|
|
48
|
+
forja spec:check pagamentos-pix --json # → {"status":"ok"|"rejected"|"error", ...}
|
|
27
49
|
forja tools:doctor --json
|
|
28
|
-
forja code:impact CapabilityRegistry 2 --json
|
|
29
|
-
forja context:budget docs/2x/SPRINT-1-CLI-CAPABILITY-PLAN.md 10000 --json
|
|
30
50
|
```
|
|
31
51
|
|
|
32
|
-
O
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
52
|
+
O `stdout` do comando-filho, quando é um objeto JSON, é fundido no resultado (flat); senão vem
|
|
53
|
+
em `raw`. `stderr` vai para o stderr. Exit code segue o contrato (0/1/2).
|
|
54
|
+
|
|
55
|
+
O **consumo via MCP** (`forja mcp:start` → `tools/call`) continua recebendo o `ExecutionResult`
|
|
56
|
+
versionado (`runId`, `correlationId`, `status`, `output`, `evidence`, erro normalizado) — o MCP
|
|
57
|
+
tem o próprio contrato de protocolo. Entrada inválida é rejeitada antes do handler (`validateInput`,
|
|
58
|
+
derivado de `params` quando não há checagem extra); a política é avaliada pelo `CapabilityRegistry`
|
|
59
|
+
antes da execução.
|
|
@@ -18,9 +18,11 @@ No checkout, use `npm run <script> -- <argumentos>` ou `npm run forja -- <comand
|
|
|
18
18
|
5. Em handoffs, informe `from`, `to`, `intent`, `context`, `acceptance`, `constraints`, `return`. Delegação depende das capacidades e permissões da sessão.
|
|
19
19
|
|
|
20
20
|
## LLMs e evidência
|
|
21
|
-
Use [o fluxo de LLMs](llm-fit-loop.md) para perfis, contexto, sessões e validação. Não deduza disponibilidade de modelo pelo nome comercial do chat. O probe verifica a CLI, não o acesso ao modelo.
|
|
21
|
+
Use [o fluxo de LLMs](llm-fit-loop.md) para perfis, contexto, sessões e validação. Não deduza disponibilidade de modelo pelo nome comercial do chat. O probe verifica a CLI, não o acesso ao modelo. Retomada por sessão vale para os adapters em `RESUME_PROVIDERS` (`codex`, `claude`); os demais provedores não a herdam. Geração estruturada nativa é só do Codex — para Claude, `--output-schema` é validação local (Ajv), não garantia do provedor (`llm:probe` reporta `features.outputSchema: false`).
|
|
22
22
|
|
|
23
23
|
Separe `executionStatus` de `validationStatus`. Schema comprova formato; checks independentes sustentam aceite. Sem checks, a validação é inconclusiva. Custo desconhecido é `null`; não converta estimativas em medições. Os checks executam com as permissões do processo Forja: revise o manifest antes de usá-lo.
|
|
24
24
|
|
|
25
25
|
## Entrega
|
|
26
26
|
Informe o que mudou, arquivos relevantes, comandos executados e resultados, limitações e pendências. Diferencie validado localmente, CI aprovado, push realizado e pacote publicado. Registre commit e link quando existirem. Antes de publicação autorizada, rode `npm run release:check -- --publish` em checkout limpo; não declare publicação sem confirmação do destino.
|
|
27
|
+
|
|
28
|
+
Toda versão nova (bump de versão, tag ou publicação) inclui, como parte da entrega: o `README` reconciliado com o comportamento da versão e a entrada no `CHANGELOG.md` abrindo pela subseção `### O que melhorou` (diff de produto vs. a versão anterior). Runbook: [`docs/publishing.md`](publishing.md).
|
|
@@ -2,6 +2,23 @@
|
|
|
2
2
|
|
|
3
3
|
Este framework deve ser operado primeiro por linha de comando. O dashboard web fica como artefato legado/opcional de consulta; nao e gate de entrega, sprint, handoff ou governanca.
|
|
4
4
|
|
|
5
|
+
## Descoberta pela propria CLI (SPEC-043, SPEC-044)
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
forja status # onde estou: workspace, sprint, corrida, specs, runs, handoffs
|
|
9
|
+
forja next # o que faco agora: 1 linha com a proxima acao + o comando
|
|
10
|
+
forja help # so o nucleo agrupado por dominio
|
|
11
|
+
forja help --all # todos os comandos + capabilities
|
|
12
|
+
forja help spec:new # uso, argumentos, exemplos e proximos passos de um comando
|
|
13
|
+
forja <comando> --help # o mesmo detalhe, inline
|
|
14
|
+
forja setup # rotina de primeiro uso: workspace:init + sync:universal (pede confirmacao)
|
|
15
|
+
forja setup --yes # sem confirmacao (uso nao-interativo)
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
`forja status` e `forja next` aceitam `--json`. Digitou errado? O `forja` sugere o comando mais
|
|
19
|
+
proximo (`forja plan` aponta `spec:plan`). Faltou um argumento obrigatorio? O comando falha antes
|
|
20
|
+
de rodar, imprimindo o `Uso:` — sem stack trace.
|
|
21
|
+
|
|
5
22
|
## Ciclo Diario
|
|
6
23
|
|
|
7
24
|
```bash
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
# Contrato de saída da CLI
|
|
2
|
+
|
|
3
|
+
Como um comando do Forja se comunica com automação — `--json` e exit codes. Decisão em
|
|
4
|
+
[ADR-0082](../memory/90-decisions/0082-contrato-saida-cli.md).
|
|
5
|
+
|
|
6
|
+
O contrato **rege apenas os comandos marcados `json: true`** no registry (`lib/core/registry.ts`).
|
|
7
|
+
Não é obrigação universal: a cobertura cresce spec a spec. `forja help <comando>` mostra `--json`
|
|
8
|
+
no uso ou num exemplo quando o comando o suporta.
|
|
9
|
+
|
|
10
|
+
## Para quem consome
|
|
11
|
+
|
|
12
|
+
Com `--json`, o **stdout carrega exatamente um valor JSON**, sempre um **objeto**, com uma string
|
|
13
|
+
`status`:
|
|
14
|
+
|
|
15
|
+
| `status` | significado | exit code | forma |
|
|
16
|
+
|---|---|---|---|
|
|
17
|
+
| `ok` | sucesso | `0` | `{ "status": "ok", ...campos do comando }` |
|
|
18
|
+
| `error` | falha operacional (args inválidos, arquivo ausente, subsistema fora) | `1` | `{ "status": "error", "error": { "message": "...", "code"?: "..." } }` |
|
|
19
|
+
| `rejected` | uma validação/gate que o **próprio comando** roda deu negativo | `2` | `{ "status": "rejected", ...payload }` |
|
|
20
|
+
|
|
21
|
+
Além disso:
|
|
22
|
+
|
|
23
|
+
- `127` — binário externo obrigatório ausente (só alvos `bin:` do registry; `bin/forja.ts` já
|
|
24
|
+
devolve esse código e a mensagem).
|
|
25
|
+
- O **diagnóstico verboso vai para o stderr** — o stdout nunca tem nada além do objeto JSON.
|
|
26
|
+
- Os campos do comando ficam **ao lado** de `status` (flat), nunca sob um `data`.
|
|
27
|
+
- `--json` desliga ANSI e qualquer prompt: o comando falha (`error`) em vez de perguntar.
|
|
28
|
+
|
|
29
|
+
Exemplo de decisão de automação:
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
out=$(forja simulate HEAD --json); code=$?
|
|
33
|
+
case "$(jq -r .status <<<"$out")" in
|
|
34
|
+
ok) echo "promovível" ;;
|
|
35
|
+
rejected) echo "não promova: $(jq -r .recommendation <<<"$out")" ;; # exit 2
|
|
36
|
+
error) echo "falhou: $(jq -r .error.message <<<"$out")" >&2 ;; # exit 1
|
|
37
|
+
esac
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
`llm:run` é o caso de referência do `rejected`: formato válido mas checks independentes
|
|
41
|
+
reprovaram → `validationStatus: "rejected"`, exit 2, `executionStatus` do modelo preservado
|
|
42
|
+
(ver [llm-fit-loop.md](llm-fit-loop.md)).
|
|
43
|
+
|
|
44
|
+
## Para quem escreve um script
|
|
45
|
+
|
|
46
|
+
Use `lib/cli-output.ts` — ele impõe o formato e o exit code:
|
|
47
|
+
|
|
48
|
+
```ts
|
|
49
|
+
import { emitOk, emitError, emitRejected } from '../lib/cli-output.ts';
|
|
50
|
+
|
|
51
|
+
if (!ref) emitError('Uso: forja simulate <ref> [--json]'); // stdout {status:error}, exit 1
|
|
52
|
+
const report = await run(ref);
|
|
53
|
+
if (report.recommendation === 'discard') emitRejected(report); // stdout {status:rejected,...}, exit 2
|
|
54
|
+
emitOk(report); // stdout {status:ok,...}, exit 0
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Cada função termina o processo. `emitError(msg, { code, detail })` põe `detail` no stderr. Sem
|
|
58
|
+
`--json`, mantenha a saída de texto atual — o helper é só para o ramo `--json`.
|
|
59
|
+
|
|
60
|
+
Marque o comando com `json: true` no registry e cite `--json` no `usage` ou num `example`. O
|
|
61
|
+
teste `test/cli-output-contract.test.js` itera o registry e reprova qualquer `json: true` que
|
|
62
|
+
não cumpra o contrato — salvo as exceções conhecidas listadas abaixo.
|
|
63
|
+
|
|
64
|
+
## Comandos cobertos
|
|
65
|
+
|
|
66
|
+
`status` · `next` · `engineer` · `simulate` · `cost:economy` · `token:economy` — saída própria.
|
|
67
|
+
|
|
68
|
+
`spec:check` · `tools:doctor` e os demais **comandos-capability** (ver
|
|
69
|
+
[`docs/2x/CLI-CAPABILITIES.md`](2x/CLI-CAPABILITIES.md)) conformam pelo adaptador `toContract`
|
|
70
|
+
em `bin/forja.ts` (SPEC-046): `succeeded`+exit 0 → `ok`, `succeeded`+exit 2 → `rejected`,
|
|
71
|
+
`failed`/exit 1 → `error`; o `stdout` do filho, se for JSON, é fundido no resultado, senão vem
|
|
72
|
+
em `raw`. `risk:assess` e o restante entram incrementalmente.
|
|
73
|
+
|
|
74
|
+
## Exceções conhecidas
|
|
75
|
+
|
|
76
|
+
`llm:sessions` (SPEC-048) é anterior a este contrato e mantém forma própria: `list --json` emite
|
|
77
|
+
um **array** e `show --json` um **objeto sem `status`**. Documentado em
|
|
78
|
+
[llm-fit-loop.md](llm-fit-loop.md); o teste de contrato o ignora explicitamente. Alinhá-lo é
|
|
79
|
+
trabalho futuro, não regressão.
|
package/docs/llm-evolution.md
CHANGED
|
@@ -30,7 +30,8 @@ e da conta. Codex, Claude, Gemini, Ollama e executáveis locais permanecem integ
|
|
|
30
30
|
|---|---|---|
|
|
31
31
|
| 1 — implementada e testada | Contexto enviado; Codex JSONL; esforço e timeout configuráveis; telemetria e validação explícitas | Testes sem rede, tipos e build |
|
|
32
32
|
| 2 — implementada e testada | Retomada por sessão, resposta com schema e validação por testes/requisitos | Continuação sem replay pelo Forja; checks independentes rejeitam resultados inválidos |
|
|
33
|
-
|
|
|
33
|
+
| 2b — implementada e testada (SPEC-050) | Adaptador Claude com paridade: `--resume` nativo e `--output-format json`; `RESUME_PROVIDERS = { codex, claude }`. `--output-schema` para Claude é validação local (Ajv), não geração garantida pelo provedor | `llm:probe claude` reporta `features.resume`/`features.outputSchema`; testes sem rede com fixture |
|
|
34
|
+
| 3 — parcial (SPEC-049) | `llm:eval` com p50/p95 de latência e custo por tarefa aprovada; `llm:recommend` pondera custo e latência com `evidence` por candidato. Falta o eixo de qualidade por avaliador e o de risco por perfil. **Nenhum percentual afirmado** antes de baseline de 30 dias | Custo por tarefa aprovada, regressões e retrabalho |
|
|
34
35
|
| 4 — planejada | Contexto incremental e cache medido; adaptador de API opcional com ADR próprio | Economia total sem perda de qualidade |
|
|
35
36
|
| 5 — planejada | Expandir MCP existente; ferramentas sob demanda; checkpoints no runtime | Mesmas políticas e auditoria para CLI e agentes |
|
|
36
37
|
|