forjajs 5.1.0 → 5.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (119) hide show
  1. package/CHANGELOG.md +108 -0
  2. package/README.md +52 -4
  3. package/README.pt-BR.md +54 -4
  4. package/dist/apps/cli/src/index.d.ts +0 -1
  5. package/dist/apps/cli/src/index.js +43 -32
  6. package/dist/apps/dashboard/app/api/forja/[...path]/route.js +34 -1
  7. package/dist/apps/dashboard/app/api/forja/capabilities.d.ts +26 -0
  8. package/dist/apps/dashboard/app/api/forja/capabilities.js +39 -0
  9. package/dist/apps/dashboard/app/dashboard-client.jsx +607 -42
  10. package/dist/apps/server/src/forja-nest.module.d.ts +6 -0
  11. package/dist/apps/server/src/forja-nest.module.js +55 -0
  12. package/dist/apps/server/src/main.d.ts +21 -4
  13. package/dist/apps/server/src/main.js +79 -57
  14. package/dist/apps/server/src/task-planning-service.d.ts +29 -0
  15. package/dist/apps/server/src/task-planning-service.js +195 -0
  16. package/dist/apps/server/src/task-runtime-coordinator.d.ts +57 -0
  17. package/dist/apps/server/src/task-runtime-coordinator.js +229 -0
  18. package/dist/bin/forja.js +3 -2
  19. package/dist/lib/agent-evals.d.ts +138 -0
  20. package/dist/lib/agent-evals.js +365 -0
  21. package/dist/lib/cli-output.js +14 -2
  22. package/dist/lib/code-context.d.ts +33 -5
  23. package/dist/lib/code-context.js +70 -5
  24. package/dist/lib/context-builder.d.ts +49 -4
  25. package/dist/lib/context-builder.js +114 -47
  26. package/dist/lib/core/coverage-gate.d.ts +59 -0
  27. package/dist/lib/core/coverage-gate.js +58 -0
  28. package/dist/lib/core/doc-graph.d.ts +38 -0
  29. package/dist/lib/core/doc-graph.js +83 -0
  30. package/dist/lib/core/health.js +286 -5
  31. package/dist/lib/core/journey.js +26 -0
  32. package/dist/lib/core/registry.js +81 -6
  33. package/dist/lib/docs-reference.d.ts +35 -0
  34. package/dist/lib/docs-reference.js +57 -0
  35. package/dist/lib/exec.d.ts +55 -0
  36. package/dist/lib/exec.js +141 -0
  37. package/dist/lib/project-wiring.js +6 -2
  38. package/dist/lib/session-memory.d.ts +38 -0
  39. package/dist/lib/session-memory.js +206 -0
  40. package/dist/lib/spec-trace.d.ts +46 -0
  41. package/dist/lib/spec-trace.js +184 -0
  42. package/dist/packages/adapter-git/src/index.js +13 -4
  43. package/dist/packages/adapter-nest/src/index.d.ts +2 -1
  44. package/dist/packages/adapter-nest/src/index.js +59 -1
  45. package/dist/packages/adapter-sqlite/src/index.d.ts +15 -1
  46. package/dist/packages/adapter-sqlite/src/index.js +61 -1
  47. package/dist/packages/context/src/index.d.ts +2 -0
  48. package/dist/packages/context/src/index.js +36 -15
  49. package/dist/packages/contracts/src/index.d.ts +64 -0
  50. package/dist/packages/core/src/index.d.ts +9 -1
  51. package/dist/packages/core/src/index.js +28 -3
  52. package/dist/packages/graph/src/index.js +14 -5
  53. package/dist/packages/llm/src/index.js +7 -24
  54. package/dist/packages/mcp/src/index.d.ts +8 -0
  55. package/dist/packages/mcp/src/index.js +12 -1
  56. package/dist/packages/observability/src/index.d.ts +11 -0
  57. package/dist/packages/observability/src/index.js +3 -0
  58. package/dist/packages/orchestration/src/index.d.ts +15 -1
  59. package/dist/packages/orchestration/src/index.js +127 -21
  60. package/dist/packages/planner/src/index.d.ts +7 -1
  61. package/dist/packages/planner/src/index.js +67 -10
  62. package/dist/packages/planner/src/proposal-store.d.ts +30 -0
  63. package/dist/packages/planner/src/proposal-store.js +109 -0
  64. package/dist/packages/policy/src/index.d.ts +9 -16
  65. package/dist/packages/policy/src/index.js +114 -31
  66. package/dist/packages/runtime/src/index.d.ts +16 -2
  67. package/dist/packages/runtime/src/index.js +176 -61
  68. package/dist/scripts/build-smart-context.d.ts +2 -0
  69. package/dist/scripts/build-smart-context.js +12 -3
  70. package/dist/scripts/code-context.d.ts +3 -1
  71. package/dist/scripts/code-context.js +13 -3
  72. package/dist/scripts/coverage-gate.d.ts +2 -0
  73. package/dist/scripts/coverage-gate.js +101 -0
  74. package/dist/scripts/eval-agents.d.ts +11 -0
  75. package/dist/scripts/eval-agents.js +96 -0
  76. package/dist/scripts/gen-commands-doc.d.ts +2 -0
  77. package/dist/scripts/gen-commands-doc.js +18 -0
  78. package/dist/scripts/hook-session-memory.d.ts +9 -0
  79. package/dist/scripts/hook-session-memory.js +20 -0
  80. package/dist/scripts/hook-session-start.js +34 -0
  81. package/dist/scripts/llm-fit.js +15 -6
  82. package/dist/scripts/simulate.js +16 -4
  83. package/dist/scripts/spec-trace.d.ts +10 -0
  84. package/dist/scripts/spec-trace.js +73 -0
  85. package/dist/scripts/sync-universal-memory.js +69 -4
  86. package/dist/scripts/token-benchmark.d.ts +33 -1
  87. package/dist/scripts/token-benchmark.js +179 -5
  88. package/dist/scripts/token-economy.js +3 -1
  89. package/dist/scripts/tools-doctor.d.ts +16 -1
  90. package/dist/scripts/tools-doctor.js +58 -17
  91. package/docs/commands.md +155 -0
  92. package/docs/fluxo.md +11 -7
  93. package/docs/init-project.md +3 -1
  94. package/docs/llm-fit-loop.md +20 -0
  95. package/docs/manual-operacional-cli-sdd-gsd.md +3 -2
  96. package/docs/produto/factsheet-marketing.md +7 -5
  97. package/docs/produto/roteiro-demo.md +14 -5
  98. package/docs/quick-reference.md +3 -3
  99. package/docs/token-optimization.md +10 -6
  100. package/memory/90-decisions/0091-memoria-de-sessao-por-hooks.md +40 -0
  101. package/memory/90-decisions/0092-criterios-de-aceite-ligados-a-testes.md +37 -0
  102. package/memory/90-decisions/0093-avaliacoes-com-agentes-reais.md +40 -0
  103. package/package.json +4 -2
  104. package/specs/avaliacoes-de-agentes/spec.md +52 -0
  105. package/specs/criterios-ligados-a-testes/spec.md +42 -0
  106. package/specs/memoria-de-sessao/spec.md +48 -0
  107. package/specs/v6-agent-runtime-portable/spec.md +83 -0
  108. package/specs/v6-core-consolidation/spec.md +70 -0
  109. package/specs/v6-docs-drift/spec.md +85 -0
  110. package/specs/v6-quality-gates/spec.md +104 -0
  111. package/specs/v6-token-economy/spec.md +84 -0
  112. package/templates/evals/agents/adr.json +25 -0
  113. package/templates/evals/agents/memoria.json +32 -0
  114. package/templates/evals/agents/proxima-acao.json +29 -0
  115. package/templates/evals/agents/spec-nova.json +26 -0
  116. package/templates/evals/agents/teste-do-criterio.json +29 -0
  117. package/templates/project/AGENTS.md +7 -0
  118. package/templates/project/CLAUDE.md +3 -2
  119. package/templates/project/skills/testing/SKILL.md +1 -1
