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.
- package/CHANGELOG.md +114 -2
- package/README.md +40 -5
- package/README.pt-BR.md +42 -4
- package/boilerplates/02-saas-starter/README.md +58 -293
- package/boilerplates/02-saas-starter/backend/.env.example +13 -0
- package/boilerplates/02-saas-starter/backend/.oxlintrc.json +8 -0
- package/boilerplates/02-saas-starter/backend/nest-cli.json +6 -0
- package/boilerplates/02-saas-starter/backend/package.json +32 -73
- package/boilerplates/02-saas-starter/backend/src/app.module.ts +16 -16
- package/boilerplates/02-saas-starter/backend/src/billing/adapters/http/billing.controller.ts +55 -0
- package/boilerplates/02-saas-starter/backend/src/billing/adapters/persistence/orm-entities.ts +28 -0
- package/boilerplates/02-saas-starter/backend/src/billing/adapters/persistence/typeorm-billing.repository.ts +46 -0
- package/boilerplates/02-saas-starter/backend/src/billing/application/billing.service.spec.ts +58 -0
- package/boilerplates/02-saas-starter/backend/src/billing/application/billing.service.ts +68 -0
- package/boilerplates/02-saas-starter/backend/src/billing/billing.module.ts +11 -0
- package/boilerplates/02-saas-starter/backend/src/billing/domain/plan.spec.ts +23 -0
- package/boilerplates/02-saas-starter/backend/src/billing/domain/plan.ts +36 -0
- package/boilerplates/02-saas-starter/backend/src/billing/domain/ports.ts +27 -0
- package/boilerplates/02-saas-starter/backend/src/billing/domain/subscription.spec.ts +28 -0
- package/boilerplates/02-saas-starter/backend/src/billing/domain/subscription.ts +47 -0
- package/boilerplates/02-saas-starter/backend/src/identity/adapters/http/auth.dto.ts +22 -0
- package/boilerplates/02-saas-starter/backend/src/identity/adapters/http/identity.controller.ts +59 -0
- package/boilerplates/02-saas-starter/backend/src/identity/adapters/persistence/orm-entities.ts +25 -0
- package/boilerplates/02-saas-starter/backend/src/identity/adapters/persistence/typeorm-identity.repository.ts +47 -0
- package/boilerplates/02-saas-starter/backend/src/identity/application/auth.service.spec.ts +72 -0
- package/boilerplates/02-saas-starter/backend/src/identity/application/auth.service.ts +63 -0
- package/boilerplates/02-saas-starter/backend/src/identity/domain/model.spec.ts +19 -0
- package/boilerplates/02-saas-starter/backend/src/identity/domain/model.ts +42 -0
- package/boilerplates/02-saas-starter/backend/src/identity/domain/password.spec.ts +17 -0
- package/boilerplates/02-saas-starter/backend/src/identity/domain/password.ts +26 -0
- package/boilerplates/02-saas-starter/backend/src/identity/identity.module.ts +12 -0
- package/boilerplates/02-saas-starter/backend/src/main.ts +19 -19
- package/boilerplates/02-saas-starter/backend/src/platform/auth/jwt-auth.guard.ts +17 -0
- package/boilerplates/02-saas-starter/backend/src/platform/auth/principal.ts +22 -0
- package/boilerplates/02-saas-starter/backend/src/platform/auth/roles.guard.spec.ts +23 -0
- package/boilerplates/02-saas-starter/backend/src/platform/auth/roles.guard.ts +20 -0
- package/boilerplates/02-saas-starter/backend/src/platform/auth/token.service.ts +54 -0
- package/boilerplates/02-saas-starter/backend/src/platform/config.spec.ts +18 -0
- package/boilerplates/02-saas-starter/backend/src/platform/config.ts +33 -0
- package/boilerplates/02-saas-starter/backend/src/platform/platform.module.ts +14 -0
- package/boilerplates/02-saas-starter/backend/tsconfig.build.json +6 -0
- package/boilerplates/02-saas-starter/backend/tsconfig.json +16 -21
- package/boilerplates/02-saas-starter/backend/vitest.config.ts +7 -0
- package/boilerplates/02-saas-starter/boilerplate.manifest.json +19 -14
- package/boilerplates/02-saas-starter/docker-compose.yml +10 -24
- package/boilerplates/02-saas-starter/memory/30-domains/billing/context.md +15 -132
- package/boilerplates/02-saas-starter/memory/30-domains/identity/context.md +20 -0
- package/boilerplates/README.md +9 -10
- package/dist/apps/cli/src/index.d.ts +0 -1
- package/dist/apps/cli/src/index.js +43 -32
- package/dist/apps/dashboard/app/api/forja/[...path]/route.js +34 -1
- package/dist/apps/dashboard/app/api/forja/capabilities.d.ts +26 -0
- package/dist/apps/dashboard/app/api/forja/capabilities.js +39 -0
- package/dist/apps/dashboard/app/dashboard-client.jsx +607 -42
- package/dist/apps/server/src/forja-nest.module.d.ts +6 -0
- package/dist/apps/server/src/forja-nest.module.js +55 -0
- package/dist/apps/server/src/main.d.ts +21 -4
- package/dist/apps/server/src/main.js +79 -57
- package/dist/apps/server/src/task-planning-service.d.ts +29 -0
- package/dist/apps/server/src/task-planning-service.js +195 -0
- package/dist/apps/server/src/task-runtime-coordinator.d.ts +57 -0
- package/dist/apps/server/src/task-runtime-coordinator.js +229 -0
- package/dist/bin/forja.js +3 -2
- package/dist/bin/init-project.js +1 -0
- package/dist/lib/agent-evals.d.ts +138 -0
- package/dist/lib/agent-evals.js +349 -0
- package/dist/lib/cli-output.js +14 -2
- package/dist/lib/code-context.d.ts +33 -5
- package/dist/lib/code-context.js +70 -5
- package/dist/lib/context-builder.d.ts +49 -4
- package/dist/lib/context-builder.js +114 -47
- package/dist/lib/core/coverage-gate.d.ts +59 -0
- package/dist/lib/core/coverage-gate.js +58 -0
- package/dist/lib/core/doc-graph.d.ts +38 -0
- package/dist/lib/core/doc-graph.js +83 -0
- package/dist/lib/core/health.js +286 -5
- package/dist/lib/core/journey.js +36 -0
- package/dist/lib/core/registry.js +81 -6
- package/dist/lib/docs-reference.d.ts +35 -0
- package/dist/lib/docs-reference.js +57 -0
- package/dist/lib/generators/memory-generator.d.ts +0 -11
- package/dist/lib/generators/memory-generator.js +5 -161
- package/dist/lib/generators/readme-generator.js +1 -1
- package/dist/lib/llm/json-output.d.ts +14 -0
- package/dist/lib/llm/json-output.js +77 -0
- package/dist/lib/project-wiring.d.ts +8 -0
- package/dist/lib/project-wiring.js +79 -3
- package/dist/lib/session-memory.d.ts +38 -0
- package/dist/lib/session-memory.js +206 -0
- package/dist/lib/spec-trace.d.ts +46 -0
- package/dist/lib/spec-trace.js +184 -0
- package/dist/lib/validators/structure-validator.js +0 -1
- package/dist/packages/adapter-nest/src/index.d.ts +2 -1
- package/dist/packages/adapter-nest/src/index.js +59 -1
- package/dist/packages/adapter-sqlite/src/index.d.ts +15 -1
- package/dist/packages/adapter-sqlite/src/index.js +61 -1
- package/dist/packages/context/src/index.d.ts +2 -0
- package/dist/packages/context/src/index.js +36 -15
- package/dist/packages/contracts/src/index.d.ts +64 -0
- package/dist/packages/core/src/index.d.ts +9 -1
- package/dist/packages/core/src/index.js +28 -3
- package/dist/packages/graph/src/index.js +14 -5
- package/dist/packages/llm/src/index.js +12 -2
- package/dist/packages/mcp/src/index.d.ts +8 -0
- package/dist/packages/mcp/src/index.js +12 -1
- package/dist/packages/observability/src/index.d.ts +11 -0
- package/dist/packages/observability/src/index.js +3 -0
- package/dist/packages/orchestration/src/index.d.ts +15 -1
- package/dist/packages/orchestration/src/index.js +127 -21
- package/dist/packages/planner/src/index.d.ts +7 -1
- package/dist/packages/planner/src/index.js +67 -10
- package/dist/packages/planner/src/proposal-store.d.ts +30 -0
- package/dist/packages/planner/src/proposal-store.js +109 -0
- package/dist/packages/policy/src/index.d.ts +9 -16
- package/dist/packages/policy/src/index.js +114 -31
- package/dist/packages/runtime/src/index.d.ts +16 -2
- package/dist/packages/runtime/src/index.js +176 -61
- package/dist/scripts/build-smart-context.d.ts +2 -0
- package/dist/scripts/build-smart-context.js +12 -3
- package/dist/scripts/code-context.d.ts +3 -1
- package/dist/scripts/code-context.js +13 -3
- package/dist/scripts/coverage-gate.d.ts +2 -0
- package/dist/scripts/coverage-gate.js +101 -0
- package/dist/scripts/eval-agents.d.ts +11 -0
- package/dist/scripts/eval-agents.js +96 -0
- package/dist/scripts/gen-commands-doc.d.ts +2 -0
- package/dist/scripts/gen-commands-doc.js +18 -0
- package/dist/scripts/hook-session-memory.d.ts +9 -0
- package/dist/scripts/hook-session-memory.js +20 -0
- package/dist/scripts/hook-session-start.js +34 -0
- package/dist/scripts/llm-fit.js +23 -1
- package/dist/scripts/spec-trace.d.ts +10 -0
- package/dist/scripts/spec-trace.js +73 -0
- package/dist/scripts/sync-universal-memory.js +69 -4
- package/dist/scripts/token-benchmark.d.ts +33 -1
- package/dist/scripts/token-benchmark.js +179 -5
- package/dist/scripts/token-economy.js +3 -1
- package/dist/scripts/tools-doctor.d.ts +16 -1
- package/dist/scripts/tools-doctor.js +58 -17
- package/docs/commands.md +155 -0
- package/docs/fluxo.md +11 -7
- package/docs/init-project.md +3 -1
- package/docs/llm-fit-loop.md +36 -0
- package/docs/manual-operacional-cli-sdd-gsd.md +3 -2
- package/docs/produto/factsheet-marketing.md +7 -5
- package/docs/produto/roteiro-demo.md +14 -5
- package/docs/quick-reference.md +3 -3
- package/docs/token-optimization.md +10 -6
- package/memory/90-decisions/0088-templates-validados.md +3 -0
- package/memory/90-decisions/0089-skills-do-projeto.md +51 -0
- package/memory/90-decisions/0090-adapters-de-agente-somente-leitura.md +47 -0
- package/memory/90-decisions/0091-memoria-de-sessao-por-hooks.md +40 -0
- package/memory/90-decisions/0092-criterios-de-aceite-ligados-a-testes.md +37 -0
- package/memory/90-decisions/0093-avaliacoes-com-agentes-reais.md +40 -0
- package/package.json +4 -2
- package/specs/avaliacoes-de-agentes/spec.md +52 -0
- package/specs/criterios-ligados-a-testes/spec.md +42 -0
- package/specs/memoria-de-sessao/spec.md +48 -0
- package/specs/skills-do-projeto/plan.md +40 -0
- package/specs/skills-do-projeto/spec.md +63 -0
- package/specs/skills-do-projeto/tasks.md +27 -0
- package/specs/v6-agent-runtime-portable/spec.md +83 -0
- package/specs/v6-core-consolidation/spec.md +70 -0
- package/specs/v6-docs-drift/spec.md +85 -0
- package/specs/v6-quality-gates/spec.md +99 -0
- package/specs/v6-token-economy/spec.md +84 -0
- package/templates/evals/agents/adr.json +25 -0
- package/templates/evals/agents/memoria.json +32 -0
- package/templates/evals/agents/proxima-acao.json +29 -0
- package/templates/evals/agents/spec-nova.json +26 -0
- package/templates/evals/agents/teste-do-criterio.json +29 -0
- package/templates/project/AGENTS.md +16 -0
- package/templates/project/CLAUDE.md +3 -2
- package/templates/project/agents/context-engineer.md +3 -0
- package/templates/project/agents/governance.md +3 -0
- package/templates/project/agents/marketing.md +3 -0
- package/templates/project/agents/orchestrator.md +3 -0
- package/templates/project/agents/product.md +3 -0
- package/templates/project/agents/sdd-architect.md +3 -0
- package/templates/project/skills/README.md +14 -0
- package/templates/project/skills/accessibility-review/SKILL.md +89 -0
- package/templates/project/skills/api-design/SKILL.md +77 -0
- package/templates/project/skills/architecture-decision-record/SKILL.md +92 -0
- package/templates/project/skills/backlog-slicing/SKILL.md +82 -0
- package/templates/project/skills/bounded-context-mapping/SKILL.md +88 -0
- package/templates/project/skills/ci-pipeline-review/SKILL.md +83 -0
- package/templates/project/skills/commit-message/SKILL.md +143 -0
- package/templates/project/skills/data-migrations/SKILL.md +88 -0
- package/templates/project/skills/dependency-upgrade/SKILL.md +75 -0
- package/templates/project/skills/docker-compose-review/SKILL.md +85 -0
- package/templates/project/skills/domain-modeling/SKILL.md +120 -0
- package/templates/project/skills/event-storming/SKILL.md +95 -0
- package/templates/project/skills/executive-writing/SKILL.md +99 -0
- package/templates/project/skills/frontend-architecture/SKILL.md +97 -0
- package/templates/project/skills/incident-postmortem/SKILL.md +93 -0
- package/templates/project/skills/lgpd-compliance/SKILL.md +108 -0
- package/templates/project/skills/llm-provider-routing/SKILL.md +18 -0
- package/templates/project/skills/observability/SKILL.md +93 -0
- package/templates/project/skills/product-evaluation/SKILL.md +130 -0
- package/templates/project/skills/prompt-spec/SKILL.md +83 -0
- package/templates/project/skills/pull-request/SKILL.md +101 -0
- package/templates/project/skills/query-performance/SKILL.md +83 -0
- package/templates/project/skills/release-checklist/SKILL.md +106 -0
- package/templates/project/skills/release-notes/SKILL.md +87 -0
- package/templates/project/skills/requirements-elicitation/SKILL.md +127 -0
- package/templates/project/skills/requirements-gathering/SKILL.md +134 -0
- package/templates/project/skills/technical-spike/SKILL.md +101 -0
- package/templates/project/skills/testing/SKILL.md +109 -0
- package/templates/project/skills/threat-modeling/SKILL.md +87 -0
- package/templates/project/skills/ts-async-patterns/SKILL.md +101 -0
- package/templates/project/skills/ts-code-review/SKILL.md +121 -0
- package/templates/project/skills/ts-module-layout/SKILL.md +104 -0
- package/templates/project/skills/ts-testing/SKILL.md +89 -0
- package/templates/project/skills/web-performance/SKILL.md +72 -0
- package/boilerplates/02-saas-starter/.env.example +0 -25
- package/boilerplates/02-saas-starter/CHECKLIST-CRIACAO.md +0 -190
- package/boilerplates/02-saas-starter/INFO.md +0 -252
- package/boilerplates/02-saas-starter/QUICK_START.md +0 -194
- package/boilerplates/02-saas-starter/START-HERE.md +0 -259
- package/boilerplates/02-saas-starter/backend/src/common/decorators/roles.decorator.ts +0 -3
- package/boilerplates/02-saas-starter/backend/src/common/decorators/tenant.decorator.ts +0 -6
- package/boilerplates/02-saas-starter/backend/src/common/middleware/roles.guard.ts +0 -23
- package/boilerplates/02-saas-starter/backend/src/config/database.ts +0 -26
- package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.controller.ts +0 -46
- package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.module.ts +0 -25
- package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.service.ts +0 -145
- package/boilerplates/02-saas-starter/backend/src/modules/auth/dto/auth.dto.ts +0 -30
- package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/jwt.strategy.ts +0 -24
- package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/local.strategy.ts +0 -19
- package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.controller.ts +0 -42
- package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.module.ts +0 -13
- package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.service.ts +0 -67
- package/boilerplates/02-saas-starter/backend/src/modules/billing/entities/invoice.entity.ts +0 -52
- package/boilerplates/02-saas-starter/backend/src/modules/organizations/entities/organization.entity.ts +0 -36
- package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.controller.ts +0 -16
- package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.module.ts +0 -13
- package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.service.ts +0 -34
- package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/entities/subscription.entity.ts +0 -40
- package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.controller.ts +0 -36
- package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.module.ts +0 -13
- package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.service.ts +0 -91
- package/boilerplates/02-saas-starter/backend/src/modules/users/entities/user.entity.ts +0 -42
- package/boilerplates/02-saas-starter/backend/src/modules/users/users.controller.ts +0 -14
- package/boilerplates/02-saas-starter/backend/src/modules/users/users.module.ts +0 -13
- package/boilerplates/02-saas-starter/backend/src/modules/users/users.service.ts +0 -48
- package/boilerplates/02-saas-starter/memory/00-global/agent-contract.md +0 -227
- package/boilerplates/02-saas-starter/memory/00-global/context-policy.md +0 -141
- package/boilerplates/02-saas-starter/memory/00-global/index.md +0 -133
- package/boilerplates/02-saas-starter/memory/00-global/mission.md +0 -45
- package/boilerplates/02-saas-starter/memory/00-global/patterns.md +0 -223
- package/boilerplates/02-saas-starter/memory/10-product/business-rules.md +0 -240
- package/boilerplates/02-saas-starter/memory/10-product/nfrs.md +0 -239
- package/boilerplates/02-saas-starter/memory/10-product/personas.md +0 -195
- package/boilerplates/02-saas-starter/memory/10-product/vision.md +0 -63
- package/boilerplates/02-saas-starter/memory/20-architecture/overview.md +0 -232
- package/boilerplates/02-saas-starter/memory/30-domains/auth/api.md +0 -186
- package/boilerplates/02-saas-starter/memory/30-domains/auth/context.md +0 -85
- package/boilerplates/02-saas-starter/memory/30-domains/billing/api.md +0 -262
- package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/api.md +0 -176
- package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/context.md +0 -100
- package/boilerplates/02-saas-starter/memory/40-delivery/backlog.md +0 -81
- package/boilerplates/02-saas-starter/memory/40-delivery/roadmap.md +0 -97
- package/boilerplates/02-saas-starter/memory/40-delivery/sprint-atual.md +0 -57
- package/boilerplates/02-saas-starter/memory/50-orchestration/topology.md +0 -90
- package/boilerplates/02-saas-starter/memory/60-runs/index.md +0 -54
- package/boilerplates/02-saas-starter/memory/70-summaries/global.md +0 -50
- package/boilerplates/02-saas-starter/memory/80-data/schema.md +0 -185
- package/boilerplates/02-saas-starter/memory/90-decisions/adr-template.md +0 -75
package/dist/lib/core/health.js
CHANGED
|
@@ -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
|
|
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 >
|
|
249
|
-
const horas = Math.round((newest -
|
|
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
|
];
|
package/dist/lib/core/journey.js
CHANGED
|
@@ -70,6 +70,16 @@ export function runJourney(opts) {
|
|
|
70
70
|
catch { /* reportado abaixo */ }
|
|
71
71
|
const wiringFails = (wiring?.checks ?? []).filter((c) => c.status === 'fail').map((c) => `${c.id}: ${c.detail}`);
|
|
72
72
|
add('project:wire', r.code === 0 && wiring?.ok === true, wiring ? (wiringFails.join('; ') || `${wiring.checks.length} checks ok`) : firstLine(r.out));
|
|
73
|
+
// SPEC-051: as skills chegam onde Claude e Codex as procuram.
|
|
74
|
+
const skillCount = (rel) => { try {
|
|
75
|
+
return fs.readdirSync(path.join(proj, rel)).filter((n) => fs.existsSync(path.join(proj, rel, n, 'SKILL.md'))).length;
|
|
76
|
+
}
|
|
77
|
+
catch {
|
|
78
|
+
return 0;
|
|
79
|
+
} };
|
|
80
|
+
const claudeSkills = skillCount(path.join('.claude', 'skills'));
|
|
81
|
+
const agentSkills = skillCount(path.join('.agents', 'skills'));
|
|
82
|
+
add('skills', claudeSkills >= 34 && agentSkills >= 34, `${claudeSkills} em .claude/skills, ${agentSkills} em .agents/skills`);
|
|
73
83
|
r = forja(['status'], proj);
|
|
74
84
|
add('status', r.code === 0 && /memória indexada: sim/.test(r.out), /memória indexada: sim/.test(r.out) ? 'memória indexada de nascença' : firstLine(r.out));
|
|
75
85
|
r = forja(['spec:new', 'pagamentos'], proj);
|
|
@@ -86,6 +96,14 @@ export function runJourney(opts) {
|
|
|
86
96
|
add('context:smart', r.code === 0 && packOk, packOk ? 'modo task inclui a spec' : firstLine(r.out));
|
|
87
97
|
r = forja(['spec:check'], proj);
|
|
88
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));
|
|
89
107
|
r = forja(['project:check'], proj);
|
|
90
108
|
add('project:check', r.code === 0, firstLine(r.out));
|
|
91
109
|
r = forja(['tools:doctor'], proj);
|
|
@@ -104,6 +122,24 @@ export function runJourney(opts) {
|
|
|
104
122
|
}
|
|
105
123
|
catch { /* reportado abaixo */ }
|
|
106
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');
|
|
107
143
|
const init = JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'journey', version: '1' } } });
|
|
108
144
|
r = forja(['mcp:start'], proj, `${init}\n`);
|
|
109
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
|
|
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
|
|
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 {};
|