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,57 @@
1
+ /**
2
+ * lib/docs-reference.ts — o lado "código" da coerência de documentação (SPEC-055).
3
+ *
4
+ * A leitura da doc como dado vive em `core/doc-graph.ts` (scanCommands/scanFlags/scanSkillCounts) e
5
+ * o juízo vive nos checks de `core/health.ts`. Aqui ficam só as três referências derivadas do código
6
+ * contra as quais a doc é comparada:
7
+ *
8
+ * declaredFlags o que cada comando aceita (usage + examples do registry + flags do dispatcher)
9
+ * skillsCount quantas skills existem de fato em templates/project/skills
10
+ * renderCommandsDoc a referência completa de comandos, gerada — conteúdo de docs/commands.md
11
+ *
12
+ * Não há scanner próprio de propósito: um segundo scanner de markdown diverge do primeiro com o
13
+ * tempo, e divergência entre superfícies que deveriam concordar é o defeito que a SPEC-009 matou.
14
+ */
15
+ import { flagTokens } from './core/doc-graph.js';
16
+ /** Flags tratadas pelo dispatcher (bin/forja.ts), não pelo comando — valem em qualquer linha. */
17
+ export const GLOBAL_FLAGS = new Set(['--help', '-h', '--json']);
18
+ /** Flags que um comando declara em `usage`/`examples`, mais as globais do dispatcher. */
19
+ export function declaredFlags(spec) {
20
+ const source = [spec.usage ?? '', ...(spec.examples ?? [])].join(' ');
21
+ return new Set([...GLOBAL_FLAGS, ...flagTokens(source)]);
22
+ }
23
+ /**
24
+ * Skills reais distribuídas aos projetos gerados — só diretórios (o README.md da pasta não conta).
25
+ * Recebe o diretório pronto para não impor separador de caminho nenhum (portável entre SOs).
26
+ */
27
+ export function skillsCount(fsLike, skillsDir) {
28
+ if (!fsLike.existsSync(skillsDir))
29
+ return 0;
30
+ return fsLike.readdirSync(skillsDir, { withFileTypes: true }).filter((e) => e.isDirectory()).length;
31
+ }
32
+ /** Referência completa de comandos, gerada do registry — conteúdo canônico de docs/commands.md. */
33
+ export function renderCommandsDoc(registry, skills) {
34
+ const domains = [];
35
+ for (const spec of Object.values(registry)) {
36
+ if (!domains.includes(spec.domain))
37
+ domains.push(spec.domain);
38
+ }
39
+ const cell = (v) => v.replace(/\|/g, '\\|');
40
+ const out = [
41
+ '# Referência de comandos',
42
+ '',
43
+ '> Gerado por `forja docs:gen` a partir de `lib/core/registry.ts` — **não edite à mão.**',
44
+ `> ${Object.keys(registry).length} comandos · ${skills} skills distribuídas aos projetos gerados.`,
45
+ '',
46
+ ];
47
+ for (const domain of domains) {
48
+ out.push(`## ${domain}`, '', '| Comando | O que faz | Uso | Tier | Gates |', '|---|---|---|---|---|');
49
+ for (const [name, spec] of Object.entries(registry)) {
50
+ if (spec.domain !== domain)
51
+ continue;
52
+ out.push(`| \`forja ${name}\` | ${cell(spec.desc)} | \`${cell(spec.usage ?? `forja ${name}`)}\` | ${spec.tier ?? 'advanced'} | ${spec.gates?.join(', ') ?? '—'} |`);
53
+ }
54
+ out.push('');
55
+ }
56
+ return out.join('\n');
57
+ }
@@ -48,16 +48,6 @@ export declare function getAllMemoryTemplates(): {
48
48
  'agents/dba.md': string;
49
49
  'agents/security.md': string;
50
50
  'agents/reviewer.md': string;
51
- 'skills/triage-task/SKILL.md': string;
52
- 'skills/context-compaction/SKILL.md': string;
53
- 'skills/handoff/SKILL.md': string;
54
- 'skills/nest-api/SKILL.md': string;
55
- 'skills/self-healing/SKILL.md': string;
56
- 'skills/validate-handoff/SKILL.md': string;
57
- 'skills/ui-fidelity/SKILL.md': string;
58
- 'skills/reasoning-protocol/SKILL.md': string;
59
- 'skills/llm-provider-routing/SKILL.md': string;
60
- 'skills/MANIFEST.json': string;
61
51
  'prompts/project-prompt-base.md': string;
62
52
  'prompts/multi-agent-orchestrator.md': string;
63
53
  'prompts/worker-task-template.md': string;
@@ -67,7 +57,6 @@ export declare function getAllMemoryTemplates(): {
67
57
  'scripts/build-context-pack.mjs': string;
68
58
  'scripts/append-handoff.mjs': string;
69
59
  'scripts/check-memory-maps.mjs': string;
70
- 'scripts/lib/skill-loader.mjs': string;
71
60
  'scripts/memory-vacuum.mjs': string;
72
61
  'scripts/memory-watcher.mjs': string;
73
62
  };
@@ -272,7 +272,7 @@ Mantenha resumos curtos por dominio para carregamento rapido de contexto.
272
272
  Armazenar indice operacional da documentacao para busca e continuidade de contexto.
273
273
 
274
274
  ## Fonte da verdade
275
- - Arquivos Markdown em memory/, docs/, agents/, skills/, prompts/
275
+ - Arquivos Markdown em memory/, docs/, agents/, prompts/
276
276
 
277
277
  ## Banco
278
278
  - SQLite em .memory/sqlite/context.db
@@ -356,144 +356,9 @@ Planejamento, decomposicao de tarefas, atribuicao de ownership e consolidacao.
356
356
  - cobertura de testes
357
357
  `,
358
358
  };
359
- /**
360
- * Gera estrutura de skills
361
- */
362
- const skillTemplates = {
363
- 'skills/triage-task/SKILL.md': `# Skill: Triage de Tarefa
364
-
365
- ## Objetivo
366
- Classificar demanda em: rapido, medio, complexo.
367
-
368
- ## Saida
369
- - resumo
370
- - risco
371
- - owner sugerido
372
- - fatias de execucao
373
- `,
374
- 'skills/context-compaction/SKILL.md': `# Skill: Compactacao de Contexto
375
-
376
- ## Objetivo
377
- Gerar resumo operacional sem perder decisoes chave.
378
-
379
- ## Regras
380
- - manter fatos verificaveis
381
- - remover redundancia
382
- - preservar links para fontes internas
383
- `,
384
- 'skills/handoff/SKILL.md': `# Skill: Handoff
385
-
386
- ## Template
387
- - contexto
388
- - alteracoes
389
- - riscos
390
- - pendencias
391
- - proximo agente
392
- `,
393
- 'skills/nest-api/SKILL.md': `# Skill: Nest API
394
-
395
- ## Checklist
396
- - modulo criado
397
- - dto com validacao
398
- - controller + service
399
- - testes
400
- `,
401
- 'skills/self-healing/SKILL.md': `# Skill: Auto-Diagnóstico (Self-Healing)
402
-
403
- ## Objetivo
404
- Resolver falhas de build, testes ou tipos sem intervenção humana.
405
-
406
- ## Fluxo
407
- 1. Analisar a stack trace completa do erro.
408
- 2. Identificar se é: erro de sintaxe, falta de dependência, erro de tipo ou lógica.
409
- 3. Consultar documentação interna ou padrões do projeto.
410
- 4. Propor correção mínima e rodar validação novamente.
411
- `,
412
- 'skills/validate-handoff/SKILL.md': `# Skill: Validação e Review de Segurança (Gatekeeper)
413
-
414
- ## Objetivo
415
- Atuar como Gatekeeper final para garantir que nenhum código inseguro ou incompleto entre no pipeline.
416
-
417
- ## Protocolo de Review (Obrigatório)
418
- Antes de aceitar um handoff, o Reviewer deve validar:
419
-
420
- 1. **Compliance de Raciocínio**: O Worker preencheu o bloco \`## Raciocínio Estruturado\`? (Se não, rejeite imediatamente).
421
- 2. **Scan de Segurança**:
422
- - Há logs sensíveis (PII, tokens) sendo impressos?
423
- - As validações de input estão no DTO?
424
- 3. **Verificação de Handoff**:
425
- - Os arquivos listados no handoff condizem com o diff real?
426
- - Existem pendências (riscos) não documentadas?
427
-
428
- ## Saída do Reviewer
429
- - [ ] Aprovado (Status: \`done\` no DB)
430
- - [ ] Rejeitado (Status: \`blocked\` + pendências listadas)
431
- `,
432
- 'skills/ui-fidelity/SKILL.md': `# Skill: Fidelidade Visual
433
-
434
- ## Objetivo
435
- Garantir que a UI segue padrões de elite.
436
-
437
- ## Instrução
438
- 1. Consultar a biblioteca \`design-md/\` para inspiração de marca/padrão.
439
- 2. Comparar o código gerado com os padrões de espaçamento, tipografia e cores da referência.
440
- 3. Ajustar CSS/Componentes para atingir qualidade visual de nível mundial.
441
- `,
442
- 'skills/reasoning-protocol/SKILL.md': `# Skill: Raciocínio Estruturado (Chain-of-Thought)
443
-
444
- ## Objetivo
445
- Reduzir erros de implementação através de análise lógica explícita.
446
-
447
- ## Protocolo Obrigatório
448
- Antes de qualquer código ou plano de ação, preencha o bloco \`## Raciocínio Estruturado\`:
449
-
450
- 1. **Entendimento**: O que foi pedido e qual o impacto no sistema?
451
- 2. **Restrições**: Quais arquivos NÃO posso tocar? Quais padrões devo seguir?
452
- 3. **Alternativas**: Existe mais de uma forma de fazer? Por que escolhi esta?
453
- 4. **Plano de Ataque**: Passo-a-passo lógico da implementação.
454
- `,
455
- 'skills/llm-provider-routing/SKILL.md': `# Skill: Roteamento de LLM Providers
456
-
457
- ## Objetivo
458
- Selecionar e configurar uma LLM por papel sem amarrar o projeto a um unico fornecedor, usando o ciclo verificável do Forja.
459
-
460
- ## Quando usar
461
- - O usuario pedir DeepSeek, MiniMax, Mistral, Qwen, Ollama, OpenRouter, Together, Groq, xAI, Cohere, Perplexity ou outro provider.
462
- - Um papel precisar trocar de modelo por custo, cota, latencia, contexto, privacidade ou qualidade.
463
- - Uma CLI/API externa precisar entrar no fluxo de handoffs sem alterar o SDD.
464
-
465
- ## Regras
466
- - Preferir providers locais para tarefas sensiveis quando o modelo disponivel for suficiente.
467
- - Usar \`manual\` quando o provider nao tiver CLI local confiavel.
468
- - Registrar perfis no workspace em \`.context/llm-profiles.json\` com \`provider\`, \`model\`, \`command\`, \`commandArgs\`, \`roles\`, \`taskTypes\`, \`privacy\` e \`enabled\`.
469
- - Nao assumir que uma CLI existe: validar o binario ou documentar o comando esperado.
470
- - Nao colocar API keys em memoria, specs, handoffs ou logs.
471
-
472
- ## Checklist
473
- 1. Identificar papel e tipo de tarefa.
474
- 2. Inicializar ou revisar os perfis com \`forja llm:profiles:init\`.
475
- 3. Preencher \`command\` com um único executável e \`commandArgs\` para argumentos fixos; nunca use shell ou grave credenciais.
476
- 4. Rodar \`forja llm:probe <perfil>\` antes de delegar uma sprint inteira.
477
- 5. Consultar \`forja llm:recommend --role <papel> --task <tipo>\` e aprovar explicitamente a escolha.
478
- 6. Executar \`forja llm:run --profile <perfil> --task <arquivo>\` e avaliar com \`forja llm:eval --scope model --id <provider:model>\`.
479
- 7. Registrar handoff Hermes quando a troca impactar entrega.
480
- `,
481
- 'skills/MANIFEST.json': `{
482
- "version": "0.5.0",
483
- "skills": [
484
- { "id": "triage", "path": "skills/triage-task/SKILL.md", "description": "Classificação de tarefas" },
485
- { "id": "compaction", "path": "skills/context-compaction/SKILL.md", "description": "Compactação de memória" },
486
- { "id": "handoff", "path": "skills/handoff/SKILL.md", "description": "Protocolo de transição" },
487
- { "id": "nest-api", "path": "skills/nest-api/SKILL.md", "description": "Geração de endpoints NestJS" },
488
- { "id": "self-healing", "path": "skills/self-healing/SKILL.md", "description": "Resolução autônoma de erros" },
489
- { "id": "validate-handoff", "path": "skills/validate-handoff/SKILL.md", "description": "Checklist de qualidade de handoff" },
490
- { "id": "ui-fidelity", "path": "skills/ui-fidelity/SKILL.md", "description": "Auditoria estética de UI" },
491
- { "id": "reasoning", "path": "skills/reasoning-protocol/SKILL.md", "description": "Protocolo de raciocínio lógico" },
492
- { "id": "llm-provider-routing", "path": "skills/llm-provider-routing/SKILL.md", "description": "Roteamento multi-LLM por papel" }
493
- ]
494
- }
495
- `,
496
- };
359
+ // Skills do projeto: instaladas pelo project:wire em .claude/skills/ e .agents/skills/ a partir de
360
+ // templates/project/skills/ (SPEC-051). As 9 "skills" de esboço que viviam aqui ficavam em skills/
361
+ // sem frontmatter, onde nenhuma IA as carregava.
497
362
  /**
498
363
  * Gera estrutura de prompts
499
364
  */
