forjajs 4.0.0 → 4.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (94) hide show
  1. package/CHANGELOG.md +115 -0
  2. package/DOC-MAP.md +1 -0
  3. package/README.md +7 -2
  4. package/dist/apps/cli/src/index.d.ts +18 -1
  5. package/dist/apps/cli/src/index.js +161 -26
  6. package/dist/apps/cli/src/params.d.ts +44 -0
  7. package/dist/apps/cli/src/params.js +123 -0
  8. package/dist/bin/forja.js +234 -13
  9. package/dist/bin/init-project.js +11 -62
  10. package/dist/lib/cli-output.d.ts +29 -0
  11. package/dist/lib/cli-output.js +39 -0
  12. package/dist/lib/core/checks.d.ts +1 -1
  13. package/dist/lib/core/health.d.ts +9 -0
  14. package/dist/lib/core/health.js +9 -0
  15. package/dist/lib/core/project-smoke.d.ts +6 -2
  16. package/dist/lib/core/project-smoke.js +83 -7
  17. package/dist/lib/core/registry.d.ts +38 -571
  18. package/dist/lib/core/registry.js +174 -25
  19. package/dist/lib/core/release.d.ts +1 -571
  20. package/dist/lib/core/release.js +0 -3
  21. package/dist/lib/handoffs-index.d.ts +16 -0
  22. package/dist/lib/handoffs-index.js +29 -0
  23. package/dist/lib/llm/claude-output.d.ts +8 -0
  24. package/dist/lib/llm/claude-output.js +54 -0
  25. package/dist/lib/llm/context.d.ts +22 -0
  26. package/dist/lib/llm/context.js +39 -0
  27. package/dist/lib/llm/session.d.ts +6 -1
  28. package/dist/lib/llm/session.js +12 -2
  29. package/dist/lib/multi-ai-instructions.d.ts +28 -0
  30. package/dist/lib/multi-ai-instructions.js +83 -0
  31. package/dist/lib/orchestrate.d.ts +5 -0
  32. package/dist/lib/orchestrate.js +18 -0
  33. package/dist/lib/specs-index.d.ts +20 -0
  34. package/dist/lib/specs-index.js +51 -0
  35. package/dist/lib/sprint-index.d.ts +15 -0
  36. package/dist/lib/sprint-index.js +34 -0
  37. package/dist/lib/status-model.d.ts +64 -0
  38. package/dist/lib/status-model.js +180 -0
  39. package/dist/packages/evals/src/index.d.ts +2 -0
  40. package/dist/packages/evals/src/index.js +21 -0
  41. package/dist/packages/llm/src/index.d.ts +24 -3
  42. package/dist/packages/llm/src/index.js +51 -5
  43. package/dist/scripts/cost-economy.js +12 -10
  44. package/dist/scripts/drift-check.d.ts +2 -0
  45. package/dist/scripts/drift-check.js +57 -1
  46. package/dist/scripts/engineer.js +7 -4
  47. package/dist/scripts/forja-setup.d.ts +14 -0
  48. package/dist/scripts/forja-setup.js +58 -0
  49. package/dist/scripts/forja-status.d.ts +11 -0
  50. package/dist/scripts/forja-status.js +70 -0
  51. package/dist/scripts/hook-session-start.js +20 -46
  52. package/dist/scripts/llm-fit.js +113 -8
  53. package/dist/scripts/project-smoke.js +13 -3
  54. package/dist/scripts/simulate.js +18 -6
  55. package/dist/scripts/token-economy.js +34 -28
  56. package/dist/scripts/tools-doctor.js +14 -6
  57. package/docs/2x/CLI-CAPABILITIES.md +34 -10
  58. package/docs/agent-operating-contract.md +1 -1
  59. package/docs/cli-first-operacao.md +17 -0
  60. package/docs/contrato-saida-cli.md +79 -0
  61. package/docs/llm-evolution.md +2 -1
  62. package/docs/llm-fit-loop.md +74 -2
  63. package/docs/quick-reference.md +13 -0
  64. package/docs/roadmap-v4.1.md +199 -0
  65. package/memory/90-decisions/0082-contrato-saida-cli.md +95 -0
  66. package/memory/90-decisions/0083-mcp-cobertura-declarativa.md +103 -0
  67. package/memory/90-decisions/0084-drift-sentinel-fecha.md +79 -0
  68. package/memory/90-decisions/0085-adaptador-claude-paridade.md +85 -0
  69. package/package.json +4 -1
  70. package/specs/cli-intuitiva-v1/plan.md +169 -0
  71. package/specs/cli-intuitiva-v1/spec.md +163 -0
  72. package/specs/cli-intuitiva-v1/tasks.md +224 -0
  73. package/specs/contrato-saida-cli/plan.md +162 -0
  74. package/specs/contrato-saida-cli/spec.md +157 -0
  75. package/specs/contrato-saida-cli/tasks.md +153 -0
  76. package/specs/drift-sentinel/spec.md +17 -8
  77. package/specs/forja-status-caminho-feliz/plan.md +149 -0
  78. package/specs/forja-status-caminho-feliz/spec.md +158 -0
  79. package/specs/forja-status-caminho-feliz/tasks.md +175 -0
  80. package/specs/llm-adaptador-claude/plan.md +117 -0
  81. package/specs/llm-adaptador-claude/spec.md +144 -0
  82. package/specs/llm-adaptador-claude/tasks.md +100 -0
  83. package/specs/llm-benchmark-recomendacao/plan.md +121 -0
  84. package/specs/llm-benchmark-recomendacao/spec.md +141 -0
  85. package/specs/llm-benchmark-recomendacao/tasks.md +88 -0
  86. package/specs/llm-contexto-e-sessoes/plan.md +143 -0
  87. package/specs/llm-contexto-e-sessoes/spec.md +139 -0
  88. package/specs/llm-contexto-e-sessoes/tasks.md +127 -0
  89. package/specs/mcp-cobertura-nucleo/plan.md +158 -0
  90. package/specs/mcp-cobertura-nucleo/spec.md +161 -0
  91. package/specs/mcp-cobertura-nucleo/tasks.md +169 -0
  92. package/specs/projeto-gerado-confiavel/plan.md +148 -0
  93. package/specs/projeto-gerado-confiavel/spec.md +142 -0
  94. package/specs/projeto-gerado-confiavel/tasks.md +139 -0
