forjajs 4.1.2 → 5.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude/settings.json +2 -2
- package/.gemini-instructions.md +1 -1
- package/.github/copilot-instructions.md +1 -1
- package/.openai-instructions.md +1 -1
- package/CHANGELOG.md +139 -0
- package/DOC-MAP.md +2 -2
- package/README.md +62 -10
- package/README.pt-BR.md +46 -7
- package/boilerplates/01-api-rest/README.md +1 -1
- package/boilerplates/06-clean-arch/README.md +5 -3
- package/boilerplates/06-clean-arch/backend/.oxlintrc.json +10 -0
- package/boilerplates/06-clean-arch/backend/nest-cli.json +8 -0
- package/boilerplates/06-clean-arch/backend/package.json +22 -24
- package/boilerplates/06-clean-arch/backend/src/app.module.ts +4 -4
- package/boilerplates/06-clean-arch/backend/src/main.ts +2 -2
- package/boilerplates/06-clean-arch/backend/src/modules/orders/application/place-order.usecase.ts +4 -4
- package/boilerplates/06-clean-arch/backend/src/modules/orders/application/ship-order.usecase.ts +2 -2
- package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.entity.ts +3 -3
- package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.repository.ts +1 -1
- package/boilerplates/06-clean-arch/backend/src/modules/orders/infrastructure/typeorm-order.repository.ts +5 -5
- package/boilerplates/06-clean-arch/backend/src/modules/orders/orders.module.ts +6 -6
- package/boilerplates/06-clean-arch/backend/src/modules/orders/presentation/orders.controller.ts +3 -3
- package/boilerplates/06-clean-arch/backend/src/modules/products/products.controller.ts +1 -1
- package/boilerplates/06-clean-arch/backend/src/modules/products/products.module.ts +2 -2
- package/boilerplates/06-clean-arch/backend/test/orders/place-order.spec.ts +2 -2
- package/boilerplates/06-clean-arch/backend/tsconfig.build.json +15 -0
- package/boilerplates/06-clean-arch/backend/tsconfig.json +24 -10
- package/boilerplates/06-clean-arch/backend/vitest.config.ts +11 -0
- package/boilerplates/06-clean-arch/boilerplate.manifest.json +6 -5
- package/boilerplates/README.md +24 -44
- package/dist/apps/cli/src/index.js +6 -6
- package/dist/apps/dashboard/next.config.d.mts +5 -5
- package/dist/apps/server/src/app.module.js +1 -1
- package/dist/apps/server/src/forja-nest.module.js +1 -1
- package/dist/apps/server/src/index.js +1 -1
- package/dist/apps/server/src/main.js +20 -20
- package/dist/apps/worker/src/main.js +4 -4
- package/dist/bin/create-memory-nest-kit.js +5 -5
- package/dist/bin/forja.js +28 -14
- package/dist/bin/init-project.d.ts +4 -9
- package/dist/bin/init-project.js +126 -182
- package/dist/lib/audit.js +1 -1
- package/dist/lib/context-builder.d.ts +6 -1
- package/dist/lib/context-builder.js +21 -12
- package/dist/lib/core/architecture-gate.js +2 -4
- package/dist/lib/core/checks.d.ts +1 -1
- package/dist/lib/core/drift-gate.js +2 -4
- package/dist/lib/core/gates.js +5 -5
- package/dist/lib/core/health.d.ts +0 -1
- package/dist/lib/core/health.js +33 -7
- package/dist/lib/core/journey.d.ts +30 -0
- package/dist/lib/core/journey.js +142 -0
- package/dist/lib/core/model-pricing.js +3 -5
- package/dist/lib/core/project-smoke.d.ts +6 -2
- package/dist/lib/core/project-smoke.js +60 -61
- package/dist/lib/core/registry.d.ts +1 -12
- package/dist/lib/core/registry.js +42 -32
- package/dist/lib/core/release.d.ts +1 -1
- package/dist/lib/core/release.js +31 -3
- package/dist/lib/core/risk-collect.js +4 -4
- package/dist/lib/drift-sentinel.js +1 -1
- package/dist/lib/generators/memory-generator.d.ts +30 -30
- package/dist/lib/generators/memory-generator.js +19 -8
- package/dist/lib/generators/nest-generator.js +192 -275
- package/dist/lib/generators/readme-generator.js +1 -1
- package/dist/lib/governance-report.js +4 -4
- package/dist/lib/handoffs-index.d.ts +16 -2
- package/dist/lib/handoffs-index.js +32 -5
- package/dist/lib/llm/session.js +1 -1
- package/dist/lib/llm/validation.js +1 -1
- package/dist/lib/memory-audit.js +1 -1
- package/dist/lib/paths.d.ts +39 -0
- package/dist/lib/paths.js +73 -0
- package/dist/lib/project-upgrade.d.ts +0 -4
- package/dist/lib/project-upgrade.js +19 -1
- package/dist/lib/project-wiring.d.ts +54 -0
- package/dist/lib/project-wiring.js +391 -0
- package/dist/lib/status-model.js +18 -7
- package/dist/lib/templates.d.ts +24 -0
- package/dist/lib/templates.js +77 -0
- package/dist/lib/validators/structure-validator.js +0 -1
- package/dist/lib/workspace.d.ts +7 -0
- package/dist/lib/workspace.js +20 -2
- package/dist/packages/adapter-git/src/index.js +2 -2
- package/dist/packages/context/src/index.js +1 -1
- package/dist/packages/core/src/index.js +1 -1
- package/dist/packages/evals/src/index.js +1 -1
- package/dist/packages/events/src/index.js +1 -1
- package/dist/packages/graph/src/index.js +1 -1
- package/dist/packages/mcp/src/index.d.ts +1 -1
- package/dist/packages/observability/src/index.js +1 -1
- package/dist/packages/orchestration/src/index.js +1 -1
- package/dist/packages/planner/src/index.js +1 -1
- package/dist/packages/policy/src/index.js +1 -1
- package/dist/packages/runtime/src/index.js +1 -1
- package/dist/packages/sandbox/src/index.js +1 -1
- package/dist/packages/validator/src/index.js +1 -1
- package/dist/scripts/adr.js +4 -4
- package/dist/scripts/agent-harness.js +30 -23
- package/dist/scripts/agent-router.js +22 -5
- package/dist/scripts/agent.js +5 -5
- package/dist/scripts/architecture.js +6 -6
- package/dist/scripts/audit-query.js +1 -1
- package/dist/scripts/audit-sync.js +1 -1
- package/dist/scripts/build-smart-context.d.ts +19 -1
- package/dist/scripts/build-smart-context.js +84 -68
- package/dist/scripts/check-standards.js +8 -3
- package/dist/scripts/code-context.js +1 -1
- package/dist/scripts/compress-memory.js +3 -2
- package/dist/scripts/compress-project-memory.js +2 -2
- package/dist/scripts/context-ops.js +13 -5
- package/dist/scripts/cost-economy.js +4 -4
- package/dist/scripts/demo-autonomy.js +11 -11
- package/dist/scripts/demo-workspace.js +12 -4
- package/dist/scripts/dev.js +8 -7
- package/dist/scripts/drift-check.js +5 -5
- package/dist/scripts/engineer.js +11 -11
- package/dist/scripts/evidence.js +4 -4
- package/dist/scripts/extract-global-knowledge.js +6 -4
- package/dist/scripts/forja-setup.js +2 -1
- package/dist/scripts/forja-status.js +5 -4
- package/dist/scripts/gates.js +1 -1
- package/dist/scripts/generate-dashboard.js +6 -4
- package/dist/scripts/governance-dashboard.js +2 -2
- package/dist/scripts/hook-session-start.js +11 -10
- package/dist/scripts/hook-user-prompt.js +3 -2
- package/dist/scripts/incident.js +4 -4
- package/dist/scripts/llm-fit.js +11 -11
- package/dist/scripts/memory-audit.js +1 -1
- package/dist/scripts/memory-schema.js +3 -2
- package/dist/scripts/orchestrate.js +4 -5
- package/dist/scripts/project-smoke.js +13 -2
- package/dist/scripts/project-templates.d.ts +1 -0
- package/dist/scripts/project-templates.js +20 -0
- package/dist/scripts/project-upgrade.d.ts +13 -0
- package/dist/scripts/project-upgrade.js +110 -40
- package/dist/scripts/project-wire.d.ts +8 -0
- package/dist/scripts/project-wire.js +55 -0
- package/dist/scripts/provenance.js +3 -3
- package/dist/scripts/query-universal-memory.js +7 -4
- package/dist/scripts/release-check.js +1 -1
- package/dist/scripts/risk.js +4 -4
- package/dist/scripts/simulate.js +9 -9
- package/dist/scripts/spec-cli.d.ts +1 -0
- package/dist/scripts/spec-cli.js +25 -5
- package/dist/scripts/sprint-manager.js +4 -3
- package/dist/scripts/sync-universal-memory.js +22 -15
- package/dist/scripts/token-benchmark.js +4 -3
- package/dist/scripts/token-economy.js +4 -3
- package/dist/scripts/tools-doctor.d.ts +1 -1
- package/dist/scripts/tools-doctor.js +25 -3
- package/docs/GUIA-ONBOARDING-EXECUTIVO.md +1 -2
- package/docs/GUIA-ONBOARDING-OPERACIONAL-PAPEIS.md +5 -6
- package/docs/GUIA-ONBOARDING-PROJETO.md +7 -9
- package/docs/glossary.md +4 -4
- package/docs/init-project.md +88 -444
- package/docs/manual-operacional-cli-sdd-gsd.md +1 -1
- package/docs/modos-de-operacao.md +1 -1
- package/docs/processo-projeto.md +14 -11
- package/docs/produto/roteiro-demo.md +15 -18
- package/docs/publishing.md +5 -0
- package/docs/quick-reference.md +15 -23
- package/docs/structure.md +16 -30
- package/lib/core/model-pricing.json +19 -0
- package/memory/30-projects/README.md +1 -1
- package/memory/90-decisions/0022-congelar-dashboard-web.md +1 -1
- package/memory/90-decisions/0086-projeto-conectado-e-jornada-como-gate.md +95 -0
- package/memory/90-decisions/0087-remover-dashboard-legado.md +35 -0
- package/memory/90-decisions/0088-templates-validados.md +55 -0
- package/package.json +26 -26
- package/templates/project/AGENTS.md +75 -0
- package/templates/project/CLAUDE.md +9 -0
- package/templates/project/agents/context-engineer.md +15 -0
- package/templates/project/agents/governance.md +15 -0
- package/templates/project/agents/marketing.md +15 -0
- package/templates/project/agents/orchestrator.md +15 -0
- package/templates/project/agents/product.md +15 -0
- package/templates/project/agents/sdd-architect.md +15 -0
- package/dist/lib/multi-ai-instructions.d.ts +0 -28
- package/dist/lib/multi-ai-instructions.js +0 -83
package/.claude/settings.json
CHANGED
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
"hooks": [
|
|
7
7
|
{
|
|
8
8
|
"type": "command",
|
|
9
|
-
"command": "node $CLAUDE_PROJECT_DIR/
|
|
9
|
+
"command": "node $CLAUDE_PROJECT_DIR/bin/forja.ts hook:session-start",
|
|
10
10
|
"timeout": 5000
|
|
11
11
|
}
|
|
12
12
|
]
|
|
@@ -17,7 +17,7 @@
|
|
|
17
17
|
"hooks": [
|
|
18
18
|
{
|
|
19
19
|
"type": "command",
|
|
20
|
-
"command": "node $CLAUDE_PROJECT_DIR/
|
|
20
|
+
"command": "node $CLAUDE_PROJECT_DIR/bin/forja.ts hook:user-prompt",
|
|
21
21
|
"timeout": 3000
|
|
22
22
|
}
|
|
23
23
|
]
|
package/.gemini-instructions.md
CHANGED
|
@@ -16,7 +16,7 @@ A Forja transforma IA de codificação em uma **equipe de engenharia com process
|
|
|
16
16
|
## Onde você está?
|
|
17
17
|
|
|
18
18
|
- **No repositório do framework** (tem `bin/forja.ts` na raiz): você está no **motor**. Ele não contém aplicações — gera e governa projetos que vivem fora dele.
|
|
19
|
-
- **Num projeto gerado
|
|
19
|
+
- **Num projeto gerado**: as instruções dele estão no `AGENTS.md` do projeto (bloco `forja:begin/end`, lido nativamente pelas IAs; `CLAUDE.md`/`GEMINI.md` o importam). Lá os comandos são `forja <comando>` e a conexão se confere com `forja project:wire --check`.
|
|
20
20
|
|
|
21
21
|
## O core `forja` (ADR-0020)
|
|
22
22
|
|
|
@@ -16,7 +16,7 @@ A Forja transforma IA de codificação em uma **equipe de engenharia com process
|
|
|
16
16
|
## Onde você está?
|
|
17
17
|
|
|
18
18
|
- **No repositório do framework** (tem `bin/forja.ts` na raiz): você está no **motor**. Ele não contém aplicações — gera e governa projetos que vivem fora dele.
|
|
19
|
-
- **Num projeto gerado
|
|
19
|
+
- **Num projeto gerado**: as instruções dele estão no `AGENTS.md` do projeto (bloco `forja:begin/end`, lido nativamente pelas IAs; `CLAUDE.md`/`GEMINI.md` o importam). Lá os comandos são `forja <comando>` e a conexão se confere com `forja project:wire --check`.
|
|
20
20
|
|
|
21
21
|
## O core `forja` (ADR-0020)
|
|
22
22
|
|
package/.openai-instructions.md
CHANGED
|
@@ -16,7 +16,7 @@ A Forja transforma IA de codificação em uma **equipe de engenharia com process
|
|
|
16
16
|
## Onde você está?
|
|
17
17
|
|
|
18
18
|
- **No repositório do framework** (tem `bin/forja.ts` na raiz): você está no **motor**. Ele não contém aplicações — gera e governa projetos que vivem fora dele.
|
|
19
|
-
- **Num projeto gerado
|
|
19
|
+
- **Num projeto gerado**: as instruções dele estão no `AGENTS.md` do projeto (bloco `forja:begin/end`, lido nativamente pelas IAs; `CLAUDE.md`/`GEMINI.md` o importam). Lá os comandos são `forja <comando>` e a conexão se confere com `forja project:wire --check`.
|
|
20
20
|
|
|
21
21
|
## O core `forja` (ADR-0020)
|
|
22
22
|
|
package/CHANGELOG.md
CHANGED
|
@@ -19,6 +19,145 @@ GitHub reusa esse bloco. O README também é reconciliado na mesma entrega — v
|
|
|
19
19
|
|
|
20
20
|
_(preencher a cada release: diff de produto vs. a versão anterior, antes das seções técnicas)_
|
|
21
21
|
|
|
22
|
+
## [5.0.1] — 2026-10-10 — Correção: o upgrade nunca toca o código do projeto
|
|
23
|
+
|
|
24
|
+
### O que melhorou
|
|
25
|
+
|
|
26
|
+
- **`forja project:upgrade` não mexe mais no código do projeto.** Na 5.0.0, um projeto com pasta
|
|
27
|
+
`backend/` recebia o scaffold do backend NestJS — inclusive quando o backend era de outra stack (um
|
|
28
|
+
backend Python ganharia um app Nest inteiro). Agora o upgrade traz só a camada do Forja (memória,
|
|
29
|
+
agentes, prompts, skills, scripts) e a conexão com a IA; `backend/`, `frontend/`, `apps/`,
|
|
30
|
+
`packages/` e `src/` ficam de fora.
|
|
31
|
+
- **A memória de um projeto existente não ganha conteúdo de exemplo.** Os domínios de exemplo do
|
|
32
|
+
scaffold (`memory/30-domains/auth`, `billing`) não entram mais pelo upgrade; ao lado dos domínios
|
|
33
|
+
reais, a IA os leria como parte do produto. Agente e skill de NestJS só entram em projeto que usa
|
|
34
|
+
NestJS.
|
|
35
|
+
- **`npm run build` mantém o `forja` executável.** Para quem usa o Forja linkado ao checkout
|
|
36
|
+
(`npm link`), o comando e os hooks dos projetos não falham mais com "Permissão negada" depois de
|
|
37
|
+
recompilar.
|
|
38
|
+
|
|
39
|
+
### Corrigido
|
|
40
|
+
|
|
41
|
+
- `scripts/project-upgrade.ts` / `lib/project-upgrade.ts`: referência sempre `--only-memory`; plano
|
|
42
|
+
exclui diretórios de código, domínios de exemplo e peças Nest fora de projeto Nest (#73). Teste de
|
|
43
|
+
regressão em `test/project-adoption.test.js`.
|
|
44
|
+
- `package.json` (`build`): restaura o bit de execução dos `bin` após o `tsc`.
|
|
45
|
+
- `docs/init-project.md` e ADR-0086 alinhados ao novo comportamento do upgrade.
|
|
46
|
+
|
|
47
|
+
### Notas
|
|
48
|
+
|
|
49
|
+
- Achado ao migrar um workspace real com `project:upgrade --all`. Quem usou o `--apply` da 5.0.0
|
|
50
|
+
num projeto com `backend/` que não é o gerado pelo Forja deve revisar o `git status` do backend.
|
|
51
|
+
|
|
52
|
+
## [5.0.0] — 2026-10-09 — Projeto conectado à IA e a jornada do usuário como gate
|
|
53
|
+
|
|
54
|
+
### O que melhorou
|
|
55
|
+
|
|
56
|
+
- **O projeto já nasce conectado à sua IA.** `forja project:new` escreve as instruções nos arquivos
|
|
57
|
+
que cada IA lê sozinha (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructions.md`),
|
|
58
|
+
configura os hooks do Claude Code (cada sessão abre com specs, handoffs e saúde do projeto; citar
|
|
59
|
+
uma spec no prompt anexa spec, plan e tasks), instala seis sub-agents por papel e registra o
|
|
60
|
+
servidor MCP do Forja. Antes, as instruções iam para uma pasta que nenhuma IA lê e mandavam rodar
|
|
61
|
+
comandos que não existiam no projeto.
|
|
62
|
+
- **`project:new` funciona instalado e no checkout, e não mente mais.** No pacote publicado o projeto
|
|
63
|
+
saía sem instruções, sem design-md e com scripts apontando para arquivos ausentes, e mesmo assim
|
|
64
|
+
terminava com "Tudo pronto!". No checkout, nem rodava. Agora sai completo, com a memória já
|
|
65
|
+
indexada, e quando algo essencial falha o comando sai com exit 1 e lista as pendências.
|
|
66
|
+
- **A inteligência funciona dentro do projeto.** `context:smart --mode task` passa a achar o que a
|
|
67
|
+
tarefa pede (o modo task nunca tinha funcionado). A memória do projeto deixa de receber as specs do
|
|
68
|
+
framework. `code:impact` analisa o código do projeto, não o do Forja. Handoffs ficam com o projeto
|
|
69
|
+
de origem, e `forja next` passa a apontar o handoff mais antigo em aberto.
|
|
70
|
+
- **Um comando para conectar e conferir:** `forja project:wire` (e `--check`) liga ou verifica
|
|
71
|
+
instruções, hooks, sub-agents, MCP e `.gitignore`. Também confere que todo comando citado à IA
|
|
72
|
+
existe e que todo script do `package.json` aponta para um arquivo real. O `tools:doctor` mostra o
|
|
73
|
+
mesmo quadro quando roda num projeto.
|
|
74
|
+
- **Adotar o Forja num repositório que já existe:** `forja project:wire` seguido de
|
|
75
|
+
`forja project:upgrade --apply`, sem instalar backend nem sobrescrever arquivos.
|
|
76
|
+
- **Projetos antigos se religam com um comando:** `forja project:upgrade --apply` migra projetos
|
|
77
|
+
gerados antes da v5, e `forja project:upgrade --all` faz o relatório (e com `--apply`, a migração)
|
|
78
|
+
do workspace inteiro. Antes, o upgrade instalava um backend NestJS inteiro em quem não tinha.
|
|
79
|
+
- **O MCP do Forja chega a todas as IAs:** além do Claude Code, o projeto registra o servidor `forja`
|
|
80
|
+
no Codex (`.codex/config.toml`), no Gemini CLI (`.gemini/settings.json`) e no Copilot do VS Code
|
|
81
|
+
(`.vscode/mcp.json`).
|
|
82
|
+
- **Projeto a partir de um template que funciona:** `forja project:new pedidos --template clean-arch`
|
|
83
|
+
parte de um boilerplate com instalação, build, testes e lint provados no CI. Boilerplates ainda não
|
|
84
|
+
validados ficam como referência, e o `--template` os recusa dizendo por quê
|
|
85
|
+
(`forja project:templates` mostra qual é qual).
|
|
86
|
+
- **O backend gerado roda o que anuncia:** segue o padrão do NestJS 12 (ESM, Vitest, oxlint). Antes,
|
|
87
|
+
compilava, mas `npm test` não carregava, o lint nunca tinha rodado e o painel `/api/ops` lia um banco
|
|
88
|
+
que não existia. Agora ele mostra as specs, os handoffs em aberto e a memória do projeto.
|
|
89
|
+
- **Handoffs com dono:** `forja agent:route list --mine` lista os handoffs do projeto em que você está,
|
|
90
|
+
cada um com o projeto de origem, e o `tools:doctor` avisa quando sobra um handoff órfão.
|
|
91
|
+
- **Dependências em dia e sem vulnerabilidades:** NestJS 12, TypeScript 7, better-sqlite3 13 (que traz
|
|
92
|
+
o binário pronto e não depende de script de instalação, bloqueado por padrão no npm 11), Next 16.4 e
|
|
93
|
+
React 19.3. O `npm audit` sai zerado.
|
|
94
|
+
- **Nenhuma versão sai com essa desconexão de novo.** A jornada inteira do usuário (workspace →
|
|
95
|
+
projeto → memória, contexto, specs, gates, hooks, MCP, handoff) roda no `npm test` e no
|
|
96
|
+
`release:check` contra o pacote instalado, e reprova se qualquer comando escrever dentro do pacote.
|
|
97
|
+
- **Repositório mais limpo:** sai o dashboard congelado (`dashboard/`), PNGs soltos, aliases
|
|
98
|
+
duplicados e branches antigas. O dashboard opcional é o `apps/dashboard`
|
|
99
|
+
(`npm run dashboard:api` + `npm run dashboard:dev`).
|
|
100
|
+
|
|
101
|
+
### Mudança de contrato (breaking)
|
|
102
|
+
|
|
103
|
+
- **Node ≥ 22** (`engines`).
|
|
104
|
+
- Projetos novos não recebem `.ia-instructions/`; a cadeia de fallback entre IAs vai para
|
|
105
|
+
`.forja/models.json`. O backend gerado perde `memory:db:init`; `memory:db:sync`/`query` chamam o
|
|
106
|
+
`forja`. Migração: `forja project:upgrade --apply` dentro do projeto.
|
|
107
|
+
- Comandos removidos: `init:project` (use `project:new`) e os aliases npm `ops:plan`,
|
|
108
|
+
`ops:handoff`, `ops:check`, `ops:sprint` (use `gsd:*` e `sprint:status`). A flag `--interactive`
|
|
109
|
+
do gerador, que só simulava um modo interativo, saiu.
|
|
110
|
+
- `dashboard/` removido (ADR-0087).
|
|
111
|
+
- Backend gerado em ESM (`"type": "module"`, imports com `.js`), Vitest no lugar do Jest e oxlint no
|
|
112
|
+
lugar do ESLint. Projetos existentes não são migrados.
|
|
113
|
+
- Hooks e MCP de um projeto chamam o binário `forja`: instale com `npm i -g forjajs`.
|
|
114
|
+
|
|
115
|
+
### Adicionado
|
|
116
|
+
|
|
117
|
+
- `lib/paths.ts`: `pkgRoot`/`codeRoot`/`script()` — raízes resolvidas num lugar só; `test/paths.test.js`
|
|
118
|
+
vigia a classe "raiz via `__dirname`" e "extensão cravada em spawn" (ADR-0086).
|
|
119
|
+
- `lib/project-wiring.ts`, `templates/project/` e os comandos `project:wire`,
|
|
120
|
+
`hook:session-start` e `hook:user-prompt`.
|
|
121
|
+
- `lib/core/journey.ts` + `test/journey.test.js` + check `consumer-journey` no `release:check`;
|
|
122
|
+
`test/project-adoption.test.js`.
|
|
123
|
+
- `currentProjectName()` (`lib/workspace.ts`) e carimbo `project` nos handoffs.
|
|
124
|
+
- `npm run dashboard:api` (API do `apps/server` compilada).
|
|
125
|
+
- `lib/templates.ts`, `forja project:templates`, `project:new --template` e
|
|
126
|
+
`project:smoke --template`. Novo job de CI `project-smoke-full` (padrão + cada template), coberto por
|
|
127
|
+
`test/templates.test.js` (ADR-0088).
|
|
128
|
+
- `project:upgrade --all [--apply] [--json]`; `agent:route list --project/--mine`; check
|
|
129
|
+
`handoff-orphans` no doctor; check `mcp-ias` no `project:wire`.
|
|
130
|
+
- `project:smoke --full` roda `test`, `test:e2e` e `lint` além do build.
|
|
131
|
+
|
|
132
|
+
### Corrigido
|
|
133
|
+
|
|
134
|
+
- Vinte scripts que no pacote instalado resolviam a raiz em `dist/` (`setup`, `project:new`,
|
|
135
|
+
`project:upgrade`, gates de drift/arquitetura, health, release etc.).
|
|
136
|
+
- `lib/core/model-pricing.json` não chegava ao pacote: preços passam a ser lidos da raiz do pacote.
|
|
137
|
+
- `sync:universal` no modo embedded indexava specs/boilerplates do framework e gravava os nós do
|
|
138
|
+
projeto como globais; `ContextBuilder` lançava em todo modo task (`MATCH` dentro de `OR`) e
|
|
139
|
+
quebrava com termos como `pix-qr` (agora `ftsQuery`).
|
|
140
|
+
- `query:universal` saía 0 em erro e quebrava com hífen/dois-pontos.
|
|
141
|
+
- `project:check` sem argumento tratava qualquer projeto como o repo do framework (64% num
|
|
142
|
+
projeto recém-gerado).
|
|
143
|
+
- `spec:new` numerava a primeira spec como SPEC-002 (contava a pasta recém-criada).
|
|
144
|
+
- `hermes:handoff`/`gsd:handoff` e `code:*` rodavam no diretório do pacote;
|
|
145
|
+
`project:dashboard`, `memory:extract` e a auditoria sem workspace gravavam dentro do pacote.
|
|
146
|
+
- MCP anunciava a versão `2.0.3` fixa; agora a do pacote.
|
|
147
|
+
- Template de ADR do projeto ganhou Status/Data (antes `adr:list` mostrava "status desconhecido").
|
|
148
|
+
- `demo:workspace` gera um projeto conectado e indexado, e a instrução de uso aponta para a CLI.
|
|
149
|
+
- Mensagens de uso citam `forja <comando>`, não scripts internos.
|
|
150
|
+
|
|
151
|
+
### Notas
|
|
152
|
+
|
|
153
|
+
- ADRs: [0086](memory/90-decisions/0086-projeto-conectado-e-jornada-como-gate.md),
|
|
154
|
+
[0087](memory/90-decisions/0087-remover-dashboard-legado.md) (supersede a 0022),
|
|
155
|
+
[0088](memory/90-decisions/0088-templates-validados.md).
|
|
156
|
+
- Handoffs #1–#14 arquivados: #1–#13 eram do framework (SPEC-030, 043–050, entregues na 4.1.x); o #14
|
|
157
|
+
era de um projeto que não existe mais no workspace.
|
|
158
|
+
- Próximos templates: 02-saas e 03-ecommerce (exigem refazer a camada de dados), 04 e 05 (topologia
|
|
159
|
+
própria). Entram quando passarem no `project-smoke-full`.
|
|
160
|
+
|
|
22
161
|
## [4.1.2] — 2026-09-18 — Correção: status reconhece specs e indexador suporta symlinks de projetos
|
|
23
162
|
|
|
24
163
|
### O que melhorou
|
package/DOC-MAP.md
CHANGED
|
@@ -34,7 +34,7 @@ Ponto de entrada por papel. Para histórico de fases ver `CHANGELOG.md`; para de
|
|
|
34
34
|
- `docs/examples.md` — snippets prontos
|
|
35
35
|
- `docs/dev-workflow.md`
|
|
36
36
|
- `docs/init-project.md` — como gerar novo projeto
|
|
37
|
-
- `docs/
|
|
37
|
+
- `docs/produto/roteiro-demo.md` — dashboard web opcional (`apps/dashboard`) sobre o cenário de demo
|
|
38
38
|
|
|
39
39
|
### QA
|
|
40
40
|
- `docs/personas/qa/README.md`
|
|
@@ -67,7 +67,7 @@ Ponto de entrada por papel. Para histórico de fases ver `CHANGELOG.md`; para de
|
|
|
67
67
|
| Publicação npm | `docs/publishing.md` |
|
|
68
68
|
| Estrutura gerada | `docs/structure.md` |
|
|
69
69
|
| Exemplos de código | `docs/examples.md` |
|
|
70
|
-
| Dashboard web (
|
|
70
|
+
| Dashboard web (opcional) | `docs/produto/roteiro-demo.md` |
|
|
71
71
|
| Factsheet de produto e marketing | `docs/produto/factsheet-marketing.md` |
|
|
72
72
|
|
|
73
73
|
---
|
package/README.md
CHANGED
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
<img src="https://img.shields.io/badge/agents-6_roles-orange?style=flat-square" alt="6 agents">
|
|
12
12
|
<img src="https://img.shields.io/badge/pipeline-SDD_+_GSD-teal?style=flat-square" alt="SDD+GSD">
|
|
13
13
|
<img src="https://img.shields.io/badge/memory-SQLite_FTS5-green?style=flat-square" alt="Memory">
|
|
14
|
-
<img src="https://img.shields.io/badge/node-%E2%89%
|
|
14
|
+
<img src="https://img.shields.io/badge/node-%E2%89%A522-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node >= 22">
|
|
15
15
|
<img src="https://img.shields.io/badge/license-MIT-1a1a1a?style=flat-square" alt="MIT">
|
|
16
16
|
<img src="https://img.shields.io/badge/PRs-welcome-8957e5?style=flat-square" alt="PRs welcome">
|
|
17
17
|
</p>
|
|
@@ -95,9 +95,21 @@ process followed?", the answer is a file, not a promise.
|
|
|
95
95
|
- **Token economy measured, not asserted** — memory (the `context.md` as a map) saves ~60% vs
|
|
96
96
|
exploring cold, and `token:economy` **proves** it across your domains. `code:context` delivers the
|
|
97
97
|
map ready to paste; `memory:audit` guarantees it doesn't lie about the code.
|
|
98
|
-
- **
|
|
99
|
-
|
|
100
|
-
|
|
98
|
+
- **Projects born connected to your AI** — `project:new` scaffolds a full project (memory, agents,
|
|
99
|
+
a NestJS backend as the default boilerplate) and wires it to the AI you use: native instructions
|
|
100
|
+
(`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, Copilot), Claude Code hooks that open every session with the
|
|
101
|
+
project state and attach the spec you mention, six role sub-agents, and the Forja MCP server in
|
|
102
|
+
Claude, Codex, Gemini and Copilot (VS Code). The
|
|
103
|
+
memory is indexed from the first minute. `project:wire --check` proves it; `project:upgrade --apply`
|
|
104
|
+
re-wires older projects without touching the user's code — or the whole workspace with `--all`
|
|
105
|
+
(ADR-0086). The NestJS backend follows the official NestJS 12 layout (ESM, Vitest, oxlint) and its
|
|
106
|
+
`/api/ops` page shows the project's specs, open handoffs and indexed memory.
|
|
107
|
+
- **Validated templates** — `project:new <name> --template clean-arch` starts from a boilerplate whose
|
|
108
|
+
install, build, tests and lint are proven in CI; `project:templates` lists what is a template and
|
|
109
|
+
what is reference architecture (ADR-0088).
|
|
110
|
+
- **The user journey is a gate** — `npm test` and `release:check` run the whole journey (workspace →
|
|
111
|
+
project → memory, context, specs, hooks, MCP, handoffs inside the project) against the source and
|
|
112
|
+
against the installed tarball, and fail if any command writes into the package itself.
|
|
101
113
|
- **3 integrated capabilities** (ADR-0016): **codegraph** (code analysis via MCP), **harness**
|
|
102
114
|
(agent-team design), **ai-engineering** (knowledge base).
|
|
103
115
|
- **LLM Fit Loop** — adapters de CLI, perfis no workspace, probes sem custo, observações e
|
|
@@ -120,8 +132,11 @@ forja # help grouped by domain
|
|
|
120
132
|
# Prepare the production workspace (the fixed home for your projects)
|
|
121
133
|
forja workspace:init
|
|
122
134
|
|
|
123
|
-
# Create a new project (generated in ~/forja-workspace/projects/<name
|
|
135
|
+
# Create a new project (generated in ~/forja-workspace/projects/<name>, already wired to your AI)
|
|
124
136
|
forja project:new my-project --ai claude,copilot
|
|
137
|
+
cd ~/forja-workspace/projects/my-project
|
|
138
|
+
forja project:wire --check # instructions, hooks, sub-agents and MCP connected
|
|
139
|
+
forja status # memory indexed, specs, handoffs — then open your AI here
|
|
125
140
|
|
|
126
141
|
# Enter the SDD/GSD cycle for the first feature
|
|
127
142
|
forja spec:new my-feature
|
|
@@ -130,10 +145,21 @@ forja spec:tasks my-feature
|
|
|
130
145
|
forja spec:check my-feature
|
|
131
146
|
```
|
|
132
147
|
|
|
148
|
+
### Already have a repository?
|
|
149
|
+
|
|
150
|
+
```bash
|
|
151
|
+
cd my-existing-app
|
|
152
|
+
forja project:wire --ai claude,codex # native instructions, hooks, sub-agents, MCP
|
|
153
|
+
forja project:upgrade --apply # memory and agents layer (additive: no backend, no overwrites)
|
|
154
|
+
forja sync:universal # index the memory
|
|
155
|
+
```
|
|
156
|
+
|
|
133
157
|
### Maintenance commands
|
|
134
158
|
|
|
135
159
|
```bash
|
|
136
|
-
forja project:upgrade
|
|
160
|
+
forja project:upgrade --apply # inside the project: new scaffold pieces + re-wire (pre-v5 projects)
|
|
161
|
+
forja project:upgrade --all # every workspace project: dry-run report (--apply to apply)
|
|
162
|
+
forja project:wire --check
|
|
137
163
|
forja code:context <domain> --code
|
|
138
164
|
forja memory:audit
|
|
139
165
|
forja token:economy --project <project>
|
|
@@ -165,8 +191,8 @@ external network or Docker handlers must be injected and permissioned by the hos
|
|
|
165
191
|
> Cloned the repo instead of installing? The same commands run as
|
|
166
192
|
> `node bin/forja.ts <command>` — the npm scripts are just thin aliases of the core.
|
|
167
193
|
> The source is TypeScript and runs natively: **dev needs Node ≥ 22.6** (type stripping). The
|
|
168
|
-
> *published* package ships `dist/*.js` and
|
|
169
|
-
> every release (SPEC-012).
|
|
194
|
+
> *published* package ships `dist/*.js` and requires **Node ≥ 22** — the `release-gate` installs the
|
|
195
|
+
> tarball and runs the full user journey on it every release (SPEC-012, ADR-0086).
|
|
170
196
|
|
|
171
197
|
Step by step on **create vs update** a project: [`docs/processo-projeto.md`](docs/processo-projeto.md).
|
|
172
198
|
|
|
@@ -227,7 +253,10 @@ forja help [<command>|--all] # the core, or one command's usage/ar
|
|
|
227
253
|
|
|
228
254
|
# Workspace & projects
|
|
229
255
|
forja workspace:init # create ~/forja-workspace
|
|
230
|
-
forja project:new <name> --ai claude,copilot # create a project in the workspace
|
|
256
|
+
forja project:new <name> --ai claude,copilot # create a project in the workspace, wired to the AI
|
|
257
|
+
forja project:wire [--check] # (inside a project) connect/verify instructions, hooks, MCP
|
|
258
|
+
forja project:upgrade --apply # (inside a project) bring new scaffold + re-wire; --all for the workspace
|
|
259
|
+
forja project:templates # validated templates (project:new --template) vs reference
|
|
231
260
|
forja project:list # list workspace projects
|
|
232
261
|
forja workspace:project:check <name> # validate standards in a workspace project
|
|
233
262
|
|
|
@@ -238,6 +267,7 @@ forja spec:new <slug> # also: spec:plan · spec:tasks · sp
|
|
|
238
267
|
forja sprint:start # also: sprint:status · sprint:complete
|
|
239
268
|
forja gsd:plan <slug> # GSD runbook in .context/
|
|
240
269
|
forja gsd:handoff <intent> <slug> # role-to-role handoff (ADR-0005)
|
|
270
|
+
forja agent:route list --open --mine # open handoffs of this project (each one stamped with its project)
|
|
241
271
|
forja gsd:check <slug> # baseline runbook gates
|
|
242
272
|
forja orchestrate "<goal>" --slug <s> # the default path: the whole SDD/GSD chain as a gated state machine (SPEC-021)
|
|
243
273
|
forja orchestrate:status <slug> # the machine state: stages, gates, verdicts
|
|
@@ -279,7 +309,7 @@ forja incident:similar "<query>" # keyword-based similar-incident sugg
|
|
|
279
309
|
# Memory & context (workspace)
|
|
280
310
|
forja sync:universal # reindex the workspace SQLite FTS5
|
|
281
311
|
forja query:universal "<query>" # FTS5 search
|
|
282
|
-
forja context:smart
|
|
312
|
+
forja context:smart --mode task --task pix # smart-context: global | domain | task (ADR-0003)
|
|
283
313
|
forja memory:compress # archive old runs + VACUUM
|
|
284
314
|
forja memory:extract # extract global knowledge from memory
|
|
285
315
|
|
|
@@ -297,6 +327,8 @@ forja tools:doctor # core X-ray; tells permission/lock f
|
|
|
297
327
|
forja release:check --publish # tarball gate before publishing
|
|
298
328
|
forja project:smoke # generated-project gate; --full installs+builds; --ai <list> checks native instructions
|
|
299
329
|
forja project:dashboard # static status report
|
|
330
|
+
forja hook:session-start # what Claude Code runs at session start (briefing)
|
|
331
|
+
forja hook:user-prompt # what it runs per prompt (attaches the cited spec)
|
|
300
332
|
|
|
301
333
|
# Governance & audit
|
|
302
334
|
forja audit:sync # project the audit trail into a queryable table
|
|
@@ -348,6 +380,26 @@ projects/ LEGACY — do not use; projects live in the external workspace
|
|
|
348
380
|
README.md
|
|
349
381
|
```
|
|
350
382
|
|
|
383
|
+
## Inside a generated project
|
|
384
|
+
|
|
385
|
+
```
|
|
386
|
+
my-project/
|
|
387
|
+
AGENTS.md # how to operate the project — read natively by Codex, Copilot agent, Gemini
|
|
388
|
+
CLAUDE.md, GEMINI.md # import AGENTS.md (+ .github/copilot-instructions.md for Copilot)
|
|
389
|
+
.claude/
|
|
390
|
+
settings.json # hooks: forja hook:session-start / hook:user-prompt
|
|
391
|
+
agents/ # orchestrator, product, sdd-architect, context-engineer, governance, marketing
|
|
392
|
+
.mcp.json # forja MCP server (+ codegraph when installed)
|
|
393
|
+
.codex/config.toml # forja MCP for Codex · .gemini/settings.json (Gemini) · .vscode/mcp.json (Copilot)
|
|
394
|
+
.forja/models.json # AI fallback chain (engine switch)
|
|
395
|
+
memory/ # hierarchical memory, indexed in memory/sqlite/ (git-ignored)
|
|
396
|
+
specs/ # spec → plan → tasks
|
|
397
|
+
backend/ # NestJS 12, ESM + Vitest + oxlint (unless --skip-backend; or the --template's)
|
|
398
|
+
```
|
|
399
|
+
|
|
400
|
+
The Forja-managed part of each instruction file lives between `<!-- forja:begin -->` and
|
|
401
|
+
`<!-- forja:end -->`; everything outside it is yours and survives `project:wire`/`project:upgrade`.
|
|
402
|
+
|
|
351
403
|
## Documentation
|
|
352
404
|
|
|
353
405
|
The docs are written in **Brazilian Portuguese** — that's part of the project's identity. The CLI
|
package/README.pt-BR.md
CHANGED
|
@@ -11,7 +11,7 @@
|
|
|
11
11
|
<img src="https://img.shields.io/badge/agentes-6_papéis-orange?style=flat-square" alt="6 agentes">
|
|
12
12
|
<img src="https://img.shields.io/badge/pipeline-SDD_+_GSD-teal?style=flat-square" alt="SDD+GSD">
|
|
13
13
|
<img src="https://img.shields.io/badge/memória-SQLite_FTS5-green?style=flat-square" alt="Memória">
|
|
14
|
-
<img src="https://img.shields.io/badge/node-%E2%89%
|
|
14
|
+
<img src="https://img.shields.io/badge/node-%E2%89%A522-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node >= 22">
|
|
15
15
|
<img src="https://img.shields.io/badge/license-MIT-1a1a1a?style=flat-square" alt="MIT">
|
|
16
16
|
<img src="https://img.shields.io/badge/PRs-welcome-8957e5?style=flat-square" alt="PRs welcome">
|
|
17
17
|
</p>
|
|
@@ -85,7 +85,9 @@ E cada comando acima ficou gravado em `.context/forja-runs.jsonl` — quando a g
|
|
|
85
85
|
- **Pipeline SDD + GSD** — `spec → plan → tasks → check`, decisões registradas como ADRs.
|
|
86
86
|
- **Auto-verificação (invariantes que rodam)** — o framework prova a si mesmo: uma família de gates guarda cada fronteira (núcleo, tarball, coerência de doc, topologia de agentes, projeto gerado), e `check:all` roda a bateria inteira num veredito só. A governança deixa de depender de disciplina — vira harness.
|
|
87
87
|
- **Economia de token medida, não afirmada** — a memória (`context.md` como mapa) economiza ~60% vs explorar no frio, e `token:economy` **prova** isso nos seus domínios. `code:context` entrega o mapa pronto; `memory:audit` garante que ele não mente sobre o código.
|
|
88
|
-
- **
|
|
88
|
+
- **Projetos que nascem conectados à sua IA** — `project:new` cria o scaffold completo (memória, agentes, backend NestJS como boilerplate padrão) e liga o projeto à IA que você usa: instruções nativas (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, Copilot), hooks do Claude Code que abrem cada sessão com o estado do projeto e anexam a spec citada no prompt, seis sub-agents por papel e o servidor MCP do Forja no Claude, Codex, Gemini e Copilot (VS Code). A memória já nasce indexada. `project:wire --check` prova a conexão; `project:upgrade --apply` religa projetos antigos sem tocar no código do usuário — ou o workspace inteiro com `--all` (ADR-0086). O backend NestJS segue o padrão oficial do NestJS 12 (ESM, Vitest, oxlint), e a página `/api/ops` mostra specs, handoffs em aberto e a memória indexada do projeto.
|
|
89
|
+
- **Templates validados** — `project:new <nome> --template clean-arch` parte de um boilerplate cuja instalação, build, testes e lint são provados no CI; `project:templates` lista o que é template e o que é arquitetura de referência (ADR-0088).
|
|
90
|
+
- **A jornada do usuário é gate** — `npm test` e `release:check` percorrem a jornada inteira (workspace → projeto → memória, contexto, specs, hooks, MCP e handoffs dentro do projeto), contra o fonte e contra o pacote instalado, e reprovam se algum comando escrever dentro do pacote.
|
|
89
91
|
- **3 capacidades integradas** (ADR-0016): **codegraph** (análise de código via MCP), **harness** (desenho de times de agentes), **ai-engineering** (base de conhecimento).
|
|
90
92
|
- **Engineering Control Plane** (v3.0, ADR-0078) — o Engineering Graph vira ADRs/SPECs em nós de primeira classe consultáveis; a Architecture Constitution checa o código real contra decisões já registradas; o Change Risk Engine pontua uma mudança 0-100 com fatores nomeados e evidenciados; `forja simulate` testa um ref num worktree isolado e nunca promove sozinho. Uma façade só, `forja engineer "<objetivo>"`, compõe tudo isso — contexto, ADRs relevantes, checagem de arquitetura, risco, agentes recomendados, incidentes parecidos — antes de você começar. Todo score é informação pra um humano/regra de política consultar, nunca uma decisão autônoma por si só.
|
|
91
93
|
|
|
@@ -99,8 +101,11 @@ forja # help agrupado por domínio
|
|
|
99
101
|
# Preparar o workspace de produção (canto fixo dos projetos)
|
|
100
102
|
forja workspace:init
|
|
101
103
|
|
|
102
|
-
# Criar um projeto novo (gera em ~/forja-workspace/projects/<nome
|
|
104
|
+
# Criar um projeto novo (gera em ~/forja-workspace/projects/<nome>, já conectado à sua IA)
|
|
103
105
|
forja project:new meu-projeto --ai claude,copilot
|
|
106
|
+
cd ~/forja-workspace/projects/meu-projeto
|
|
107
|
+
forja project:wire --check # instruções, hooks, sub-agents e MCP conectados
|
|
108
|
+
forja status # memória indexada, specs, handoffs — depois abra sua IA aqui
|
|
104
109
|
|
|
105
110
|
# Entrar no ciclo SDD/GSD da primeira feature
|
|
106
111
|
forja spec:new minha-feature
|
|
@@ -109,6 +114,15 @@ forja spec:tasks minha-feature
|
|
|
109
114
|
forja spec:check minha-feature
|
|
110
115
|
```
|
|
111
116
|
|
|
117
|
+
### Já tem um repositório?
|
|
118
|
+
|
|
119
|
+
```bash
|
|
120
|
+
cd meu-app-existente
|
|
121
|
+
forja project:wire --ai claude,codex # instruções nativas, hooks, sub-agents, MCP
|
|
122
|
+
forja project:upgrade --apply # camada de memória e agentes (aditivo: sem backend, sem sobrescrever)
|
|
123
|
+
forja sync:universal # indexa a memória
|
|
124
|
+
```
|
|
125
|
+
|
|
112
126
|
### Provar autonomia supervisionada localmente
|
|
113
127
|
|
|
114
128
|
A prova offline determinística usa uma fixture externa, Git worktree real,
|
|
@@ -134,7 +148,7 @@ handlers externos de rede ou Docker precisam ser injetados e permissionados pelo
|
|
|
134
148
|
> Clonou o repo em vez de instalar? Os mesmos comandos rodam como
|
|
135
149
|
> `node bin/forja.ts <comando>` — os scripts npm são apenas aliases finos do core.
|
|
136
150
|
> A fonte é TypeScript e roda nativa: **dev exige Node ≥ 22.6** (strip-types). O pacote *publicado*
|
|
137
|
-
> embarca `dist/*.js` e
|
|
151
|
+
> embarca `dist/*.js` e exige **Node ≥ 22** — o `release-gate` instala o tarball e percorre a jornada inteira do usuário nele a cada release (SPEC-012, ADR-0086).
|
|
138
152
|
|
|
139
153
|
Passo a passo de **criar vs atualizar** projeto: [`docs/processo-projeto.md`](docs/processo-projeto.md).
|
|
140
154
|
|
|
@@ -190,9 +204,11 @@ Os scripts npm do repo são aliases finos que roteiam pelo core.
|
|
|
190
204
|
```bash
|
|
191
205
|
# Workspace & projetos
|
|
192
206
|
forja workspace:init # cria ~/forja-workspace
|
|
193
|
-
forja project:new <nome> --ai claude,copilot # cria projeto no workspace
|
|
207
|
+
forja project:new <nome> --ai claude,copilot # cria projeto no workspace, conectado à IA
|
|
208
|
+
forja project:wire [--check] # (no projeto) conecta/verifica instruções, hooks, MCP
|
|
209
|
+
forja project:upgrade --apply # (no projeto) peças novas de scaffold + religa (aditivo); --all p/ o workspace
|
|
210
|
+
forja project:templates # templates validados (project:new --template) × referência
|
|
194
211
|
forja project:list # lista projetos do workspace
|
|
195
|
-
forja project:upgrade # traz peças novas de scaffold p/ um projeto (aditivo; --apply)
|
|
196
212
|
forja workspace:project:check <nome> # valida padrões num projeto do workspace
|
|
197
213
|
|
|
198
214
|
# Pipeline SDD
|
|
@@ -202,6 +218,7 @@ forja spec:new <slug> # também: spec:plan · spec:tasks ·
|
|
|
202
218
|
forja sprint:start # também: sprint:status · sprint:complete
|
|
203
219
|
forja gsd:plan <slug> # runbook GSD em .context/
|
|
204
220
|
forja gsd:handoff <intent> <slug> # handoff entre papéis (ADR-0005)
|
|
221
|
+
forja agent:route list --open --mine # handoffs em aberto deste projeto (cada um carimbado com o projeto)
|
|
205
222
|
forja gsd:check <slug> # gates básicos do runbook
|
|
206
223
|
forja orchestrate "<objetivo>" --slug <s> # abre a corrida: a cadeia SDD/GSD como máquina de estados (SPEC-021)
|
|
207
224
|
forja orchestrate:status <slug> # o estado da máquina: etapas, gates, vereditos
|
|
@@ -216,7 +233,7 @@ forja code:query "<termo>" # também: code:index · code:sync ·
|
|
|
216
233
|
# Memória & contexto (workspace)
|
|
217
234
|
forja sync:universal # reindexa SQLite FTS5 do workspace
|
|
218
235
|
forja query:universal "<query>" # busca FTS5
|
|
219
|
-
forja context:smart
|
|
236
|
+
forja context:smart --mode task --task pix # smart-context: global | domain | task (ADR-0003)
|
|
220
237
|
forja token:economy [--project <path>] # economia de token; --project mede seus domínios reais (ADR-0009)
|
|
221
238
|
forja memory:compress # arquiva runs antigos + VACUUM
|
|
222
239
|
forja memory:extract # extrai conhecimento global da memória
|
|
@@ -229,6 +246,8 @@ forja release:check --publish # gate do tarball antes de publicar
|
|
|
229
246
|
forja project:smoke # gate do projeto gerado; --full instala e builda o backend
|
|
230
247
|
forja check:all # a bateria inteira de gates, um veredito; --full inclui os caros (SPEC-020)
|
|
231
248
|
forja project:dashboard # relatório estático de status
|
|
249
|
+
forja hook:session-start # o que o Claude Code roda ao abrir a sessão (briefing)
|
|
250
|
+
forja hook:user-prompt # o que roda a cada prompt (anexa a spec citada)
|
|
232
251
|
|
|
233
252
|
# Governança & auditoria
|
|
234
253
|
forja audit:sync # projeta a trilha de auditoria numa tabela consultável
|
|
@@ -279,6 +298,26 @@ projects/ LEGADO — não usar; projetos vivem no workspace externo
|
|
|
279
298
|
README.md
|
|
280
299
|
```
|
|
281
300
|
|
|
301
|
+
## Dentro de um projeto gerado
|
|
302
|
+
|
|
303
|
+
```
|
|
304
|
+
meu-projeto/
|
|
305
|
+
AGENTS.md # como operar o projeto — lido nativamente por Codex, Copilot agent, Gemini
|
|
306
|
+
CLAUDE.md, GEMINI.md # importam o AGENTS.md (+ .github/copilot-instructions.md para o Copilot)
|
|
307
|
+
.claude/
|
|
308
|
+
settings.json # hooks: forja hook:session-start / hook:user-prompt
|
|
309
|
+
agents/ # orchestrator, product, sdd-architect, context-engineer, governance, marketing
|
|
310
|
+
.mcp.json # servidor MCP do forja (+ codegraph quando instalado)
|
|
311
|
+
.codex/config.toml # MCP do forja no Codex · .gemini/settings.json (Gemini) · .vscode/mcp.json (Copilot)
|
|
312
|
+
.forja/models.json # cadeia de fallback entre IAs (troca de motor)
|
|
313
|
+
memory/ # memória hierárquica, indexada em memory/sqlite/ (fora do git)
|
|
314
|
+
specs/ # spec → plan → tasks
|
|
315
|
+
backend/ # NestJS 12, ESM + Vitest + oxlint (exceto com --skip-backend; ou o do --template)
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
A parte gerenciada pelo Forja em cada arquivo de instrução fica entre `<!-- forja:begin -->` e
|
|
319
|
+
`<!-- forja:end -->`; o que estiver fora é seu e sobrevive a `project:wire`/`project:upgrade`.
|
|
320
|
+
|
|
282
321
|
## Documentação
|
|
283
322
|
|
|
284
323
|
- [`DOC-MAP.md`](DOC-MAP.md) — mapa por papel e por tópico (comece aqui)
|
|
@@ -10,7 +10,7 @@ Uma API REST profissional com autenticação, validação, rate-limiting e teste
|
|
|
10
10
|
|
|
11
11
|
```bash
|
|
12
12
|
# 1. Criar projeto
|
|
13
|
-
|
|
13
|
+
forja project:new minha-api # o backend NestJS padrão do Forja é esta API REST
|
|
14
14
|
|
|
15
15
|
# 2. Setup
|
|
16
16
|
cd minha-api
|
|
@@ -39,9 +39,11 @@ agregado, orquestração no use-case, persistência na infra). Arquitetura como
|
|
|
39
39
|
## Rodando
|
|
40
40
|
|
|
41
41
|
```bash
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
npm
|
|
42
|
+
forja project:new pedidos --template clean-arch # cria o projeto a partir deste template
|
|
43
|
+
cd ~/forja-workspace/projects/pedidos/backend
|
|
44
|
+
npm run start:dev # sobe o Nest 12 (ESM; precisa de DATABASE_URL Postgres)
|
|
45
|
+
npm test # Vitest: testes de domínio — sem Postgres, sem Nest
|
|
46
|
+
npm run lint # oxlint
|
|
45
47
|
```
|
|
46
48
|
|
|
47
49
|
O `npm test` prova a premissa: a invariante do domínio (`test/orders/place-order.spec.ts`) roda
|
|
@@ -7,37 +7,35 @@
|
|
|
7
7
|
"start": "nest start",
|
|
8
8
|
"start:dev": "nest start --watch",
|
|
9
9
|
"start:prod": "node dist/main",
|
|
10
|
-
"
|
|
11
|
-
"
|
|
12
|
-
"test
|
|
13
|
-
"test:
|
|
14
|
-
"test:
|
|
10
|
+
"format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
|
|
11
|
+
"lint": "oxlint --type-aware src/ test/",
|
|
12
|
+
"test": "vitest run",
|
|
13
|
+
"test:watch": "vitest",
|
|
14
|
+
"test:cov": "vitest run --coverage"
|
|
15
15
|
},
|
|
16
16
|
"dependencies": {
|
|
17
|
-
"@nestjs/common": "^
|
|
18
|
-
"@nestjs/core": "^
|
|
19
|
-
"@nestjs/platform-express": "^
|
|
20
|
-
"@nestjs/typeorm": "^
|
|
17
|
+
"@nestjs/common": "^12.1.2",
|
|
18
|
+
"@nestjs/core": "^12.1.2",
|
|
19
|
+
"@nestjs/platform-express": "^12.1.2",
|
|
20
|
+
"@nestjs/typeorm": "^12.0.2",
|
|
21
21
|
"class-transformer": "^0.5.1",
|
|
22
22
|
"class-validator": "^0.14.1",
|
|
23
23
|
"pg": "^8.13.0",
|
|
24
24
|
"reflect-metadata": "^0.2.2",
|
|
25
|
-
"rxjs": "^7.8.
|
|
26
|
-
"typeorm": "^
|
|
25
|
+
"rxjs": "^7.8.2",
|
|
26
|
+
"typeorm": "^1.1.2"
|
|
27
27
|
},
|
|
28
28
|
"devDependencies": {
|
|
29
|
-
"@nestjs/
|
|
30
|
-
"@
|
|
31
|
-
"@
|
|
32
|
-
"
|
|
33
|
-
"
|
|
34
|
-
"
|
|
29
|
+
"@nestjs/cli": "^12.0.8",
|
|
30
|
+
"@nestjs/schematics": "^12.0.6",
|
|
31
|
+
"@nestjs/testing": "^12.1.2",
|
|
32
|
+
"@types/node": "^26.6.4",
|
|
33
|
+
"oxlint": "^1.87.0",
|
|
34
|
+
"oxlint-tsgolint": "^7.0.2003",
|
|
35
|
+
"prettier": "^3.9.9",
|
|
36
|
+
"typescript": "^6.0.3",
|
|
37
|
+
"vite-tsconfig-paths": "^6.1.1",
|
|
38
|
+
"vitest": "^5.0.3"
|
|
35
39
|
},
|
|
36
|
-
"
|
|
37
|
-
"moduleFileExtensions": ["js", "json", "ts"],
|
|
38
|
-
"rootDir": ".",
|
|
39
|
-
"testRegex": ".*\\.spec\\.ts$",
|
|
40
|
-
"transform": { "^.+\\.ts$": "ts-jest" },
|
|
41
|
-
"testEnvironment": "node"
|
|
42
|
-
}
|
|
40
|
+
"type": "module"
|
|
43
41
|
}
|
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
import { Module } from '@nestjs/common';
|
|
2
2
|
import { TypeOrmModule } from '@nestjs/typeorm';
|
|
3
|
-
import { OrdersModule } from './modules/orders/orders.module';
|
|
4
|
-
import { ProductsModule } from './modules/products/products.module';
|
|
5
|
-
import { OrderOrmEntity } from './modules/orders/infrastructure/order.orm-entity';
|
|
6
|
-
import { Product } from './modules/products/product.entity';
|
|
3
|
+
import { OrdersModule } from './modules/orders/orders.module.js';
|
|
4
|
+
import { ProductsModule } from './modules/products/products.module.js';
|
|
5
|
+
import { OrderOrmEntity } from './modules/orders/infrastructure/order.orm-entity.js';
|
|
6
|
+
import { Product } from './modules/products/product.entity.js';
|
|
7
7
|
|
|
8
8
|
@Module({
|
|
9
9
|
imports: [
|
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
import { NestFactory } from '@nestjs/core';
|
|
2
2
|
import { ValidationPipe } from '@nestjs/common';
|
|
3
|
-
import { AppModule } from './app.module';
|
|
3
|
+
import { AppModule } from './app.module.js';
|
|
4
4
|
|
|
5
5
|
async function bootstrap() {
|
|
6
6
|
const app = await NestFactory.create(AppModule);
|
|
7
7
|
app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true }));
|
|
8
8
|
await app.listen(process.env.PORT ?? 3000);
|
|
9
9
|
}
|
|
10
|
-
bootstrap();
|
|
10
|
+
await bootstrap();
|