forjajs 5.0.1 → 5.3.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 (268) hide show
  1. package/CHANGELOG.md +114 -2
  2. package/README.md +40 -5
  3. package/README.pt-BR.md +42 -4
  4. package/boilerplates/02-saas-starter/README.md +58 -293
  5. package/boilerplates/02-saas-starter/backend/.env.example +13 -0
  6. package/boilerplates/02-saas-starter/backend/.oxlintrc.json +8 -0
  7. package/boilerplates/02-saas-starter/backend/nest-cli.json +6 -0
  8. package/boilerplates/02-saas-starter/backend/package.json +32 -73
  9. package/boilerplates/02-saas-starter/backend/src/app.module.ts +16 -16
  10. package/boilerplates/02-saas-starter/backend/src/billing/adapters/http/billing.controller.ts +55 -0
  11. package/boilerplates/02-saas-starter/backend/src/billing/adapters/persistence/orm-entities.ts +28 -0
  12. package/boilerplates/02-saas-starter/backend/src/billing/adapters/persistence/typeorm-billing.repository.ts +46 -0
  13. package/boilerplates/02-saas-starter/backend/src/billing/application/billing.service.spec.ts +58 -0
  14. package/boilerplates/02-saas-starter/backend/src/billing/application/billing.service.ts +68 -0
  15. package/boilerplates/02-saas-starter/backend/src/billing/billing.module.ts +11 -0
  16. package/boilerplates/02-saas-starter/backend/src/billing/domain/plan.spec.ts +23 -0
  17. package/boilerplates/02-saas-starter/backend/src/billing/domain/plan.ts +36 -0
  18. package/boilerplates/02-saas-starter/backend/src/billing/domain/ports.ts +27 -0
  19. package/boilerplates/02-saas-starter/backend/src/billing/domain/subscription.spec.ts +28 -0
  20. package/boilerplates/02-saas-starter/backend/src/billing/domain/subscription.ts +47 -0
  21. package/boilerplates/02-saas-starter/backend/src/identity/adapters/http/auth.dto.ts +22 -0
  22. package/boilerplates/02-saas-starter/backend/src/identity/adapters/http/identity.controller.ts +59 -0
  23. package/boilerplates/02-saas-starter/backend/src/identity/adapters/persistence/orm-entities.ts +25 -0
  24. package/boilerplates/02-saas-starter/backend/src/identity/adapters/persistence/typeorm-identity.repository.ts +47 -0
  25. package/boilerplates/02-saas-starter/backend/src/identity/application/auth.service.spec.ts +72 -0
  26. package/boilerplates/02-saas-starter/backend/src/identity/application/auth.service.ts +63 -0
  27. package/boilerplates/02-saas-starter/backend/src/identity/domain/model.spec.ts +19 -0
  28. package/boilerplates/02-saas-starter/backend/src/identity/domain/model.ts +42 -0
  29. package/boilerplates/02-saas-starter/backend/src/identity/domain/password.spec.ts +17 -0
  30. package/boilerplates/02-saas-starter/backend/src/identity/domain/password.ts +26 -0
  31. package/boilerplates/02-saas-starter/backend/src/identity/identity.module.ts +12 -0
  32. package/boilerplates/02-saas-starter/backend/src/main.ts +19 -19
  33. package/boilerplates/02-saas-starter/backend/src/platform/auth/jwt-auth.guard.ts +17 -0
  34. package/boilerplates/02-saas-starter/backend/src/platform/auth/principal.ts +22 -0
  35. package/boilerplates/02-saas-starter/backend/src/platform/auth/roles.guard.spec.ts +23 -0
  36. package/boilerplates/02-saas-starter/backend/src/platform/auth/roles.guard.ts +20 -0
  37. package/boilerplates/02-saas-starter/backend/src/platform/auth/token.service.ts +54 -0
  38. package/boilerplates/02-saas-starter/backend/src/platform/config.spec.ts +18 -0
  39. package/boilerplates/02-saas-starter/backend/src/platform/config.ts +33 -0
  40. package/boilerplates/02-saas-starter/backend/src/platform/platform.module.ts +14 -0
  41. package/boilerplates/02-saas-starter/backend/tsconfig.build.json +6 -0
  42. package/boilerplates/02-saas-starter/backend/tsconfig.json +16 -21
  43. package/boilerplates/02-saas-starter/backend/vitest.config.ts +7 -0
  44. package/boilerplates/02-saas-starter/boilerplate.manifest.json +19 -14
  45. package/boilerplates/02-saas-starter/docker-compose.yml +10 -24
  46. package/boilerplates/02-saas-starter/memory/30-domains/billing/context.md +15 -132
  47. package/boilerplates/02-saas-starter/memory/30-domains/identity/context.md +20 -0
  48. package/boilerplates/README.md +9 -10
  49. package/dist/apps/cli/src/index.d.ts +0 -1
  50. package/dist/apps/cli/src/index.js +43 -32
  51. package/dist/apps/dashboard/app/api/forja/[...path]/route.js +34 -1
  52. package/dist/apps/dashboard/app/api/forja/capabilities.d.ts +26 -0
  53. package/dist/apps/dashboard/app/api/forja/capabilities.js +39 -0
  54. package/dist/apps/dashboard/app/dashboard-client.jsx +607 -42
  55. package/dist/apps/server/src/forja-nest.module.d.ts +6 -0
  56. package/dist/apps/server/src/forja-nest.module.js +55 -0
  57. package/dist/apps/server/src/main.d.ts +21 -4
  58. package/dist/apps/server/src/main.js +79 -57
  59. package/dist/apps/server/src/task-planning-service.d.ts +29 -0
  60. package/dist/apps/server/src/task-planning-service.js +195 -0
  61. package/dist/apps/server/src/task-runtime-coordinator.d.ts +57 -0
  62. package/dist/apps/server/src/task-runtime-coordinator.js +229 -0
  63. package/dist/bin/forja.js +3 -2
  64. package/dist/bin/init-project.js +1 -0
  65. package/dist/lib/agent-evals.d.ts +138 -0
  66. package/dist/lib/agent-evals.js +349 -0
  67. package/dist/lib/cli-output.js +14 -2
  68. package/dist/lib/code-context.d.ts +33 -5
  69. package/dist/lib/code-context.js +70 -5
  70. package/dist/lib/context-builder.d.ts +49 -4
  71. package/dist/lib/context-builder.js +114 -47
  72. package/dist/lib/core/coverage-gate.d.ts +59 -0
  73. package/dist/lib/core/coverage-gate.js +58 -0
  74. package/dist/lib/core/doc-graph.d.ts +38 -0
  75. package/dist/lib/core/doc-graph.js +83 -0
  76. package/dist/lib/core/health.js +286 -5
  77. package/dist/lib/core/journey.js +36 -0
  78. package/dist/lib/core/registry.js +81 -6
  79. package/dist/lib/docs-reference.d.ts +35 -0
  80. package/dist/lib/docs-reference.js +57 -0
  81. package/dist/lib/generators/memory-generator.d.ts +0 -11
  82. package/dist/lib/generators/memory-generator.js +5 -161
  83. package/dist/lib/generators/readme-generator.js +1 -1
  84. package/dist/lib/llm/json-output.d.ts +14 -0
  85. package/dist/lib/llm/json-output.js +77 -0
  86. package/dist/lib/project-wiring.d.ts +8 -0
  87. package/dist/lib/project-wiring.js +79 -3
  88. package/dist/lib/session-memory.d.ts +38 -0
  89. package/dist/lib/session-memory.js +206 -0
  90. package/dist/lib/spec-trace.d.ts +46 -0
  91. package/dist/lib/spec-trace.js +184 -0
  92. package/dist/lib/validators/structure-validator.js +0 -1
  93. package/dist/packages/adapter-nest/src/index.d.ts +2 -1
  94. package/dist/packages/adapter-nest/src/index.js +59 -1
  95. package/dist/packages/adapter-sqlite/src/index.d.ts +15 -1
  96. package/dist/packages/adapter-sqlite/src/index.js +61 -1
  97. package/dist/packages/context/src/index.d.ts +2 -0
  98. package/dist/packages/context/src/index.js +36 -15
  99. package/dist/packages/contracts/src/index.d.ts +64 -0
  100. package/dist/packages/core/src/index.d.ts +9 -1
  101. package/dist/packages/core/src/index.js +28 -3
  102. package/dist/packages/graph/src/index.js +14 -5
  103. package/dist/packages/llm/src/index.js +12 -2
  104. package/dist/packages/mcp/src/index.d.ts +8 -0
  105. package/dist/packages/mcp/src/index.js +12 -1
  106. package/dist/packages/observability/src/index.d.ts +11 -0
  107. package/dist/packages/observability/src/index.js +3 -0
  108. package/dist/packages/orchestration/src/index.d.ts +15 -1
  109. package/dist/packages/orchestration/src/index.js +127 -21
  110. package/dist/packages/planner/src/index.d.ts +7 -1
  111. package/dist/packages/planner/src/index.js +67 -10
  112. package/dist/packages/planner/src/proposal-store.d.ts +30 -0
  113. package/dist/packages/planner/src/proposal-store.js +109 -0
  114. package/dist/packages/policy/src/index.d.ts +9 -16
  115. package/dist/packages/policy/src/index.js +114 -31
  116. package/dist/packages/runtime/src/index.d.ts +16 -2
  117. package/dist/packages/runtime/src/index.js +176 -61
  118. package/dist/scripts/build-smart-context.d.ts +2 -0
  119. package/dist/scripts/build-smart-context.js +12 -3
  120. package/dist/scripts/code-context.d.ts +3 -1
  121. package/dist/scripts/code-context.js +13 -3
  122. package/dist/scripts/coverage-gate.d.ts +2 -0
  123. package/dist/scripts/coverage-gate.js +101 -0
  124. package/dist/scripts/eval-agents.d.ts +11 -0
  125. package/dist/scripts/eval-agents.js +96 -0
  126. package/dist/scripts/gen-commands-doc.d.ts +2 -0
  127. package/dist/scripts/gen-commands-doc.js +18 -0
  128. package/dist/scripts/hook-session-memory.d.ts +9 -0
  129. package/dist/scripts/hook-session-memory.js +20 -0
  130. package/dist/scripts/hook-session-start.js +34 -0
  131. package/dist/scripts/llm-fit.js +23 -1
  132. package/dist/scripts/spec-trace.d.ts +10 -0
  133. package/dist/scripts/spec-trace.js +73 -0
  134. package/dist/scripts/sync-universal-memory.js +69 -4
  135. package/dist/scripts/token-benchmark.d.ts +33 -1
  136. package/dist/scripts/token-benchmark.js +179 -5
  137. package/dist/scripts/token-economy.js +3 -1
  138. package/dist/scripts/tools-doctor.d.ts +16 -1
  139. package/dist/scripts/tools-doctor.js +58 -17
  140. package/docs/commands.md +155 -0
  141. package/docs/fluxo.md +11 -7
  142. package/docs/init-project.md +3 -1
  143. package/docs/llm-fit-loop.md +36 -0
  144. package/docs/manual-operacional-cli-sdd-gsd.md +3 -2
  145. package/docs/produto/factsheet-marketing.md +7 -5
  146. package/docs/produto/roteiro-demo.md +14 -5
  147. package/docs/quick-reference.md +3 -3
  148. package/docs/token-optimization.md +10 -6
  149. package/memory/90-decisions/0088-templates-validados.md +3 -0
  150. package/memory/90-decisions/0089-skills-do-projeto.md +51 -0
  151. package/memory/90-decisions/0090-adapters-de-agente-somente-leitura.md +47 -0
  152. package/memory/90-decisions/0091-memoria-de-sessao-por-hooks.md +40 -0
  153. package/memory/90-decisions/0092-criterios-de-aceite-ligados-a-testes.md +37 -0
  154. package/memory/90-decisions/0093-avaliacoes-com-agentes-reais.md +40 -0
  155. package/package.json +4 -2
  156. package/specs/avaliacoes-de-agentes/spec.md +52 -0
  157. package/specs/criterios-ligados-a-testes/spec.md +42 -0
  158. package/specs/memoria-de-sessao/spec.md +48 -0
  159. package/specs/skills-do-projeto/plan.md +40 -0
  160. package/specs/skills-do-projeto/spec.md +63 -0
  161. package/specs/skills-do-projeto/tasks.md +27 -0
  162. package/specs/v6-agent-runtime-portable/spec.md +83 -0
  163. package/specs/v6-core-consolidation/spec.md +70 -0
  164. package/specs/v6-docs-drift/spec.md +85 -0
  165. package/specs/v6-quality-gates/spec.md +99 -0
  166. package/specs/v6-token-economy/spec.md +84 -0
  167. package/templates/evals/agents/adr.json +25 -0
  168. package/templates/evals/agents/memoria.json +32 -0
  169. package/templates/evals/agents/proxima-acao.json +29 -0
  170. package/templates/evals/agents/spec-nova.json +26 -0
  171. package/templates/evals/agents/teste-do-criterio.json +29 -0
  172. package/templates/project/AGENTS.md +16 -0
  173. package/templates/project/CLAUDE.md +3 -2
  174. package/templates/project/agents/context-engineer.md +3 -0
  175. package/templates/project/agents/governance.md +3 -0
  176. package/templates/project/agents/marketing.md +3 -0
  177. package/templates/project/agents/orchestrator.md +3 -0
  178. package/templates/project/agents/product.md +3 -0
  179. package/templates/project/agents/sdd-architect.md +3 -0
  180. package/templates/project/skills/README.md +14 -0
  181. package/templates/project/skills/accessibility-review/SKILL.md +89 -0
  182. package/templates/project/skills/api-design/SKILL.md +77 -0
  183. package/templates/project/skills/architecture-decision-record/SKILL.md +92 -0
  184. package/templates/project/skills/backlog-slicing/SKILL.md +82 -0
  185. package/templates/project/skills/bounded-context-mapping/SKILL.md +88 -0
  186. package/templates/project/skills/ci-pipeline-review/SKILL.md +83 -0
  187. package/templates/project/skills/commit-message/SKILL.md +143 -0
  188. package/templates/project/skills/data-migrations/SKILL.md +88 -0
  189. package/templates/project/skills/dependency-upgrade/SKILL.md +75 -0
  190. package/templates/project/skills/docker-compose-review/SKILL.md +85 -0
  191. package/templates/project/skills/domain-modeling/SKILL.md +120 -0
  192. package/templates/project/skills/event-storming/SKILL.md +95 -0
  193. package/templates/project/skills/executive-writing/SKILL.md +99 -0
  194. package/templates/project/skills/frontend-architecture/SKILL.md +97 -0
  195. package/templates/project/skills/incident-postmortem/SKILL.md +93 -0
  196. package/templates/project/skills/lgpd-compliance/SKILL.md +108 -0
  197. package/templates/project/skills/llm-provider-routing/SKILL.md +18 -0
  198. package/templates/project/skills/observability/SKILL.md +93 -0
  199. package/templates/project/skills/product-evaluation/SKILL.md +130 -0
  200. package/templates/project/skills/prompt-spec/SKILL.md +83 -0
  201. package/templates/project/skills/pull-request/SKILL.md +101 -0
  202. package/templates/project/skills/query-performance/SKILL.md +83 -0
  203. package/templates/project/skills/release-checklist/SKILL.md +106 -0
  204. package/templates/project/skills/release-notes/SKILL.md +87 -0
  205. package/templates/project/skills/requirements-elicitation/SKILL.md +127 -0
  206. package/templates/project/skills/requirements-gathering/SKILL.md +134 -0
  207. package/templates/project/skills/technical-spike/SKILL.md +101 -0
  208. package/templates/project/skills/testing/SKILL.md +109 -0
  209. package/templates/project/skills/threat-modeling/SKILL.md +87 -0
  210. package/templates/project/skills/ts-async-patterns/SKILL.md +101 -0
  211. package/templates/project/skills/ts-code-review/SKILL.md +121 -0
  212. package/templates/project/skills/ts-module-layout/SKILL.md +104 -0
  213. package/templates/project/skills/ts-testing/SKILL.md +89 -0
  214. package/templates/project/skills/web-performance/SKILL.md +72 -0
  215. package/boilerplates/02-saas-starter/.env.example +0 -25
  216. package/boilerplates/02-saas-starter/CHECKLIST-CRIACAO.md +0 -190
  217. package/boilerplates/02-saas-starter/INFO.md +0 -252
  218. package/boilerplates/02-saas-starter/QUICK_START.md +0 -194
  219. package/boilerplates/02-saas-starter/START-HERE.md +0 -259
  220. package/boilerplates/02-saas-starter/backend/src/common/decorators/roles.decorator.ts +0 -3
  221. package/boilerplates/02-saas-starter/backend/src/common/decorators/tenant.decorator.ts +0 -6
  222. package/boilerplates/02-saas-starter/backend/src/common/middleware/roles.guard.ts +0 -23
  223. package/boilerplates/02-saas-starter/backend/src/config/database.ts +0 -26
  224. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.controller.ts +0 -46
  225. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.module.ts +0 -25
  226. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.service.ts +0 -145
  227. package/boilerplates/02-saas-starter/backend/src/modules/auth/dto/auth.dto.ts +0 -30
  228. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/jwt.strategy.ts +0 -24
  229. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/local.strategy.ts +0 -19
  230. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.controller.ts +0 -42
  231. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.module.ts +0 -13
  232. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.service.ts +0 -67
  233. package/boilerplates/02-saas-starter/backend/src/modules/billing/entities/invoice.entity.ts +0 -52
  234. package/boilerplates/02-saas-starter/backend/src/modules/organizations/entities/organization.entity.ts +0 -36
  235. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.controller.ts +0 -16
  236. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.module.ts +0 -13
  237. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.service.ts +0 -34
  238. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/entities/subscription.entity.ts +0 -40
  239. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.controller.ts +0 -36
  240. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.module.ts +0 -13
  241. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.service.ts +0 -91
  242. package/boilerplates/02-saas-starter/backend/src/modules/users/entities/user.entity.ts +0 -42
  243. package/boilerplates/02-saas-starter/backend/src/modules/users/users.controller.ts +0 -14
  244. package/boilerplates/02-saas-starter/backend/src/modules/users/users.module.ts +0 -13
  245. package/boilerplates/02-saas-starter/backend/src/modules/users/users.service.ts +0 -48
  246. package/boilerplates/02-saas-starter/memory/00-global/agent-contract.md +0 -227
  247. package/boilerplates/02-saas-starter/memory/00-global/context-policy.md +0 -141
  248. package/boilerplates/02-saas-starter/memory/00-global/index.md +0 -133
  249. package/boilerplates/02-saas-starter/memory/00-global/mission.md +0 -45
  250. package/boilerplates/02-saas-starter/memory/00-global/patterns.md +0 -223
  251. package/boilerplates/02-saas-starter/memory/10-product/business-rules.md +0 -240
  252. package/boilerplates/02-saas-starter/memory/10-product/nfrs.md +0 -239
  253. package/boilerplates/02-saas-starter/memory/10-product/personas.md +0 -195
  254. package/boilerplates/02-saas-starter/memory/10-product/vision.md +0 -63
  255. package/boilerplates/02-saas-starter/memory/20-architecture/overview.md +0 -232
  256. package/boilerplates/02-saas-starter/memory/30-domains/auth/api.md +0 -186
  257. package/boilerplates/02-saas-starter/memory/30-domains/auth/context.md +0 -85
  258. package/boilerplates/02-saas-starter/memory/30-domains/billing/api.md +0 -262
  259. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/api.md +0 -176
  260. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/context.md +0 -100
  261. package/boilerplates/02-saas-starter/memory/40-delivery/backlog.md +0 -81
  262. package/boilerplates/02-saas-starter/memory/40-delivery/roadmap.md +0 -97
  263. package/boilerplates/02-saas-starter/memory/40-delivery/sprint-atual.md +0 -57
  264. package/boilerplates/02-saas-starter/memory/50-orchestration/topology.md +0 -90
  265. package/boilerplates/02-saas-starter/memory/60-runs/index.md +0 -54
  266. package/boilerplates/02-saas-starter/memory/70-summaries/global.md +0 -50
  267. package/boilerplates/02-saas-starter/memory/80-data/schema.md +0 -185
  268. package/boilerplates/02-saas-starter/memory/90-decisions/adr-template.md +0 -75