@@ -55,6 +55,10 @@ export const COMMANDS = {
55
55
  desc: 'Cria a estrutura base do workspace (~/forja-workspace)',
56
56
  node: 'scripts/agent-harness.ts',
57
57
  args: ['workspace:init'],
58
+ tier: 'core',
59
+ usage: 'forja workspace:init',
60
+ examples: ['forja workspace:init'],
61
+ next: ['project:new', 'sync:universal'],
58
62
  },
59
63
  'project:new': {
60
64
  domain: 'workspace',
@@ -62,6 +66,22 @@ export const COMMANDS = {
62
66
  node: 'scripts/agent-harness.ts',
63
67
  args: ['project:new'],
64
68
  gates: ['workspace'],
69
+ tier: 'core',
70
+ usage: 'forja project:new <nome> [-- --ai claude,copilot]',
71
+ cliArgs: [{ name: 'nome', required: true, desc: 'slug do projeto (kebab-case)' }],
72
+ examples: ['forja project:new meu-app -- --ai claude,copilot'],
73
+ next: ['workspace:project:check'],
74
+ },
75
+ setup: {
76
+ domain: 'workspace',
77
+ desc: 'Rotina de primeiro uso: workspace:init + sync:universal, atrás de confirmação',
78
+ node: 'scripts/forja-setup.ts',
79
+ spec: 'SPEC-043',
80
+ tier: 'core',
81
+ readonly: false,
82
+ usage: 'forja setup [--yes]',
83
+ examples: ['forja setup', 'forja setup --yes'],
84
+ next: ['project:new', 'spec:new'],
65
85
  },
66
86
  'project:list': {
67
87
  domain: 'workspace',
@@ -87,61 +107,128 @@ export const COMMANDS = {
87
107
  desc: 'Cria specs/<slug>/spec.md a partir do template',
88
108
  node: 'scripts/spec-cli.ts',
89
109
  args: ['new'],
110
+ tier: 'core',
111
+ usage: 'forja spec:new <slug>',
112
+ cliArgs: [{ name: 'slug', required: true, desc: 'identificador da feature em kebab-case' }],
113
+ examples: ['forja spec:new pagamentos-pix'],
114
+ next: ['spec:plan', 'spec:check'],
90
115
  },
91
116
  'spec:plan': {
92
117
  domain: 'sdd',
93
118
  desc: 'Deriva plan.md de uma spec',
94
119
  node: 'scripts/spec-cli.ts',
95
120
  args: ['plan'],
121
+ tier: 'core',
122
+ usage: 'forja spec:plan <slug>',
123
+ cliArgs: [{ name: 'slug', required: true, desc: 'feature com spec.md em approved' }],
124
+ examples: ['forja spec:plan pagamentos-pix'],
125
+ next: ['spec:tasks'],
96
126
  },
97
127
  'spec:tasks': {
98
128
  domain: 'sdd',
99
129
  desc: 'Decompõe plan.md em tasks.md',
100
130
  node: 'scripts/spec-cli.ts',
101
131
  args: ['tasks'],
132
+ tier: 'core',
133
+ usage: 'forja spec:tasks <slug>',
134
+ cliArgs: [{ name: 'slug', required: true, desc: 'feature com plan.md em approved' }],
135
+ examples: ['forja spec:tasks pagamentos-pix'],
136
+ next: ['hermes:handoff'],
102
137
  },
103
138
  'spec:check': {
104
139
  domain: 'sdd',
105
140
  desc: 'Valida completude da spec (gate de governança)',
106
141
  node: 'scripts/spec-cli.ts',
107
142
  args: ['check'],
143
+ tier: 'core',
144
+ readonly: true,
145
+ json: true,
146
+ usage: 'forja spec:check [slug] [--json]',
147
+ cliArgs: [{ name: 'slug', required: false, desc: 'feature; omitido = valida todas' }],
148
+ examples: ['forja spec:check', 'forja spec:check pagamentos-pix', 'forja spec:check --json'],
149
+ next: ['spec:plan'],
108
150
  },
109
151
  // --- GSD & handoffs ------------------------------------------------------
110
- 'gsd:plan': {
152
+ status: {
111
153
  domain: 'gsd',
112
- desc: 'Cria runbook GSD em .context/',
113
- node: 'scripts/agent-harness.ts',
114
- args: ['gsd:plan'],
115
- },
116
- 'gsd:handoff': {
117
- domain: 'gsd',
118
- desc: 'Registra handoff GSD padronizado (ADR-0005)',
119
- node: 'scripts/agent-harness.ts',
120
- args: ['gsd:handoff'],
121
- },
122
- 'gsd:check': {
154
+ desc: 'Retrato único do estado: workspace, sprint, corrida, specs, runs, handoffs',
155
+ node: 'scripts/forja-status.ts',
156
+ args: ['status'],
157
+ gates: ['workspace-warn'],
158
+ spec: 'SPEC-044',
159
+ tier: 'core',
160
+ readonly: true,
161
+ json: true,
162
+ usage: 'forja status [--json]',
163
+ examples: ['forja status', 'forja status --json'],
164
+ next: ['next'],
165
+ },
166
+ next: {
123
167
  domain: 'gsd',
124
- desc: 'Valida gates básicos do runbook GSD',
125
- node: 'scripts/agent-harness.ts',
126
- args: ['gsd:check'],
168
+ desc: 'A próxima ação recomendada + o comando exato para executá-la',
169
+ node: 'scripts/forja-status.ts',
170
+ args: ['next'],
171
+ gates: ['workspace-warn'],
172
+ spec: 'SPEC-044',
173
+ tier: 'core',
174
+ readonly: true,
175
+ json: true,
176
+ usage: 'forja next [--json]',
177
+ examples: ['forja next'],
178
+ next: ['status'],
127
179
  },
128
180
  orchestrate: {
129
181
  domain: 'gsd',
130
- desc: 'Abre uma corrida: a cadeia SDD/GSD como máquina de estados guardada por gates (SPEC-021). "<objetivo>" --slug <slug>',
182
+ desc: 'Abre uma corrida: a cadeia SDD/GSD como máquina de estados guardada por gates',
131
183
  node: 'scripts/orchestrate.ts',
132
184
  args: ['start'],
185
+ spec: 'SPEC-021',
186
+ tier: 'core',
187
+ usage: 'forja orchestrate "<objetivo>" --slug <slug>',
188
+ cliArgs: [{ name: 'objetivo', required: true, desc: 'frase do que a corrida entrega (entre aspas)' }],
189
+ examples: ['forja orchestrate "checkout via pix" --slug pagamentos-pix'],
190
+ next: ['orchestrate:status', 'orchestrate:advance'],
133
191
  },
134
192
  'orchestrate:status': {
135
193
  domain: 'gsd',
136
194
  desc: 'O estado da corrida: etapas feitas, aberta, gates e vereditos',
137
195
  node: 'scripts/orchestrate.ts',
138
196
  args: ['status'],
197
+ spec: 'SPEC-021',
198
+ tier: 'core',
199
+ readonly: true,
200
+ usage: 'forja orchestrate:status [--slug <slug>]',
201
+ examples: ['forja orchestrate:status'],
202
+ next: ['orchestrate:advance'],
139
203
  },
140
204
  'orchestrate:advance': {
141
205
  domain: 'gsd',
142
206
  desc: 'Roda o gate da etapa aberta; verde → abre a próxima; vermelho → trava com o parecer',
143
207
  node: 'scripts/orchestrate.ts',
144
208
  args: ['advance'],
209
+ spec: 'SPEC-021',
210
+ tier: 'core',
211
+ usage: 'forja orchestrate:advance [--slug <slug>]',
212
+ examples: ['forja orchestrate:advance'],
213
+ next: ['orchestrate:status'],
214
+ },
215
+ 'gsd:plan': {
216
+ domain: 'gsd',
217
+ desc: 'Cria runbook GSD em .context/',
218
+ node: 'scripts/agent-harness.ts',
219
+ args: ['gsd:plan'],
220
+ },
221
+ 'gsd:handoff': {
222
+ domain: 'gsd',
223
+ desc: 'Registra handoff GSD padronizado (ADR-0005)',
224
+ node: 'scripts/agent-harness.ts',
225
+ args: ['gsd:handoff'],
226
+ },
227
+ 'gsd:check': {
228
+ domain: 'gsd',
229
+ desc: 'Valida gates básicos do runbook GSD',
230
+ node: 'scripts/agent-harness.ts',
231
+ args: ['gsd:check'],
145
232
  },
146
233
  'hermes:handoff': {
147
234
  domain: 'gsd',
@@ -206,7 +293,7 @@ export const COMMANDS = {
206
293
  },
207
294
  'drift:check': {
208
295
  domain: 'code',
209
- desc: 'Reindexa e sinaliza relações verified que a extração atual não reproduz mais (SPEC-030). --domain <d> restringe',
296
+ desc: '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',
210
297
  node: 'scripts/drift-check.ts',
211
298
  gates: ['workspace-warn'],
212
299
  },
@@ -291,9 +378,16 @@ export const COMMANDS = {
291
378
  },
292
379
  'engineer': {
293
380
  domain: 'code',
294
- desc: 'Façade: contexto + ADRs relevantes + architecture:check + risco + fluxo recomendado (SPEC-035)',
381
+ desc: 'Façade: contexto + ADRs relevantes + architecture:check + risco + fluxo recomendado',
295
382
  node: 'scripts/engineer.ts',
296
383
  gates: ['workspace-warn'],
384
+ spec: 'SPEC-035',
385
+ tier: 'core',
386
+ json: true,
387
+ usage: 'forja engineer "<objetivo>" [--ref <ref>] [--role <role>] [--json]',
388
+ cliArgs: [{ name: 'objetivo', required: true, desc: 'o que você quer fazer (entre aspas)' }],
389
+ examples: ['forja engineer "adicionar rate limit no login"', 'forja engineer "auth por token" --json'],
390
+ next: ['risk:assess'],
297
391
  },
298
392
  'agent:register': {
299
393
  domain: 'code',
@@ -367,9 +461,14 @@ export const COMMANDS = {
367
461
  },
368
462
  'simulate': {
369
463
  domain: 'code',
370
- desc: 'Testa+arquitetura+risco de um ref num worktree isolado, nunca promove (SPEC-038)',
464
+ desc: 'Testa+arquitetura+risco de um ref num worktree isolado, nunca promove',
371
465
  node: 'scripts/simulate.ts',
372
466
  gates: ['workspace-warn'],
467
+ spec: 'SPEC-038',
468
+ json: true,
469
+ usage: 'forja simulate <ref> [--command "npm test"] [--json]',
470
+ cliArgs: [{ name: 'ref', required: true, desc: 'git ref a simular' }],
471
+ examples: ['forja simulate HEAD', 'forja simulate HEAD --json'],
373
472
  },
374
473
  'provenance:record': {
375
474
  domain: 'code',
@@ -427,12 +526,22 @@ export const COMMANDS = {
427
526
  desc: 'Reindexa a memória universal (SQLite FTS5)',
428
527
  node: 'scripts/sync-universal-memory.ts',
429
528
  gates: ['workspace-warn'],
529
+ tier: 'core',
530
+ usage: 'forja sync:universal',
531
+ examples: ['forja sync:universal'],
532
+ next: ['query:universal'],
430
533
  },
431
534
  'query:universal': {
432
535
  domain: 'memoria',
433
536
  desc: 'Busca FTS5 na memória universal',
434
537
  node: 'scripts/query-universal-memory.ts',
435
538
  gates: ['workspace-warn'],
539
+ tier: 'core',
540
+ readonly: true,
541
+ usage: 'forja query:universal "<termo>"',
542
+ cliArgs: [{ name: 'termo', required: true, desc: 'consulta FTS5 (entre aspas)' }],
543
+ examples: ['forja query:universal "handoff 7 campos"'],
544
+ next: ['context:smart'],
436
545
  },
437
546
  'memory:compress': {
438
547
  domain: 'memoria',
@@ -462,9 +571,14 @@ export const COMMANDS = {
462
571
  // --- Contexto & token economy ---------------------------------------------
463
572
  'context:smart': {
464
573
  domain: 'contexto',
465
- desc: 'Gera smart-context (3 modos, ADR-0003)',
574
+ desc: 'Gera smart-context (3 modos: global | domain | task)',
466
575
  node: 'scripts/build-smart-context.ts',
467
576
  gates: ['workspace-warn'],
577
+ spec: 'ADR-0003',
578
+ tier: 'core',
579
+ usage: 'forja context:smart [--mode global|domain|task] [--domain <d>]',
580
+ examples: ['forja context:smart --mode task --domain pagamentos'],
581
+ next: ['context:budget'],
468
582
  },
469
583
  'context:budget': {
470
584
  domain: 'contexto',
@@ -503,8 +617,12 @@ export const COMMANDS = {
503
617
  },
504
618
  'token:economy': {
505
619
  domain: 'contexto',
506
- desc: 'Economia de token: eixos arquitetura + memória; --project mede seus domínios reais (ADR-0009/0027)',
620
+ desc: 'Economia de token: eixos arquitetura + memória; --project mede seus domínios reais',
507
621
  node: 'scripts/token-economy.ts',
622
+ spec: 'ADR-0009, ADR-0027',
623
+ json: true,
624
+ usage: 'forja token:economy [--project <path>] [--json]',
625
+ examples: ['forja token:economy', 'forja token:economy --json'],
508
626
  },
509
627
  'benchmark:context': {
510
628
  domain: 'contexto',
@@ -548,11 +666,22 @@ export const COMMANDS = {
548
666
  },
549
667
  'llm:run': {
550
668
  domain: 'llm',
551
- desc: 'Executa um perfil LLM e registra observação normalizada',
669
+ desc: 'Executa um perfil LLM e registra observação normalizada. --engineer "<objetivo>" monta o contexto pelo façade',
552
670
  node: 'scripts/llm-fit.ts',
553
671
  args: ['run'],
554
672
  gates: ['workspace'],
555
673
  },
674
+ 'llm:sessions': {
675
+ domain: 'llm',
676
+ desc: 'Lista/mostra sessões LLM registradas (o SESSION_ID de llm:run --resume) — somente leitura (SPEC-048)',
677
+ node: 'scripts/llm-fit.ts',
678
+ args: ['sessions'],
679
+ gates: ['workspace'],
680
+ readonly: true,
681
+ json: true,
682
+ usage: 'forja llm:sessions <list|show> [id] [--json]',
683
+ examples: ['forja llm:sessions list', 'forja llm:sessions show <id> --json'],
684
+ },
556
685
  'llm:eval': {
557
686
  domain: 'llm',
558
687
  desc: 'Avalia execuções LLM com métricas determinísticas',
@@ -562,20 +691,36 @@ export const COMMANDS = {
562
691
  },
563
692
  'cost:economy': {
564
693
  domain: 'llm',
565
- desc: 'Custo real acumulado (USD) das execuções LLM registradas, por modelo — tabela de preço local (SPEC-029)',
694
+ desc: 'Custo real acumulado (USD) das execuções LLM registradas, por modelo — tabela de preço local',
566
695
  node: 'scripts/cost-economy.ts',
567
696
  gates: ['workspace'],
697
+ spec: 'SPEC-029',
698
+ json: true,
699
+ usage: 'forja cost:economy [--json]',
700
+ examples: ['forja cost:economy', 'forja cost:economy --json'],
568
701
  },
569
702
  // --- Governança & qualidade ---------------------------------------------------
570
703
  'project:check': {
571
704
  domain: 'governanca',
572
705
  desc: 'Standards check do framework (pre-commit)',
573
706
  node: 'scripts/check-standards.ts',
707
+ tier: 'core',
708
+ readonly: true,
709
+ usage: 'forja project:check',
710
+ examples: ['forja project:check'],
711
+ next: ['check:all'],
574
712
  },
575
713
  'tools:doctor': {
576
714
  domain: 'governanca',
577
- desc: 'Raio-x do núcleo (gate, exit 1) + ferramentas de processo (ADR-0023, ADR-0018)',
715
+ desc: 'Raio-x do núcleo (gate, exit 1) + ferramentas de processo',
578
716
  node: 'scripts/tools-doctor.ts',
717
+ spec: 'ADR-0023, ADR-0018',
718
+ tier: 'core',
719
+ readonly: true,
720
+ json: true,
721
+ usage: 'forja tools:doctor [--json]',
722
+ examples: ['forja tools:doctor', 'forja tools:doctor --json'],
723
+ next: ['setup'],
579
724
  },
580
725
  'demo:autonomy': {
581
726
  domain: 'governanca',
@@ -594,8 +739,12 @@ export const COMMANDS = {
594
739
  },
595
740
  'project:smoke': {
596
741
  domain: 'governanca',
597
- desc: 'Gate do projeto gerado: gera isolado e prova que é coerente (SPEC-015). --full instala e builda o backend',
742
+ desc: 'Gate do projeto gerado: gera isolado e prova que é coerente. --full instala e builda o backend; --ai <lista> valida as instruções nativas',
598
743
  node: 'scripts/project-smoke.ts',
744
+ spec: 'SPEC-015, SPEC-047',
745
+ readonly: true,
746
+ usage: 'forja project:smoke [--full] [--ai claude,copilot,gemini,codex]',
747
+ examples: ['forja project:smoke', 'forja project:smoke --ai claude,copilot'],
599
748
  },
600
749
  'check:all': {
601
750
  domain: 'governanca',