@@ -38,7 +38,8 @@ import { fileURLToPath } from 'node:url';
38
38
  import { getWorkspaceDbPath, getWorkspaceInfo } from '../workspace.js';
39
39
  import { runChecks as run, worstStatus, stripTemplateLiterals, asErrno } from './checks.js';
40
40
  import { COMMANDS } from './registry.js';
41
- import { scanCommands, scanLinks, projectCommands, scanAdrRefs, adrNumbers, commandCited } from './doc-graph.js';
41
+ import { scanCommands, scanLinks, projectCommands, scanAdrRefs, adrNumbers, commandCited, scanFlags, scanSkillCounts } from './doc-graph.js';
42
+ import { declaredFlags, renderCommandsDoc, skillsCount } from '../docs-reference.js';
42
43
  import { topologyIssues } from '../agent-topology.js';
43
44
  import { CLI_INTERFACE_COMMANDS } from '../../apps/cli/src/index.js';
44
45
  import { pkgRoot } from '../paths.js';
@@ -223,6 +224,31 @@ function newestMarkdownMtime(env, dir, acc = { t: 0 }) {
223
224
  }
224
225
  return acc.t;
225
226
  }
227
+ /**
228
+ * Quando o último sync rodou, dito pelo próprio sync (`sync_meta.last_sync`). O mtime do arquivo não
229
+ * serve de fonte: o banco abre em WAL e uma escrita pequena fica no `-wal` sem tocar o `.db`, então o
230
+ * índice em dia parecia velho. Achado da SPEC-057 — o sync passou a pular o que não mudou, ou seja, a
231
+ * não escrever quase nada, e a mentira do mtime virou rotina.
232
+ */
233
+ async function lastSyncAt(env, dbPath) {
234
+ try {
235
+ const { default: Database } = await env.importModule('better-sqlite3');
236
+ const db = new Database(dbPath, { readonly: true });
237
+ try {
238
+ const row = db.prepare("SELECT value FROM sync_meta WHERE name = 'last_sync'").get();
239
+ const at = row ? Date.parse(JSON.parse(row.value).at) : Number.NaN;
240
+ return Number.isNaN(at) ? null : at;
241
+ }
242
+ finally {
243
+ db.close();
244
+ }
245
+ }
246
+ catch {
247
+ // Índice de versão anterior (sem `sync_meta`) ou banco que não abre: `memory-db` já classifica a
248
+ // causa. Aqui só cai no mtime, que é a aproximação antiga — melhor que avisar errado.
249
+ return null;
250
+ }
251
+ }
226
252
  /**
227
253
  * Índice defasado é a falha mais barata de corrigir e a mais cara de ignorar: `query:universal`
228
254
  * é o primeiro passo da economia de tokens (ADR-0009), então um índice velho alimenta os agentes
@@ -236,17 +262,18 @@ const memoryFresh = {
236
262
  severity: 'warn',
237
263
  scope: 'runtime',
238
264
  dependsOn: 'memory-db',
239
- probe(env) {
265
+ async probe(env) {
240
266
  const dbPath = env.workspace.dbPath();
241
267
  // `memory-db` passa com aviso quando o banco nunca foi indexado, então a cascata não nos pula:
242
268
  // um índice que não existe não pode estar defasado.
243
269
  if (!env.fs.existsSync(dbPath)) {
244
270
  return { status: 'skipped', detail: 'não há índice para comparar', fix: null };
245
271
  }
246
- const dbMtime = env.fs.statSync(dbPath).mtimeMs;
272
+ const syncedAt = await lastSyncAt(env, dbPath);
273
+ const dbTime = syncedAt ?? env.fs.statSync(dbPath).mtimeMs;
247
274
  const newest = newestMarkdownMtime(env, path.join(env.root, 'memory'));
248
- if (newest > dbMtime) {
249
- const horas = Math.round((newest - dbMtime) / 36e5);
275
+ if (newest > dbTime) {
276
+ const horas = Math.round((newest - dbTime) / 36e5);
250
277
  return {
251
278
  status: 'warn',
252
279
  detail: `memory/ mudou depois do último sync (${horas}h) — query:universal vai responder ` +
@@ -515,6 +542,255 @@ const commandsDocumented = {
515
542
  return { status: 'ok', detail: 'todos os comandos do registry aparecem na doc', fix: null };
516
543
  },
517
544
  };
545
+ /**
546
+ * Flag que o comando não declara faz o agente executar algo que falha — ou, pior, que é ignorado em
547
+ * silêncio e produz um resultado diferente do pedido. `critical`, mesma família de `docs-commands`:
548
+ * a doc instrui execução. O juízo compara contra `usage`/`examples` do registry (fonte única);
549
+ * quando o registry não declara `usage`, a flag documentada é o sintoma de um `usage` faltando.
550
+ */
551
+ const docsFlags = {
552
+ id: 'docs-flags',
553
+ title: 'flags citadas na doc existem no comando',
554
+ severity: 'critical',
555
+ scope: 'repo',
556
+ probe(env) {
557
+ if (!isFrameworkRepo(env)) {
558
+ return { status: 'ok', detail: 'fora do repo do framework — não se aplica', fix: null };
559
+ }
560
+ const invalidas = scanFlags(env).filter((h) => {
561
+ const spec = COMMANDS[h.command];
562
+ // Comando que o registry não conhece não é deste check — quem julga citação inexistente é
563
+ // `docs-commands` (docs/2x/* descreve superfície planejada, não implementada).
564
+ if (!spec)
565
+ return false;
566
+ const declara = (name) => {
567
+ const other = COMMANDS[name];
568
+ return other ? declaredFlags(other).has(h.flag) : false;
569
+ };
570
+ // A linha pode atribuir a flag a outro comando do Forja citado nela ("... (project:new
571
+ // --template)" na célula de project:templates) — isso é prosa correta, não drift.
572
+ return !declaredFlags(spec).has(h.flag) && !h.mentions.some((m) => declara(m));
573
+ });
574
+ if (invalidas.length) {
575
+ const amostra = invalidas.slice(0, 5).map((h) => `${h.command} ${h.flag} (${h.file}:${h.line})`).join(', ');
576
+ return {
577
+ status: 'fail',
578
+ detail: `${invalidas.length} flag(s) documentadas que o comando não declara: ${amostra}`,
579
+ fix: 'declare a flag no usage/examples em lib/core/registry.ts, ou corrija a citação no arquivo:linha indicado',
580
+ };
581
+ }
582
+ return { status: 'ok', detail: 'toda flag citada na doc resolve no usage do comando', fix: null };
583
+ },
584
+ };
585
+ /**
586
+ * Comando `tier: 'core'` é o caminho feliz que o README ensina — diferente de `commands-documented`
587
+ * (warn, qualquer superfície): aqui a fronteira é o onboarding nos dois READMEs, que é o que um
588
+ * usuário novo e o agente que chega frio leem primeiro. `critical`: core ausente é onboarding quebrado.
589
+ */
590
+ const coreInReadme = {
591
+ id: 'core-in-readme',
592
+ title: 'todo comando core aparece nos dois READMEs',
593
+ severity: 'critical',
594
+ scope: 'repo',
595
+ probe(env) {
596
+ if (!isFrameworkRepo(env)) {
597
+ return { status: 'ok', detail: 'fora do repo do framework — não se aplica', fix: null };
598
+ }
599
+ const faltando = [];
600
+ for (const rel of ['README.md', 'README.pt-BR.md']) {
601
+ let src;
602
+ try {
603
+ src = env.fs.readFileSync(path.join(env.root, rel), 'utf8');
604
+ }
605
+ catch {
606
+ faltando.push(`(README ausente: ${rel})`);
607
+ continue;
608
+ }
609
+ for (const [name, spec] of Object.entries(COMMANDS)) {
610
+ if (spec.tier !== 'core')
611
+ continue;
612
+ const citado = new RegExp(`\\bforja[ \\t]+${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`).test(src);
613
+ if (!citado)
614
+ faltando.push(`${name} (${rel})`);
615
+ }
616
+ }
617
+ if (faltando.length) {
618
+ return {
619
+ status: 'fail',
620
+ detail: `${faltando.length} comando(s) core fora do README: ${faltando.slice(0, 6).join(', ')}`,
621
+ fix: 'documente cada um no quick start/comandos essenciais dos dois READMEs, ou rebaixe o tier no registry',
622
+ };
623
+ }
624
+ return { status: 'ok', detail: 'os dois READMEs ensinam todos os comandos core', fix: null };
625
+ },
626
+ };
627
+ /**
628
+ * Contagem de skills afirmada na doc vs pastas reais de `templates/project/skills/`. Número errado é
629
+ * fato falso entregue a quem avalia o produto. `warn`: não impede trabalho, mas o gate de release lê.
630
+ */
631
+ const docsSkillsCount = {
632
+ id: 'docs-skills-count',
633
+ title: 'contagem de skills da doc confere com o template',
634
+ severity: 'warn',
635
+ scope: 'repo',
636
+ probe(env) {
637
+ if (!isFrameworkRepo(env)) {
638
+ return { status: 'ok', detail: 'fora do repo do framework — não se aplica', fix: null };
639
+ }
640
+ const real = skillsCount(env.fs, path.join(env.root, 'templates', 'project', 'skills'));
641
+ const erradas = scanSkillCounts(env).filter((h) => h.claimed !== real);
642
+ if (erradas.length) {
643
+ const amostra = erradas.slice(0, 5).map((h) => `${h.claimed} em ${h.file}:${h.line}`).join(', ');
644
+ return {
645
+ status: 'warn',
646
+ detail: `${erradas.length} contagem(ns) de skills divergem das ${real} pastas reais: ${amostra}`,
647
+ fix: 'atualize o número nos arquivos indicados — a fonte real é templates/project/skills/ (só diretórios contam)',
648
+ };
649
+ }
650
+ return { status: 'ok', detail: `doc fala em ${real} skills, que é o que o template tem`, fix: null };
651
+ },
652
+ };
653
+ /**
654
+ * `docs/commands.md` é derivada do registry — se diverge, alguém adicionou/renomeou comando e não
655
+ * regenerou. `critical` porque a correção é um comando só e a referência é a superfície que promete
656
+ * completude (os READMEs ensinam o caminho feliz, não os 100+ comandos).
657
+ */
658
+ const commandsRef = {
659
+ id: 'commands-ref',
660
+ title: 'docs/commands.md é o que o registry gera',
661
+ severity: 'critical',
662
+ scope: 'repo',
663
+ probe(env) {
664
+ if (!isFrameworkRepo(env)) {
665
+ return { status: 'ok', detail: 'fora do repo do framework — não se aplica', fix: null };
666
+ }
667
+ const esperado = renderCommandsDoc(COMMANDS, skillsCount(env.fs, path.join(env.root, 'templates', 'project', 'skills')));
668
+ let atual = null;
669
+ try {
670
+ atual = env.fs.readFileSync(path.join(env.root, 'docs', 'commands.md'), 'utf8');
671
+ }
672
+ catch {
673
+ atual = null;
674
+ }
675
+ if (atual === null) {
676
+ return { status: 'fail', detail: 'docs/commands.md não existe', fix: 'forja docs:gen' };
677
+ }
678
+ // CRLF não é deriva: no checkout Windows o arquivo lido chega com `\r\n` e o gerado com `\n`, e a
679
+ // comparação literal reprovaria uma doc que está exatamente no dia.
680
+ if (atual.replace(/\r\n/g, '\n') !== esperado) {
681
+ return {
682
+ status: 'fail',
683
+ detail: `docs/commands.md diverge do registry (${Object.keys(COMMANDS).length} comandos esperados)`,
684
+ fix: 'forja docs:gen',
685
+ };
686
+ }
687
+ return { status: 'ok', detail: `referência completa em dia (${Object.keys(COMMANDS).length} comandos)`, fix: null };
688
+ },
689
+ };
690
+ /**
691
+ * Ratchet de dívida de tipos (SPEC-056). Sem ESLint de propósito: o repo não tem toolchain de lint, e
692
+ * adotar `typescript-eslint` só para contar o que uma regex conta é importar uma segunda máquina —
693
+ * o defeito que a SPEC-058 ataca. O teto vive versionado em `lib/core/quality-budget.json`: descer o
694
+ * número é um diff visível no PR, e é assim que a dívida só diminui.
695
+ *
696
+ * `critical` quando cresce: `any` é onde o on-ramp do checkJs (SPEC-012) deixa de proteger, e código
697
+ * sem tipos que roda em três SOs é o que quebra na máquina do usuário, não na nossa.
698
+ * Abaixo do teto é `warn` (não `ok`): teto folgado é teto esquecido.
699
+ */
700
+ /**
701
+ * `any` explícito: anotação, cast, argumento de genérico ou array. Sem lookbehind na frente do grupo —
702
+ * o caractere antes de `: any` é quase sempre parte do identificador (`probe(env: any)`), e a âncora
703
+ * errada fazia o ratchet contar 37 de 300. `\b` antes de `as` impede "was any" de virar cast.
704
+ */
705
+ const ANY_RE = /(?:\bas\s+any\b|:\s*any\b|<any>|\bany\[\])/g;
706
+ const QUALITY_BUDGET = ['lib', 'core', 'quality-budget.json'];
707
+ const budgetLabel = QUALITY_BUDGET.join('/');
708
+ const budgetPath = (root) => path.join(root, ...QUALITY_BUDGET);
709
+ /** `any` explícito por arquivo, nos diretórios de código-fonte do framework. */
710
+ function explicitAnyByFile(env) {
711
+ const skip = new Set(['node_modules', 'dist', '.next', 'archive']);
712
+ const out = new Map();
713
+ const walk = (dir) => {
714
+ let entries;
715
+ try {
716
+ entries = env.fs.readdirSync(dir);
717
+ }
718
+ catch {
719
+ return;
720
+ }
721
+ for (const entry of entries) {
722
+ if (skip.has(entry) || entry.startsWith('.'))
723
+ continue;
724
+ const p = path.join(dir, entry);
725
+ let st;
726
+ try {
727
+ st = env.fs.statSync(p);
728
+ }
729
+ catch {
730
+ continue;
731
+ }
732
+ if (st.isDirectory()) {
733
+ walk(p);
734
+ continue;
735
+ }
736
+ if (!/\.tsx?$/.test(entry) || entry.endsWith('.d.ts'))
737
+ continue;
738
+ // Sem apagar template literals, os geradores de boilerplate acusam a si mesmos: eles *escrevem*
739
+ // TS com `any` para o projeto gerado, e aquele código não é tipado por nós (mesma razão do
740
+ // `runtime-deps`).
741
+ const hits = stripTemplateLiterals(env.fs.readFileSync(p, 'utf8')).match(ANY_RE);
742
+ if (hits?.length)
743
+ out.set(path.relative(env.root, p).replaceAll(path.sep, '/'), hits.length);
744
+ }
745
+ };
746
+ for (const d of ['bin', 'lib', 'scripts', 'apps'])
747
+ walk(path.join(env.root, d));
748
+ return out;
749
+ }
750
+ const typeDebt = {
751
+ id: 'type-debt',
752
+ title: 'dívida de `any` explícito não cresce',
753
+ severity: 'critical',
754
+ scope: 'repo',
755
+ probe(env) {
756
+ if (!isFrameworkRepo(env)) {
757
+ return { status: 'ok', detail: 'fora do repo do framework — não se aplica', fix: null };
758
+ }
759
+ let teto;
760
+ try {
761
+ teto = JSON.parse(env.fs.readFileSync(budgetPath(env.root), 'utf8')).anyCeiling;
762
+ }
763
+ catch (err) {
764
+ return {
765
+ status: 'fail',
766
+ detail: `orçamento de qualidade ilegível (${budgetLabel}): ${asErrno(err).message}`,
767
+ fix: `crie ${budgetLabel} com { "anyCeiling": <contagem atual>, "coverageLineFloor": <piso> }`,
768
+ };
769
+ }
770
+ if (typeof teto !== 'number') {
771
+ return { status: 'fail', detail: `${budgetLabel} sem anyCeiling numérico`, fix: `declare "anyCeiling" em ${budgetLabel}` };
772
+ }
773
+ const porArquivo = explicitAnyByFile(env);
774
+ const total = [...porArquivo.values()].reduce((a, b) => a + b, 0);
775
+ const maiores = [...porArquivo].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, 3)
776
+ .map(([f, n]) => `${f} (${n})`).join(', ');
777
+ if (total > teto) {
778
+ return {
779
+ status: 'fail',
780
+ detail: `${total} \`any\` explícitos, teto é ${teto} — maiores: ${maiores}`,
781
+ fix: 'tipue o que o PR adicionou (o teto não sobe); se a dívida for inevitável, suba o teto num commit próprio e justificado',
782
+ };
783
+ }
784
+ if (total < teto) {
785
+ return {
786
+ status: 'warn',
787
+ detail: `${total} \`any\` explícitos contra teto ${teto} — folga de ${teto - total}`,
788
+ fix: `baixe anyCeiling para ${total} em ${budgetLabel}: ratchet que não desce não trava nada`,
789
+ };
790
+ }
791
+ return { status: 'ok', detail: `${total} \`any\` explícitos, no teto (${teto})`, fix: null };
792
+ },
793
+ };
518
794
  /** Link relativo para o nada é step obscuro. `warn`: atrapalha a navegação, não impede trabalho. */