@@ -0,0 +1,99 @@
1
+ # Spec: v6-quality-gates
2
+
3
+ - **ID**: SPEC-056
4
+ - **Status**: implementing
5
+ - **Owner**: allanpablo
6
+ - **Criado em**: 2026-11-05
7
+ - **Sprint alvo**: v6.0 Wave 1
8
+ - **ADRs relacionadas**: a criar em memory/90-decisions/
9
+
10
+ ## 1. Problema
11
+ O forja vende gates de qualidade para os projetos que adota, mas não aplica todos a si mesmo. Estado validado em 2026-11-05 (`.github/workflows/ci.yml`, v5.2.0):
12
+
13
+ - CI roda **100% em ubuntu-latest** — o framework é usado em macOS e Windows (paths, `bin:` shells, cópia de skills), e regressões de plataforma só aparecem na máquina do usuário. O próprio `lib/paths.ts` documenta histórico de bug de raiz dupla (v1.6.1, v4.x, 18 scripts).
14
+ - **Sem lint do próprio repo e sem coverage** — `any` explícito aparece **359×** no código-fonte (medição da máquina desta spec, não grep de linha), `process.exit(1)` em 32 arquivos, e `cli-output.ts` é usado em apenas 8 de 54 scripts sem que nada sinalize a tendência.
15
+ - A suíte nunca foi rodada sob instrumentação de cobertura, e é justamente aí que um defeito real do contrato `--json` estava escondido (ver Evidências: stdout truncado em 64KB com exit 0).
16
+
17
+ Quem sente: mantenedor (regressões descobertas tarde), usuários Windows/macOS (bugs de plataforma), agentes de IA (saída inconsistente — e às vezes cortada — entre scripts).
18
+
19
+ ## 2. Proposta de valor
20
+ CI que roda a suíte em matriz multi-OS e cobra, a cada push, dois ratchets versionados em `lib/core/quality-budget.json`: teto de `any` explícito (check `type-debt` no doctor) e piso de cobertura de linhas (`forja quality:coverage`, com a cobertura nativa do Node). Sem ESLint e sem c8 de propósito: adotar toolchain nova para medir o que uma regex e o `--experimental-test-coverage` já medem é importar uma segunda máquina — o defeito que a SPEC-058 ataca. Qualidade do próprio forja passa a ser medida a cada push, como ele exige dos projetos que adota.
21
+
22
+ ## 3. User stories
23
+ - **Como** usuário Windows/macOS, **quero** que o CI rode nos três SOs, **para que** bugs de caminho/shell sejam pegos antes do release.
24
+ - **Como** maintainer, **quero** um teto de `any` e piso de coverage versionados, **para que** a dívida de tipos não cresça silenciosamente.
25
+ - **Como** contribuidor, **quero** feedback de lint no PR, **para que** eu corrija antes do review humano.
26
+
27
+ ## 4. Critérios de aceite (Definition of Done)
28
+ - [x] AC-1: Job `test` roda em matriz multi-OS (`ubuntu-latest` × Node 22/24, `macos-latest` e `windows-latest` × Node 24) com `fail-fast: false`; falha em qualquer célula bloqueia.
29
+ - [x] AC-2: Check `type-debt` no catálogo do doctor conta `any` explícito (`: any`, `as any`, `<any>`, `any[]`) em `bin/lib/scripts/apps` (`.ts`/`.tsx`, fora `.d.ts`, com template literals descartados) e compara com `anyCeiling` versionado em `lib/core/quality-budget.json`: acima do teto → `critical` fail; abaixo → `warn` mandando descer o teto. Sem ESLint.
30
+ - [x] AC-3: `forja quality:coverage` roda **a mesma suíte** com `--experimental-test-coverage`, lê a linha `all files` da tabela e cobra `coverageLineFloor` (exit 2 abaixo do piso, exit 1 se a suíte falhar, `--json` no contrato do ADR-0082). O CI usa esse passo na célula ubuntu **no lugar** de `npm test` — custo adicional zero.
31
+ - [ ] AC-4: Testes que dependem de comportamento unix (permissões, `bin:` shells) têm skip condicional explícito e justificado, não falha silenciosa — a levantar pela primeira rodada verde/vermelha das células macOS/Windows. **Levantado (2026-11-06)**: macOS 665/665; Windows 23 → 14 → 11 → 10 em quatro rodadas, com 7 causas de produto/robustez fechadas no caminho e o *skip justificado* escrito para o caso SIGTERM. Restam 3 causas no inventário — uma delas (runtime de agentes) é lacuna de produto, não teste. Ver Evidências.
32
+ - [x] AC-5: Tempo total do CI não cresce por causa das réguas: a cobertura substitui o passo de teste no ubuntu (não soma), e as células novas rodam em paralelo.
33
+ - [x] AC-6: O stdout do contrato `--json` nunca sai truncado — `lib/cli-output.ts` escreve com `fs.writeSync` em laço antes do `process.exit()`, com teste de regressão de payload de 400KB (6× o buffer do pipe).
34
+
35
+ ## 5. Escopo
36
+ **Dentro**:
37
+ - `.github/workflows/ci.yml`: matriz OS/Node do job `test`, passo de cobertura no ubuntu.
38
+ - `lib/core/quality-budget.json` (novo): `anyCeiling` + `coverageLineFloor` versionados.
39
+ - Check `type-debt` em `lib/core/health.ts` (`scope: 'repo'`, `critical`).
40
+ - `scripts/coverage-gate.ts` (novo) + entrada `quality:coverage` no registry + script npm `test:coverage`; a leitura da tabela e a decisão de código de saída em `lib/core/coverage-gate.ts`, para que o critério tenha teste sem rodar a suíte dentro da suíte.
41
+ - Correção do truncamento de stdout em `lib/cli-output.ts` (+ fixture e teste).
42
+ - Testes em `test/health.test.js` (6), `test/cli-output.test.js` (1), `test/coverage-gate.test.js` (10) e `test/ci-workflow.test.js` (7).
43
+
44
+ **Fora**:
45
+ - ESLint/`typescript-eslint` e c8/istanbul: nada de toolchain nova para medir o que o `tsc` e o runner nativo já medem.
46
+ - Refatorar os 359 `any` existentes (Wave 2/3 — aqui só o teto; SPEC-058).
47
+ - Substituir `process.exit(1)`/consolidar `cli-output` nos 54 scripts (SPEC-058).
48
+ - Codecov/serviço externo — a tabela do Node já vai para o log do CI.
49
+ - `release-gate`, `project-smoke-ai`, `project-smoke-full`: continuam ubuntu (o custo deles é compilar better-sqlite3, e replicar isso em três SOs não prova mais).
50
+
51
+ ## 6. NFRs / restrições
52
+ - Performance: matriz em paralelo com cache de npm por SO; `quality:coverage` custa o mesmo que `npm test` (é a mesma suíte).
53
+ - Custo: minutos de Actions dentro do free tier para repo público (4 células no job `test`, antes 2).
54
+ - Compatibilidade: não muda `release:check`, `tools:doctor`, `project:smoke` existentes; `type-debt` é `scope: 'repo'`, logo não toca o orçamento de 5s do hook SessionStart.
55
+ - Portabilidade: o contador de `any` emite caminho relativo com `/` (independente do SO), e a suíte já depende só do runner do Node — `npm test` funciona no Windows porque o Node expande o glob `test/*.test.js` sem shell (verificado localmente).
56
+
57
+ ## 7. Riscos e mitigação
58
+ | Risco | Probabilidade | Impacto | Mitigação |
59
+ |---|---|---|---|
60
+ | Testes falharem só em Windows/macOS por paths/shell | M | A | **Realizado na primeira rodada**: macOS limpo, 23 falhas no Windows — 3 causas de produto consertadas (paths POSIX, CRLF, limpeza de temp) e o resto em inventário não-bloqueante. Ver Evidências. |
61
+ | Ratchet de `any` bloquear PR legítimo | M | B | Teto = contagem atual (359); só impede crescimento, e subir o teto exige commit próprio justificado |
62
+ | Piso de cobertura oscilar entre SOs e dar falso vermelho | M | B | A régua roda só no ubuntu; piso 87 contra 87,45 medido dá folga, e branch/function não bloqueiam. **Realizado, mas por outro caminho**: a oscilação veio do próprio Node (blocos de processos-filho no agregado) — ver Evidências; piso re-ancorado em medição determinística. |
63
+ | CI mais lento desestimular contribuição | B | B | Células em paralelo + cache; AC-5 mede |
64
+
65
+ ## 8. Métricas de sucesso
66
+ 30 dias após: zero releases com regressão exclusiva de Windows/macOS; `any` ≤ 357 e caindo; cobertura de linhas ≥ 90% em todo PR, com o número se repetindo igual entre execuções; nenhum `--json` truncado.
67
+
68
+ ## Evidências e estado real
69
+ Medições de 2026-11-05, branch `feat/v6-wave1`:
70
+
71
+ - **Diagnóstico**: leitura direta de `ci.yml` (5 jobs, todos `ubuntu-latest`) e contagem medida pela própria máquina nova — **359 `any` explícitos** (o grep ingênuo de linhas dava 301 e o de ocorrências 388; a diferença são template literals de geradores de boilerplate, `.d.ts` e `node_modules`, que o check descarta). Maiores arquivos listados no detail do check.
72
+ - **Cobertura baseline**: `node --test --experimental-test-coverage` → `all files | 86.40 | 74.18 | 77.85` na primeira medição (com 1 teste falho) e **87.45% de linhas** após o reparo abaixo → piso fixado em **87**.
73
+ - **A régua media ruído (achado da Wave 1, 2026-11-05)**: a suíte inteira, dois commits depois, dava `85,71 / 86,09 / 86,50 / 86,96 / 87,33` em execuções *idênticas*, e o gate ficava vermelho ou verde conforme a sorte. Causa raiz, isolada por pares de execução: com `--experimental-test-coverage` o runner expõe `NODE_V8_COVERAGE` e **todo CLI filho herda** — dezenas de processos escrevem blocos parciais dos mesmos arquivos no diretório de agregação, e o agregador do Node não faz união. Reprodução mínima: `packages/adapter-nest/src/index.ts` apareceu **100,00%** numa execução e **51,09%** na seguinte, com branches (70,30) e funções (63,16) idênticos, e o conjunto de arquivos da tabela mudando entre execuções. Um número que muda sem que nada mude não é uma régua: `test/isolate-workspace.mjs` passou a retirar `NODE_V8_COVERAGE` do ambiente (o processo de teste continua medindo a si mesmo; os filhos param de contaminar a agregação), a medição ficou **bit a bit reproduzível** (`91,80 | 79,8x | 87,99` em duas execuções seguidas, exit 0 nas duas) e o piso subiu de 87 para **90** — folga de 1,8pp para a variação entre SOs/Node que só a CI vai medir. `--test-concurrency=1` não muda nada: a instabilidade não é de agendamento.
74
+ - **Bug real achado pela instrumentação** (e não pela suíte normal): `contrato: spec:trace --json` falhava **só sob cobertura** com `SyntaxError: Unterminated string in JSON at position 64695`. Causa raiz reproduzida fora do teste — `process.stdout.write(json)` seguido de `process.exit()` trunca no buffer do pipe: payload de 400KB saía com **65536 bytes e exit 0**. Ou seja: qualquer comando `json:true` com resposta grande devolvia JSON cortado para o agente que o consumia, sem sinal de erro. Reparo: escrita síncrona no fd 1 em laço (`lib/cli-output.ts`), regressão coberta por `test/cli-output.test.js` + fixture `big`. Sob cobertura, a suíte voltou a 100%.
75
+ - **Estado final**: `forja quality:coverage` → `OK cobertura de linhas 87.45% (piso 87%) · branches 74.28% · funções 77.92%`, exit 0. `forja tools:doctor` → `OK type-debt 359 any explícitos, no teto (359)`. `npm run types:check` → 0 erros. `test/health.test.js` + `test/cli-output.test.js` → **82/82 verdes**.
76
+ - **AC-4 levantado pela primeira rodada das células (2026-11-06, PR #83)**: `macos-latest` passou **665/665** — a aposta de que o macOS era a plataforma de risco não se sustentou; quem trouxe defeito foi o `windows-latest`, com **23 falhas em 665**. Era exatamente o que a célula existia para caçar: nenhuma delas aparecia em ubuntu.
77
+ - **Consertado na hora (causa no produto, não no teste)**:
78
+ 1. *Separador de caminho no pack* — `lib/code-context.ts` e `lib/context-builder.ts` emitiam `path.relative()` cru, então o mesmo domínio produzía `backend\src\...` no Windows e `backend/src/...` no resto. O pacote é texto colado no contexto de um agente: agora é POSIX nos dois (`relFrom()`; `**Path**` do `context:smart` normalizado na renderização). Derrubava `code-context.test.js:123`, `:232` e o contrato do `modo task`.
79
+ 2. *CRLF no frontmatter das skills* — `skillProblem()` exigia `\n` literal (`lib/project-wiring.ts:59`); no checkout Windows toda a validação de skills virava ruído ("frontmatter sem name/description" em 34/34), e o que isso puxava era o `project:new`/`project:wire` falhando — ou seja, a jornada inteira do usuário gerava projeto quebrado só por causa do separador de linha. Aceita `\r?\n`, com regressão que força o CRLF.
80
+ 3. *`rmSync` do diretório temp* — EPERM transitório no Windows com SQLite recém-fechado; a limpeza do `test/memory-index.test.js` ganhou retry.
81
+ - **Rodada 2 (23 → 14), rodada 3 (14 → 11, com 1 skip justificado) e rodada 4 (11 → 10)**. As causas 1-3 caíram como previsto; a 4 não caiu na primeira tentativa e caiu na segunda; e a célula passou a medir 666 com 1 skipped. As restantes se agruparam em quatro causas — três delas defeito de produto, não de teste:
82
+ 4. *Forma do caminho do nó* — em Windows o mesmo arquivo era indexado com outra identidade: `memory/00-global/mission.md` em vez de `projects/demo/memory/00-global/mission.md`. Dois atalhos unix-cêntricos no sync, isolados por inferência e confirmados pela forma do sintoma: `path.relative()` entre **unidades diferentes** devolve caminho absoluto (e o teste de "está fora" era `startsWith('..')`, que deixa o absoluto passar), e o `os.tmpdir()` do runner chega como nome **8.3** (`RUNNER~1`) enquanto o walk devolve a forma longa. A chave do nó alimenta busca, dedupe e o classificador de tipo — não era detalhe de exibição. Primeira tentativa (só `realpathSync` dos dois lados) não bastou; o que fecha é seleção por **contenção** (`inside()` com `path.isAbsolute`), com a forma canônica como segundo passo. Em unix o caminho direto vence, então nada mudou localmente — e a rodada 4 é o que prova: o contrato do `modo task` e o `sync:universal` passaram, e o `code:context` já tinha passado na rodada 2. **Regra que ficou do jeito errado da tentativa**: `startsWith('..')` não é teste de contenção; o repo já fazia certo em `lib/workspace.ts:263`, `lib/session-memory.ts:43` e `scripts/build-smart-context.ts:52` (`!rel || startsWith('..') || isAbsolute`). O sync era o único lugar com a versão incompleta — o `inside()` novo segue a convenção que já existia, não uma regra inventada aqui.
83
+ 5. *CRLF na régua de derivação de doc* — `commands-ref` comparava `docs/commands.md` byte a byte com o renderizado; em checkout CRLF isso é "diverge" falso, e o `tools:doctor` do repo ficava vermelho sem nada estar velho. A comparação normaliza `\r\n`. **Regra geral que ficou**: o framework valida texto de *projeto do usuário*, que chega em CRLF seja lá o que a gente fizer no nosso repo — tolerar é o certo, `.gitattributes` não resolve o mundo.
84
+ 6. *Handle vazado no próprio teste* — o `antes` do teste de sync incremental abria uma conexão `readonly` e nunca fechava. Em unix é inocente; em Windows tranca o `.db` até o processo do runner acabar, e o `rmSync` do temp volta EPERM **para sempre** (a retry de 10×100ms da rodada 1 só provou que não era transitório). Fecha na leitura.
85
+ 7. *Sinal POSIX* — `test/server-shutdown.test.js` manda SIGTERM num filho: o sinal não existe em Windows e o probe usa `--import tsx`, opção de runtime que a célula não resolve. Este é o **skip explícito e justificado** que o AC-4 pedia, não um conserto; o contrato continua provado nas células unix. Está marcado como skipped na rodada 3, não como aprovado.
86
+ - **Inventário aberto (a célula está `continue-on-error` só por isto)** — 3 causas, 10 casos na rodada 4:
87
+ - *Runtime de agentes é unix por construção* (6 casos na rodada 4: `test/llm-resume-validation.test.js:142` com `spawn EFTYPE`; `test/agent-evals.test.js:85` e os AC-4/AC-5/AC-6 com `agent.args` nunca escrito; `test/llm-claude-adapter.test.js:99`; `test/llm-integration.test.js:111` — e os 2 casos do AC-1, que eram desta mesma família e ficaram verdes na rodada 2, o que confirma que a causa deles era o CRLF das skills e não o stub). Os testes modelam o CLI do agente como script com shebang, e é assim que ele falha — mas a causa é do produto, em três lugares lidos no código, não chutados do log:
88
+ - `scripts/llm-fit.ts:76,84,91,104,108` sondam o binário com **`shell: false`** explícito. Em Windows o shim que `npm i -g` instala é `codex.cmd`/`claude.cmd`, e Node recusa spawnar `.cmd` sem `shell: true` (endurecimento da CVE-2024-27980). O `llm:probe` não tem como reportar features de um agente instalado nesse SO.
89
+ - `lib/agent-evals.ts:254` executa o check `type: 'command'` com **`spawnSync('sh', ['-c', …])`** — sem `sh`, o check inteiro é inaplicável.
90
+ - `lib/agent-evals.ts:177,183` spawnam o binário direto, mesma restrição do probe.
91
+ Não é para pular: é portabilidade do `llm:run`/`llm:probe`/`eval:agents`, e merece spec própria — redigida em 2026-11-08 como **SPEC-059 (`specs/v6-agent-runtime-portable`, Wave 2)**: caminho resolvido por `where`/`PATHEXT`, `sh -c` trocado por launcher de shell portável, e o kill do timeout derrubando a árvore.
92
+ - *`git worktree`*: os 3 de `test/simulate-cli.test.js` (o `worktree list` antes/depois não fecha igual).
93
+ - *`spec:trace` sem critérios no projeto gerado*: único resto da `jornada` nas quatro rodadas, que já ficou verde em `project:new`, `project:wire`, `context:smart` e `tools:doctor` — as causas 1/2/5 eram a jornada. O que a rodada 4 permite **eliminar**: não é a família do separador de caminho (`loadSpecs` lê o slug por `readdirSync`, e `listFiles` usa `git ls-files`, que fala POSIX por protocolo), não é CRLF na leitura do checklist (`AC_LINE` termina em `(.+)$`, que engole o `\r`), e não é a contagem de *tokens por critério* (AC-7 da SPEC-053) — `0/0` vem de `trace.totals`, antes de qualquer preço. O que fica de hipótese, sem prova: `specs/` vazio ou `readdirSync` lançando no `root` resolvido pela CLI em Windows (a função devolve `[]` nesse caso, e `0/0` é exatamente o que isso produz). Precisa de uma célula com diagnostico impresso, não de mais um patch adivinhado.
94
+ - **Regra de saída**: tirar `continue-on-error` da matriz é o gate de que o inventário zerou. A linha existe no `ci.yml` com esta frase ao lado, para não virar mobília.
95
+ - **Rastreabilidade fechada (2026-11-09)**: `spec:trace v6-quality-gates` marcava **1/6** critérios com teste, embora AC-1/2/3/5/6 estivessem implementados e dois deles já tivessem teste real. Duas causas diferentes, tratadas de forma diferente:
96
+ - *Faltava a citação, não o teste* (AC-2, AC-6): os 6 testes do ratchet `type-debt` em `test/health.test.js` e o payload de 400KB em `test/cli-output.test.js` já provavam o critério — só não escreviam `SPEC-056 AC-n`, que é o que o trace lê. Marcados. Nenhum teste novo: inventar um segundo teste para o mesmo comportamento inflaria a métrica sem aumentar a garantia.
97
+ - *Faltava teste mesmo* (AC-3): a régua vivia inteira dentro de `scripts/coverage-gate.ts`, cujo caminho de execução é spawnar a suíte — testá-lo de ponta a ponta seria rodar a suíte dentro da suíte. A leitura da linha `all files`, a leitura do piso e a tabela de decisão saíram para `lib/core/coverage-gate.ts`, e o script virou coleta + emissão. `test/coverage-gate.test.js` (10) prova o que o script não podia provar: **suíte verde com tabela ausente é exit 1, nunca OK** (o formato do Node já mudou uma vez), processo morto por sinal não sai 0, e no piso exato passa — é ratchet, não folga.
98
+ - *Propriedade de arquivo que nenhuma suíte executa* (AC-1, AC-5): `test/ci-workflow.test.js` (7) lê o `ci.yml` como texto — sem parser YAML, pela mesma razão do §2: não importar uma segunda máquina para medir o que já se mede. Prova as 4 células efetivas (ubuntu×22/24, macos×24, windows×24), o `fail-fast: false`, e que `continue-on-error` aparece **uma vez**, condicionado a `windows-latest`, com a regra de saída ao lado. Do lado do AC-5, prova que os dois passos de teste têm `if:` complementares e que cada um aparece uma única vez — nenhuma célula roda a suíte duas vezes.
99
+ - **Medido depois**: `spec:trace v6-quality-gates` → **6/6**. AC-4 já era rastreado (o skip justificado do SIGTERM e o CRLF das skills) e continua com o checkbox aberto porque o inventário acima não zerou — teste não fecha inventário de produto. `npm test` → **683/683**, 0 skipped (666 + 17 novos). `forja quality:coverage` → `OK cobertura de linhas 91.84% (piso 90%) · branches 79.91% · funções 88.03%`, exit 0 — 0,04pp acima do estado anterior, com a régua agora coberta pelos próprios testes. `forja tools:doctor` → `OK type-debt 357 any explícitos, no teto (357)`: nenhum `any` novo. `npm run types:check` → 0 erros.
@@ -0,0 +1,84 @@
1
+ # Spec: v6-token-economy
2
+
3
+ - **ID**: SPEC-057
4
+ - **Status**: implementing — Wave 1 entregue e medida (AC-1..AC-5); Wave 3 (tokenizer real, memória híbrida, skills lazy) segue aberta
5
+ - **Owner**: allanpablo
6
+ - **Criado em**: 2026-11-05
7
+ - **Sprint alvo**: v6.0 Wave 1 (snippets + sync incremental); Wave 3 (tokenizer real, memória híbrida)
8
+ - **ADRs relacionadas**: a criar em memory/90-decisions/
9
+
10
+ ## 1. Problema
11
+ O forja injeta mais contexto do que o necessário em cada comando, e o custo é pago pelo usuário em tokens. Estado validado em 2026-11-05 (v5.2.0):
12
+
13
+ - `lib/context-builder.ts:199` injeta `node.content` **inteiro** para cada nó de memória relevante, apesar de o SQLite ser FTS5 (que tem `snippet()` nativo para retornar apenas o trecho casado).
14
+ - `lib/code-context.ts:100-120`: `--code` lê **todos os arquivos do módulo por completo**, sem filtro por relevância nem cache.
15
+ - Skills são copiadas fisicamente em **2 destinos por projeto** (`.claude/skills` + `.agents/skills`, `lib/project-wiring.ts:41-47` e loop :235-249): 34 pastas / 276KB duplicados por agente suportado.
16
+ - Estimativa de tokens = `bytes/4` em `context-builder.ts:223` e `scripts/token-economy.ts:18/:127/:143` — sem tokenizer real, o relatório de economia mede aproximado.
17
+ - Sync de memória reprocessa conteúdo sem `content_hash` incremental (re-trabalho a cada sync).
18
+
19
+ Quem sente: todo usuário que roda `forja` com agentes de IA — contexto inflado = custo maior e janela útil menor.
20
+
21
+ ## 2. Proposta de valor
22
+ Reduzir os tokens injetados por comando sem perder sinal: snippet FTS5 no lugar de conteúdo integral, sync incremental por hash, e medição honesta com tokenizer real — meta Wave 1: ≥ 50% de redução no payload de memória injetado nos comandos `context`/`code:context`, medida por um cenário de referência determinístico (`forja token:benchmark`), não pelo `token-economy` (que mede outro eixo).
23
+
24
+ ## 3. User stories
25
+ - **Como** usuário pagando tokens, **quero** que só o trecho relevante da memória seja injetado, **para que** cada comando custe menos e caiba mais contexto útil na janela.
26
+ - **Como** agente de IA, **quero** que `--code` traga só arquivos/trechos pertinentes à tarefa, **para que** eu não desperdice janela com módulo inteiro.
27
+ - **Como** maintainer, **quero** sync incremental por `content_hash`, **para que** re-sync de projeto grande não reprocessa tudo.
28
+ - **Como** maintainer, **quero** que `token-economy` use tokenizer real, **para que** a métrica de economia seja confiável.
29
+
30
+ ## 4. Critérios de aceite (Definition of Done)
31
+ - [x] AC-1: `context-builder.ts` usa `snippet(fts, col, marker, marker, radius)` para nós de memória; conteúdo integral só quando o nó for curto (< limite configurável, default ~400 tokens) ou marcado como sempre-integral.
32
+ - [x] AC-2: Redução ≥ 50% no total de tokens injetados em cenário de referência (projeto com ≥ 50 nós de memória), medido por máquina de evidência própria, registrada nas evidências.
33
+ - [x] AC-3: Sync de memória grava `content_hash` por nó e pula reprocessamento quando inalterado; re-sync de projeto inalterado custa ~0 reprocessamentos (log mostra skipped).
34
+ - [x] AC-4: `code-context` limita leitura por relevância (ordem FTS/grep interno) com flag `--full` como opt-in para comportamento atual.
35
+ - [x] AC-5: Nenhum teste existente quebra; saída dos comandos continua parseável pelos consumidores atuais (contrato de formato preservado).
36
+
37
+ ## 5. Escopo
38
+ **Dentro**:
39
+ - `lib/context-builder.ts` (snippet FTS5 + política de integral).
40
+ - `lib/code-context.ts` (seleção por relevância + `--full`).
41
+ - Sync de memória (`scripts/memory-*`): `content_hash` incremental.
42
+ - `scripts/token-economy.ts`: medição antes/depois para evidência.
43
+ - `scripts/token-benchmark.ts`: cenário de referência determinístico (fixture própria, 60 nós) — é dele que sai o número do AC-2, porque medir "economia" num projeto inexistente produz número sem medição.
44
+
45
+ **Fora**:
46
+ - Tokenizer real (tiktoken) — Wave 3; bytes/4 continua, documentado como limitação.
47
+ - Embeddings/memória híbrida (sqlite-vec) — Wave 3.
48
+ - Skills lazy por trigger — Wave 3 (SPEC de skills, se houver).
49
+ - Mudança do schema FTS5 além do necessário para snippet.
50
+
51
+ ## 6. NFRs / restrições
52
+ - Performance: `context` não pode ficar mais lento que hoje (snippet é mais barato que SELECT content inteiro).
53
+ - Compatibilidade: projetos com memória antiga continuam funcionando (migração de `content_hash` lazy no primeiro sync).
54
+ - Determinismo: snippets estáveis para o mesmo par query/nó (sem ordem aleatória).
55
+
56
+ ## 7. Riscos e mitigação
57
+ | Risco | Probabilidade | Impacto | Mitigação |
58
+ |---|---|---|---|
59
+ | Snippet cortar informação essencial do nó | M | A | Política de integral para nós curtos/críticos + flag `--full-context`; AC-2 mede só payload, testes cobrem qualidade |
60
+ | `content_hash` invalidar cache errado (falso skip) | B | A | Hash do conteúdo normalizado + teste de mutação (muda 1 char → reprocessa) |
61
+ | `--code` por relevância omitir arquivo necessário | M | M | `--full` opt-in documentado; ranking por path+módulo antes de cortar |
62
+
63
+ ## 8. Métricas de sucesso
64
+ 30 dias após: redução ≥ 50% nos tokens de memória por comando `context` em projetos reais; tempo de re-sync de projeto inalterado < 10% do sync cheio; zero issues de "contexto cortou informação".
65
+
66
+ ## Evidências e estado real
67
+ Medições de 2026-11-05, branch `feat/v6-wave1`, sobre v5.2.0.
68
+
69
+ - **Diagnóstico validado**: leitura direta de `context-builder.ts` (conteúdo integral por nó), `code-context.ts` (fatia inteira, sem relevância), `project-wiring.ts:41-47/:235-249` (skills em 2 destinos), `token-economy.ts` (bytes/4), e a contagem de skills (34 pastas = 276KB).
70
+ - **AC-1 (trecho, não inteiro)**: `snippet(search_idx, 2, '**', '**', ' … ', 24)` no caminho FTS e janela calculada (`excerptAround`) no caminho `LIKE`, com política de integral abaixo de `FULL_CONTENT_MAX_CHARS` (1600 chars ≈ 400 tokens, configurável por `FORJA_CONTEXT_FULL_MAX_CHARS`) e `mission.md`/`standards.md` sempre inteiros — o corte da constituição do pack orienta pior que o silêncio. Todo corte é visível: rodapé `- **Excerpts**: N/M nodes` e a linha `⋯ X chars omitidos — leia o arquivo acima ou rode com --full-context`.
71
+ - **AC-2 (meta ≥ 50%)**: a evidência não vem do `token-economy` (que mede outro eixo) mas de uma máquina própria e determinística, `referenceScenario()` em `scripts/token-benchmark.ts`, com 60 nós de texto fixo num workspace descartável. Medido: **−80%** no termo que casa pelo FTS (`pagamentos`), **−81%** no termo que só o `LIKE` casa (`pagament`), **−29%** no termo composto em que os globais sempre-integral dominam o pacote, **0%** no termo sem casamento (controle: sem casamento não há o que cortar, e a máquina diz isso em vez de inventar). Veredito impresso: `Meta AC-2 (≥ 50% no termo que casa): −80% → ✅`.
72
+ - **Defeito achado ao medir (o pior tipo)**: `forja token:benchmark` media um projeto chamado `benchmark-project`, que não existe em lugar nenhum — `domain`/`task` voltavam só com os globais e o relatório anunciava **~99,6% de economia** de um pacote vazio, com ar de número. Agora o projeto de referência sai do banco (o que tem mais nós), o termo sai dos caminhos indexados (`30-domains/<x>/`, senão slug de spec), cada modo imprime `Nodes:`, e se `domain`/`task` não trouxerem um nó a mais que `global` o relatório cospe `⚠️ nenhum nó do projeto além dos globais — economia vazia, não conte este número` e sai cedo em vez de tabular vento.
73
+ - **AC-3 (sync incremental)**: `content_hash` por nó + `project_id`; nó inalterado é pulado antes de qualquer trabalho e o sync fecha com `N indexados · M inalterados (pulados) · K falhas`. O pulo é por hash, não por mtime — provado no teste que mexe o mtime e ainda assim pula.
74
+ - **Segundo defeito achado pelo caminho**: `memory-fresh`, o check que existe para avisar que o índice está velho, comparava o mtime do `.db` com o de `memory/`. Com WAL ativo, um sync pequeno escreve no `-wal` e **não toca no mtime do banco** — o check dizia "índice em dia" para índice velho, exatamente o caso que deveria pegar. Reparo duplo: o sync grava `sync_meta(last_sync)` e faz `wal_checkpoint(TRUNCATE)`, e o check lê o timestamp registrado (mtime só como fallback para banco de versão anterior). Testado nos dois lados.
75
+ - **AC-4 (código por relevância)**: `byRelevance` (termo no caminho > termo no conteúdo, depois camada `domain → application → infrastructure → presentation`, depois caminho para o desempate ser sempre o mesmo) + `withinBudget` de `CODE_TOKEN_BUDGET = 6000` tokens, com `codeOmitted` no pacote e no rodapé do comando — nunca corte calado. `--full` repõe a fatia inteira, e é o que `token:economy` usa explicitamente para não passar a medir outra coisa.
76
+ - **AC-5 (contrato)**: formatos antigos seguem válidos — os testes de regressão do pack checam `**Path**: \`…\`` e os consumidores de `docs/commands.md` não mudaram de forma. Um segundo ponto de entrada morto (CLI module-level em `lib/context-builder.ts`, com usage apontando para um `scripts/context-builder.mjs` que não existe) foi removido; o caminho vivo é `forja context:smart`.
77
+ - **AC-5 no Windows (rodada de CI de 2026-11-06)**: dois níveis. (a) *Renderização*: `code:context` e `context:smart` agora escrevem caminho com `/` (`relFrom()`; `**Path**` normalizado), porque um pacote colado no contexto de um agente não pode mudar de letra conforme a máquina. Provado na rodada 2 (os dois testes desta wave que falhavam passaram). (b) *Identidade do nó*: o caminho **gravado** no banco ainda saía com outra forma no Windows — `path.relative()` entre unidades diferentes devolve caminho absoluto, e o atalho `startsWith('..')` lia isso como "está dentro". Corrigido por contenção (`inside()` + forma canônica nos dois lados em `scripts/sync-universal-memory.ts`); em unix o caminho direto continua vencendo, então nada muda aqui (666/666). A confirmação é a célula Windows, onde o contrato do `modo task` ainda estava vermelho.
78
+ - **Limitação assumida**: tokens = bytes/4 em todo o framework (Wave 3 traz tokenizer real). Os percentuais acima são da mesma régua usada antes, então a *comparação* é válida mesmo que o valor absoluto não seja.
79
+ - **Cobertura (gate da SPEC-056 no caminho desta wave)**: `forja quality:coverage` reprovava em 86,1–86,9% contra o piso 87 — e o número mudava entre execuções idênticas. Isolado: a variação vinha dos CLIs filhos escrevendo cobertura no mesmo agregador do Node (não desta wave). Com a medição consertada em `test/isolate-workspace.mjs`, o estado aqui é **`OK 91,80% (piso subido para 90)`**, exit 0, reproduzido duas vezes com o mesmo valor, 662/662 verdes.
80
+ - **Terceiro ponto de entrada morto removido**: o bloco CLI de módulo em `lib/context-builder.ts` (usage apontando para um `scripts/context-builder.mjs` que nunca existiu) — dois caminhos para o mesmo comando é o que gera documentação que mente.
81
+ - **Defeito achado no smoke do AC-4 (e que a suíte não via)**: `forja code:context <domínio> --full` **não chegava ao script**. Comandos roteados como capability não recebem o argv do usuário: o roteador o parseia contra `params` declarados e reconstrói — flag não declarada é descartada em silêncio. `--full`, o `[termo]` e `--project` estavam fora dos params de `code.context`, então o help prometia três flags mortas. Corrigido nos params, e o teste novo em `test/cli-params.test.js` agora atravessa o `usage` de todo comando-capability e reprova qualquer `--flag` anunciada que não esteja declarada — a mesma varredura pegou dois drifts pré-existentes (`orchestrate:status`/`advance` prometiam `--slug` para um script que lê `argv[0]`; usage corrigido para `<slug>`).
82
+ - **Estado final da wave**: `npm test` → 666/666 verdes; `npm run types:check` → 0 erros; `forja quality:coverage` → `OK 91,80% (piso 90%)`; `forja tools:doctor` → ressalva só de `handoff-orphans` (35, pré-existente) e da ferramenta opcional `codegraph`.
83
+ - AC-2 será evidenciado com números antes/depois do `token-economy` na mesma base de referência.
84
+ - **Rastreabilidade fechada (2026-11-09)**: `spec:trace v6-token-economy` marcava **3/5**. AC-1 e AC-5 já tinham teste real — a política de trecho nas unidades puras e no pack FTS5/`LIKE` (`test/context-builder.test.js`), e o `**Path**: \`…\`` preservado com separador POSIX — mas nenhum dos dois citava o critério, que é o que o trace lê. Marcados, sem teste novo. Estado medido: **5/5** e suíte **683/683** com 0 skipped, o que transforma o AC-5 ("nenhum teste existente quebra") de afirmação em número.
@@ -0,0 +1,25 @@
1
+ {
2
+ "id": "adr",
3
+ "title": "Decisão vira ADR no lugar certo",
4
+ "prompt": "Decidimos usar PostgreSQL como banco principal deste produto: precisamos de transações e de colunas JSONB, e o time já opera Postgres. Registre essa decisão no projeto. Não escreva código.",
5
+ "checks": [
6
+ {
7
+ "type": "file",
8
+ "desc": "ADR novo em memory/90-decisions/ com Postgres, Contexto e Decisão",
9
+ "glob": "memory/90-decisions/*.md",
10
+ "contains": [
11
+ "postgres",
12
+ "^#+ *Contexto",
13
+ "^#+ *Decis[aã]o"
14
+ ],
15
+ "exclude": [
16
+ "memory/90-decisions/_template.md"
17
+ ]
18
+ },
19
+ {
20
+ "type": "unchanged",
21
+ "desc": "não mexeu no template de ADR",
22
+ "glob": "memory/90-decisions/_template.md"
23
+ }
24
+ ]
25
+ }
@@ -0,0 +1,32 @@
1
+ {
2
+ "id": "memoria",
3
+ "title": "Resposta vem da memória do projeto",
4
+ "prompt": "Um cliente perguntou em quantos dias úteis vence um boleto no nosso produto. Qual é a regra e em que arquivo do projeto ela está registrada? Não altere nada.",
5
+ "seed": {
6
+ "files": {
7
+ "memory/30-domains/cobranca/context.md": "# Cobrança — contexto\n\n## Regras\n\n- Boleto vence em **3 dias úteis** a partir da emissão.\n- Pix expira em 30 minutos.\n- Cartão é capturado na hora.\n"
8
+ }
9
+ },
10
+ "checks": [
11
+ {
12
+ "type": "answer",
13
+ "desc": "responde 3 dias úteis",
14
+ "matches": [
15
+ "\\b3\\b|\\btr[eê]s\\b",
16
+ "[uú]teis"
17
+ ]
18
+ },
19
+ {
20
+ "type": "answer",
21
+ "desc": "cita o arquivo de memória",
22
+ "matches": [
23
+ "memory/30-domains/cobranca"
24
+ ]
25
+ },
26
+ {
27
+ "type": "unchanged",
28
+ "desc": "não alterou a memória",
29
+ "glob": "memory/**"
30
+ }
31
+ ]
32
+ }
@@ -0,0 +1,29 @@
1
+ {
2
+ "id": "proxima-acao",
3
+ "title": "Próxima ação vem do forja",
4
+ "prompt": "Acabei de voltar de férias. O que devo fazer agora neste projeto? Seja breve e não altere nada.",
5
+ "seed": {
6
+ "files": {
7
+ "specs/exportar-relatorios/spec.md": "# Spec: exportar-relatorios\n\n- **ID**: SPEC-001\n- **Status**: approved\n- **Owner**: time\n- **Criado em**: 2026-10-01\n\n## 1. Problema\nClientes copiam a tabela de relatórios à mão para a planilha.\n\n## 4. Critérios de aceite (Definition of Done)\n- [ ] AC-1: o relatório mensal pode ser baixado em CSV.\n"
8
+ }
9
+ },
10
+ "checks": [
11
+ {
12
+ "type": "ran",
13
+ "desc": "consultou forja next ou status",
14
+ "matches": "forja\\s+(next|status)|mcp__forja__(next|status)"
15
+ },
16
+ {
17
+ "type": "answer",
18
+ "desc": "recomenda o plano da spec aprovada",
19
+ "matches": [
20
+ "spec:plan|plan\\.md|plano"
21
+ ]
22
+ },
23
+ {
24
+ "type": "unchanged",
25
+ "desc": "não alterou specs",
26
+ "glob": "specs/**"
27
+ }
28
+ ]
29
+ }
@@ -0,0 +1,26 @@
1
+ {
2
+ "id": "spec-nova",
3
+ "title": "Feature nova começa por spec, pelo spec:new",
4
+ "prompt": "Queremos que o cliente consiga exportar o extrato da conta em PDF. Comece essa feature do jeito que este projeto pede. Não escreva código ainda.",
5
+ "checks": [
6
+ {
7
+ "type": "ran",
8
+ "desc": "criou a spec com forja spec:new",
9
+ "matches": "forja\\s+spec:new|mcp__forja__spec_new"
10
+ },
11
+ {
12
+ "type": "file",
13
+ "desc": "spec com ID e critério de aceite preenchido",
14
+ "glob": "specs/*/spec.md",
15
+ "contains": [
16
+ "\\*\\*ID\\*\\*: *SPEC-\\d+",
17
+ "^- \\[ \\] \\**AC-1\\b[^:\\n]*: *[^<\\s]"
18
+ ]
19
+ },
20
+ {
21
+ "type": "unchanged",
22
+ "desc": "não escreveu código",
23
+ "glob": "src/**"
24
+ }
25
+ ]
26
+ }
@@ -0,0 +1,29 @@
1
+ {
2
+ "id": "teste-do-criterio",
3
+ "title": "Teste cita o critério que prova",
4
+ "prompt": "Escreva o teste automatizado que prova o critério AC-1 da spec de pagamentos. Use o executor de testes nativo do Node (node --test). Não altere o código de produção.",
5
+ "seed": {
6
+ "files": {
7
+ "specs/pagamentos/spec.md": "# Spec: pagamentos\n\n- **ID**: SPEC-001\n- **Status**: approved\n- **Owner**: time\n- **Criado em**: 2026-10-01\n\n## 1. Problema\nPagamentos com valor zero ou negativo chegam ao gateway e são recusados lá, tarde demais.\n\n## 4. Critérios de aceite (Definition of Done)\n- [ ] AC-1: `validarValor` rejeita valor zero ou negativo com erro \"valor inválido\".\n- [ ] AC-2: `validarValor` devolve o valor quando ele é positivo.\n",
8
+ "src/pagamentos.js": "export function validarValor(valor) {\n if (!(valor > 0)) throw new Error('valor inválido');\n return valor;\n}\n"
9
+ }
10
+ },
11
+ "checks": [
12
+ {
13
+ "type": "criterion",
14
+ "desc": "um teste cita SPEC-001 AC-1 (spec:trace)",
15
+ "spec": "pagamentos",
16
+ "ac": "AC-1"
17
+ },
18
+ {
19
+ "type": "command",
20
+ "desc": "os testes passam",
21
+ "run": "node --test"
22
+ },
23
+ {
24
+ "type": "unchanged",
25
+ "desc": "não mexeu no código de produção",
26
+ "glob": "src/pagamentos.js"
27
+ }
28
+ ]
29
+ }
@@ -33,6 +33,7 @@ forja spec:set-status <slug> spec approved # depois da revisão
33
33
  forja spec:plan <slug> # plan.md (exige spec aprovada)
34
34
  forja spec:tasks <slug> # tasks.md
35
35
  forja spec:check <slug> # gate de completude
36
+ forja spec:trace <slug> # critérios AC-N × testes que os citam
36
37
  forja orchestrate "<objetivo>" --slug <slug> # corrida guardada por gates
37
38
  forja orchestrate:advance # roda o gate da etapa aberta
38
39
  ```
@@ -45,8 +46,13 @@ forja code:impact <símbolo> # quem chama e o que quebra
45
46
  forja project:check # documentação de fundação
46
47
  forja tools:doctor # saúde do Forja e das ferramentas
47
48
  forja project:wire --check # IA, hooks e MCP conectados a este projeto
49
+ forja spec:trace <slug> --strict # todo critério da spec tem teste (exit 2 se não)
48
50
  ```
49
51
 
52
+ Teste que prova um critério cita a spec e o critério no nome ou num comentário: `SPEC-NNN AC-N`
53
+ (ex.: `test('SPEC-004 AC-2: estorno parcial', …)`). É o que o `spec:trace` lê.
54
+ Fixture com citações de exemplo fica entre comentários `spec-trace:off` e `spec-trace:on`.
55
+
50
56
  ## Onde fica cada coisa
51
57
 
52
58
  ```
@@ -56,12 +62,22 @@ memory/20-architecture/ design técnico
56
62
  memory/30-domains/ regras por domínio
57
63
  memory/40-delivery/ roadmap, sprint, backlog
58
64
  memory/50-orchestration/ topologia e handoffs
65
+ memory/60-runs/sessions/ checkpoint de cada sessão do Claude Code (gerado pelos hooks; não edite)
59
66
  memory/70-summaries/ resumos compactos (prefira a arquivos brutos)
60
67
  memory/90-decisions/ ADRs
61
68
  specs/<slug>/ spec → plan → tasks
62
69
  agents/, prompts/ papéis e prompts do projeto
63
70
  ```
64
71
 
72
+ ## Skills
73
+
74
+ O projeto traz 34 skills (`.claude/skills/` para o Claude Code, `.agents/skills/` para o Codex), uma por
75
+ tarefa: avaliar produto, levantar requisitos, fatiar backlog, modelar domínio, registrar ADR, desenhar
76
+ API e migrações, front-end, acessibilidade, desempenho web, testar, revisar código, atualizar dependências, modelar ameaças, LGPD, observabilidade, release e git. As que
77
+ geram artefatos têm uma seção "No Forja" dizendo onde gravar (`specs/`, `memory/`, ADRs, handoffs).
78
+ Encadeamento típico: `product-evaluation` → `requirements-gathering` → `backlog-slicing` →
79
+ `domain-modeling` → `testing` → `ts-code-review` → `release-checklist`.
80
+
65
81
  ## Papéis e handoffs
66
82
 
67
83
  Orchestrator, product, sdd-architect, context-engineer, governance e marketing. No Claude Code
@@ -3,7 +3,8 @@
3
3
  ## Claude Code neste projeto
4
4
 
5
5
  - Os hooks em `.claude/settings.json` abrem cada sessão com o estado do projeto (`forja hook:session-start`)
6
- e anexam a spec citada no prompt (`forja hook:user-prompt`). Se o briefing não aparecer, rode
7
- `forja project:wire --check`.
6
+ e anexam a spec citada no prompt (`forja hook:user-prompt`); ao fim de cada turno e antes de compactar,
7
+ `forja hook:session-memory` grava o checkpoint da sessão em `memory/60-runs/sessions/`. Se o
8
+ briefing não aparecer, rode `forja project:wire --check`.
8
9
  - O servidor MCP `forja` (`.mcp.json`) expõe as capacidades do Forja como ferramentas.
9
10
  - Sub-agents de cada papel ficam em `.claude/agents/`. Delegue a eles quando a tarefa cruzar papéis.
@@ -11,5 +11,8 @@ Siga o `AGENTS.md` da raiz do projeto. Comunique-se em pt-BR, salvo preferência
11
11
  ## Procedimento
12
12
  Identifique a pergunta. `forja sync:universal` se a memória mudou; depois `forja context:smart --mode task --task "<termo>"` (ou `--mode domain` para uma área). O pack sai em `.context/smart-context.md`. Para medir, `forja context:budget`. Não remova nem compacte memória por tamanho ou idade.
13
13
 
14
+ ## Skills
15
+ Use as skills do projeto (`.claude/skills/`) que cabem na tarefa: `requirements-elicitation`, `domain-modeling`, `query-performance`, `observability`, `web-performance`. Quando a skill tiver uma seção "No Forja", siga-a para gravar o resultado no lugar certo.
16
+
14
17
  ## Entrega esperada
15
18
  Fontes com caminhos, resumo factual, lacunas e por que esse contexto foi escolhido.
@@ -11,5 +11,8 @@ Siga o `AGENTS.md` da raiz do projeto. Comunique-se em pt-BR, salvo preferência
11
11
  ## Procedimento
12
12
  Leia o diff e os critérios de aceite. Rode `forja project:check`, `forja spec:check`, `forja tools:doctor` e `forja project:wire --check`, além dos testes do projeto. Ferramenta opcional ausente é limitação, não falha. Confira se cada mudança estrutural tem ADR e se dados pessoais seguem a política do projeto.
13
13
 
14
+ ## Skills
15
+ Use as skills do projeto (`.claude/skills/`) que cabem na tarefa: `ts-code-review`, `testing`, `ts-testing`, `threat-modeling`, `lgpd-compliance`, `ci-pipeline-review`, `docker-compose-review`, `release-checklist`, `incident-postmortem`, `accessibility-review`, `web-performance`, `dependency-upgrade`. Quando a skill tiver uma seção "No Forja", siga-a para gravar o resultado no lugar certo.
16
+
14
17
  ## Entrega esperada
15
18
  Parecer aprovado, reprovado ou inconclusivo, com evidência por critério, bloqueios concretos e limitações. Execução bem-sucedida de LLM não prova qualidade.
@@ -11,5 +11,8 @@ Siga o `AGENTS.md` da raiz do projeto. Comunique-se em pt-BR, salvo preferência
11
11
  ## Procedimento
12
12
  Leia a dor descrita na spec e o que já foi entregue. Separe o que existe do que é roadmap. Use métricas só com fonte, período e método; hipótese é apresentada como hipótese. Publique apenas dentro da autorização vigente.
13
13
 
14
+ ## Skills
15
+ Use as skills do projeto (`.claude/skills/`) que cabem na tarefa: `product-evaluation`, `executive-writing`, `release-notes`. Quando a skill tiver uma seção "No Forja", siga-a para gravar o resultado no lugar certo.
16
+
14
17
  ## Entrega esperada
15
18
  Texto pronto para revisão, público e objetivo, fonte de cada alegação e proposta de medição sem resultados inventados.
@@ -11,5 +11,8 @@ Siga o `AGENTS.md` da raiz do projeto. Comunique-se em pt-BR, salvo preferência
11
11
  ## Procedimento
12
12
  Comece por `forja status` e `forja next`. Para uma entrega com várias etapas, abra uma corrida com `forja orchestrate "<objetivo>" --slug <slug>` e avance com `forja orchestrate:advance`, que só abre a próxima etapa quando o gate da atual passa. Registre cada delegação com `forja hermes:handoff '<json>'` contendo os 7 campos (`from`, `to`, `intent`, `context`, `acceptance`, `constraints`, `return`). Não apague nem compacte memória como rotina.
13
13
 
14
+ ## Skills
15
+ Use as skills do projeto (`.claude/skills/`) que cabem na tarefa: `prompt-spec`, `backlog-slicing`, `commit-message`, `pull-request`, `executive-writing`. Quando a skill tiver uma seção "No Forja", siga-a para gravar o resultado no lugar certo.
16
+
14
17
  ## Entrega esperada
15
18
  Plano de execução, handoffs com os sete campos, evidências recebidas e pendências. Alegação de um agente não é validação: confirme pelo gate.
@@ -11,5 +11,8 @@ Siga o `AGENTS.md` da raiz do projeto. Comunique-se em pt-BR, salvo preferência
11
11
  ## Procedimento
12
12
  Leia `memory/10-product/` via `forja query:universal`. Para feature nova, `forja spec:new <slug>` e preencha problema, público, comportamento esperado, exclusões e critérios de aceite observáveis. Ao terminar a revisão, `forja spec:set-status <slug> spec approved`. Na priorização (RICE), separe dado medido, estimativa e hipótese; não invente KPIs.
13
13
 
14
+ ## Skills
15
+ Use as skills do projeto (`.claude/skills/`) que cabem na tarefa: `product-evaluation`, `requirements-elicitation`, `requirements-gathering`, `backlog-slicing`, `lgpd-compliance`. Quando a skill tiver uma seção "No Forja", siga-a para gravar o resultado no lugar certo.
16
+
14
17
  ## Entrega esperada
15
18
  Spec preenchida, critérios de aceite numerados, suposições e dúvidas que de fato bloqueiam a implementação.
@@ -11,5 +11,8 @@ Siga o `AGENTS.md` da raiz do projeto. Comunique-se em pt-BR, salvo preferência
11
11
  ## Procedimento
12
12
  Leia a spec e `memory/20-architecture/`. Antes de propor mudança em código existente, `forja code:impact <símbolo>` (sem codegraph, busque chamadores com `rg`). Gere `forja spec:plan <slug>` e `forja spec:tasks <slug>`; descreva contratos, falhas, compatibilidade, testes e rollout. Decisão estrutural durável vira ADR em `memory/90-decisions/` a partir de `_template.md`.
13
13
 
14
+ ## Skills
15
+ Use as skills do projeto (`.claude/skills/`) que cabem na tarefa: `event-storming`, `bounded-context-mapping`, `domain-modeling`, `architecture-decision-record`, `technical-spike`, `api-design`, `data-migrations`, `ts-module-layout`, `ts-async-patterns`, `frontend-architecture`. Quando a skill tiver uma seção "No Forja", siga-a para gravar o resultado no lugar certo.
16
+
14
17
  ## Entrega esperada
15
18
  Plan e tasks ligados aos critérios de aceite, arquivos afetados, decisões justificadas e como validar. Não marque aceite ainda não verificado.
@@ -0,0 +1,14 @@
1
+ # Skills do projeto
2
+
3
+ Instaladas pelo `forja project:wire` em `.claude/skills/` (Claude Code) e `.agents/skills/` (Codex).
4
+ Cada pasta tem um `SKILL.md` com frontmatter (`name`, `description`); o `name` é igual ao nome da pasta.
5
+
6
+ ## Origem
7
+
8
+ As skills de produto, requisitos, design, qualidade, TypeScript, segurança, operações, entrega, IA,
9
+ compliance, comunicação e git vêm do skill ledger de Allan Pablo (`allus-co/my-skill-ledger`),
10
+ traduzidas para pt-BR, com a trilha de Go convertida para TypeScript e publicadas no Forja sob a licença
11
+ MIT com autorização do autor. As seções "No Forja" são a integração com o processo do Forja.
12
+ `llm-provider-routing` é do próprio Forja.
13
+
14
+ Para atualizar a partir do ledger: copie as skills e reaplique as seções "No Forja" (ADR-0089).
@@ -0,0 +1,89 @@
1
+ ---
2
+ name: accessibility-review
3
+ description: Use quando criar ou revisar telas, componentes ou fluxos de interface: verifica a conformidade com a WCAG 2.2 nível AA (teclado, foco, semântica, nomes acessíveis, contraste, formulários, movimento) com ferramentas automáticas e testes manuais, e reporta os achados por severidade.
4
+ ---
5
+
6
+ # Revisão de Acessibilidade
7
+
8
+ Acessibilidade é se uma pessoa consegue concluir a tarefa: com teclado, com leitor de tela, com zoom, com pouca visão de cor. Ferramentas automáticas encontram só parte dos problemas; o resto aparece navegando de verdade.
9
+
10
+ A saída padrão é uma **tabela de achados ligados aos critérios da WCAG 2.2**. Edite código só quando o usuário pedir.
11
+
12
+ ## Convenções
13
+
14
+ - Alvo: WCAG 2.2 nível AA, a menos que o projeto declare outro. No Brasil, a Lei Brasileira de Inclusão (Lei nº 13.146/2015) e o eMAG se aplicam a serviços públicos; sinalize quando for o caso.
15
+ - Escopo: as telas ou componentes que o usuário nomear, ou o diff.
16
+ - Todo achado cita o critério (por exemplo, `2.4.7 Foco Visível`), onde ocorre e como reproduzir.
17
+ - Componentes do design system: um achado no componente vale para todas as telas que o usam; corrija na origem.
18
+
19
+ ## Verifique
20
+
21
+ **Automático** (encontra o óbvio, não aprova nada sozinho):
22
+ - `axe` no navegador ou nos testes (`@axe-core/playwright`, `vitest-axe`), e o Lighthouse de acessibilidade.
23
+ - Lint de JSX (`eslint-plugin-jsx-a11y` ou as regras equivalentes do oxlint/biome).
24
+
25
+ **Manual** (obrigatório):
26
+ 1. **Só teclado**: percorra a tarefa inteira com Tab, Shift+Tab, Enter, Espaço, Esc e setas. Tudo alcançável, na ordem visual, sem armadilhas de foco.
27
+ 2. **Foco visível** em todo elemento interativo; o foco nunca fica escondido atrás de cabeçalhos fixos (`2.4.11`).
28
+ 3. **Leitor de tela** (NVDA ou VoiceOver): títulos, regiões, nomes de botões e links, mensagens de erro e de status anunciados.
29
+ 4. **Zoom a 200% e largura de 320 px**: nada some, nada exige rolagem horizontal (`1.4.10`).
30
+ 5. **Contraste**: texto 4,5:1 (texto grande 3:1); componentes e ícones informativos 3:1 (`1.4.3`, `1.4.11`).
31
+ 6. **Movimento**: animações respeitam `prefers-reduced-motion`; nada pisca mais de 3 vezes por segundo.
32
+
33
+ ## Checklist
34
+
35
+ **Semântica e estrutura**
36
+ - Um `h1` por página e títulos em ordem; regiões (`header`, `nav`, `main`, `footer`).
37
+ - Elementos nativos antes de ARIA: `button` para ações, `a` para navegação. ARIA só quando não houver elemento nativo, e completo (papel, estado, propriedades).
38
+ - `lang` da página definido.
39
+
40
+ **Nomes e textos**
41
+ - Todo controle tem um nome acessível; ícones sem texto têm `aria-label`.
42
+ - Imagens informativas com `alt` que descreve a função; decorativas com `alt=""`.
43
+ - Links com texto que faz sentido fora do contexto ("Baixar a fatura de março", não "clique aqui").
44
+
45
+ **Formulários**
46
+ - Cada campo com `label` associado; obrigatoriedade indicada além da cor.
47
+ - Erros identificados no campo, descritos em texto e anunciados (`aria-describedby`, região de status).
48
+ - Não exigir digitar de novo o que já foi informado (`3.3.7`); autenticação sem teste cognitivo (`3.3.8`).
49
+
50
+ **Interação**
51
+ - Alvos de toque com pelo menos 24×24 px (`2.5.8`).
52
+ - Ações de arrastar têm alternativa de clique (`2.5.7`).
53
+ - Diálogos prendem o foco enquanto abertos e devolvem o foco ao fechar; Esc fecha.
54
+ - Conteúdo que aparece no hover ou foco pode ser dispensado e não some sob o ponteiro (`1.4.13`).
55
+
56
+ **Conteúdo dinâmico**
57
+ - Mudanças de rota anunciadas e com o foco movido para o conteúdo novo.
58
+ - Mensagens de status (salvo, erro, carregando) em `role="status"` ou `aria-live`.
59
+ - Tempo limite avisado e extensível.
60
+
61
+ ## Severidade
62
+
63
+ Bloqueador (impede concluir a tarefa: armadilha de teclado, controle sem nome, formulário sem rótulo) · Maior (dificulta muito: contraste insuficiente, foco invisível) · Menor · Detalhe.
64
+
65
+ ## Formato
66
+
67
+ ```
68
+ ## Escopo e método
69
+ <telas, ferramentas rodadas, leitor de tela e navegador usados>
70
+
71
+ ## Achados
72
+ | # | Onde | Critério WCAG | Severidade | Problema | Como reproduzir | Correção |
73
+ |---|---|---|---|---|---|---|
74
+
75
+ ## O que foi verificado sem achados
76
+ ```
77
+
78
+ ## Próximo
79
+
80
+ - `testing`: um teste automático (axe) por tela e um caso de teclado para cada fluxo crítico.
81
+ - `frontend-architecture` quando o problema vem de um componente compartilhado.
82
+
83
+ ## Evite
84
+
85
+ - Aprovar uma tela só porque o axe não acusou nada.
86
+ - ARIA em cima de `div` clicável em vez de um `button`.
87
+ - `outline: none` sem um estilo de foco no lugar.
88
+ - Indicar erro ou obrigatoriedade só pela cor.
89
+ - Corrigir tela a tela o que é defeito de um componente compartilhado.