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.
Files changed (96) hide show
  1. package/CHANGELOG.md +170 -7
  2. package/DOC-MAP.md +1 -0
  3. package/README.md +10 -2
  4. package/README.pt-BR.md +3 -0
  5. package/dist/apps/cli/src/index.d.ts +18 -1
  6. package/dist/apps/cli/src/index.js +161 -26
  7. package/dist/apps/cli/src/params.d.ts +44 -0
  8. package/dist/apps/cli/src/params.js +123 -0
  9. package/dist/bin/forja.js +234 -13
  10. package/dist/bin/init-project.js +11 -62
  11. package/dist/lib/cli-output.d.ts +29 -0
  12. package/dist/lib/cli-output.js +39 -0
  13. package/dist/lib/core/checks.d.ts +1 -1
  14. package/dist/lib/core/health.d.ts +9 -0
  15. package/dist/lib/core/health.js +9 -0
  16. package/dist/lib/core/project-smoke.d.ts +6 -2
  17. package/dist/lib/core/project-smoke.js +83 -7
  18. package/dist/lib/core/registry.d.ts +38 -571
  19. package/dist/lib/core/registry.js +174 -25
  20. package/dist/lib/core/release.d.ts +1 -571
  21. package/dist/lib/core/release.js +0 -3
  22. package/dist/lib/handoffs-index.d.ts +16 -0
  23. package/dist/lib/handoffs-index.js +29 -0
  24. package/dist/lib/llm/claude-output.d.ts +8 -0
  25. package/dist/lib/llm/claude-output.js +54 -0
  26. package/dist/lib/llm/context.d.ts +22 -0
  27. package/dist/lib/llm/context.js +39 -0
  28. package/dist/lib/llm/session.d.ts +6 -1
  29. package/dist/lib/llm/session.js +12 -2
  30. package/dist/lib/multi-ai-instructions.d.ts +28 -0
  31. package/dist/lib/multi-ai-instructions.js +83 -0
  32. package/dist/lib/orchestrate.d.ts +5 -0
  33. package/dist/lib/orchestrate.js +18 -0
  34. package/dist/lib/specs-index.d.ts +20 -0
  35. package/dist/lib/specs-index.js +51 -0
  36. package/dist/lib/sprint-index.d.ts +15 -0
  37. package/dist/lib/sprint-index.js +34 -0
  38. package/dist/lib/status-model.d.ts +64 -0
  39. package/dist/lib/status-model.js +180 -0
  40. package/dist/packages/evals/src/index.d.ts +2 -0
  41. package/dist/packages/evals/src/index.js +21 -0
  42. package/dist/packages/llm/src/index.d.ts +24 -3
  43. package/dist/packages/llm/src/index.js +51 -5
  44. package/dist/scripts/cost-economy.js +12 -10
  45. package/dist/scripts/drift-check.d.ts +2 -0
  46. package/dist/scripts/drift-check.js +57 -1
  47. package/dist/scripts/engineer.js +7 -4
  48. package/dist/scripts/forja-setup.d.ts +14 -0
  49. package/dist/scripts/forja-setup.js +58 -0
  50. package/dist/scripts/forja-status.d.ts +11 -0
  51. package/dist/scripts/forja-status.js +70 -0
  52. package/dist/scripts/hook-session-start.js +20 -46
  53. package/dist/scripts/llm-fit.js +113 -8
  54. package/dist/scripts/project-smoke.js +13 -3
  55. package/dist/scripts/simulate.js +18 -6
  56. package/dist/scripts/token-economy.js +34 -28
  57. package/dist/scripts/tools-doctor.js +14 -6
  58. package/docs/2x/CLI-CAPABILITIES.md +34 -10
  59. package/docs/agent-operating-contract.md +3 -1
  60. package/docs/cli-first-operacao.md +17 -0
  61. package/docs/contrato-saida-cli.md +79 -0
  62. package/docs/llm-evolution.md +2 -1
  63. package/docs/llm-fit-loop.md +74 -2
  64. package/docs/publishing.md +13 -16
  65. package/docs/quick-reference.md +13 -0
  66. package/docs/roadmap-v4.1.md +199 -0
  67. package/memory/90-decisions/0082-contrato-saida-cli.md +95 -0
  68. package/memory/90-decisions/0083-mcp-cobertura-declarativa.md +103 -0
  69. package/memory/90-decisions/0084-drift-sentinel-fecha.md +79 -0
  70. package/memory/90-decisions/0085-adaptador-claude-paridade.md +85 -0
  71. package/package.json +4 -1
  72. package/specs/cli-intuitiva-v1/plan.md +169 -0
  73. package/specs/cli-intuitiva-v1/spec.md +163 -0
  74. package/specs/cli-intuitiva-v1/tasks.md +224 -0
  75. package/specs/contrato-saida-cli/plan.md +162 -0
  76. package/specs/contrato-saida-cli/spec.md +157 -0
  77. package/specs/contrato-saida-cli/tasks.md +153 -0
  78. package/specs/drift-sentinel/spec.md +17 -8
  79. package/specs/forja-status-caminho-feliz/plan.md +149 -0
  80. package/specs/forja-status-caminho-feliz/spec.md +158 -0
  81. package/specs/forja-status-caminho-feliz/tasks.md +175 -0
  82. package/specs/llm-adaptador-claude/plan.md +117 -0
  83. package/specs/llm-adaptador-claude/spec.md +144 -0
  84. package/specs/llm-adaptador-claude/tasks.md +100 -0
  85. package/specs/llm-benchmark-recomendacao/plan.md +121 -0
  86. package/specs/llm-benchmark-recomendacao/spec.md +141 -0
  87. package/specs/llm-benchmark-recomendacao/tasks.md +88 -0
  88. package/specs/llm-contexto-e-sessoes/plan.md +143 -0
  89. package/specs/llm-contexto-e-sessoes/spec.md +139 -0
  90. package/specs/llm-contexto-e-sessoes/tasks.md +127 -0
  91. package/specs/mcp-cobertura-nucleo/plan.md +158 -0
  92. package/specs/mcp-cobertura-nucleo/spec.md +161 -0
  93. package/specs/mcp-cobertura-nucleo/tasks.md +169 -0
  94. package/specs/projeto-gerado-confiavel/plan.md +148 -0
  95. package/specs/projeto-gerado-confiavel/spec.md +142 -0
  96. package/specs/projeto-gerado-confiavel/tasks.md +139 -0