519
795
  const docsLinks = {
520
796
  id: 'docs-links',
@@ -632,8 +908,13 @@ export const CHECKS = [
632
908
  mcpJson,
633
909
  docsCommands,
634
910
  commandsDocumented,
911
+ docsFlags,
912
+ coreInReadme,
913
+ docsSkillsCount,
914
+ commandsRef,
635
915
  docsLinks,
636
916
  adrRefs,
917
+ typeDebt,
637
918
  agentTopology,
638
919
  handoffOrphans,
639
920
  ];
@@ -96,6 +96,14 @@ export function runJourney(opts) {
96
96
  add('context:smart', r.code === 0 && packOk, packOk ? 'modo task inclui a spec' : firstLine(r.out));
97
97
  r = forja(['spec:check'], proj);
98
98
  add('spec:check', r.code === 0 && /pagamentos/.test(r.out), firstLine(r.out));
99
+ // SPEC-053: o rastreio critério × teste roda no projeto do consumidor e lê a spec recém-criada.
100
+ r = forja(['spec:trace', 'pagamentos', '--json'], proj);
101
+ let trace = null;
102
+ try {
103
+ trace = JSON.parse(r.stdout);
104
+ }
105
+ catch { /* reportado abaixo */ }
106
+ add('spec:trace', r.code === 0 && trace?.status === 'ok' && trace.specs?.[0]?.slug === 'pagamentos', trace ? `${trace.totals.covered}/${trace.totals.criteria} critérios com teste` : firstLine(r.out));
99
107
  r = forja(['project:check'], proj);
100
108
  add('project:check', r.code === 0, firstLine(r.out));
101
109
  r = forja(['tools:doctor'], proj);
@@ -114,6 +122,24 @@ export function runJourney(opts) {
114
122
  }
115
123
  catch { /* reportado abaixo */ }
116
124
  add('hook:user-prompt', r.code === 0 && ctx.includes('specs/pagamentos/spec.md'), ctx ? 'injeta a spec citada' : firstLine(r.out));
125
+ // SPEC-052: o checkpoint gravado no Stop/PreCompact volta no SessionStart depois da compactação.
126
+ const sid = 'jornada0-0000-4000-8000-000000000000';
127
+ const transcript = path.join(base, 'transcript.jsonl');
128
+ fs.writeFileSync(transcript, [
129
+ { type: 'assistant', timestamp: new Date().toISOString(), gitBranch: 'main', message: { content: [{ type: 'tool_use', id: 'w1', name: 'Write', input: { file_path: path.join(proj, 'specs', 'pagamentos', 'plan.md') } }] } },
130
+ { type: 'user', timestamp: new Date().toISOString(), message: { content: [{ type: 'tool_result', tool_use_id: 'w1', content: 'ok' }] } },
131
+ ].map((l) => JSON.stringify(l)).join('\n') + '\n');
132
+ r = forja(['hook:session-memory'], proj, JSON.stringify({ session_id: sid, transcript_path: transcript, cwd: proj, hook_event_name: 'PreCompact' }));
133
+ const sessions = path.join(proj, 'memory', '60-runs', 'sessions');
134
+ const saved = fs.existsSync(sessions) && fs.readdirSync(sessions).some((n) => n.endsWith('-jornada0.md'));
135
+ r = forja(['hook:session-start'], proj, JSON.stringify({ session_id: sid, source: 'compact' }));
136
+ ctx = '';
137
+ try {
138
+ ctx = JSON.parse(r.stdout).hookSpecificOutput.additionalContext;
139
+ }
140
+ catch { /* reportado abaixo */ }
141
+ const back = ctx.includes('specs/pagamentos/plan.md');
142
+ add('session-memory', saved && back, saved ? (back ? 'checkpoint gravado e devolvido após compactar' : 'checkpoint gravado, mas o SessionStart não o devolveu') : 'hook:session-memory não gravou o checkpoint');
117
143
  const init = JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'journey', version: '1' } } });
