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
@@ -0,0 +1,153 @@
1
+ # Tasks: contrato-saida-cli
2
+
3
+ - **Spec**: ./spec.md
4
+ - **Plan**: ./plan.md
5
+ - **Status**: approved
6
+ - **Criado em**: 2026-09-08
7
+
8
+ > Decomposição executável. Cada task tem dono, critério de done e paths.
9
+
10
+ Grafo de dependência:
11
+
12
+ ```
13
+ T1 ─┐
14
+ T2 ─┤
15
+ T3 ─┼─ T5 ─┬─ T4 ─┬─ T7 ─┐
16
+ └─ T6 ─┘ │ │
17
+ T8 ─────────────────────► T9
18
+ todas ─────────────────► T9
19
+ ```
20
+
21
+ Paralelizável no início: **T1 · T2 · T3 · T8**.
22
+
23
+ ---
24
+
25
+ ## T1 — ADR-0082
26
+ - **Owner**: SDD Architect · **Est**: P · **Depende de**: —
27
+ - **Paths**: `memory/90-decisions/0082-contrato-saida-cli.md`
28
+ - **Escopo**: registrar o contrato — chave `status` (`ok`|`error`|`rejected`), tabela de exit
29
+ codes (0/1/2/127), regra "stdout = um objeto JSON, diagnóstico no stderr", natureza **aditiva e
30
+ incremental** (só rege quem opta por `json: true`). Documentar as duas quebras: `token:economy
31
+ --json` (array → objeto) e `simulate` discard (exit 1 → 2). Status `accepted`.
32
+ - **Done**:
33
+ - [ ] ADR existe; `forja tools:doctor` → `adr-refs` verde (78 ADRs)
34
+
35
+ ## T2 — `docs/contrato-saida-cli.md` + DOC-MAP
36
+ - **Owner**: SDD Architect · **Est**: P · **Depende de**: —
37
+ - **Paths**: `docs/contrato-saida-cli.md` (novo), `DOC-MAP.md`, `docs/llm-fit-loop.md`
38
+ - **Escopo**: o contrato para quem escreve script e para quem consome, com exemplos de cada
39
+ `status` e do exit code. Linha no `DOC-MAP.md` (tabela por tópico). Nota em `llm-fit-loop.md`
40
+ apontando o doc novo (o contrato de `llm:run` é o caso de referência).
41
+ - **Done**:
42
+ - [ ] `forja tools:doctor` → `docs-links`, `docs-commands`, `commands-documented` verdes
43
+
44
+ ## T3 — `lib/cli-output.ts`
45
+ - **Owner**: Worker · **Est**: P · **Depende de**: —
46
+ - **Paths**: `lib/cli-output.ts` (novo), `test/cli-output.test.js` (novo)
47
+ - **Escopo**: `emitOk(fields?)`, `emitError(message, { code?, detail? })`, `emitRejected(fields?)`
48
+ (contrato no plan §4). Cada uma: `console.log(JSON.stringify({ status, ...fields }))` no stdout,
49
+ `detail` (se houver) no stderr, `process.exit(0|1|2)`. Sem cor, sem prompt.
50
+ - **Done**:
51
+ - [ ] testes unitários: cada função → objeto com `status` correto, exit code correto, stdout com
52
+ exatamente uma linha JSON
53
+ - [ ] `tsc --noEmit` verde
54
+
55
+ ## T4 — Registry: `json: true` no conjunto + `--json` no help
56
+ - **Owner**: Worker · **Est**: P · **Depende de**: T5, T6
57
+ - **Paths**: `lib/core/registry.ts`
58
+ - **Escopo**: `json: true` em `status`, `next`, `spec:check`, `tools:doctor`, `engineer`,
59
+ `simulate`, `cost:economy`, `token:economy`. Garantir que `usage` ou um `example` de cada um
60
+ cita `--json`.
61
+ - **Done**:
62
+ - [ ] `forja help spec:check` (e os demais) mostram `--json`
63
+ - [ ] `test/forja-core.test.js` verde
64
+
65
+ ## T5 — Conformar os que já têm `--json`
66
+ - **Owner**: Worker · **Est**: M · **Depende de**: T3
67
+ - **Paths**: `scripts/forja-status.ts`, `scripts/engineer.ts`, `scripts/simulate.ts`,
68
+ `scripts/cost-economy.ts`, `scripts/token-economy.ts`
69
+ - **Escopo**:
70
+ - `forja-status.ts` — trocar os `console.log(JSON.stringify(...))` por `emitOk` (forma já OK).
71
+ - `engineer.ts` — `--json` → `emitOk({ ...report })`; erro de arg → `emitError`.
72
+ - `simulate.ts` — caminho normal → `emitOk`; **recommendation `discard` → `emitRejected` (exit
73
+ 2)**; erro de arg → `emitError`.
74
+ - `cost-economy.ts` — mover os `console.log` de aviso para **stderr**; `--json` → `emitOk`.
75
+ - `token-economy.ts` — `--json` **deixa de emitir array cru** → `emitOk({ rows: [...] })`.
76
+ - Nenhuma mudança na saída **sem** `--json`.
77
+ - **Done**:
78
+ - [ ] cada um, com `--json`, emite um objeto com `status`
79
+ - [ ] `simulate` com ref cujo teste falha → exit 2, `status:"rejected"`
80
+ - [ ] snapshot da saída default (sem `--json`) inalterada
81
+
82
+ ## T6 — Adicionar `--json` a `spec:check` e `tools:doctor`
83
+ - **Owner**: Worker · **Est**: M · **Depende de**: T3
84
+ - **Paths**: `scripts/spec-cli.ts`, `scripts/tools-doctor.ts`
85
+ - **Escopo**:
86
+ - `spec-cli.ts` (`check`) — `--json` → `emitOk({ features: [{ slug, spec, plan, tasks }] })`;
87
+ sem `--json`, saída atual.
88
+ - `tools-doctor.ts` — `--json` → `emitOk`/`emitError({ core: [...], tools: [...] })` a partir do
89
+ que `runChecks` já devolve (id, status, detail, fix, bucket) + a detecção de ferramentas;
90
+ falha crítica do núcleo → `status:"error"` + exit 1 (preserva o gate); sem `--json`, os 3
91
+ blocos de texto de hoje. **Não** tocar `runChecks`/`worstStatus`.
92
+ - **Done**:
93
+ - [ ] `forja spec:check --json` e `forja tools:doctor --json` emitem objeto com `status`
94
+ - [ ] `forja tools:doctor` (texto) inalterado; exit-code do gate preservado (núcleo quebrado → 1)
95
+
96
+ ## T7 — `test/cli-output-contract.test.js`
97
+ - **Owner**: Worker · **Est**: M · **Depende de**: T4, T5, T6
98
+ - **Paths**: `test/cli-output-contract.test.js` (novo)
99
+ - **Escopo**: para cada comando `json: true` no registry, num `FORJA_WORKSPACE` temporário com
100
+ fixtures mínimas: (a) roda com `--json` + args válidos → stdout é **um** JSON parseável, objeto,
101
+ `status ∈ {ok, error, rejected}`; (b) exit code casa com `status` (ok→0, error→1, rejected→2);
102
+ (c) com args inválidos → `status:"error"` + exit 1. Itera o registry, não uma lista hardcoded.
103
+ - **Done**:
104
+ - [ ] `node --test test/cli-output-contract.test.js` verde
105
+ - [ ] remover `json:true` de um comando não-conforme faria o teste apontá-lo (checagem manual)
106
+
107
+ ## T8 — Tabela de exit codes em `bin/forja.ts`
108
+ - **Owner**: Worker · **Est**: P · **Depende de**: —
109
+ - **Paths**: `bin/forja.ts`
110
+ - **Escopo**: bloco de comentário com a tabela (0/1/2/127) junto ao dispatch e à auditoria.
111
+ Confirmar que exit 2 do filho passa direto (`result.status ?? 1` já faz). **Sem** mudança de
112
+ comportamento.
113
+ - **Done**:
114
+ - [ ] comentário presente; `test/forja-core.test.js` verde; `simulate` discard → `forja
115
+ simulate` sai 2
116
+
117
+ ## T9 — CHANGELOG + validação final + fecho
118
+ - **Owner**: Worker → Governance · **Est**: P · **Depende de**: T1–T8
119
+ - **Paths**: `CHANGELOG.md`, `specs/contrato-saida-cli/spec.md`
120
+ - **Escopo**: `[Unreleased]` — Adicionado (contrato, `--json` em `spec:check`/`tools:doctor`,
121
+ `lib/cli-output.ts`); **Alterado (breaking, só `--json`)**: `token:economy` array→objeto,
122
+ `simulate` discard exit 1→2. Atualizar `spec.md` §Evidências. Mover status. Handoff `review`.
123
+ - **Done**:
124
+ - [ ] `tsc --noEmit`, `node --test test/*.test.js`, `forja spec:check`, `forja project:check` verdes — AC-9
125
+ - [ ] `spec:set-status contrato-saida-cli spec implementing` no início; handoff `worker →
126
+ governance (review)` registrado ao fim
127
+
128
+ ---
129
+
130
+ ## Mapa AC → task
131
+
132
+ | AC | Tasks | Verificação-chave |
133
+ |---|---|---|
134
+ | AC-1 | T1 | ADR-0082, `adr-refs` verde |
135
+ | AC-2 | T2 | doc + DOC-MAP; `docs-*` verdes |
136
+ | AC-3 | T3 | `lib/cli-output.ts` + testes das 3 funções |
137
+ | AC-4 | T8 | comentário da tabela em `bin/forja.ts` |
138
+ | AC-5 | T4, T5, T6 | registry `json:true` no conjunto |
139
+ | AC-6 | T7 | `test/cli-output-contract.test.js` |
140
+ | AC-7 | T5, T6 | `token:economy --json`→objeto; `simulate` discard→exit 2; default inalterada |
141
+ | AC-8 | T4 | `--json` no `usage`/`examples` dos `json:true` |
142
+ | AC-9 | T9 | bateria completa verde |
143
+
144
+ ## Handoffs entre agentes
145
+
146
+ SDD Architect (spec+plan+tasks + ADR-0082 na T1) → **Worker** (T3–T8) → **Governance** (T9 +
147
+ `project:check`). Registrar via Hermes no início da implementação.
148
+
149
+ ## Evidências e estado real
150
+
151
+ - Nada executado — caixas `[ ]` abertas.
152
+ - **Dependência viva**: `feat/forja-status` (PR #62) e, por baixo, `feat/cli-intuitiva-v1` (#61).
153
+ - **Quebras deliberadas** (ADR-0082 + CHANGELOG): `token:economy --json`, `simulate` discard exit.
@@ -1,7 +1,7 @@
1
1
  # Spec: Drift Sentinel — verificação contínua de que o verificado continua verdade
2
2
 
3
3
  - **ID**: SPEC-030
4
- - **Status**: implementing
4
+ - **Status**: done
5
5
  - **Owner**: apk
6
6
  - **Criado em**: 2026-08-31
7
7
  - **Sprint alvo**: <a definir>
@@ -12,10 +12,11 @@
12
12
  `runGates`/`CHECKS` para rodar `drift:check` in-process, o gate opt-in chama o comando real via
13
13
  subprocess (mesmo padrão de `lib/core/release.ts`/`project-smoke.ts`) e traduz o resultado —
14
14
  mantém `check:all` desacoplado do wiring do grafo (SQLite/git) sem tocar o contrato do runner de
15
- checks. Não marcado `done` porque a métrica de sucesso do §8 (drift genuíno encontrado em projeto
16
- real, confirmado por humano, 30 dias após o release) ainda não foi observada — só dogfooding
17
- local contra o próprio monorepo, que não achou drift real algum ainda.
18
- - **ADRs relacionadas**: nenhuma ainda — nasce da auditoria de segurança de 2026-08-31, que corrigiu
15
+ checks. **Fechado em 2026-09-08 por ADR-0084**: a métrica original do §8 (drift real encontrado
16
+ no mundo, confirmado por humano) é infalsificável como bloqueio de `done`; foi reformulada para
17
+ um aceite observável e "drift real no mundo" virou janela de observação até 2026-10-08.
18
+ Adicionado `drift:check --all` (lote por projeto do workspace, §3). Status → `done`.
19
+ - **ADRs relacionadas**: **ADR-0084** (fecho da spec). Nasce da auditoria de segurança de 2026-08-31, que corrigiu
19
20
  `packages/graph` para que `status: 'verified'` só venha de fontes de evidência confiáveis
20
21
  (`deterministic-extractor`, `sandbox.*`). Este spec é a continuação natural: **verified é um
21
22
  instantâneo, não uma garantia permanente.**
@@ -112,6 +113,14 @@ que já foi verdade e hoje não é mais, sem que nada tenha formalmente revogado
112
113
 
113
114
  ## 8. Métricas de sucesso
114
115
 
115
- 30 dias após o release: rodar `drift:check` num projeto real e ativo (não um fixture) resulta em pelo
116
- menos um drift genuíno encontrado que um humano confirma como real (não falso positivo) — provando que
117
- o sinal vale o custo de rodar.
116
+ **Reformulada por ADR-0084** (a original era infalsificável como bloqueio de `done` — dependia de
117
+ drift *acontecer* no mundo num intervalo dado).
118
+
119
+ **Aceite (verificável agora)**:
120
+ - `drift:check` é determinístico: duas rodadas sobre o mesmo input dão o mesmo resultado.
121
+ - Contra o monorepo, reporta **zero** drift — nenhum falso positivo.
122
+ - `drift:check --all` completa sobre o workspace (0 projetos → saída limpa; N → semeia cada grafo).
123
+
124
+ **Janela de observação (não bloqueia `done`)** — até **2026-10-08**: se nenhum drift real for
125
+ confirmado **e** um falso positivo **for** reportado, rebaixar `drift:check` a ferramenta manual
126
+ (tirar do `check:all --with-drift`). Na ausência dessa combinação, mantém-se como está.
@@ -0,0 +1,149 @@
1
+ # Plan: forja-status-caminho-feliz
2
+
3
+ - **Spec**: ./spec.md
4
+ - **Status**: approved
5
+ - **Criado em**: 2026-09-07
6
+
7
+ > Como vamos construir o que a spec define. Sem código aqui — só estrutura e decisões.
8
+
9
+ ## 1. Abordagem técnica
10
+
11
+ **Compor, não coletar de novo.** Um módulo puro `lib/status-model.ts` monta um `StatusModel`
12
+ (workspace, sprint, orchestrate, specs, recentRuns, handoffs) chamando helpers que já existem ou
13
+ que extraímos de onde já vivem — nada de re-parsear. `scripts/forja-status.ts` é o único script
14
+ novo e serve os dois comandos (`args: ['status']` / `args: ['next']`): `status` renderiza o
15
+ model (texto ou `--json`); `next` roda `recommendNext(model)` — a escada de prioridade da AC-4,
16
+ uma função pura. Cada coletor é `try/catch` → `{ available: false, reason }`; o comando nunca
17
+ lança. Somente leitura, sem gate bloqueante.
18
+
19
+ ## 2. Módulos afetados
20
+
21
+ | Caminho | Mudança | Risco |
22
+ |---|---|---|
23
+ | `scripts/forja-status.ts` | **criar** — dispatch `status`/`next`; flags `--json`; render de texto; sai 0 sempre que o model montou | B |
24
+ | `lib/status-model.ts` | **criar** — `collectStatus(root, opts): StatusModel` + `recommendNext(model): { action, command, reason }` (puro) | M |
25
+ | `lib/specs-index.ts` | **criar** — `listSpecs(root): {slug,status}[]`, movido de `scripts/hook-session-start.ts` | B |
26
+ | `lib/sprint-index.ts` | **criar** — `readSprint(root): {active, title, items} \| null`, lendo `memory/40-delivery/current-sprint.md` (espelha `showStatus` de `sprint-manager.ts`, sem reusá-lo: aquele só imprime) | B |
27
+ | `lib/handoffs-index.ts` | **criar** — `openHandoffs(): Row[]`, movido de `scripts/hook-session-start.ts` (query SQLite readonly, `try/catch`→`[]`) | B |
28
+ | `lib/orchestrate.ts` | editar — `export function listRuns(root, env?): string[]` (glob `.context/orchestrate-*.json` → slugs); `loadState` já é exportado | B |
29
+ | `scripts/hook-session-start.ts` | editar — importar `listSpecs`/`openHandoffs` dos novos `lib/` em vez das cópias locais | B |
30
+ | `lib/core/registry.ts` | editar — entradas `status` e `next` (`tier:'core'`, `readonly:true`, `usage`/`examples`/`next`, `json:true`); mover os 3 `orchestrate*` para o topo do bloco `gsd` (ordem do objeto = ordem no `forja help`) | B |
31
+ | `README.md` | editar — uma linha: `orchestrate` como caminho padrão | B |
32
+ | `test/forja-status.test.js` | **criar** — AC-8 | B |
33
+ | `test/hook-session-start*.test.js` | editar se existir — garantir que a extração não regrediu | B |
34
+
35
+ ## 3. Diagrama de fluxo
36
+
37
+ ```
38
+ forja status [--json] forja next [--json]
39
+ │ │
40
+ └── collectStatus(root) └── collectStatus(root)
41
+ ├─ workspace ← getWorkspaceInfo() │
42
+ ├─ sprint ← lib/sprint-index └── recommendNext(model) (função pura, AC-4)
43
+ ├─ orchestrate← lib/orchestrate: listRuns→loadState 1 workspace ausente → forja setup
44
+ ├─ specs ← lib/specs-index 2 memória crua → forja sync:universal
45
+ ├─ recentRuns ← tail(.context/forja-runs.jsonl) 3 corrida gate vermelho → (parecer) + orchestrate:advance
46
+ └─ handoffs ← lib/handoffs-index (SQLite ro) 4 corrida etapa pronta → forja orchestrate:advance
47
+ │ 5 spec approved s/ plan → forja spec:plan <slug>
48
+ ├─ --json → { status:"ok", workspace, sprint, ... } plan approved s/ tasks → forja spec:tasks <slug>
49
+ │ subsistema em erro → { available:false, reason } 6 spec implementing → forja spec:check <slug>
50
+ └─ texto → seções rotuladas; seção em erro → "indisponível: …" 7 nada pendente → orchestrate "<obj>" --slug / spec:new
51
+ ```
52
+
53
+ `collectStatus` é chamado uma vez por invocação; `status` e `next` compartilham o mesmo model.
54
+
55
+ ## 4. Contratos (API/CLI/Schema)
56
+
57
+ ```ts
58
+ // lib/status-model.ts
59
+ interface Sub<T> { available: true; value: T } // ou { available: false; reason: string }
60
+ interface StatusModel {
61
+ workspace: { root: string; source: string; exists: boolean };
62
+ sprint: Sub<{ active: boolean; title: string | null; items: number }>;
63
+ orchestrate: Sub<{ runs: { slug: string; goal: string; openStage: string | null;
64
+ lastVerdict: string | null; concluded: boolean }[] }>;
65
+ specs: Sub<{ slug: string; status: string }[]>;
66
+ recentRuns: Sub<{ cmd: string; exitCode: number; ts: string }[]>; // até 5
67
+ handoffs: Sub<{ id: number; from: string; to: string; intent: string; slug: string }[]>;
68
+ }
69
+ interface NextAction { action: string; command: string; reason: string }
70
+
71
+ export function collectStatus(root: string, opts?: { runsLimit?: number }): StatusModel;
72
+ export function recommendNext(model: StatusModel): NextAction;
73
+ ```
74
+
75
+ - `forja status` / `forja next`: exit **0** sempre que o model montou (subsistema em erro não é
76
+ falha do comando). Exit 1 só se o próprio processo não conseguir escrever a saída.
77
+ - `forja status --json`: objeto com as 6 chaves + `status: "ok"`.
78
+ - `forja next --json`: `{ action, command, reason }`.
79
+ - Sem `--json`: texto legível; nunca stack trace.
80
+
81
+ ## 5. Decisões e alternativas
82
+
83
+ **D1 — Um script, dois comandos, model compartilhado.** `scripts/forja-status.ts` cobre `status`
84
+ e `next` via `args`. Rejeitado: dois scripts (duplica bootstrap + coleta); pôr a lógica no
85
+ `bin/forja.ts` (o core não deve crescer com lógica de domínio).
86
+
87
+ **D2 — Extrair `listSpecs`/`openHandoffs` do hook para `lib/`, o hook reimporta.** É o reuso que
88
+ a AC-7 exige e remove a cópia que já existia solta no hook. Rejeitado: `forja status` spawnar o
89
+ hook (o hook devolve JSON de `hookSpecificOutput`, não um model) ou duplicar a leitura.
90
+
91
+ **D3 — Estado da corrida via `loadState` + novo `listRuns`, não `orchestrate:status --json`.**
92
+ `lib/orchestrate.ts` já exporta `loadState(root, slug)`. Falta só descobrir os slugs — `listRuns`
93
+ faz glob de `.context/orchestrate-*.json`. Rejeitado: adicionar `--json` a `orchestrate` (mais
94
+ superfície pública para manter; fora do escopo da spec).
95
+
96
+ **D4 — `sprint-index` novo, não reusar `sprint-manager.ts`.** `showStatus` daquele script só
97
+ imprime; extrair exigiria refatorá-lo. `readSprint` lê o mesmo arquivo
98
+ (`memory/40-delivery/current-sprint.md`) e devolve dado. Se `sprint-manager` for tocado depois,
99
+ consolidar então.
100
+
101
+ **D5 — `--json` destes 2 comandos segue as convenções que W5 vai formalizar** (`status: "ok"`,
102
+ sem exit code novo). Não bloqueia em W5; quando W5 entrar, `json: true` no registry já está posto.
103
+
104
+ Nenhuma decisão é estrutural/irreversível → **sem ADR** (consistente com a spec).
105
+
106
+ ## 6. Dependências
107
+
108
+ - **Spec `cli-intuitiva-v1` (SPEC-043, PR #61)** — branch empilhada. Usa `forja setup` (AC-4
109
+ passo 1) e os campos `tier`/`next`/`readonly`/`json` do registry. Se #61 renomear algo, ajustar.
110
+ - **Pacotes npm**: nenhum novo. SQLite via `better-sqlite3` já presente.
111
+ - **Migrações**: nenhuma.
112
+
113
+ ## 7. Rollout
114
+
115
+ - [ ] Feature flag: não. Comandos novos, aditivos.
116
+ - [ ] Migração de dados: não.
117
+ - [ ] Doc/persona: `README.md` (linha do caminho padrão), `docs/cli-first-operacao.md` (bloco
118
+ "Descoberta pela própria CLI" ganha `forja status`/`forja next`), `docs/quick-reference.md`.
119
+ - [ ] `CHANGELOG.md`: `[Unreleased]` → Adicionado (`forja status`, `forja next`); Alterado
120
+ (`orchestrate` no topo do bloco GSD do help).
121
+
122
+ ## 8. Sinais de fracasso (kill criteria)
123
+
124
+ - A escada da AC-4 não converge para uma recomendação clara em estados reais do dogfooding (dois
125
+ passos empatam, ou o passo 7 dispara com trabalho pendente) → simplificar para 3 níveis
126
+ (bootstrap / corrida / specs) e aceitar "veja `forja status`" como fallback.
127
+ - Extrair `listSpecs`/`openHandoffs` do hook faz o SessionStart regredir (ordem de import,
128
+ ciclo entre `lib/` e `scripts/`) → manter as cópias no hook e só **reusá-las** a partir de
129
+ `lib/` no comando novo (duplicação tolerada, teste cobre as duas).
130
+ - `listRuns` por glob de `.context/` traz lixo (runs de projetos gerados misturados) → restringir
131
+ ao `contextDir` do workspace resolvido e ignorar o resto.
132
+
133
+ ## Evidências e estado real
134
+
135
+ | AC | Task | Verificação |
136
+ |---|---|---|
137
+ | AC-1 | T4 | `forja status` num workspace real mostra as 6 seções rotuladas |
138
+ | AC-2 | T4, T7 | `forja status --json` num WS vazio → 6 chaves + `status:"ok"`, subs `available:false` |
139
+ | AC-3 | T5 | `forja next` imprime 1 linha `→ forja …`; `--json` → `{action,command,reason}` |
140
+ | AC-4 | T3, T7 | testes de `recommendNext` cobrindo os 7 ramos |
141
+ | AC-5 | T6 | registry: `readonly:true`, sem gate `workspace`; `forja next` não altera estado |
142
+ | AC-6 | T6 | `forja help` mostra `status`/`next` no núcleo; `orchestrate` no topo do bloco GSD |
143
+ | AC-7 | T1, T2 | `hook-session-start` importa de `lib/specs-index` e `lib/handoffs-index`; teste do hook verde |
144
+ | AC-8 | T7 | `node --test test/forja-status.test.js` |
145
+ | AC-9 | T8 | bateria completa verde |
146
+
147
+ - **Hipótese, não medição**: os ganhos de §8 da spec dependem de instrumentação inexistente.
148
+ - **Contrato**: nenhuma mudança em comando existente. Se a lista/ordem do núcleo mudar entre plan
149
+ e implementação, registrar aqui.
@@ -0,0 +1,158 @@
1
+ # Spec: forja-status-caminho-feliz — "onde estou e o que faço agora?"
2
+
3
+ - **ID**: SPEC-044
4
+ - **Status**: done
5
+ - **Owner**: apk
6
+ - **Criado em**: 2026-09-07
7
+ - **Sprint alvo**: <a definir>
8
+ - **ADRs relacionadas**: nenhuma — comandos novos, somente leitura, aditivos ao registry (ADR-0020).
9
+ - **Origem**: `docs/roadmap-v4.1.md`, Onda 2 (W4).
10
+ - **Depende de**: `cli-intuitiva-v1` (SPEC-043, PR #61) — reusa `tier`/`next`/`readonly` do registry
11
+ e o comando `forja setup`. Branch empilhada sobre `feat/cli-intuitiva-v1`.
12
+
13
+ ## 1. Problema
14
+
15
+ Não existe um comando que responda **"onde estou e o que faço agora?"**. O estado do trabalho
16
+ está espalhado por cinco lugares que o operador (humano ou agente LLM) precisa consultar e cruzar
17
+ de cabeça:
18
+
19
+ - `sprint:status` — sprint atual
20
+ - `orchestrate:status` — etapa aberta / gate travado, mas só se você souber o `--slug`
21
+ - `spec:check` — specs e seus estados
22
+ - `forja-runs.jsonl` — o que foi executado por último
23
+ - tabela `handoffs` no `universal.db` — passagens em aberto
24
+
25
+ `orchestrate` é o caminho feliz (a cadeia SDD/GSD como máquina de estados guardada por gates,
26
+ SPEC-021), mas nada aponta proativamente "a etapa está verde, rode `orchestrate:advance`" ou
27
+ "o gate travou aqui". O hook SessionStart já dá um retrato parcial, mas (a) só roda no início da
28
+ sessão do Claude Code, (b) não existe como comando, (c) não diz a **próxima ação**.
29
+
30
+ **Como medimos hoje**: não há instrumentação. Evidência qualitativa: um agente que entra sem
31
+ contexto roda 4–5 comandos de orientação antes de agir.
32
+
33
+ ## 2. Proposta de valor
34
+
35
+ `forja status` — um retrato único do estado (workspace, sprint, corrida orchestrate aberta +
36
+ etapa/gate, specs por status, últimos runs, handoffs). `forja next` — **uma linha**: a próxima
37
+ ação recomendada e o comando exato para executá-la. Um operador sem contexto prévio sabe o que
38
+ fazer com um comando.
39
+
40
+ ## 3. User stories
41
+
42
+ - **Como** agente LLM começando uma sessão, **quero** `forja next` com a próxima ação + comando,
43
+ **para que** eu não reconstrua o estado com cinco comandos.
44
+ - **Como** dev voltando a um projeto depois de dias, **quero** `forja status` com sprint + specs +
45
+ corrida aberta num lugar só, **para que** eu retome contexto rápido.
46
+ - **Como** orchestrator, **quero** que `forja next` aponte `orchestrate:advance` quando há etapa
47
+ verde esperando, ou mostre o gate travado quando vermelho.
48
+ - **Como** consumidor de automação, **quero** `forja status --json` estável, **para que** um
49
+ script decida o próximo passo.
50
+
51
+ ## 4. Critérios de aceite (Definition of Done)
52
+
53
+ - [ ] **AC-1**: `forja status` imprime, em seções rotuladas: (a) **workspace** (path, origem,
54
+ existe?); (b) **sprint** atual ou "sem sprint"; (c) **corrida** orchestrate aberta — slug,
55
+ etapa aberta, último veredito de gate — ou "nenhuma corrida aberta"; (d) **specs** agrupadas
56
+ por status; (e) **últimos runs** (até 5 linhas de `forja-runs.jsonl`: cmd, exitCode,
57
+ quando); (f) **handoffs** abertos (se a memória estiver de pé). Cada seção degrada com
58
+ `indisponível: <motivo>` em vez de quebrar.
59
+ - [ ] **AC-2**: `forja status --json` emite objeto com chaves estáveis (`workspace`, `sprint`,
60
+ `orchestrate`, `specs`, `recentRuns`, `handoffs`) e `status: "ok"`; nunca lança — erro de
61
+ subsistema vira `{ available: false, reason }` naquela chave.
62
+ - [ ] **AC-3**: `forja next` imprime **uma** recomendação: rótulo curto + comando exato numa linha
63
+ `→ forja <cmd> …`. `forja next --json` → `{ action, command, reason }`.
64
+ - [ ] **AC-4**: prioridade determinística do `forja next`:
65
+ 1. workspace ausente → `forja setup`
66
+ 2. memória não indexada → `forja sync:universal`
67
+ 3. corrida aberta com gate **vermelho** → mostra o parecer + `forja orchestrate:advance` (após corrigir)
68
+ 4. corrida aberta com etapa **pronta** → `forja orchestrate:advance`
69
+ 5. spec em `approved` sem `plan.md` → `forja spec:plan <slug>`; plan `approved` sem `tasks.md` → `forja spec:tasks <slug>`
70
+ 6. spec em `implementing` → aponta a spec + `forja spec:check <slug>`
71
+ 7. nada pendente → `forja orchestrate "<objetivo>" --slug <slug>` ou `forja spec:new <slug>`
72
+ - [ ] **AC-5**: ambos são `readonly: true`, sem gate bloqueante de workspace (`workspace-warn` no
73
+ máximo), e não escrevem nada além da linha de auditoria padrão.
74
+ - [ ] **AC-6**: `status` e `next` entram no registry com `tier: 'core'`, `usage`, `examples`,
75
+ `next`; `orchestrate` sobe para o topo do bloco GSD no `forja help` e ganha uma linha no
76
+ `README.md` como caminho padrão.
77
+ - [ ] **AC-7**: reuso — `forja status` **não** reimplementa parsing de sprint/orchestrate/specs.
78
+ `listSpecs` (hoje embutido em `scripts/hook-session-start.ts`) é extraído para `lib/` e
79
+ compartilhado pelo hook e pelo novo comando. O estado da corrida vem de um export de
80
+ `scripts/orchestrate.ts` (ou de `orchestrate:status --json`, criado se não existir), nunca
81
+ de parsear o arquivo cru de `.context/`.
82
+ - [ ] **AC-8**: testes — `forja status --json` num workspace temporário vazio → todas as chaves,
83
+ subsistemas `available:false` com `reason`, exit 0; `forja next --json` no mesmo →
84
+ `{ action: "setup" | "sync", … }`; com fixture de spec `approved` sem plan → `forja next`
85
+ aponta `spec:plan <slug>`.
86
+ - [ ] **AC-9**: `tsc --noEmit`, `node --test test/*.test.js`, `forja spec:check`,
87
+ `forja project:check` verdes.
88
+
89
+ ## 5. Escopo
90
+
91
+ **Dentro**:
92
+ - `scripts/forja-status.ts` (novo) — implementa `status` e `next` (subcomando por `args`).
93
+ - `lib/specs-index.ts` (novo) — `listSpecs()` extraído do hook; hook passa a importar de lá.
94
+ - Export legível de estado da corrida em `scripts/orchestrate.ts` **ou** `orchestrate:status --json`.
95
+ - Entradas `status` e `next` no registry; reordenação de `orchestrate` no bloco GSD.
96
+ - Uma linha no `README.md`; testes.
97
+
98
+ **Fora** (evita scope creep):
99
+ - `forja status --watch` / TUI — só snapshot.
100
+ - Contrato `--json` + exit codes global — Onda 2 (W5), spec própria. Aqui só o objeto destes 2 comandos.
101
+ - Dashboard / painel HTML.
102
+ - Qualquer mudança em `orchestrate` além de posição na listagem e um modo `--json` se necessário.
103
+ - Qualquer escrita de estado.
104
+
105
+ ## 6. NFRs / restrições
106
+
107
+ - **Performance**: `forja status` e `forja next` < 300 ms (leitura de arquivos + 1–2 queries
108
+ SQLite pequenas).
109
+ - **Compatibilidade**: nenhum comando existente muda de assinatura, saída ou exit code.
110
+ `orchestrate` só muda de posição no `forja help`.
111
+ - **Segurança**: somente leitura; degrada com `indisponível: <motivo>`, nunca stack trace.
112
+ - **Observabilidade**: auditado em `forja-runs.jsonl` como qualquer comando.
113
+
114
+ ## 7. Riscos e mitigação
115
+
116
+ | Risco | Probabilidade | Impacto | Mitigação |
117
+ |---|---|---|---|
118
+ | Reconstruir estado do orchestrate lendo o arquivo interno de `.context/` acopla a formato privado | M | M | Consumir via export de `orchestrate.ts` ou `orchestrate:status --json`; não parsear cru (AC-7) |
119
+ | `forja next` recomenda ação errada em estado ambíguo | M | M | Ordem de prioridade fixa e testada (AC-4/AC-8); `forja status` sempre disponível para o humano decidir |
120
+ | Extrair `listSpecs` do hook quebra o SessionStart | B | A | Mover + reimportar; teste do hook cobre; `hook-session-start` roda no CI |
121
+ | `forja next` com nenhuma pendência vira ruído ("crie uma spec") | B | B | Passo 7 só sugere, com verbo claro de que não há nada pendente |
122
+
123
+ ## 8. Métricas de sucesso
124
+
125
+ Avaliar 30 dias após o release, baseline sobre `forja-runs.jsonl` antes:
126
+
127
+ - Adoção: `forja next` / `forja status` aparecem em `forja-runs.jsonl` como comandos usados por agentes.
128
+ - Queda na sequência de comandos de orientação (`sprint:status` + `orchestrate:status` + `spec:check`
129
+ rodados em < 2 min no início de uma sessão) — proxy de "reconstruí o estado na mão".
130
+ - Zero regressões no hook SessionStart atribuídas à extração de `listSpecs`.
131
+
132
+ ## Evidências e estado real
133
+
134
+ **Implementado em 2026-09-08** na branch `feat/forja-status` (empilhada sobre `feat/cli-intuitiva-v1`).
135
+ Bateria: `tsc --noEmit` limpo; `node --test test/*.test.js` **492/492** (+13 em
136
+ `test/forja-status.test.js`); `forja spec:check` e `forja project:check` (100%) verdes.
137
+
138
+ | AC | Onde | Verificado |
139
+ |---|---|---|
140
+ | AC-1 | `scripts/forja-status.ts` `renderStatus()` | `forja status` mostra as 6 seções rotuladas; seção sem fonte → `indisponível: <reason>` |
141
+ | AC-2 | `lib/status-model.ts` `collectStatus()` + `--json` | `forja status --json` → `{ status:"ok", workspace, sprint, orchestrate, specs, recentRuns, handoffs }`; coletor em erro → `{available:false,reason}`; nunca lança (teste) |
142
+ | AC-3 | `scripts/forja-status.ts` (ramo `next`) | `forja next` → `→ forja <cmd>` + motivo; `--json` → `{action,command,reason}` |
143
+ | AC-4 | `lib/status-model.ts` `recommendNext()` | 7 ramos + ordem, testados em `test/forja-status.test.js` (pura, sem spawn) |
144
+ | AC-5 | `lib/core/registry.ts` | `status`/`next`: `readonly:true`, `json:true`, gate `workspace-warn` (não bloqueante) |
145
+ | AC-6 | `lib/core/registry.ts`, `README.md` | `forja help` lista `status`/`next` no núcleo; `status`→`next`→`orchestrate*` abrem o bloco GSD; README ganhou o bloco "Orientation" |
146
+ | AC-7 | `lib/specs-index.ts`, `lib/handoffs-index.ts`, `lib/orchestrate.ts` (`listRuns`), `scripts/hook-session-start.ts` | hook importa de `lib/`; corrida via `loadState`/`listRuns`; smoke do hook sem regressão (Specs ativas + Handoffs presentes) |
147
+ | AC-8 | `test/forja-status.test.js` | 13 testes verdes |
148
+ | AC-9 | — | bateria acima verde |
149
+
150
+ - **Decisões do plan aplicadas**: um único `scripts/forja-status.ts` para os dois comandos (D1);
151
+ `listSpecs`/`openHandoffs` extraídos para `lib/`, hook reimporta (D2); estado da corrida via
152
+ `loadState` + `listRuns` novo, sem `orchestrate:status --json` (D3); `lib/sprint-index.ts` novo
153
+ em vez de reusar `sprint-manager.ts` (D4). Nenhum desvio vs. o plan.
154
+ - **`SpecEntry` ganhou `plan`/`tasks`** (status de cada artefato) para a escada da AC-4 — o hook
155
+ só usa `slug`/`status`, sem impacto.
156
+ - **Hipótese, não medição**: os ganhos de §8 dependem de instrumentação inexistente; baseline antes.
157
+ - **Pendências**: revisão de Governança sobre o diff; handoff `review` registrado; depende do
158
+ merge de #61 (SPEC-043).