@@ -691,26 +556,6 @@ if (dangling) {
691
556
  }
692
557
  console.log('');
693
558
  console.log('OK -- os mapas de memoria batem com o codigo.');
694
- `,
695
- 'scripts/lib/skill-loader.mjs': `import fs from 'node:fs';
696
- import path from 'node:path';
697
- import { fileURLToPath } from 'node:url';
698
-
699
- const __filename = fileURLToPath(import.meta.url);
700
- const __dirname = path.dirname(__filename);
701
- const root = path.resolve(__dirname, '..', '..');
702
-
703
- export function loadSkills() {
704
- const manifestPath = path.join(root, 'skills', 'MANIFEST.json');
705
- if (!fs.existsSync(manifestPath)) return [];
706
- const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
707
- return manifest.skills;
708
- }
709
-
710
- export function getSkill(id) {
711
- const skills = loadSkills();
712
- return skills.find(s => s.id === id);
713
- }
714
559
  `,
715
560
  'scripts/memory-vacuum.mjs': `import fs from 'node:fs';
716
561
  import path from 'node:path';
@@ -758,7 +603,7 @@ const __filename = fileURLToPath(import.meta.url);
758
603
  const __dirname = path.dirname(__filename);
759
604
  const root = path.resolve(__dirname, '..');