118
144
  r = forja(['mcp:start'], proj, `${init}\n`);
119
145
  let version = '';
@@ -45,7 +45,7 @@ export const COMMANDS = {
45
45
  args: ['project:new'],
46
46
  gates: ['workspace'],
47
47
  tier: 'core',
48
- usage: 'forja project:new <nome> [-- --ai claude,copilot] [--template <nome>]',
48
+ usage: 'forja project:new <nome> [-- --ai claude,copilot --skip-backend] [--template <nome>]',
49
49
  cliArgs: [{ name: 'nome', required: true, desc: 'slug do projeto (kebab-case)' }],
50
50
  examples: ['forja project:new meu-app -- --ai claude,copilot'],
51
51
  next: ['workspace:project:check'],
@@ -117,6 +117,18 @@ export const COMMANDS = {
117
117
  examples: ['forja spec:tasks pagamentos-pix'],
118
118
  next: ['hermes:handoff'],
119
119
  },
120
+ 'spec:trace': {
121
+ domain: 'sdd',
122
+ desc: 'Critérios de aceite × testes que os citam (SPEC-NNN AC-N): cobertos, sem teste e órfãos',
123
+ node: 'scripts/spec-trace.ts',
124
+ readonly: true,
125
+ json: true,
126
+ spec: 'SPEC-053',
127
+ usage: 'forja spec:trace [slug] [--strict] [--json]',
128
+ cliArgs: [{ name: 'slug', required: false, desc: 'feature ou SPEC-NNN; omitido = todas' }],
129
+ examples: ['forja spec:trace', 'forja spec:trace pagamentos', 'forja spec:trace --strict'],
130
+ next: ['spec:check'],
131
+ },
120
132
  'spec:check': {
121
133
  domain: 'sdd',
122
134
  desc: 'Valida completude da spec (gate de governança)',
@@ -179,8 +191,8 @@ export const COMMANDS = {
179
191
  spec: 'SPEC-021',
180
192
  tier: 'core',
181
193
  readonly: true,
182
- usage: 'forja orchestrate:status [--slug <slug>]',
183
- examples: ['forja orchestrate:status'],
194
+ usage: 'forja orchestrate:status <slug>',
195
+ examples: ['forja orchestrate:status pagamentos-pix'],
184
196
  next: ['orchestrate:advance'],
185
197
  },
186
198
  'orchestrate:advance': {
@@ -190,8 +202,8 @@ export const COMMANDS = {
190
202
  args: ['advance'],
191
203
  spec: 'SPEC-021',
192
204
  tier: 'core',
193
- usage: 'forja orchestrate:advance [--slug <slug>]',
194
- examples: ['forja orchestrate:advance'],
205
+ usage: 'forja orchestrate:advance <slug>',
206
+ examples: ['forja orchestrate:advance pagamentos-pix'],
195
207
  next: ['orchestrate:status'],
196
208
  },
197
209
  'gsd:plan': {
@@ -222,6 +234,8 @@ export const COMMANDS = {
222
234
  domain: 'gsd',
223
235
  desc: 'Roteia/inspeciona handoffs (agent-router)',
224
236
  node: 'scripts/agent-router.ts',
237
+ usage: 'forja agent:route <append|list [--open] [--mine|--project <nome>] [--to <papel>]|show|done|in_progress|cancel|archive|schema> [args]',
238
+ examples: ['forja agent:route list --open --mine'],
225
239
  },
226
240
  'sprint:start': {
227
241
  domain: 'gsd',
@@ -278,6 +292,8 @@ export const COMMANDS = {
278
292
  desc: 'Reindexa e sinaliza relações verified que a extração atual não reproduz mais (SPEC-030). --domain <d> restringe; --all roda por projeto do workspace',
279
293
  node: 'scripts/drift-check.ts',
280
294
  gates: ['workspace-warn'],
295
+ usage: 'forja drift:check [--domain <d>] [--all]',
296
+ examples: ['forja drift:check', 'forja drift:check --domain pagamentos'],
281
297
  },
282
298
  'adr:list': {
283
299
  domain: 'code',
@@ -377,6 +393,8 @@ export const COMMANDS = {
377
393
  node: 'scripts/agent.ts',
378
394
  args: ['register'],
379
395
  gates: ['workspace-warn'],
396
+ usage: 'forja agent:register <id> --role <role> [--provider <p>] [--model <m>] [--capabilities <c1,c2>] [--domains <d1,d2>] [--max-files <n>] [--max-cost-usd <n>]',
397
+ examples: ['forja agent:register sdd-architect --role architect --provider anthropic'],
380
398
  },
381
399
  'agent:list': {
382
400
  domain: 'code',
@@ -398,6 +416,8 @@ export const COMMANDS = {
398
416
  node: 'scripts/agent.ts',
399
417
  args: ['score'],
400
418
  gates: ['workspace-warn'],
419
+ usage: 'forja agent:score <id> [--domain <d>]',
420
+ examples: ['forja agent:score sdd-architect'],
401
421
  },
402
422
  'agent:history': {
403
423
  domain: 'code',
@@ -412,6 +432,8 @@ export const COMMANDS = {
412
432
  node: 'scripts/agent.ts',
413
433
  args: ['recommend'],
414
434
  gates: ['workspace-warn'],
435
+ usage: 'forja agent:recommend --role <role> [--domain <d>]',
436
+ examples: ['forja agent:recommend --role reviewer --domain pagamentos'],
415
437
  },
416
438
  'agent:monitor': {
417
439
  domain: 'code',
@@ -419,6 +441,8 @@ export const COMMANDS = {
419
441
  node: 'scripts/agent.ts',
420
442
  args: ['monitor'],
421
443
  gates: ['workspace-warn'],
444
+ usage: 'forja agent:monitor <id> [--window-hours <n>]',
445
+ examples: ['forja agent:monitor sdd-architect --window-hours 48'],
422
446
  },
423
447
  'incident:record': {
424
448
  domain: 'code',
@@ -426,6 +450,8 @@ export const COMMANDS = {
426
450
  node: 'scripts/incident.ts',
427
451
  args: ['record'],
428
452
  gates: ['workspace-warn'],
453
+ usage: 'forja incident:record --title <t> [--description <d>]',
454
+ examples: ['forja incident:record --title "build quebrou no CI"'],
429
455
  },
430
456
  'incident:list': {
431
457
  domain: 'code',
@@ -477,6 +503,8 @@ export const COMMANDS = {
477
503
  domain: 'code',
478
504
  desc: 'Pacote de contexto mínimo de um domínio: o mapa (context.md), + código com --code (ADR-0009)',
479
505
  node: 'scripts/code-context.ts',
506
+ usage: 'forja code:context <domínio> [termo] [--code] [--full] [--project <path>]',
507
+ examples: ['forja code:context pagamentos', 'forja code:context pagamentos --code'],
480
508
  },
481
509
  'code:index': {
482
510
  domain: 'code',
@@ -558,7 +586,7 @@ export const COMMANDS = {
558
586
  gates: ['workspace-warn'],
559
587
  spec: 'ADR-0003',
560
588
  tier: 'core',
561
- usage: 'forja context:smart [--mode global|domain|task] [--domain <d>]',
589
+ usage: 'forja context:smart [--mode global|domain|task] [--domain <d>] [--task <termo>] [--keyword <k>] [--project <nome>] [--full-context]',
562
590
  examples: ['forja context:smart --mode task --domain pagamentos'],
563
591
  next: ['context:budget'],
564
592
  },
@@ -645,6 +673,8 @@ export const COMMANDS = {
645
673
  node: 'scripts/llm-fit.ts',
646
674
  args: ['recommend'],
647
675
  gates: ['workspace'],
676
+ usage: 'forja llm:recommend [--role <papel>] [--task <tarefa>] [--json]',
677
+ examples: ['forja llm:recommend --role worker --task implementation'],
648
678
  },
649
679
  'llm:run': {
650
680
  domain: 'llm',
@@ -652,6 +682,8 @@ export const COMMANDS = {
652
682
  node: 'scripts/llm-fit.ts',
653
683
  args: ['run'],
654
684
  gates: ['workspace'],
685
+ usage: 'forja llm:run [--profile <perfil>] [--task <caminho>] [--prompt <texto>] [--engineer "<objetivo>"] [--context <caminho>...] [--output-schema <arquivo>] [--validation <arquivo>] [--resume <id>] [--json]',
686
+ examples: ['forja llm:run --profile codex --task specs/my-feature/spec.md'],
655
687
  },
656
688
  'llm:sessions': {
657
689
  domain: 'llm',
@@ -670,6 +702,18 @@ export const COMMANDS = {
670
702
  node: 'scripts/llm-fit.ts',
671
703
  args: ['eval'],
672
704
  gates: ['workspace'],
705
+ usage: 'forja llm:eval [--scope <escopo>] [--id <id>] [--json]',
706
+ examples: ['forja llm:eval --scope model --id codex:default'],
707
+ },
708
+ 'eval:agents': {
709
+ domain: 'llm',
710
+ desc: 'Avalia agentes reais (Claude, Codex) numa suíte de tarefas do Forja, em projeto descartável — custa',
711
+ node: 'scripts/eval-agents.ts',
712
+ spec: 'SPEC-054',
713
+ json: true,
714
+ usage: 'forja eval:agents --agent claude|codex [--case a,b] [--model m] [--budget-usd n] [--timeout s] [--keep] [--list] [--json]',
715
+ examples: ['forja eval:agents --list', 'forja eval:agents --agent claude --case adr', 'forja eval:agents --agent codex'],
716
+ next: ['llm:recommend'],
673
717
  },
674
718
  'cost:economy': {
675
719
  domain: 'llm',
@@ -737,6 +781,12 @@ export const COMMANDS = {
737
781
  spec: 'ADR-0086',
738
782
  readonly: true,
739
783
  },
784
+ 'hook:session-memory': {
785
+ domain: 'governanca',
786
+ desc: 'Hook Stop/PreCompact: grava o checkpoint da sessão em memory/60-runs/sessions/',
787
+ node: 'scripts/hook-session-memory.ts',
788
+ spec: 'SPEC-052',
789
+ },
740
790
  'demo:autonomy': {
741
791
  domain: 'governanca',
742
792
  desc: 'Executa a prova offline de autonomia supervisionada com Git worktree real',
@@ -746,11 +796,14 @@ export const COMMANDS = {
746
796
  domain: 'governanca',
747
797
  desc: 'Cria um workspace isolado e rotulado para demonstração do produto',
748
798
  node: 'scripts/demo-workspace.ts',
799
+ usage: 'forja demo:workspace [--path <diretório>] [--json]',
749
800
  },
750
801
  'release:check': {
751
802
  domain: 'governanca',
752
803
  desc: 'Gate do tarball: instala limpo e prova que o pacote funciona (ADR-0024). --publish para o modo estrito',
753
804
  node: 'scripts/release-check.ts',
805
+ usage: 'forja release:check [--publish]',
806
+ examples: ['forja release:check', 'forja release:check --publish'],
754
807
  },
755
808
  'project:smoke': {
756
809
  domain: 'governanca',
@@ -765,6 +818,8 @@ export const COMMANDS = {
765
818
  domain: 'governanca',
766
819
  desc: 'Roda a bateria inteira de gates e dá um veredito (SPEC-020). --full inclui tarball e build',
767
820
  node: 'scripts/gates.ts',
821
+ usage: 'forja check:all [--full] [--with-architecture] [--with-drift]',
822
+ examples: ['forja check:all', 'forja check:all --full'],
768
823
  },
769
824
  'project:dashboard': {
770
825
  domain: 'governanca',
@@ -780,6 +835,26 @@ export const COMMANDS = {
780
835
  domain: 'governanca',
781
836
  desc: 'Consulta a auditoria: --failed, --cmd <x>, --since 7d',
782
837
  node: 'scripts/audit-query.ts',
838
+ usage: 'forja audit:query [--failed] [--cmd <comando>] [--gate <gate>] [--since <janela>]',
839
+ examples: ['forja audit:query --failed', 'forja audit:query --since 7d'],
840
+ },
841
+ 'docs:gen': {
842
+ domain: 'governanca',
843
+ desc: 'Regenera docs/commands.md a partir do registry — a referência completa de comandos (SPEC-055)',
844
+ node: 'scripts/gen-commands-doc.ts',
845
+ spec: 'SPEC-055',
846
+ usage: 'forja docs:gen',
847
+ examples: ['forja docs:gen'],
848
+ next: ['tools:doctor'],
849
+ },
850
+ 'quality:coverage': {
851
+ domain: 'governanca',
852
+ desc: 'Roda a suíte com a cobertura nativa do Node e cobra o piso versionado (SPEC-056) — exit 2 abaixo do piso',
853
+ node: 'scripts/coverage-gate.ts',
854
+ spec: 'SPEC-056',
855
+ usage: 'forja quality:coverage [--json]',
856
+ examples: ['forja quality:coverage', 'forja quality:coverage --json'],
857
+ next: ['tools:doctor', 'check:all'],
783
858
  },
784
859
  'governance:dashboard': {
785
860
  domain: 'governanca',
@@ -0,0 +1,35 @@
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 type { CommandSpec } from './core/registry.ts';
16
+ /** Flags tratadas pelo dispatcher (bin/forja.ts), não pelo comando — valem em qualquer linha. */
17
+ export declare const GLOBAL_FLAGS: Set<string>;
18
+ /** Flags que um comando declara em `usage`/`examples`, mais as globais do dispatcher. */
19
+ export declare function declaredFlags(spec: CommandSpec): Set<string>;
20
+ interface FsLike {
21
+ existsSync(p: string): boolean;
22
+ readdirSync(p: string, opts: {
23
+ withFileTypes: true;
24
+ }): {
25
+ isDirectory(): boolean;
26
+ }[];
27
+ }
28
+ /**
29
+ * Skills reais distribuídas aos projetos gerados — só diretórios (o README.md da pasta não conta).
30
+ * Recebe o diretório pronto para não impor separador de caminho nenhum (portável entre SOs).
31
+ */
32
+ export declare function skillsCount(fsLike: FsLike, skillsDir: string): number;
33
+ /** Referência completa de comandos, gerada do registry — conteúdo canônico de docs/commands.md. */
34
+ export declare function renderCommandsDoc(registry: Record<string, CommandSpec>, skills: number): string;
35
+ export {};