@@ -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 { LlmSessionStore, validSessionId } from "../lib/llm/session.js";
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 prompt = option(input, '--prompt') ?? (option(input, '--task') ? fs.readFileSync(path.resolve(option(input, '--task')), 'utf8') : undefined);
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
- const context = buildContextPrompt(prompt, input.get('--context') ?? []);
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' ? normalizeCodexResult(raw) : raw;
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 === 'codex' && sessionId !== undefined)
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
- console.log(`\nForja project smoke${full ? ' (tier --full)' : ''}\n`);
19
- console.log(`Gerando um projeto num diretório isolado${full ? ' e buildando o backend — isto leva minutos' : ''}.\n`);
20
- const results = await runProjectSmoke({ full });
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)
@@ -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
- console.error('Uso: forja simulate <ref> [--command "npm test"] [--json]');
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
- const report = { ref, changedFiles: paths, testCommand, testResult, architectureCheck, risk, recommendation };
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
- console.log(`\nToken economy — eixo memória nos domínios de ${projectRoot} (ADR-0009)\n`);
37
+ say(`\nToken economy — eixo memória nos domínios de ${projectRoot} (ADR-0009)\n`);
33
38
  if (!domains.length) {
34
- console.log(`Nenhum domínio em ${path.join(projectRoot, 'memory/30-domains')}. Rode dentro de um projeto gerado.`);
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
- console.log('Para cada domínio: ler o mapa (context.md) vs ler todo o código da fatia.\n');
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
- console.log(`■ ${domain}`);
44
- console.log(` mapa (context.md): ${String(pack.mapTokens).padStart(5)} tok`);
45
- console.log(` código da fatia: ${String(pack.codeTokens).padStart(5)} tok (${pack.code.length} arq.)`);
46
- console.log(` o mapa custa ${economy} do código — é o resumo que substitui a leitura da árvore\n`);
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
- console.log('O mapa é o resumo do domínio: lê-lo custa uma fração de ler a fatia inteira. Essa é a');
49
- console.log('economia da memória, medida no SEU projeto. (Sem mapa? rode `forja memory:audit`.)\n');
50
- if (process.argv.includes('--json'))
51
- console.log(JSON.stringify(rows, null, 2));
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
- console.log('\nToken economy — o custo do CONTEXTO por cenário (ADR-0027, ADR-0009)\n');
117
- console.log('Token ≈ bytes/4. Não mede o custo de gerar do zero (custo único); mede o regime permanente.\n');
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
- console.log(`■ [${s.axis}] ${s.name}`);
124
- console.log(` ${s.question}`);
125
- console.log(` ${s.a.label.padEnd(18)} ${String(a).padStart(5)} tok (${s.a.files.length} arq.)`);
126
- console.log(` ${s.b.label.padEnd(18)} ${String(b).padStart(5)} tok (${s.b.files.length} arq.)`);
127
- console.log(` ${s.a.label} vs ${s.b.label}: ${pct(a, b)}\n`);
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
- console.log('Veredito (derivado dos números):');
132
- console.log(` • EIXO ARQUITETURA: numa feature pequena, camadas custam MAIS token (${arch.a_vs_b} para`);
133
- console.log(` a mudança isolada). "Clean Architecture economiza tokens" não se sustenta nessa escala —`);
134
- console.log(` a justificativa das camadas é isolamento e testabilidade, não token.`);
135
- console.log(` • EIXO MEMÓRIA: o mapa (context.md) faz o contexto mínimo custar ${mem.a_vs_b} vs varrer`);
136
- console.log(` a fatia no frio. É AQUI que a economia mora — e ela COMPÕE: o scaffold é custo único,`);
137
- console.log(` o mapa economiza a cada tarefa futura. Depois do projeto levantado, a memória paga de volta.\n`);
138
- if (process.argv.includes('--json')) {
139
- console.log(JSON.stringify(out, null, 2));
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 r of results) {
75
- console.log(`${TAG[r.status]} ${r.id.padEnd(13)} ${r.detail}`);
76
- if (r.fix)
77
- console.log(` corrigir: ${r.fix}`);
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('Ferramentas de processo — opcionais (ADR-0018)\n');
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
- Sprint 1 unifica os três comandos de prova abaixo com o registry executável. O comando legado
4
- continua disponível como alias; a lógica é executada por um handler injetado no adaptador, e não
5
- por uma implementação paralela no CLI.
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 três comandos legados também aceitam `--json` e retornam o mesmo `ExecutionResult` versionado:
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 envelope inclui `runId`, `correlationId`, `status`, `output`, `evidence` e erro normalizado
33
- quando aplicável. Entrada inválida é rejeitada antes do handler; política é avaliada pelo
34
- `CapabilityRegistry` antes da execução. Comandos ainda não migrados permanecem no dispatch
35
- legado durante a migração progressiva.
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. Recursos de resume e output schema são específicos do adapter Codex atual; outros provedores não herdam essas garantias.
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.
@@ -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
- | 3 — planejada | Benchmark real; recomendação por qualidade, risco, custo e latência | Custo por tarefa aprovada, regressões e retrabalho |
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