760
605
 
761
- const watchDirs = ['memory', 'agents', 'skills', 'prompts', 'docs'];
606
+ const watchDirs = ['memory', 'agents', 'prompts', 'docs'];
762
607
  let timeout = null;
763
608
 
764
609
  console.log('👀 Memory Watcher iniciado...');
@@ -787,7 +632,6 @@ export function getAllMemoryTemplates() {
787
632
  return {
788
633
  ...memoryTemplates,
789
634
  ...agentTemplates,
790
- ...skillTemplates,
791
635
  ...promptTemplates,
792
636
  ...configTemplates,
793
637
  ...scriptTemplates,
@@ -28,7 +28,7 @@ Este projeto segue uma arquitetura modular com:
28
28
  - 90-decisions/ — ADRs
29
29
 
30
30
  - **agents/** — Definição de agentes especializados
31
- - **skills/** — Capacidades reutilizáveis
31
+ - **.claude/skills/** e **.agents/skills/** — Skills por papel (instaladas pelo \`forja project:wire\`)
32
32
  - **prompts/** — Instruções por contexto
33
33
  - **backend/** — API NestJS (se gerado)
34
34
 
@@ -0,0 +1,14 @@
1
+ import type { LlmExecutionResult } from '../../packages/llm/src/index.ts';
2
+ import type { NormalizedLlmResult } from './codex-output.ts';
3
+ /**
4
+ * Normaliza `gemini -o json` (ADR-0090): um objeto `{ session_id, response, stats, error }`, com o uso
5
+ * por modelo em `stats.models[<modelo>].tokens.{prompt, candidates, cached}` — formato lido do
6
+ * JsonFormatter do próprio Gemini CLI. Campos ausentes viram `undefined`, nunca zero inventado.
7
+ */
8
+ export declare function normalizeGeminiResult(result: LlmExecutionResult): NormalizedLlmResult;
9
+ /**
10
+ * Normaliza `cursor-agent -p --output-format json`: o mesmo envelope do Claude
11
+ * (`type: "result"`, `subtype`, `is_error`, `result`, `session_id`, `usage`). O Cursor usa
12
+ * `inputTokens`/`outputTokens` em camelCase em alguns caminhos; os nomes são alinhados antes.
13
+ */
14
+ export declare function normalizeCursorResult(result: LlmExecutionResult): NormalizedLlmResult;
@@ -0,0 +1,77 @@
1
+ import { normalizeClaudeResult } from './claude-output.js';
2
+ /**
3
+ * Normaliza `gemini -o json` (ADR-0090): um objeto `{ session_id, response, stats, error }`, com o uso
4
+ * por modelo em `stats.models[<modelo>].tokens.{prompt, candidates, cached}` — formato lido do
5
+ * JsonFormatter do próprio Gemini CLI. Campos ausentes viram `undefined`, nunca zero inventado.
6
+ */
7
+ export function normalizeGeminiResult(result) {
8
+ let parsed;
9
+ try {
10
+ parsed = JSON.parse(result.stdout);
11
+ }
12
+ catch {
13
+ return withError(result, '', undefined, undefined, 'INVALID_PROVIDER_OUTPUT');
14
+ }
15
+ if (!record(parsed))
16
+ return withError(result, '', undefined, undefined, 'INVALID_PROVIDER_OUTPUT');
17
+ const answer = typeof parsed.response === 'string' ? parsed.response : undefined;
18
+ const sessionId = typeof parsed.session_id === 'string' ? parsed.session_id : undefined;
19
+ let usage;
20
+ const models = record(parsed.stats) && record(parsed.stats.models) ? Object.values(parsed.stats.models) : [];
21
+ let input = 0, output = 0, cached = 0, seen = false;
22
+ for (const m of models) {
23
+ if (!record(m) || !record(m.tokens))
24
+ continue;
25
+ const t = m.tokens;
26
+ if (tokens(t.prompt) && tokens(t.candidates)) {
27
+ seen = true;
28
+ input += t.prompt;
29
+ output += t.candidates + (tokens(t.thoughts) ? t.thoughts : 0);
30
+ if (tokens(t.cached))
31
+ cached += t.cached;
32
+ }
33
+ }
34
+ if (seen)
35
+ usage = { inputTokens: input, outputTokens: output, ...(cached ? { cachedInputTokens: cached } : {}) };
36
+ const errorCode = result.errorCode
37
+ ?? (result.exitCode !== 0 ? 'COMMAND_FAILED'
38
+ : parsed.error !== undefined ? 'PROVIDER_FAILED'
39
+ : answer === undefined ? 'INVALID_PROVIDER_OUTPUT'
40
+ : undefined);
41
+ return withError(result, answer ?? '', sessionId, usage, errorCode);
42
+ }
43
+ /**
44
+ * Normaliza `cursor-agent -p --output-format json`: o mesmo envelope do Claude
45
+ * (`type: "result"`, `subtype`, `is_error`, `result`, `session_id`, `usage`). O Cursor usa
46
+ * `inputTokens`/`outputTokens` em camelCase em alguns caminhos; os nomes são alinhados antes.
47
+ */
48
+ export function normalizeCursorResult(result) {
49
+ let parsed;
50
+ try {
51
+ parsed = JSON.parse(result.stdout);
52
+ }
53
+ catch {
54
+ return withError(result, '', undefined, undefined, 'INVALID_PROVIDER_OUTPUT');
55
+ }
56
+ if (record(parsed) && record(parsed.usage)) {
57
+ const u = parsed.usage;
58
+ parsed = {
59
+ ...parsed,
60
+ usage: {
61
+ input_tokens: u.input_tokens ?? u.inputTokens,
62
+ output_tokens: u.output_tokens ?? u.outputTokens,
63
+ cache_read_input_tokens: u.cache_read_input_tokens ?? u.cacheReadTokens,
64
+ },
65
+ };
66
+ }
67
+ return normalizeClaudeResult({ ...result, stdout: JSON.stringify(parsed) });
68
+ }
69
+ function withError(result, stdout, sessionId, usage, errorCode) {
70
+ return { ...result, stdout, sessionId, usage, exitCode: result.exitCode !== 0 ? result.exitCode : errorCode ? 1 : 0, ...(errorCode ? { errorCode } : {}) };
71
+ }
72
+ function record(value) {
73
+ return value !== null && typeof value === 'object' && !Array.isArray(value);
74
+ }
75
+ function tokens(value) {
76
+ return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
77
+ }
@@ -19,6 +19,14 @@ export declare const END = "<!-- forja:end -->";
19
19
  export declare const SUPPORTED_AI: readonly ['claude', 'codex', 'gemini', 'copilot'];
20
20
  /** Onde cada IA lê as instruções nativamente. */
21
21
  export declare const INSTRUCTION_FILE: Readonly<Record<string, string>>;
22
+ /**
23
+ * Skills do projeto (SPEC-051): pastas com SKILL.md em templates/project/skills/, instaladas onde cada
24
+ * IA as procura sozinha. Codex e o padrão comum entre ferramentas leem `.agents/skills/`.
25
+ */
26
+ export declare const SKILL_TARGETS: Readonly<Record<string, string>>;
27
+ export declare function templateSkills(): string[];
28
+ /** Valida o frontmatter de um SKILL.md: devolve o problema ou null. */
29
+ export declare function skillProblem(name: string, text: string | null): string | null;
22
30
  export declare const ROLES: readonly ['orchestrator', 'product', 'sdd-architect', 'context-engineer', 'governance', 'marketing'];
23
31
  /** Hooks do Claude Code. Guardados por `command -v`: sem `forja` no PATH, a sessão abre sem erro. */
24
32
  export declare const HOOKS: Readonly<Record<string, string>>;
@@ -31,11 +31,43 @@ export const INSTRUCTION_FILE = {
31
31
  };
32
32
  const CODEX_MCP = '# Forja — servidor MCP (forja project:wire)\n[mcp_servers.forja]\ncommand = "forja"\nargs = ["mcp:start"]\n';
33
33
  const GITIGNORE = ['memory/sqlite/', '.context/'];
34
+ /**
35
+ * Skills do projeto (SPEC-051): pastas com SKILL.md em templates/project/skills/, instaladas onde cada
36
+ * IA as procura sozinha. Codex e o padrão comum entre ferramentas leem `.agents/skills/`.
37
+ */
38
+ export const SKILL_TARGETS = {
39
+ claude: path.join('.claude', 'skills'),
40
+ codex: path.join('.agents', 'skills'),
41
+ };
42
+ export function templateSkills() {
43
+ const dir = asset('templates', 'project', 'skills');
44
+ try {
45
+ return fs.readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name).sort();
46
+ }
47
+ catch {
48
+ return [];
49
+ }
50
+ }
51
+ /** Valida o frontmatter de um SKILL.md: devolve o problema ou null. */
52
+ export function skillProblem(name, text) {
53
+ if (text == null)
54
+ return 'ausente';
55
+ // `\r?\n`: no Windows o checkout traz CRLF, e uma skill perfeitamente válida seria lida como inválida.
56
+ const m = text.match(/^---\r?\nname: ([^\r\n]+)\r?\ndescription: ([^\r\n]+)\r?\n/);
57
+ if (!m)
58
+ return 'frontmatter sem name/description';
59
+ if (m[1].trim() !== name)
60
+ return `name "${m[1].trim()}" ≠ pasta`;
61
+ return null;
62
+ }
34
63
  export const ROLES = ['orchestrator', 'product', 'sdd-architect', 'context-engineer', 'governance', 'marketing'];
35
64
  /** Hooks do Claude Code. Guardados por `command -v`: sem `forja` no PATH, a sessão abre sem erro. */
36
65
  export const HOOKS = {
37
66
  SessionStart: 'hook:session-start',
38
67
  UserPromptSubmit: 'hook:user-prompt',
68
+ // SPEC-052: checkpoint da sessão ao fim de cada turno e antes de compactar.
69
+ Stop: 'hook:session-memory',
70
+ PreCompact: 'hook:session-memory',
39
71
  };
40
72
  export function hookCommand(cmd) {
41
73
  return `command -v forja >/dev/null 2>&1 && forja ${cmd} || true`;
@@ -204,6 +236,21 @@ export function wireProject(dir, opts = {}) {
204
236
  else if (mcp.mcpServers.codegraph && !hasBinary('codegraph'))
205
237
  delete mcp.mcpServers.codegraph;
206
238
  writeJson(dir, '.mcp.json', mcp, changes);
239
+ // Skills: uma cópia por IA conectada que as lê nativamente. Skill editada pelo usuário (sem a marca)
240
+ // não é sobrescrita.
241
+ for (const [agent, target] of Object.entries(SKILL_TARGETS)) {
242
+ if (!ai.includes(agent))
243
+ continue;
244
+ for (const name of templateSkills()) {
245
+ const rel = path.join(target, name, 'SKILL.md');
246
+ const current = readOrNull(path.join(dir, rel));
247
+ if (current != null && !current.includes(AGENT_MARK)) {
248
+ changes.push({ file: rel, action: 'unchanged' });
249
+ continue;
250
+ }
251
+ write(dir, rel, `${template(path.join('skills', name, 'SKILL.md'))}\n\n${AGENT_MARK}\n`, changes);
252
+ }
253
+ }
207
254
  // O mesmo servidor nas outras IAs, cada uma na config de projeto que ela lê sozinha.
208
255
  if (ai.includes('codex')) {
209
256
  const rel = path.join('.codex', 'config.toml');
@@ -303,7 +350,7 @@ export function checkProjectWiring(dir, { commands, ai }) {
303
350
  }
304
351
  if (settings !== undefined) {
305
352
  const missing = Object.entries(HOOKS).filter(([event, cmd]) => !(settings?.hooks?.[event] || []).some((g) => (g.hooks || []).some((h) => String(h.command || '').includes(`forja ${cmd}`))));
306
- add('claude-hooks', missing.length ? 'fail' : 'ok', missing.length ? `hooks ausentes: ${missing.map(([e]) => e).join(', ')}` : 'SessionStart + UserPromptSubmit');
353
+ add('claude-hooks', missing.length ? 'fail' : 'ok', missing.length ? `hooks ausentes: ${missing.map(([e]) => e).join(', ')}` : Object.keys(HOOKS).join(' + '));
307
354
  }
308
355
  const absent = ROLES.filter((r) => !fs.existsSync(path.join(dir, '.claude', 'agents', `${r}.md`)));
309
356
  add('claude-agents', absent.length ? 'fail' : 'ok', absent.length ? `sub-agents ausentes: ${absent.join(', ')}` : `${ROLES.length} sub-agents`);
@@ -360,10 +407,38 @@ export function checkProjectWiring(dir, { commands, ai }) {
360
407
  const others = wiredAi.filter((a) => a !== 'claude');
361
408
  if (others.length)
362
409
  add('mcp-ias', mcpGaps.length ? 'fail' : 'ok', mcpGaps.length ? `servidor forja ausente em: ${mcpGaps.join(', ')}` : `servidor forja também em: ${others.join(', ')}`);
410
+ // Skills: presentes, com frontmatter válido, e citando só skills que existem.
411
+ const expectedSkills = templateSkills();
412
+ const skillTexts = [];
413
+ for (const [agent, target] of Object.entries(SKILL_TARGETS)) {
414
+ if (!wiredAi.includes(agent))
415
+ continue;
416
+ const problems = [];
417
+ const installed = new Set();
418
+ for (const name of expectedSkills) {
419
+ const rel = path.join(target, name, 'SKILL.md');
420
+ const text = readOrNull(path.join(dir, rel));
421
+ const p = skillProblem(name, text);
422
+ if (p)
423
+ problems.push(`${name}: ${p}`);
424
+ else {
425
+ installed.add(name);
426
+ skillTexts.push(rel);
427
+ }
428
+ }
429
+ for (const rel of skillTexts.filter((r) => r.startsWith(target))) {
430
+ const text = readOrNull(path.join(dir, rel)) ?? '';
431
+ for (const ref of text.matchAll(/`([a-z]+(?:-[a-z]+)+)`/g)) {
432
+ if (expectedSkills.includes(ref[1]) && !installed.has(ref[1]))
433
+ problems.push(`${path.basename(path.dirname(rel))} cita ${ref[1]}, ausente`);
434
+ }
435
+ }
436
+ add(`skills-${agent}`, problems.length ? 'fail' : 'ok', problems.length ? `${target}: ${problems.slice(0, 4).join('; ')}${problems.length > 4 ? ` (+${problems.length - 4})` : ''}` : `${installed.size} skills em ${target}`);
437
+ }
363
438
  // Todo comando citado ao usuário/IA precisa existir — é o que impede instrução que não funciona.
364
439
  const cited = new Map();
365
440
  const texts = ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md', path.join('.github', 'copilot-instructions.md'),
366
- ...ROLES.map((r) => path.join('.claude', 'agents', `${r}.md`))];
441
+ ...ROLES.map((r) => path.join('.claude', 'agents', `${r}.md`)), ...skillTexts];
367
442
  for (const rel of texts) {
368
443
  const t = readOrNull(path.join(dir, rel));
369
444
  if (t)
@@ -378,7 +453,8 @@ export function checkProjectWiring(dir, { commands, ai }) {
378
453
  cited.set(c, '.claude/settings.json');
379
454
  }
380
455
  catch { /* já reportado acima */ }
381
- const unknown = [...cited].filter(([c]) => !(c in commands)).map(([c, f]) => `${c} (${f})`);
456
+ // `help` é embutido no core (não está no registry).
457
+ const unknown = [...cited].filter(([c]) => !(c in commands) && c !== 'help').map(([c, f]) => `${c} (${f})`);
382
458
  add('commands', unknown.length ? 'fail' : 'ok', unknown.length ? `comandos inexistentes citados: ${unknown.join(', ')}` : `${cited.size} comandos citados, todos no registry`);
383
459
  const broken = ['.', 'backend'].flatMap((sub) => fs.existsSync(path.join(dir, sub, 'package.json'))
384
460
  ? brokenNodeScripts(path.join(dir, sub)).map((b) => (sub === '.' ? b : `${sub}/${b}`)) : []);
@@ -0,0 +1,38 @@
1
+ /**
2
+ * lib/session-memory.ts — checkpoint determinístico de uma sessão do Claude Code (SPEC-052, ADR-0091).
3
+ *
4
+ * Lê o transcript JSONL que o Claude Code passa aos hooks e extrai só fatos estruturais: título da
5
+ * sessão, branch, arquivos editados, comandos `forja`, specs tocadas e assuntos de commit. Nunca o
6
+ * texto de prompts, comandos inteiros ou saídas de ferramenta: o checkpoint vai para `memory/`, que é
7
+ * commitada, e um segredo colado no chat não pode acabar no git.
8
+ *
9
+ * O formato do transcript não é contrato público: o que não for reconhecido é ignorado.
10
+ */
11
+ export interface SessionDigest {
12
+ readonly sessionId: string;
13
+ readonly title: string | null;
14
+ readonly branch: string | null;
15
+ readonly startedAt: string | null;
16
+ readonly updatedAt: string | null;
17
+ readonly files: readonly string[];
18
+ readonly forjaCommands: readonly string[];
19
+ readonly specs: readonly string[];
20
+ readonly commits: readonly string[];
21
+ }
22
+ /**
23
+ * Lê o transcript e devolve o resumo. `root` é a raiz do projeto: arquivos fora dela não entram.
24
+ * Linhas sem `tool_use` nem `ai-title` são descartadas antes do `JSON.parse` (transcripts têm MBs).
25
+ */
26
+ export declare function digestTranscript(transcriptPath: string, root: string, sessionId: string): SessionDigest;
27
+ /** Sessão sem edição, sem comando forja e sem commit não é memória: é conversa. */
28
+ export declare function hasWork(d: SessionDigest): boolean;
29
+ export declare function checkpointPath(root: string, d: Pick<SessionDigest, 'sessionId' | 'startedAt'>): string;
30
+ export declare function renderCheckpoint(d: SessionDigest, event: string): string;
31
+ /** Grava (ou reescreve) o checkpoint. Devolve o caminho, ou null quando não há trabalho a registrar. */
32
+ export declare function writeCheckpoint(root: string, transcriptPath: string, sessionId: string, event: string): string | null;
33
+ /** Checkpoint desta sessão (para o SessionStart `compact`), ou null. */
34
+ export declare function findCheckpoint(root: string, sessionId: string): string | null;
35
+ /** Checkpoint mais recente (por mtime), exceto o da sessão atual. */
36
+ export declare function latestCheckpoint(root: string, exceptSessionId?: string): string | null;
37
+ /** Uma linha sobre um checkpoint: data, título, nº de arquivos, specs. */
38
+ export declare function summarizeCheckpoint(file: string): string;