forjajs 2.0.4 → 3.0.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/.claude/agents/context-engineer.md +25 -25
- package/.claude/agents/governance.md +55 -55
- package/.claude/agents/marketing.md +24 -24
- package/.claude/agents/orchestrator.md +31 -31
- package/.claude/agents/product.md +26 -26
- package/.claude/agents/release-auditor.md +50 -50
- package/.claude/agents/sdd-architect.md +34 -34
- package/.claude/settings.json +76 -76
- package/.claude/skills/new-adr/SKILL.md +61 -61
- package/.claude/skills/new-command/SKILL.md +67 -67
- package/.gemini-instructions.md +87 -87
- package/.github/copilot-instructions.md +87 -87
- package/.memoryrc.json +104 -104
- package/.openai-instructions.md +87 -87
- package/AGENTS.md +133 -133
- package/CHANGELOG.md +619 -555
- package/CONTRIBUTING.md +32 -32
- package/DOC-MAP.md +64 -60
- package/LICENSE +21 -21
- package/README.md +404 -343
- package/README.pt-BR.md +374 -345
- package/boilerplates/01-api-rest/README.md +336 -336
- package/boilerplates/01-api-rest/boilerplate.manifest.json +41 -41
- package/boilerplates/02-saas-starter/.env.example +25 -25
- package/boilerplates/02-saas-starter/CHECKLIST-CRIACAO.md +190 -190
- package/boilerplates/02-saas-starter/INFO.md +252 -252
- package/boilerplates/02-saas-starter/QUICK_START.md +194 -194
- package/boilerplates/02-saas-starter/README.md +305 -305
- package/boilerplates/02-saas-starter/START-HERE.md +259 -259
- package/boilerplates/02-saas-starter/backend/package.json +87 -87
- package/boilerplates/02-saas-starter/backend/src/app.module.ts +27 -27
- package/boilerplates/02-saas-starter/backend/src/common/decorators/roles.decorator.ts +3 -3
- package/boilerplates/02-saas-starter/backend/src/common/decorators/tenant.decorator.ts +6 -6
- package/boilerplates/02-saas-starter/backend/src/common/middleware/roles.guard.ts +23 -23
- package/boilerplates/02-saas-starter/backend/src/config/database.ts +26 -26
- package/boilerplates/02-saas-starter/backend/src/main.ts +26 -26
- package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.controller.ts +46 -46
- package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.module.ts +25 -25
- package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.service.ts +145 -145
- package/boilerplates/02-saas-starter/backend/src/modules/auth/dto/auth.dto.ts +30 -30
- package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/jwt.strategy.ts +24 -24
- package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/local.strategy.ts +19 -19
- package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.controller.ts +42 -42
- package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.module.ts +13 -13
- package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.service.ts +67 -67
- package/boilerplates/02-saas-starter/backend/src/modules/billing/entities/invoice.entity.ts +52 -52
- package/boilerplates/02-saas-starter/backend/src/modules/organizations/entities/organization.entity.ts +36 -36
- package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.controller.ts +16 -16
- package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.module.ts +13 -13
- package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.service.ts +34 -34
- package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/entities/subscription.entity.ts +40 -40
- package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.controller.ts +36 -36
- package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.module.ts +13 -13
- package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.service.ts +91 -91
- package/boilerplates/02-saas-starter/backend/src/modules/users/entities/user.entity.ts +42 -42
- package/boilerplates/02-saas-starter/backend/src/modules/users/users.controller.ts +14 -14
- package/boilerplates/02-saas-starter/backend/src/modules/users/users.module.ts +13 -13
- package/boilerplates/02-saas-starter/backend/src/modules/users/users.service.ts +48 -48
- package/boilerplates/02-saas-starter/backend/tsconfig.json +28 -28
- package/boilerplates/02-saas-starter/boilerplate.manifest.json +42 -42
- package/boilerplates/02-saas-starter/docker-compose.yml +34 -34
- package/boilerplates/02-saas-starter/memory/00-global/agent-contract.md +227 -227
- package/boilerplates/02-saas-starter/memory/00-global/context-policy.md +141 -141
- package/boilerplates/02-saas-starter/memory/00-global/index.md +133 -133
- package/boilerplates/02-saas-starter/memory/00-global/mission.md +45 -45
- package/boilerplates/02-saas-starter/memory/00-global/patterns.md +223 -223
- package/boilerplates/02-saas-starter/memory/10-product/business-rules.md +240 -240
- package/boilerplates/02-saas-starter/memory/10-product/nfrs.md +239 -239
- package/boilerplates/02-saas-starter/memory/10-product/personas.md +195 -195
- package/boilerplates/02-saas-starter/memory/10-product/vision.md +63 -63
- package/boilerplates/02-saas-starter/memory/20-architecture/overview.md +232 -232
- package/boilerplates/02-saas-starter/memory/30-domains/auth/api.md +186 -186
- package/boilerplates/02-saas-starter/memory/30-domains/auth/context.md +85 -85
- package/boilerplates/02-saas-starter/memory/30-domains/billing/api.md +262 -262
- package/boilerplates/02-saas-starter/memory/30-domains/billing/context.md +137 -137
- package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/api.md +176 -176
- package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/context.md +100 -100
- package/boilerplates/02-saas-starter/memory/40-delivery/backlog.md +81 -81
- package/boilerplates/02-saas-starter/memory/40-delivery/roadmap.md +97 -97
- package/boilerplates/02-saas-starter/memory/40-delivery/sprint-atual.md +57 -57
- package/boilerplates/02-saas-starter/memory/50-orchestration/topology.md +90 -90
- package/boilerplates/02-saas-starter/memory/60-runs/index.md +54 -54
- package/boilerplates/02-saas-starter/memory/70-summaries/global.md +50 -50
- package/boilerplates/02-saas-starter/memory/80-data/schema.md +185 -185
- package/boilerplates/02-saas-starter/memory/90-decisions/adr-template.md +75 -75
- package/boilerplates/03-ecommerce-starter/FLOW_EXEMPLOS.md +599 -599
- package/boilerplates/03-ecommerce-starter/GUIA_RAPIDO.md +322 -322
- package/boilerplates/03-ecommerce-starter/MANIFEST.md +463 -463
- package/boilerplates/03-ecommerce-starter/README.md +465 -465
- package/boilerplates/03-ecommerce-starter/backend/.env.example +121 -121
- package/boilerplates/03-ecommerce-starter/backend/Dockerfile +15 -15
- package/boilerplates/03-ecommerce-starter/backend/docker-compose.yml +56 -56
- package/boilerplates/03-ecommerce-starter/backend/jest.config.js +16 -16
- package/boilerplates/03-ecommerce-starter/backend/package.json +71 -71
- package/boilerplates/03-ecommerce-starter/backend/src/app.controller.ts +12 -12
- package/boilerplates/03-ecommerce-starter/backend/src/app.module.ts +48 -48
- package/boilerplates/03-ecommerce-starter/backend/src/app.service.ts +12 -12
- package/boilerplates/03-ecommerce-starter/backend/src/main.ts +51 -51
- package/boilerplates/03-ecommerce-starter/backend/src/modules/auth/auth.module.ts +8 -8
- package/boilerplates/03-ecommerce-starter/backend/src/modules/cart/cart.module.ts +8 -8
- package/boilerplates/03-ecommerce-starter/backend/src/modules/coupons/coupons.module.ts +8 -8
- package/boilerplates/03-ecommerce-starter/backend/src/modules/inventory/inventory.module.ts +8 -8
- package/boilerplates/03-ecommerce-starter/backend/src/modules/orders/orders.module.ts +10 -10
- package/boilerplates/03-ecommerce-starter/backend/src/modules/payments/payments.module.ts +8 -8
- package/boilerplates/03-ecommerce-starter/backend/src/modules/products/dto/create-product.dto.ts +34 -34
- package/boilerplates/03-ecommerce-starter/backend/src/modules/products/entities/category.entity.ts +47 -47
- package/boilerplates/03-ecommerce-starter/backend/src/modules/products/entities/product.entity.ts +66 -66
- package/boilerplates/03-ecommerce-starter/backend/src/modules/products/products.controller.ts +78 -78
- package/boilerplates/03-ecommerce-starter/backend/src/modules/products/products.module.ts +14 -14
- package/boilerplates/03-ecommerce-starter/backend/src/modules/products/products.service.ts +112 -112
- package/boilerplates/03-ecommerce-starter/backend/src/modules/reviews/entities/review.entity.ts +32 -32
- package/boilerplates/03-ecommerce-starter/backend/src/modules/reviews/reviews.module.ts +11 -11
- package/boilerplates/03-ecommerce-starter/backend/test/health.e2e-spec.ts +31 -31
- package/boilerplates/03-ecommerce-starter/backend/test/jest-e2e.json +12 -12
- package/boilerplates/03-ecommerce-starter/backend/tsconfig.json +23 -23
- package/boilerplates/03-ecommerce-starter/boilerplate.manifest.json +42 -42
- package/boilerplates/03-ecommerce-starter/boilerplate.md +128 -128
- package/boilerplates/03-ecommerce-starter/memory/00-global/agent-contract.md +53 -53
- package/boilerplates/03-ecommerce-starter/memory/00-global/context-index.md +55 -55
- package/boilerplates/03-ecommerce-starter/memory/00-global/context-policy.md +31 -31
- package/boilerplates/03-ecommerce-starter/memory/00-global/mission.md +25 -25
- package/boilerplates/03-ecommerce-starter/memory/00-global/standards.md +45 -45
- package/boilerplates/03-ecommerce-starter/memory/10-product/business-rules.md +62 -62
- package/boilerplates/03-ecommerce-starter/memory/10-product/nfrs.md +62 -62
- package/boilerplates/03-ecommerce-starter/memory/10-product/vision.md +124 -124
- package/boilerplates/03-ecommerce-starter/memory/20-architecture/backend.md +253 -253
- package/boilerplates/03-ecommerce-starter/memory/20-architecture/observability.md +319 -319
- package/boilerplates/03-ecommerce-starter/memory/20-architecture/overview.md +133 -133
- package/boilerplates/03-ecommerce-starter/memory/20-architecture/security.md +227 -227
- package/boilerplates/03-ecommerce-starter/memory/30-domains/catalog/context.md +210 -210
- package/boilerplates/03-ecommerce-starter/memory/30-domains/inventory/context.md +233 -233
- package/boilerplates/03-ecommerce-starter/memory/30-domains/orders/context.md +210 -210
- package/boilerplates/03-ecommerce-starter/memory/30-domains/payments/context.md +168 -168
- package/boilerplates/03-ecommerce-starter/memory/80-data/sqlite.md +260 -260
- package/boilerplates/03-ecommerce-starter/memory/90-decisions/ADR-TEMPLATE.md +223 -223
- package/boilerplates/04-microservices-starter/.env.example +43 -43
- package/boilerplates/04-microservices-starter/API-EXAMPLES.md +609 -609
- package/boilerplates/04-microservices-starter/ARCHITECTURE.md +512 -512
- package/boilerplates/04-microservices-starter/GETTING-STARTED.md +246 -246
- package/boilerplates/04-microservices-starter/INDEX.md +377 -377
- package/boilerplates/04-microservices-starter/MANIFEST.md +456 -456
- package/boilerplates/04-microservices-starter/README.md +466 -466
- package/boilerplates/04-microservices-starter/SUMMARY.md +386 -386
- package/boilerplates/04-microservices-starter/backend/api-gateway/Dockerfile +14 -14
- package/boilerplates/04-microservices-starter/backend/api-gateway/package.json +29 -29
- package/boilerplates/04-microservices-starter/backend/api-gateway/src/app.module.ts +9 -9
- package/boilerplates/04-microservices-starter/backend/api-gateway/src/gateway.controller.ts +45 -45
- package/boilerplates/04-microservices-starter/backend/api-gateway/src/gateway.service.ts +114 -114
- package/boilerplates/04-microservices-starter/backend/api-gateway/src/main.ts +9 -9
- package/boilerplates/04-microservices-starter/backend/api-gateway/tsconfig.json +20 -20
- package/boilerplates/04-microservices-starter/backend/services/auth-service/Dockerfile +14 -14
- package/boilerplates/04-microservices-starter/backend/services/auth-service/package.json +42 -42
- package/boilerplates/04-microservices-starter/backend/services/auth-service/src/app.module.ts +7 -7
- package/boilerplates/04-microservices-starter/backend/services/auth-service/src/main.ts +9 -9
- package/boilerplates/04-microservices-starter/backend/services/auth-service/src/modules/auth/auth.controller.ts +130 -130
- package/boilerplates/04-microservices-starter/backend/services/auth-service/src/modules/auth/auth.module.ts +21 -21
- package/boilerplates/04-microservices-starter/backend/services/auth-service/src/modules/auth/auth.service.ts +159 -159
- package/boilerplates/04-microservices-starter/backend/services/auth-service/src/modules/auth/jwt.strategy.ts +19 -19
- package/boilerplates/04-microservices-starter/backend/services/auth-service/src/modules/auth/local.strategy.ts +18 -18
- package/boilerplates/04-microservices-starter/backend/services/auth-service/tsconfig.json +21 -21
- package/boilerplates/04-microservices-starter/backend/services/notification-service/Dockerfile +14 -14
- package/boilerplates/04-microservices-starter/backend/services/notification-service/package.json +25 -25
- package/boilerplates/04-microservices-starter/backend/services/notification-service/src/app.module.ts +7 -7
- package/boilerplates/04-microservices-starter/backend/services/notification-service/src/main.ts +9 -9
- package/boilerplates/04-microservices-starter/backend/services/notification-service/src/modules/notification/notification.controller.ts +160 -160
- package/boilerplates/04-microservices-starter/backend/services/notification-service/src/modules/notification/notification.module.ts +10 -10
- package/boilerplates/04-microservices-starter/backend/services/notification-service/src/modules/notification/notification.service.ts +92 -92
- package/boilerplates/04-microservices-starter/backend/services/notification-service/tsconfig.json +20 -20
- package/boilerplates/04-microservices-starter/backend/services/user-service/Dockerfile +14 -14
- package/boilerplates/04-microservices-starter/backend/services/user-service/package.json +25 -25
- package/boilerplates/04-microservices-starter/backend/services/user-service/src/app.module.ts +7 -7
- package/boilerplates/04-microservices-starter/backend/services/user-service/src/main.ts +9 -9
- package/boilerplates/04-microservices-starter/backend/services/user-service/src/modules/user/user.controller.ts +122 -122
- package/boilerplates/04-microservices-starter/backend/services/user-service/src/modules/user/user.module.ts +10 -10
- package/boilerplates/04-microservices-starter/backend/services/user-service/src/modules/user/user.service.ts +161 -161
- package/boilerplates/04-microservices-starter/backend/services/user-service/tsconfig.json +20 -20
- package/boilerplates/04-microservices-starter/backend/shared/package.json +15 -15
- package/boilerplates/04-microservices-starter/backend/shared/src/constants/index.ts +84 -84
- package/boilerplates/04-microservices-starter/backend/shared/src/decorators/index.ts +12 -12
- package/boilerplates/04-microservices-starter/backend/shared/src/index.ts +4 -4
- package/boilerplates/04-microservices-starter/backend/shared/src/interfaces/index.ts +152 -152
- package/boilerplates/04-microservices-starter/backend/shared/src/utils/index.ts +54 -54
- package/boilerplates/04-microservices-starter/backend/shared/tsconfig.json +20 -20
- package/boilerplates/04-microservices-starter/boilerplate.manifest.json +41 -41
- package/boilerplates/04-microservices-starter/docker-compose.yml +164 -164
- package/boilerplates/04-microservices-starter/memory/00-global/agent-contract.md +171 -171
- package/boilerplates/04-microservices-starter/memory/00-global/context-policy.md +89 -89
- package/boilerplates/04-microservices-starter/memory/00-global/index.md +102 -102
- package/boilerplates/04-microservices-starter/memory/00-global/mission.md +44 -44
- package/boilerplates/04-microservices-starter/memory/00-global/patterns.md +106 -106
- package/boilerplates/04-microservices-starter/memory/10-product/vision.md +76 -76
- package/boilerplates/04-microservices-starter/memory/20-architecture/overview.md +247 -247
- package/boilerplates/04-microservices-starter/memory/30-domains/auth-service/api.md +293 -293
- package/boilerplates/04-microservices-starter/memory/30-domains/auth-service/context.md +108 -108
- package/boilerplates/04-microservices-starter/memory/30-domains/notification-service/api.md +333 -333
- package/boilerplates/04-microservices-starter/memory/30-domains/notification-service/context.md +121 -121
- package/boilerplates/04-microservices-starter/memory/30-domains/user-service/api.md +308 -308
- package/boilerplates/04-microservices-starter/memory/30-domains/user-service/context.md +120 -120
- package/boilerplates/04-microservices-starter/memory/50-orchestration/topology.md +216 -216
- package/boilerplates/04-microservices-starter/package.json +21 -21
- package/boilerplates/05-monorepo-starter/.env.example +1 -1
- package/boilerplates/05-monorepo-starter/BOILERPLATE_SUMMARY.md +193 -193
- package/boilerplates/05-monorepo-starter/DEVELOPMENT.md +481 -481
- package/boilerplates/05-monorepo-starter/Dockerfile +35 -35
- package/boilerplates/05-monorepo-starter/README.md +318 -318
- package/boilerplates/05-monorepo-starter/boilerplate.manifest.json +43 -43
- package/boilerplates/05-monorepo-starter/docker-compose.yml +36 -36
- package/boilerplates/05-monorepo-starter/memory/00-global/agent-contract.md +28 -28
- package/boilerplates/05-monorepo-starter/memory/00-global/context-policy.md +21 -21
- package/boilerplates/05-monorepo-starter/memory/00-global/index.md +44 -44
- package/boilerplates/05-monorepo-starter/memory/00-global/mission.md +17 -17
- package/boilerplates/05-monorepo-starter/memory/00-global/patterns.md +48 -48
- package/boilerplates/05-monorepo-starter/memory/10-product/business-rules.md +24 -24
- package/boilerplates/05-monorepo-starter/memory/10-product/nfrs.md +39 -39
- package/boilerplates/05-monorepo-starter/memory/10-product/personas.md +25 -25
- package/boilerplates/05-monorepo-starter/memory/10-product/vision.md +22 -22
- package/boilerplates/05-monorepo-starter/memory/20-architecture/backend.md +85 -85
- package/boilerplates/05-monorepo-starter/memory/20-architecture/data.md +66 -66
- package/boilerplates/05-monorepo-starter/memory/20-architecture/frontend.md +58 -58
- package/boilerplates/05-monorepo-starter/memory/20-architecture/overview.md +86 -86
- package/boilerplates/05-monorepo-starter/memory/20-architecture/security.md +58 -58
- package/boilerplates/05-monorepo-starter/memory/30-domains/order/api.md +81 -81
- package/boilerplates/05-monorepo-starter/memory/30-domains/order/context.md +63 -63
- package/boilerplates/05-monorepo-starter/memory/30-domains/product/api.md +81 -81
- package/boilerplates/05-monorepo-starter/memory/30-domains/product/context.md +56 -56
- package/boilerplates/05-monorepo-starter/memory/30-domains/user/api.md +99 -99
- package/boilerplates/05-monorepo-starter/memory/30-domains/user/context.md +58 -58
- package/boilerplates/05-monorepo-starter/package.json +30 -30
- package/boilerplates/05-monorepo-starter/packages/apps/backend/.env.example +15 -15
- package/boilerplates/05-monorepo-starter/packages/apps/backend/README.md +28 -28
- package/boilerplates/05-monorepo-starter/packages/apps/backend/package.json +53 -53
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/app.module.ts +40 -40
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/common/exceptions/global.exception.ts +32 -32
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/common/guards/jwt.guard.ts +5 -5
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/common/guards/jwt.strategy.ts +11 -11
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/common/guards/roles.guard.ts +17 -17
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/common/health.controller.ts +13 -13
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/main.ts +28 -28
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/orders/dto/index.ts +23 -23
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/orders/entities/order.entity.ts +48 -48
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/orders/orders.controller.ts +51 -51
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/orders/orders.module.ts +13 -13
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/orders/orders.service.ts +123 -123
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/products/dto/index.ts +35 -35
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/products/entities/product.entity.ts +28 -28
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/products/products.controller.ts +49 -49
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/products/products.module.ts +12 -12
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/products/products.service.ts +79 -79
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/users/dto/index.ts +24 -24
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/users/entities/user.entity.ts +28 -28
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/users/users.controller.ts +29 -29
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/users/users.module.ts +15 -15
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/users/users.service.ts +78 -78
- package/boilerplates/05-monorepo-starter/packages/apps/backend/tsconfig.json +25 -25
- package/boilerplates/05-monorepo-starter/packages/apps/frontend/.env.example +1 -1
- package/boilerplates/05-monorepo-starter/packages/apps/frontend/README.md +30 -30
- package/boilerplates/05-monorepo-starter/packages/apps/frontend/app/dashboard/page.tsx +39 -39
- package/boilerplates/05-monorepo-starter/packages/apps/frontend/app/layout.tsx +15 -15
- package/boilerplates/05-monorepo-starter/packages/apps/frontend/app/page.tsx +47 -47
- package/boilerplates/05-monorepo-starter/packages/apps/frontend/app/products/page.tsx +51 -51
- package/boilerplates/05-monorepo-starter/packages/apps/frontend/components/features/product-card.tsx +19 -19
- package/boilerplates/05-monorepo-starter/packages/apps/frontend/components/layout/footer.tsx +10 -10
- package/boilerplates/05-monorepo-starter/packages/apps/frontend/components/layout/header.tsx +24 -24
- package/boilerplates/05-monorepo-starter/packages/apps/frontend/components/layout/layout.tsx +13 -13
- package/boilerplates/05-monorepo-starter/packages/apps/frontend/lib/api-client.ts +34 -34
- package/boilerplates/05-monorepo-starter/packages/apps/frontend/lib/auth.ts +35 -35
- package/boilerplates/05-monorepo-starter/packages/apps/frontend/lib/orders.ts +28 -28
- package/boilerplates/05-monorepo-starter/packages/apps/frontend/lib/products.ts +28 -28
- package/boilerplates/05-monorepo-starter/packages/apps/frontend/next.config.js +15 -15
- package/boilerplates/05-monorepo-starter/packages/apps/frontend/package.json +31 -31
- package/boilerplates/05-monorepo-starter/packages/apps/frontend/postcss.config.js +3 -3
- package/boilerplates/05-monorepo-starter/packages/apps/frontend/styles/globals.css +7 -7
- package/boilerplates/05-monorepo-starter/packages/apps/frontend/tailwind.config.js +7 -7
- package/boilerplates/05-monorepo-starter/packages/apps/frontend/tsconfig.json +14 -14
- package/boilerplates/05-monorepo-starter/packages/packages/shared-types/README.md +35 -35
- package/boilerplates/05-monorepo-starter/packages/packages/shared-types/package.json +17 -17
- package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/api/common.ts +18 -18
- package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/api/order.ts +38 -38
- package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/api/product.ts +33 -33
- package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/api/user.ts +32 -32
- package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/domain/index.ts +41 -41
- package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/errors/index.ts +46 -46
- package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/index.ts +7 -7
- package/boilerplates/05-monorepo-starter/packages/packages/shared-types/tsconfig.json +8 -8
- package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/README.md +30 -30
- package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/package.json +17 -17
- package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/constants/index.ts +45 -45
- package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/index.ts +4 -4
- package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/utils/index.ts +3 -3
- package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/utils/math.ts +30 -30
- package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/utils/string.ts +48 -48
- package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/validators/index.ts +44 -44
- package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/tsconfig.json +8 -8
- package/boilerplates/05-monorepo-starter/tsconfig.json +23 -23
- package/boilerplates/05-monorepo-starter/turbo.json +35 -35
- package/boilerplates/06-clean-arch/README.md +48 -48
- package/boilerplates/06-clean-arch/WHEN-CLEAN-WHEN-LEAN.md +71 -71
- package/boilerplates/06-clean-arch/backend/package.json +43 -43
- package/boilerplates/06-clean-arch/backend/src/app.module.ts +20 -20
- package/boilerplates/06-clean-arch/backend/src/main.ts +10 -10
- package/boilerplates/06-clean-arch/backend/src/modules/orders/application/place-order.usecase.ts +47 -47
- package/boilerplates/06-clean-arch/backend/src/modules/orders/application/ship-order.usecase.ts +28 -28
- package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/money.vo.ts +30 -30
- package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order-status.vo.ts +36 -36
- package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.entity.ts +85 -85
- package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.repository.ts +17 -17
- package/boilerplates/06-clean-arch/backend/src/modules/orders/infrastructure/order.orm-entity.ts +24 -24
- package/boilerplates/06-clean-arch/backend/src/modules/orders/infrastructure/typeorm-order.repository.ts +57 -57
- package/boilerplates/06-clean-arch/backend/src/modules/orders/orders.module.ts +28 -28
- package/boilerplates/06-clean-arch/backend/src/modules/orders/presentation/orders.controller.ts +31 -31
- package/boilerplates/06-clean-arch/backend/src/modules/orders/presentation/orders.http.dto.ts +30 -30
- package/boilerplates/06-clean-arch/backend/src/modules/products/product.entity.ts +20 -20
- package/boilerplates/06-clean-arch/backend/src/modules/products/products.controller.ts +43 -43
- package/boilerplates/06-clean-arch/backend/src/modules/products/products.module.ts +11 -11
- package/boilerplates/06-clean-arch/backend/src/shared/result.ts +32 -32
- package/boilerplates/06-clean-arch/backend/test/orders/place-order.spec.ts +46 -46
- package/boilerplates/06-clean-arch/backend/tsconfig.json +16 -16
- package/boilerplates/06-clean-arch/boilerplate.manifest.json +43 -43
- package/boilerplates/06-clean-arch/memory/30-domains/orders/context.md +39 -39
- package/boilerplates/06-clean-arch/memory/30-domains/products/context.md +23 -23
- package/boilerplates/README.md +427 -427
- package/design-md/BRIEF-TEMPLATE.md +47 -47
- package/design-md/INDEX.md +35 -35
- package/design-md/MATRIX.md +24 -24
- package/design-md/PLAYBOOK.md +35 -35
- package/design-md/examples/agent-console-brief.md +48 -48
- package/dist/apps/dashboard/app/api/forja/[...path]/route.js +8 -1
- package/dist/apps/dashboard/app/api/forja/guard.d.ts +24 -0
- package/dist/apps/dashboard/app/api/forja/guard.js +63 -0
- package/dist/apps/dashboard/app/dashboard-client.jsx +10 -10
- package/dist/apps/server/src/forja-nest.module.js +9 -4
- package/dist/apps/server/src/main.js +10 -1
- package/dist/bin/create-memory-nest-kit.js +17 -17
- package/dist/bin/init-project.js +38 -38
- package/dist/lib/audit.js +7 -7
- package/dist/lib/code-context.js +6 -0
- package/dist/lib/context-builder.js +32 -32
- package/dist/lib/core/architecture-gate.d.ts +20 -0
- package/dist/lib/core/architecture-gate.js +60 -0
- package/dist/lib/core/drift-gate.d.ts +18 -0
- package/dist/lib/core/drift-gate.js +55 -0
- package/dist/lib/core/gates.d.ts +9 -2
- package/dist/lib/core/gates.js +13 -2
- package/dist/lib/core/health.js +15 -0
- package/dist/lib/core/incident-search.d.ts +19 -0
- package/dist/lib/core/incident-search.js +32 -0
- package/dist/lib/core/model-pricing.d.ts +31 -0
- package/dist/lib/core/model-pricing.js +74 -0
- package/dist/lib/core/registry.d.ts +194 -0
- package/dist/lib/core/registry.js +194 -0
- package/dist/lib/core/release.d.ts +194 -0
- package/dist/lib/core/risk-collect.d.ts +19 -0
- package/dist/lib/core/risk-collect.js +173 -0
- package/dist/lib/drift-sentinel.d.ts +59 -0
- package/dist/lib/drift-sentinel.js +126 -0
- package/dist/lib/generators/memory-generator.js +691 -691
- package/dist/lib/generators/nest-generator.js +412 -398
- package/dist/lib/generators/readme-generator.js +180 -180
- package/dist/lib/governance-report.js +39 -39
- package/dist/lib/workspace.js +29 -29
- package/dist/packages/adapter-git/src/index.d.ts +1 -1
- package/dist/packages/adapter-git/src/index.js +11 -6
- package/dist/packages/adapter-nest/src/index.d.ts +19 -0
- package/dist/packages/adapter-nest/src/index.js +26 -1
- package/dist/packages/adapter-sqlite/src/index.d.ts +27 -1
- package/dist/packages/adapter-sqlite/src/index.js +61 -12
- package/dist/packages/contracts/src/index.d.ts +33 -0
- package/dist/packages/contracts/src/index.js +13 -0
- package/dist/packages/core/src/index.d.ts +12 -0
- package/dist/packages/core/src/index.js +29 -0
- package/dist/packages/engineering/architecture/src/index.d.ts +76 -0
- package/dist/packages/engineering/architecture/src/index.js +131 -0
- package/dist/packages/engineering/evidence/src/index.d.ts +41 -0
- package/dist/packages/engineering/evidence/src/index.js +31 -0
- package/dist/packages/engineering/identity/src/index.d.ts +57 -0
- package/dist/packages/engineering/identity/src/index.js +88 -0
- package/dist/packages/engineering/monitoring/src/index.d.ts +37 -0
- package/dist/packages/engineering/monitoring/src/index.js +40 -0
- package/dist/packages/engineering/provenance/src/index.d.ts +25 -0
- package/dist/packages/engineering/provenance/src/index.js +21 -0
- package/dist/packages/engineering/risk/src/index.d.ts +89 -0
- package/dist/packages/engineering/risk/src/index.js +120 -0
- package/dist/packages/graph/src/index.d.ts +23 -1
- package/dist/packages/graph/src/index.js +88 -15
- package/dist/packages/llm/src/index.js +27 -4
- package/dist/packages/mcp/src/index.js +27 -8
- package/dist/packages/orchestration/src/index.d.ts +11 -1
- package/dist/packages/orchestration/src/index.js +34 -7
- package/dist/packages/policy/src/index.d.ts +40 -0
- package/dist/packages/policy/src/index.js +39 -4
- package/dist/packages/runtime/src/index.js +3 -0
- package/dist/packages/sandbox/src/index.d.ts +47 -0
- package/dist/packages/sandbox/src/index.js +59 -0
- package/dist/packages/validator/src/index.d.ts +8 -0
- package/dist/packages/validator/src/index.js +21 -6
- package/dist/scripts/adr.d.ts +17 -0
- package/dist/scripts/adr.js +152 -0
- package/dist/scripts/agent-harness.js +72 -64
- package/dist/scripts/agent-router.js +20 -20
- package/dist/scripts/agent.d.ts +27 -0
- package/dist/scripts/agent.js +249 -0
- package/dist/scripts/architecture.d.ts +16 -0
- package/dist/scripts/architecture.js +186 -0
- package/dist/scripts/build-smart-context.js +22 -22
- package/dist/scripts/compress-memory.js +8 -8
- package/dist/scripts/context-ops.js +29 -29
- package/dist/scripts/cost-economy.d.ts +2 -0
- package/dist/scripts/cost-economy.js +79 -0
- package/dist/scripts/demo-autonomy.js +13 -6
- package/dist/scripts/dev.js +13 -13
- package/dist/scripts/drift-check.d.ts +17 -0
- package/dist/scripts/drift-check.js +63 -0
- package/dist/scripts/engineer.d.ts +20 -0
- package/dist/scripts/engineer.js +208 -0
- package/dist/scripts/evidence.d.ts +12 -0
- package/dist/scripts/evidence.js +55 -0
- package/dist/scripts/extract-global-knowledge.js +5 -5
- package/dist/scripts/gates.d.ts +6 -2
- package/dist/scripts/gates.js +14 -4
- package/dist/scripts/generate-dashboard.js +11 -11
- package/dist/scripts/incident.d.ts +19 -0
- package/dist/scripts/incident.js +103 -0
- package/dist/scripts/llm-fit.js +32 -3
- package/dist/scripts/memory-schema.js +48 -48
- package/dist/scripts/provenance.d.ts +14 -0
- package/dist/scripts/provenance.js +114 -0
- package/dist/scripts/query-universal-memory.js +13 -13
- package/dist/scripts/risk.d.ts +15 -0
- package/dist/scripts/risk.js +81 -0
- package/dist/scripts/simulate.d.ts +20 -0
- package/dist/scripts/simulate.js +150 -0
- package/dist/scripts/sprint-manager.js +39 -39
- package/dist/scripts/sync-universal-memory.js +44 -44
- package/docs/2x/CLI-CAPABILITIES.md +35 -35
- package/docs/2x/IMPLEMENTATION-AUDIT.md +40 -40
- package/docs/2x/SPRINT-1-CLI-CAPABILITY-PLAN.md +53 -53
- package/docs/2x/SPRINT-10-GRAPH-SYNC-PLAN.md +54 -54
- package/docs/2x/SPRINT-11-GRAPH-SYNC-CLI-MCP-PLAN.md +38 -38
- package/docs/2x/SPRINT-12-REAL-AUTONOMY-PLAN.md +40 -40
- package/docs/2x/SPRINT-13-MCP-STDIO-PLAN.md +26 -26
- package/docs/2x/SPRINT-14-SERVER-RESTART-PLAN.md +28 -28
- package/docs/2x/SPRINT-15-CHAOS-SECURITY-PLAN.md +22 -22
- package/docs/2x/SPRINT-16-LAST-MILE-PLAN.md +25 -25
- package/docs/2x/SPRINT-2-CLI-CAPABILITY-PLAN.md +39 -39
- package/docs/2x/SPRINT-3-RUNTIME-PERSISTENCE-PLAN.md +42 -42
- package/docs/2x/SPRINT-4-MCP-REGISTRY-PLAN.md +35 -35
- package/docs/2x/SPRINT-5-SERVER-APPROVALS-AUDIT-PLAN.md +31 -31
- package/docs/2x/SPRINT-6-EVENTS-E2E-PLAN.md +55 -55
- package/docs/2x/SPRINT-7-GRAPHLOOP-PERSISTENCE-PLAN.md +60 -60
- package/docs/2x/SPRINT-8-CONTEXT-GRAPH-PLAN.md +64 -64
- package/docs/2x/SPRINT-9-DETERMINISTIC-EXTRACTORS-PLAN.md +51 -51
- package/docs/GUIA-ONBOARDING-EXECUTIVO.md +63 -63
- package/docs/GUIA-ONBOARDING-OPERACIONAL-PAPEIS.md +136 -136
- package/docs/GUIA-ONBOARDING-PROJETO.md +279 -279
- package/docs/agent-harnesses.md +149 -149
- package/docs/architecture/FORJA-2.0-ARCHITECTURE.md +109 -109
- package/docs/architecture/FORJA-2.0-IMPACT-FOUNDATION.md +273 -273
- package/docs/architecture/FORJA-3-ENGINEERING-INTELLIGENCE-ARCHITECTURE.md +442 -0
- package/docs/archive/CHECKLIST-FINAL.md +295 -295
- package/docs/archive/FASE2-SUMMARY.md +263 -263
- package/docs/archive/FASE3-PROGRESS.md +355 -355
- package/docs/archive/IMPLEMENTACAO-FASE1.md +476 -476
- package/docs/archive/INDICE-MASTER.md +282 -282
- package/docs/archive/PROJETO-COMPLETO.md +363 -363
- package/docs/archive/README-REFINAMENTO.md +293 -293
- package/docs/archive/REFERENCIA-RAPIDA.md +324 -324
- package/docs/archive/REFINAMENTO-v1.0.md +565 -565
- package/docs/archive/RELATORIO-TESTES-INTEGRACAO.md +223 -223
- package/docs/archive/START-HERE.md +319 -319
- package/docs/archive/SUMARIO-EXECUTIVO.md +268 -268
- package/docs/archive/examples/v1/AGENTS.md +10 -10
- package/docs/archive/examples/v1/README.md +36 -36
- package/docs/archive/examples/v1/backend/jest-e2e.json +9 -9
- package/docs/archive/examples/v1/backend/nest-cli.json +4 -4
- package/docs/archive/examples/v1/backend/package.json +42 -42
- package/docs/archive/examples/v1/backend/src/app.controller.ts +12 -12
- package/docs/archive/examples/v1/backend/src/app.module.ts +10 -10
- package/docs/archive/examples/v1/backend/src/app.service.ts +8 -8
- package/docs/archive/examples/v1/backend/src/main.ts +10 -10
- package/docs/archive/examples/v1/backend/test/app.e2e-spec.ts +24 -24
- package/docs/archive/examples/v1/backend/tsconfig.build.json +4 -4
- package/docs/archive/examples/v1/backend/tsconfig.json +17 -17
- package/docs/archive/examples/v1/memory/00-global/glossary.md +5 -5
- package/docs/archive/examples/v1/memory/00-global/mission.md +9 -9
- package/docs/archive/examples/v1/memory/00-global/standards.md +12 -12
- package/docs/archive/examples/v1/memory/00-global/tooling.md +10 -10
- package/docs/archive/examples/v1/memory/10-product/business-rules.md +3 -3
- package/docs/archive/examples/v1/memory/10-product/nfrs.md +6 -6
- package/docs/archive/examples/v1/memory/10-product/personas.md +3 -3
- package/docs/archive/examples/v1/memory/10-product/vision.md +3 -3
- package/docs/archive/examples/v1/memory/20-architecture/backend.md +10 -10
- package/docs/archive/examples/v1/memory/20-architecture/data.md +3 -3
- package/docs/archive/examples/v1/memory/20-architecture/frontend.md +3 -3
- package/docs/archive/examples/v1/memory/20-architecture/observability.md +5 -5
- package/docs/archive/examples/v1/memory/20-architecture/security.md +6 -6
- package/docs/archive/examples/v1/memory/20-architecture/system-overview.md +3 -3
- package/docs/archive/examples/v1/memory/30-domains/auth/api.md +3 -3
- package/docs/archive/examples/v1/memory/30-domains/auth/context.md +3 -3
- package/docs/archive/examples/v1/memory/30-domains/auth/rules.md +3 -3
- package/docs/archive/examples/v1/memory/30-domains/billing/api.md +3 -3
- package/docs/archive/examples/v1/memory/30-domains/billing/context.md +3 -3
- package/docs/archive/examples/v1/memory/30-domains/billing/rules.md +3 -3
- package/docs/archive/examples/v1/memory/40-delivery/backlog.md +3 -3
- package/docs/archive/examples/v1/memory/40-delivery/current-sprint.md +10 -10
- package/docs/archive/examples/v1/memory/40-delivery/roadmap.md +3 -3
- package/docs/archive/examples/v1/memory/90-decisions/ADR-0001-template.md +9 -9
- package/docs/archive/examples/v1/prompts/project-prompt-base.md +19 -19
- package/docs/archive/examples/v2/.memoryrc.json +8 -8
- package/docs/archive/examples/v2/AGENTS.md +16 -16
- package/docs/archive/examples/v2/README.md +35 -35
- package/docs/archive/examples/v2/agents/README.md +3 -3
- package/docs/archive/examples/v2/agents/backend-nest.md +9 -9
- package/docs/archive/examples/v2/agents/dba.md +4 -4
- package/docs/archive/examples/v2/agents/frontend.md +4 -4
- package/docs/archive/examples/v2/agents/orchestrator.md +9 -9
- package/docs/archive/examples/v2/agents/reviewer.md +6 -6
- package/docs/archive/examples/v2/agents/security.md +4 -4
- package/docs/archive/examples/v2/backend/jest-e2e.json +9 -9
- package/docs/archive/examples/v2/backend/nest-cli.json +4 -4
- package/docs/archive/examples/v2/backend/package.json +42 -42
- package/docs/archive/examples/v2/backend/src/app.controller.ts +12 -12
- package/docs/archive/examples/v2/backend/src/app.module.ts +10 -10
- package/docs/archive/examples/v2/backend/src/app.service.ts +8 -8
- package/docs/archive/examples/v2/backend/src/main.ts +10 -10
- package/docs/archive/examples/v2/backend/test/app.e2e-spec.ts +24 -24
- package/docs/archive/examples/v2/backend/tsconfig.build.json +4 -4
- package/docs/archive/examples/v2/backend/tsconfig.json +17 -17
- package/docs/archive/examples/v2/memory/00-global/agent-contract.md +15 -15
- package/docs/archive/examples/v2/memory/00-global/context-index.md +12 -12
- package/docs/archive/examples/v2/memory/00-global/context-policy.md +14 -14
- package/docs/archive/examples/v2/memory/00-global/mission.md +9 -9
- package/docs/archive/examples/v2/memory/00-global/standards.md +12 -12
- package/docs/archive/examples/v2/memory/10-product/business-rules.md +3 -3
- package/docs/archive/examples/v2/memory/10-product/nfrs.md +6 -6
- package/docs/archive/examples/v2/memory/10-product/personas.md +3 -3
- package/docs/archive/examples/v2/memory/10-product/vision.md +3 -3
- package/docs/archive/examples/v2/memory/20-architecture/backend.md +10 -10
- package/docs/archive/examples/v2/memory/20-architecture/data.md +3 -3
- package/docs/archive/examples/v2/memory/20-architecture/frontend.md +3 -3
- package/docs/archive/examples/v2/memory/20-architecture/observability.md +5 -5
- package/docs/archive/examples/v2/memory/20-architecture/security.md +6 -6
- package/docs/archive/examples/v2/memory/20-architecture/system-overview.md +3 -3
- package/docs/archive/examples/v2/memory/30-domains/auth/api.md +3 -3
- package/docs/archive/examples/v2/memory/30-domains/auth/context.md +3 -3
- package/docs/archive/examples/v2/memory/30-domains/auth/rules.md +3 -3
- package/docs/archive/examples/v2/memory/30-domains/billing/api.md +3 -3
- package/docs/archive/examples/v2/memory/30-domains/billing/context.md +3 -3
- package/docs/archive/examples/v2/memory/30-domains/billing/rules.md +3 -3
- package/docs/archive/examples/v2/memory/40-delivery/backlog.md +3 -3
- package/docs/archive/examples/v2/memory/40-delivery/current-sprint.md +10 -10
- package/docs/archive/examples/v2/memory/40-delivery/roadmap.md +3 -3
- package/docs/archive/examples/v2/memory/50-orchestration/handoff-protocol.md +8 -8
- package/docs/archive/examples/v2/memory/50-orchestration/handoffs/2026-04-18T18-40-10.517Z_orchestrator_para_backend-nest.md +19 -19
- package/docs/archive/examples/v2/memory/50-orchestration/handoffs/README.md +4 -4
- package/docs/archive/examples/v2/memory/50-orchestration/parallel-playbook.md +9 -9
- package/docs/archive/examples/v2/memory/50-orchestration/routing.md +10 -10
- package/docs/archive/examples/v2/memory/50-orchestration/topology.md +15 -15
- package/docs/archive/examples/v2/memory/60-runs/README.md +3 -3
- package/docs/archive/examples/v2/memory/70-summaries/domain-summary.md +3 -3
- package/docs/archive/examples/v2/memory/70-summaries/global-summary.md +6 -6
- package/docs/archive/examples/v2/memory/90-decisions/ADR-0001-template.md +9 -9
- package/docs/archive/examples/v2/memory/README.md +8 -8
- package/docs/archive/examples/v2/prompts/multi-agent-orchestrator.md +12 -12
- package/docs/archive/examples/v2/prompts/project-prompt-base.md +21 -21
- package/docs/archive/examples/v2/prompts/worker-task-template.md +10 -10
- package/docs/archive/examples/v2/scripts/append-handoff.mjs +25 -25
- package/docs/archive/examples/v2/scripts/build-context-pack.mjs +31 -31
- package/docs/archive/examples/v2/skills/context-compaction/SKILL.md +9 -9
- package/docs/archive/examples/v2/skills/handoff/SKILL.md +8 -8
- package/docs/archive/examples/v2/skills/nest-api/SKILL.md +7 -7
- package/docs/archive/examples/v2/skills/triage-task/SKILL.md +10 -10
- package/docs/archive/legacy-bin/create-memory-nest-kit-monolith.js +1486 -1486
- package/docs/capacidades-externas.md +86 -86
- package/docs/cli-first-operacao.md +74 -74
- package/docs/dev-workflow.md +421 -421
- package/docs/examples.md +546 -546
- package/docs/fluxo.md +103 -103
- package/docs/glossary.md +453 -453
- package/docs/init-project.md +457 -457
- package/docs/manual-operacional-cli-sdd-gsd.md +1014 -1014
- package/docs/personas/architect/README.md +333 -333
- package/docs/personas/developer/README.md +371 -371
- package/docs/personas/executive/README.md +172 -172
- package/docs/personas/qa/README.md +350 -350
- package/docs/processo-projeto.md +138 -138
- package/docs/publishing.md +377 -377
- package/docs/quick-reference.md +409 -409
- package/docs/security/FORJA-2.0-RELEASE-AUDIT-2026-08-01.md +95 -95
- package/docs/structure.md +360 -360
- package/docs/token-optimization.md +502 -502
- package/docs/vision/FORJA-2.0-VISION.md +72 -72
- package/memory/00-global/mission.md +15 -15
- package/memory/00-global/shared-knowledge.md +8 -8
- package/memory/00-global/standards.md +47 -47
- package/memory/10-product/personas.md +21 -21
- package/memory/10-product/vision.md +27 -27
- package/memory/30-projects/README.md +15 -15
- package/memory/40-delivery/backlog.md +15 -15
- package/memory/40-delivery/current-sprint.md +20 -20
- package/memory/50-orchestration/gsd-harness.md +55 -55
- package/memory/50-orchestration/handoffs/2026-07-31_architect_foundation-contracts.md +15 -15
- package/memory/50-orchestration/handoffs/2026-07-31_backend-nest.md +22 -22
- package/memory/50-orchestration/handoffs/2026-07-31_context-engine.md +16 -16
- package/memory/50-orchestration/handoffs/2026-07-31_control-plane.md +28 -28
- package/memory/50-orchestration/handoffs/2026-07-31_core-capability-registry.md +15 -15
- package/memory/50-orchestration/handoffs/2026-07-31_evals-plugin-sdk.md +22 -22
- package/memory/50-orchestration/handoffs/2026-07-31_events-scheduler.md +16 -16
- package/memory/50-orchestration/handoffs/2026-07-31_graphloop.md +16 -16
- package/memory/50-orchestration/handoffs/2026-07-31_mcp.md +21 -21
- package/memory/50-orchestration/handoffs/2026-07-31_nest-bootstrap.md +28 -28
- package/memory/50-orchestration/handoffs/2026-07-31_next-dashboard.md +22 -22
- package/memory/50-orchestration/handoffs/2026-07-31_observability.md +27 -27
- package/memory/50-orchestration/handoffs/2026-07-31_orchestration.md +21 -21
- package/memory/50-orchestration/handoffs/2026-07-31_planner-validator.md +16 -16
- package/memory/50-orchestration/handoffs/2026-07-31_policy-engine.md +14 -14
- package/memory/50-orchestration/handoffs/2026-07-31_runtime-control-plane.md +23 -23
- package/memory/50-orchestration/handoffs/2026-07-31_runtime-controlado.md +15 -15
- package/memory/50-orchestration/handoffs/2026-07-31_sandbox.md +21 -21
- package/memory/50-orchestration/handoffs/2026-07-31_sdk.md +27 -27
- package/memory/50-orchestration/handoffs/2026-07-31_sqlite-adapter.md +21 -21
- package/memory/50-orchestration/handoffs/2026-07-31_worker-dashboard-boundary.md +23 -23
- package/memory/50-orchestration/handoffs/2026-08-01_approval-server-identity.md +23 -23
- package/memory/50-orchestration/handoffs/2026-08-01_dashboard-auth-query.md +24 -24
- package/memory/50-orchestration/handoffs/2026-08-01_graphloop-approvals.md +23 -23
- package/memory/50-orchestration/handoffs/2026-08-01_sprint-1-cli-capabilities.md +41 -41
- package/memory/50-orchestration/handoffs/2026-08-01_sprint-10-graph-sync.md +23 -23
- package/memory/50-orchestration/handoffs/2026-08-01_sprint-11-graph-sync-cli-mcp.md +22 -22
- package/memory/50-orchestration/handoffs/2026-08-01_sprint-12-real-autonomy.md +16 -16
- package/memory/50-orchestration/handoffs/2026-08-01_sprint-2-cli-capabilities.md +30 -30
- package/memory/50-orchestration/handoffs/2026-08-01_sprint-3-runtime-persistence.md +29 -29
- package/memory/50-orchestration/handoffs/2026-08-01_sprint-4-mcp.md +29 -29
- package/memory/50-orchestration/handoffs/2026-08-01_sprint-5-server-approvals-audit.md +22 -22
- package/memory/50-orchestration/handoffs/2026-08-01_sprint-6-events-e2e.md +25 -25
- package/memory/50-orchestration/handoffs/2026-08-01_sprint-7-graphloop.md +23 -23
- package/memory/50-orchestration/handoffs/2026-08-01_sprint-8-context-graph.md +23 -23
- package/memory/50-orchestration/handoffs/2026-08-01_sprint-9-extractors.md +21 -21
- package/memory/50-orchestration/handoffs/2026-08-02_sprint-13-mcp-stdio.md +14 -14
- package/memory/50-orchestration/handoffs/2026-08-02_sprint-14-server-restart.md +15 -15
- package/memory/50-orchestration/handoffs/2026-08-02_sprint-15-chaos-security.md +13 -13
- package/memory/50-orchestration/handoffs/2026-08-02_sprint-16-last-mile.md +11 -11
- package/memory/90-decisions/0001-memoria-hierarquica.md +38 -38
- package/memory/90-decisions/0002-sqlite-fts5-busca.md +25 -25
- package/memory/90-decisions/0003-smart-context-3-modos.md +31 -31
- package/memory/90-decisions/0004-validacao-obrigatoria-nest.md +27 -27
- package/memory/90-decisions/0005-handoff-7-campos.md +32 -32
- package/memory/90-decisions/0006-docs-por-persona.md +23 -23
- package/memory/90-decisions/0007-sdd-pipeline.md +33 -33
- package/memory/90-decisions/0008-sub-agents-claude-handoff-sqlite.md +36 -36
- package/memory/90-decisions/0009-claude-hooks-token-economy.md +43 -43
- package/memory/90-decisions/0010-banco-postgres.md +30 -30
- package/memory/90-decisions/0011-adrs-de-produto-realocadas.md +19 -19
- package/memory/90-decisions/0016-integracao-capacidades-externas.md +64 -64
- package/memory/90-decisions/0017-codegraph-no-harness-gsd.md +40 -40
- package/memory/90-decisions/0018-ferramentas-de-processo.md +46 -46
- package/memory/90-decisions/0019-workspace-separado.md +45 -45
- package/memory/90-decisions/0020-forja-core-cli-unica.md +45 -45
- package/memory/90-decisions/0021-guardrails-de-harness.md +111 -111
- package/memory/90-decisions/0022-congelar-dashboard-web.md +101 -101
- package/memory/90-decisions/0023-doctor-como-gate-do-nucleo.md +114 -114
- package/memory/90-decisions/0024-gate-do-tarball.md +103 -103
- package/memory/90-decisions/0025-coerencia-da-documentacao.md +105 -105
- package/memory/90-decisions/0026-migracao-typescript-runtime-duplo.md +66 -66
- package/memory/90-decisions/0027-clean-arch-calibrada.md +127 -127
- package/memory/90-decisions/0028-governanca-visivel.md +84 -84
- package/memory/90-decisions/0029-gate-do-projeto-gerado.md +59 -59
- package/memory/90-decisions/0030-projeto-gerado-herda-os-gates.md +53 -53
- package/memory/90-decisions/0031-motor-de-orquestracao.md +55 -55
- package/memory/90-decisions/0032-superficies-do-projeto-usam-cwd.md +63 -63
- package/memory/90-decisions/0033-doctor-distingue-permissao-de-corrupcao.md +64 -64
- package/memory/90-decisions/0034-forja-2-core-e-contratos.md +29 -29
- package/memory/90-decisions/0035-forja-2-local-first-e-autonomia.md +23 -23
- package/memory/90-decisions/0036-forja-2-capability-registry.md +30 -30
- package/memory/90-decisions/0037-forja-2-policy-engine-obrigatorio.md +28 -28
- package/memory/90-decisions/0038-forja-2-runtime-controlado.md +28 -28
- package/memory/90-decisions/0039-forja-2-event-bus-scheduler-local-first.md +31 -31
- package/memory/90-decisions/0040-forja-2-context-engine-budget-cache.md +32 -32
- package/memory/90-decisions/0041-forja-2-graphloop-separado-codegraph.md +32 -32
- package/memory/90-decisions/0042-forja-2-planner-validator-independentes.md +29 -29
- package/memory/90-decisions/0043-forja-2-orchestration-entities.md +16 -16
- package/memory/90-decisions/0044-forja-2-sandbox-worktree.md +19 -19
- package/memory/90-decisions/0045-forja-2-sqlite-adapter.md +19 -19
- package/memory/90-decisions/0046-forja-2-mcp-adapter.md +18 -18
- package/memory/90-decisions/0047-forja-2-backend-nest-adapter.md +19 -19
- package/memory/90-decisions/0048-forja-2-sdk-transport.md +18 -18
- package/memory/90-decisions/0049-forja-2-observability-control-plane.md +18 -18
- package/memory/90-decisions/0050-forja-2-control-plane-application-ports.md +18 -18
- package/memory/90-decisions/0051-forja-2-runtime-control-plane-composition.md +18 -18
- package/memory/90-decisions/0052-forja-2-deterministic-evaluation.md +15 -15
- package/memory/90-decisions/0053-forja-2-plugin-sdk-permissionado.md +16 -16
- package/memory/90-decisions/0054-forja-2-worker-dashboard-boundary.md +15 -15
- package/memory/90-decisions/0055-forja-2-next-dashboard-distribution.md +16 -16
- package/memory/90-decisions/0056-forja-2-dashboard-proxy-auth-query.md +16 -16
- package/memory/90-decisions/0057-forja-2-graphloop-approvals-dashboard.md +15 -15
- package/memory/90-decisions/0058-forja-2-approval-server-identity.md +15 -15
- package/memory/90-decisions/0059-cli-adapter-capability-registry.md +17 -17
- package/memory/90-decisions/0060-runtime-persistence-port.md +17 -17
- package/memory/90-decisions/0061-mcp-dynamic-registry-stdio.md +16 -16
- package/memory/90-decisions/0062-server-catalog-approval-audit.md +17 -17
- package/memory/90-decisions/0063-events-persistent-e2e.md +19 -19
- package/memory/90-decisions/0064-graphloop-sqlite-store.md +20 -20
- package/memory/90-decisions/0065-context-graph-source-cache.md +20 -20
- package/memory/90-decisions/0066-graph-deterministic-extractors.md +16 -16
- package/memory/90-decisions/0067-graph-sync-capability.md +17 -17
- package/memory/90-decisions/0068-graph-sync-cli-mcp.md +17 -17
- package/memory/90-decisions/0069-real-autonomy-demo.md +16 -16
- package/memory/90-decisions/0070-mcp-stdio-real.md +11 -11
- package/memory/90-decisions/0071-server-persistence-composition.md +12 -12
- package/memory/90-decisions/0072-sandbox-security-boundaries.md +9 -9
- package/memory/90-decisions/0073-last-mile-rollback-benchmark-plugins.md +17 -17
- package/memory/90-decisions/0077-cost-aware-autonomy-budget.md +95 -0
- package/memory/90-decisions/0078-forjajs-3-engineering-control-plane.md +116 -0
- package/memory/90-decisions/0079-autonomous-maintenance-readiness.md +102 -0
- package/memory/90-decisions/_template.md +28 -28
- package/package.json +157 -157
- package/prompts/context-engineer-agent.md +19 -19
- package/prompts/governance-agent.md +16 -16
- package/prompts/marketing-agent.md +13 -13
- package/prompts/orchestrator-agent.md +18 -18
- package/prompts/product-agent.md +13 -13
- package/prompts/sdd-architect-agent.md +20 -20
- package/specs/README.md +70 -70
- package/specs/_templates/plan.md +43 -43
- package/specs/_templates/spec.md +43 -43
- package/specs/_templates/tasks.md +32 -32
- package/specs/agent-identity-reputation/plan.md +133 -0
- package/specs/agent-identity-reputation/spec.md +125 -0
- package/specs/agent-identity-reputation/tasks.md +51 -0
- package/specs/agent-runtime-monitoring/plan.md +78 -0
- package/specs/agent-runtime-monitoring/spec.md +92 -0
- package/specs/agent-runtime-monitoring/tasks.md +39 -0
- package/specs/ai-code-provenance/plan.md +71 -0
- package/specs/ai-code-provenance/spec.md +97 -0
- package/specs/ai-code-provenance/tasks.md +39 -0
- package/specs/architecture-constitution/plan.md +110 -0
- package/specs/architecture-constitution/spec.md +114 -0
- package/specs/architecture-constitution/tasks.md +58 -0
- package/specs/change-risk-engine/plan.md +130 -0
- package/specs/change-risk-engine/spec.md +119 -0
- package/specs/change-risk-engine/tasks.md +72 -0
- package/specs/clean-arch-boilerplate/plan.md +137 -137
- package/specs/clean-arch-boilerplate/spec.md +121 -121
- package/specs/clean-arch-boilerplate/tasks.md +70 -70
- package/specs/cli-first-operacao/plan.md +53 -53
- package/specs/cli-first-operacao/spec.md +53 -53
- package/specs/cli-first-operacao/tasks.md +53 -53
- package/specs/code-context/spec.md +56 -56
- package/specs/coerencia-do-sistema/plan.md +155 -155
- package/specs/coerencia-do-sistema/spec.md +123 -123
- package/specs/coerencia-do-sistema/tasks.md +115 -115
- package/specs/cost-aware-autonomy-budget/spec.md +102 -0
- package/specs/dev-token-assets-db/plan.md +71 -71
- package/specs/dev-token-assets-db/spec.md +58 -58
- package/specs/dev-token-assets-db/tasks.md +58 -58
- package/specs/doctor-do-nucleo/plan.md +165 -165
- package/specs/doctor-do-nucleo/spec.md +139 -139
- package/specs/doctor-do-nucleo/tasks.md +172 -172
- package/specs/drift-sentinel/spec.md +117 -0
- package/specs/engineer-facade-extension/plan.md +71 -0
- package/specs/engineer-facade-extension/spec.md +98 -0
- package/specs/engineer-facade-extension/tasks.md +36 -0
- package/specs/engineering-evidence-ledger/plan.md +121 -0
- package/specs/engineering-evidence-ledger/spec.md +90 -0
- package/specs/engineering-evidence-ledger/tasks.md +54 -0
- package/specs/engineering-graph-extensions/plan.md +92 -0
- package/specs/engineering-graph-extensions/spec.md +101 -0
- package/specs/engineering-graph-extensions/tasks.md +60 -0
- package/specs/engineering-intelligence/spec.md +177 -0
- package/specs/forja-core/spec.md +71 -71
- package/specs/gates/spec.md +63 -63
- package/specs/governanca-visivel/plan.md +122 -122
- package/specs/governanca-visivel/spec.md +112 -112
- package/specs/governanca-visivel/tasks.md +60 -60
- package/specs/harness-codegraph/spec.md +71 -71
- package/specs/learning-loop-incidents/plan.md +59 -0
- package/specs/learning-loop-incidents/spec.md +93 -0
- package/specs/learning-loop-incidents/tasks.md +36 -0
- package/specs/memory-audit/spec.md +54 -54
- package/specs/orchestrate/spec.md +108 -108
- package/specs/orchestration-coherent/spec.md +95 -95
- package/specs/pipeline-sdd-e-orquestracao/spec.md +61 -61
- package/specs/predictive-change-simulation/plan.md +109 -0
- package/specs/predictive-change-simulation/spec.md +107 -0
- package/specs/predictive-change-simulation/tasks.md +41 -0
- package/specs/project-smoke/spec.md +96 -96
- package/specs/project-upgrade/spec.md +58 -58
- package/specs/reestruturacao-forja-v2/plan.md +95 -95
- package/specs/reestruturacao-forja-v2/spec.md +74 -74
- package/specs/reestruturacao-forja-v2/tasks.md +113 -113
- package/specs/release-auditor-health/spec.md +23 -23
- package/specs/release-gate/plan.md +174 -174
- package/specs/release-gate/spec.md +122 -122
- package/specs/release-gate/tasks.md +183 -183
- package/specs/smart-agent-routing/plan.md +55 -0
- package/specs/smart-agent-routing/spec.md +85 -0
- package/specs/smart-agent-routing/tasks.md +26 -0
- package/specs/ts-migration/plan.md +200 -200
- package/specs/ts-migration/spec.md +119 -119
- package/specs/ts-migration/tasks.md +110 -110
|
@@ -1,105 +1,105 @@
|
|
|
1
|
-
# ADR-0025: Coerência da documentação como gate
|
|
2
|
-
|
|
3
|
-
- **Status**: accepted
|
|
4
|
-
- **Data**: 2026-07-18
|
|
5
|
-
- **Autor(es)**: Allan Pablo
|
|
6
|
-
- **Tags**: governance, docs, harness, diagnostics, registry
|
|
7
|
-
|
|
8
|
-
## Contexto
|
|
9
|
-
|
|
10
|
-
Os ADRs 0023 e 0024 fecharam a classe "erra sem avisar" (ADR-0021) no **núcleo** e no **tarball**.
|
|
11
|
-
Faltava a fronteira mais barata de corromper e a mais cara de perceber: a **palavra escrita**.
|
|
12
|
-
|
|
13
|
-
O Forja é operado por agentes que leem a documentação e executam o que ela manda. Quando a doc e o
|
|
14
|
-
código divergem, o agente não erra por burrice — erra por **obediência**. Uma auditoria manual em
|
|
15
|
-
2026-07-14 encontrou, entre outras coisas:
|
|
16
|
-
|
|
17
|
-
- `docs/token-optimization.md` — o documento que ensina a economia de tokens (ADR-0009) — mandava
|
|
18
|
-
rodar **quatro comandos que não existem** (`context:build`, `memory:db:reindex`, …) e linkava um
|
|
19
|
-
`docs/DEPLOYMENT.md` que nunca existiu.
|
|
20
|
-
- O Governance descrevia `tools:doctor` pela definição anterior ao ADR-0023.
|
|
21
|
-
- Comandos do registry sem menção em lugar nenhum — capacidade obscura é capacidade morta.
|
|
22
|
-
|
|
23
|
-
Nada disso quebrava um teste nem aparecia no `git status`. A correção manual apagou os sintomas do
|
|
24
|
-
dia; nada impedia a reincidência. Toda vez que um comando é renomeado ou um gate muda de contrato, a
|
|
25
|
-
doc pode silenciosamente passar a mentir.
|
|
26
|
-
|
|
27
|
-
## Decisão
|
|
28
|
-
|
|
29
|
-
Três checks novos no catálogo de `health.mjs` (`scope: repo`), sobre um scanner puro
|
|
30
|
-
`lib/core/doc-graph.mjs` que lê os `.md` de instrução como dado:
|
|
31
|
-
|
|
32
|
-
- **`docs-commands`** (critical): todo `forja <cmd>` / `npm run <cmd>` citado numa superfície de
|
|
33
|
-
instrução existe no registry. Comando fantasma faz o agente agir errado — trava.
|
|
34
|
-
- **`commands-documented`** (warn): todo comando do registry é mencionado em ao menos um `.md`.
|
|
35
|
-
- **`docs-links`** (warn): todo link markdown relativo entre arquivos versionados resolve.
|
|
36
|
-
- **`adr-refs`** (warn, adicionado depois): toda citação `ADR-NNNN` em doc/spec/ADR aponta para um
|
|
37
|
-
ADR que existe. Fecha o último invariante que vivia por disciplina ("toda decisão vira ADR") pelo
|
|
38
|
-
lado verificável: referência a decisão inexistente é trilha que apodrece. Pegou o `ADR-0026`
|
|
39
|
-
pendurado (citado pela SPEC-012, nunca escrito) na primeira execução.
|
|
40
|
-
- **`agent-topology`** (warn, SPEC-019): a topologia de orquestração é descrita em três fontes
|
|
41
|
-
(`VALID_AGENTS` do router, `.claude/agents/*.md`, `AGENTS.md`) e pode divergir em silêncio — o
|
|
42
|
-
namesake do framework (orquestração multiagente) vivendo por disciplina. O check cruza as três:
|
|
43
|
-
sub-agent sem rota, papel roteável sem executor, agente não documentado. `user`/`worker` são
|
|
44
|
-
endpoints isentos. Pegou o `release-auditor` (executável, sem rota) na primeira execução. Mesma
|
|
45
|
-
classe dos checks acima, aplicada a quem-orquestra-quem.
|
|
46
|
-
|
|
47
|
-
Princípios:
|
|
48
|
-
|
|
49
|
-
- **Scanner puro, checks finos.** `doc-graph.mjs` lê e devolve dados (`scanCommands`, `scanLinks`,
|
|
50
|
-
`projectCommands`); os checks julgam. Testar o parsing — a parte difícil — não exige montar o
|
|
51
|
-
ambiente do doctor.
|
|
52
|
-
- **Allowlist derivada, jamais literal.** Os comandos do projeto *gerado* (`start:dev`, `test:e2e`,
|
|
53
|
-
`memory:db:*`) não são do Forja e não podem reprovar. A allowlist deriva de **duas** fontes: os
|
|
54
|
-
blocos `"scripts"` inline dos geradores **e** os `package.json` dos boilerplates. Foi `test:e2e`
|
|
55
|
-
— que vive no boilerplate, não no gerador — que provou que uma fonte só produz falso positivo. Uma
|
|
56
|
-
lista manual mente no primeiro comando novo do boilerplate (a lição do `.gitignore`, SPEC-009).
|
|
57
|
-
- **Escopo = instrução, não histórico.** Escaneia `docs/` (menos `archive/`), `prompts/`,
|
|
58
|
-
`.claude/agents/` e os `.md` de raiz. **Fora**: `boilerplates/` (conteúdo do projeto gerado),
|
|
59
|
-
`specs/` e `memory/90-*` (registro histórico — uma spec ou ADR pode legitimamente citar um comando
|
|
60
|
-
proposto ou já removido). O gate protege o que instrui o agente *agora*.
|
|
61
|
-
- **`:` como discriminador de comando.** Cobre 42/42 do registry e nenhuma prosa (`"forja does X"`)
|
|
62
|
-
casa por acidente. Inventar parser de gramática para um comando-sem-`:` inexistente seria criar o
|
|
63
|
-
problema que não temos.
|
|
64
|
-
- **Severidade honesta.** Só `docs-commands` é crítico. Comando não-documentado e link quebrado
|
|
65
|
-
atrapalham, não impedem — `warn`. Um gate que reprova o que não trava é um gate que se aprende a
|
|
66
|
-
ignorar.
|
|
67
|
-
|
|
68
|
-
## Alternativas consideradas
|
|
69
|
-
|
|
70
|
-
- **Manter a auditoria manual** — rejeitada: ela apaga sintomas, não fecha a classe. Reincide na
|
|
71
|
-
próxima renomeação.
|
|
72
|
-
- **Lista literal de comandos do projeto gerado** — rejeitada: é a armadilha do `.gitignore` da
|
|
73
|
-
SPEC-009. Uma lista que não acompanha o gerador vira mentira.
|
|
74
|
-
- **Parsear markdown com um lexer de CommonMark** — rejeitada: peso morto. Precisamos de citações e
|
|
75
|
-
links, não de um AST. Regex + o discriminador `:` bastam.
|
|
76
|
-
- **Gerar a doc a partir do registry** — rejeitada: doc gerada por máquina descreve o *quê*, nunca o
|
|
77
|
-
*porquê*, e o porquê é o que importa. O gate cobra que a explicação exista; não escreve por você.
|
|
78
|
-
- **Escanear `specs/` e `memory/` também** — rejeitada: são registro histórico. Reprovar um ADR por
|
|
79
|
-
citar um comando já removido puniria a memória por lembrar.
|
|
80
|
-
|
|
81
|
-
## Consequências
|
|
82
|
-
|
|
83
|
-
**Positivas**:
|
|
84
|
-
- Renomear um comando vira **ato detectável**: a doc que ficou para trás reprova o CI (o
|
|
85
|
-
`tools:doctor` já é step, ADR-0024) — não espera a próxima auditoria manual.
|
|
86
|
-
- Os quatro comandos-fantasma e os 22 links quebrados da auditoria manual viram zero, verificado a
|
|
87
|
-
cada CI. `memory:extract` (o único órfão) passou a ser documentado.
|
|
88
|
-
- O gate pegou o **próprio autor**: ao corrigir os links, um erro de profundidade relativa
|
|
89
|
-
(`../../` vs `../../../`) foi detectado na hora, antes do commit. É a prova de que ele mede o que
|
|
90
|
-
deve.
|
|
91
|
-
|
|
92
|
-
**Negativas / Trade-offs**:
|
|
93
|
-
- Análise estática conservadora: o `:` como discriminador deixaria escapar um futuro comando sem
|
|
94
|
-
`:`. Aceito — nenhum existe, e falso negativo raro é melhor que falso positivo crítico.
|
|
95
|
-
- Os checks leem todos os `.md` de instrução a cada `tools:doctor`. Barato hoje (< 1s); se crescer,
|
|
96
|
-
vira lazy por mtime. São `scope: repo`, fora do `SessionStart`.
|
|
97
|
-
|
|
98
|
-
## Rastreamento
|
|
99
|
-
|
|
100
|
-
- Implementação: `lib/core/doc-graph.mjs`, `lib/core/health.mjs` (checks `docs-commands`,
|
|
101
|
-
`commands-documented`, `docs-links`), `test/doc-graph.test.js`, `test/health.test.js`
|
|
102
|
-
- Spec: `specs/coerencia-do-sistema/` (SPEC-011)
|
|
103
|
-
- ADRs relacionadas: ADR-0023 (gate do núcleo) e ADR-0024 (gate do tarball) — a mesma família, agora
|
|
104
|
-
na terceira fronteira: a instrução. ADR-0021 (a classe "erra sem avisar"). ADR-0020 (registry como
|
|
105
|
-
fonte da verdade dos comandos).
|
|
1
|
+
# ADR-0025: Coerência da documentação como gate
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Data**: 2026-07-18
|
|
5
|
+
- **Autor(es)**: Allan Pablo
|
|
6
|
+
- **Tags**: governance, docs, harness, diagnostics, registry
|
|
7
|
+
|
|
8
|
+
## Contexto
|
|
9
|
+
|
|
10
|
+
Os ADRs 0023 e 0024 fecharam a classe "erra sem avisar" (ADR-0021) no **núcleo** e no **tarball**.
|
|
11
|
+
Faltava a fronteira mais barata de corromper e a mais cara de perceber: a **palavra escrita**.
|
|
12
|
+
|
|
13
|
+
O Forja é operado por agentes que leem a documentação e executam o que ela manda. Quando a doc e o
|
|
14
|
+
código divergem, o agente não erra por burrice — erra por **obediência**. Uma auditoria manual em
|
|
15
|
+
2026-07-14 encontrou, entre outras coisas:
|
|
16
|
+
|
|
17
|
+
- `docs/token-optimization.md` — o documento que ensina a economia de tokens (ADR-0009) — mandava
|
|
18
|
+
rodar **quatro comandos que não existem** (`context:build`, `memory:db:reindex`, …) e linkava um
|
|
19
|
+
`docs/DEPLOYMENT.md` que nunca existiu.
|
|
20
|
+
- O Governance descrevia `tools:doctor` pela definição anterior ao ADR-0023.
|
|
21
|
+
- Comandos do registry sem menção em lugar nenhum — capacidade obscura é capacidade morta.
|
|
22
|
+
|
|
23
|
+
Nada disso quebrava um teste nem aparecia no `git status`. A correção manual apagou os sintomas do
|
|
24
|
+
dia; nada impedia a reincidência. Toda vez que um comando é renomeado ou um gate muda de contrato, a
|
|
25
|
+
doc pode silenciosamente passar a mentir.
|
|
26
|
+
|
|
27
|
+
## Decisão
|
|
28
|
+
|
|
29
|
+
Três checks novos no catálogo de `health.mjs` (`scope: repo`), sobre um scanner puro
|
|
30
|
+
`lib/core/doc-graph.mjs` que lê os `.md` de instrução como dado:
|
|
31
|
+
|
|
32
|
+
- **`docs-commands`** (critical): todo `forja <cmd>` / `npm run <cmd>` citado numa superfície de
|
|
33
|
+
instrução existe no registry. Comando fantasma faz o agente agir errado — trava.
|
|
34
|
+
- **`commands-documented`** (warn): todo comando do registry é mencionado em ao menos um `.md`.
|
|
35
|
+
- **`docs-links`** (warn): todo link markdown relativo entre arquivos versionados resolve.
|
|
36
|
+
- **`adr-refs`** (warn, adicionado depois): toda citação `ADR-NNNN` em doc/spec/ADR aponta para um
|
|
37
|
+
ADR que existe. Fecha o último invariante que vivia por disciplina ("toda decisão vira ADR") pelo
|
|
38
|
+
lado verificável: referência a decisão inexistente é trilha que apodrece. Pegou o `ADR-0026`
|
|
39
|
+
pendurado (citado pela SPEC-012, nunca escrito) na primeira execução.
|
|
40
|
+
- **`agent-topology`** (warn, SPEC-019): a topologia de orquestração é descrita em três fontes
|
|
41
|
+
(`VALID_AGENTS` do router, `.claude/agents/*.md`, `AGENTS.md`) e pode divergir em silêncio — o
|
|
42
|
+
namesake do framework (orquestração multiagente) vivendo por disciplina. O check cruza as três:
|
|
43
|
+
sub-agent sem rota, papel roteável sem executor, agente não documentado. `user`/`worker` são
|
|
44
|
+
endpoints isentos. Pegou o `release-auditor` (executável, sem rota) na primeira execução. Mesma
|
|
45
|
+
classe dos checks acima, aplicada a quem-orquestra-quem.
|
|
46
|
+
|
|
47
|
+
Princípios:
|
|
48
|
+
|
|
49
|
+
- **Scanner puro, checks finos.** `doc-graph.mjs` lê e devolve dados (`scanCommands`, `scanLinks`,
|
|
50
|
+
`projectCommands`); os checks julgam. Testar o parsing — a parte difícil — não exige montar o
|
|
51
|
+
ambiente do doctor.
|
|
52
|
+
- **Allowlist derivada, jamais literal.** Os comandos do projeto *gerado* (`start:dev`, `test:e2e`,
|
|
53
|
+
`memory:db:*`) não são do Forja e não podem reprovar. A allowlist deriva de **duas** fontes: os
|
|
54
|
+
blocos `"scripts"` inline dos geradores **e** os `package.json` dos boilerplates. Foi `test:e2e`
|
|
55
|
+
— que vive no boilerplate, não no gerador — que provou que uma fonte só produz falso positivo. Uma
|
|
56
|
+
lista manual mente no primeiro comando novo do boilerplate (a lição do `.gitignore`, SPEC-009).
|
|
57
|
+
- **Escopo = instrução, não histórico.** Escaneia `docs/` (menos `archive/`), `prompts/`,
|
|
58
|
+
`.claude/agents/` e os `.md` de raiz. **Fora**: `boilerplates/` (conteúdo do projeto gerado),
|
|
59
|
+
`specs/` e `memory/90-*` (registro histórico — uma spec ou ADR pode legitimamente citar um comando
|
|
60
|
+
proposto ou já removido). O gate protege o que instrui o agente *agora*.
|
|
61
|
+
- **`:` como discriminador de comando.** Cobre 42/42 do registry e nenhuma prosa (`"forja does X"`)
|
|
62
|
+
casa por acidente. Inventar parser de gramática para um comando-sem-`:` inexistente seria criar o
|
|
63
|
+
problema que não temos.
|
|
64
|
+
- **Severidade honesta.** Só `docs-commands` é crítico. Comando não-documentado e link quebrado
|
|
65
|
+
atrapalham, não impedem — `warn`. Um gate que reprova o que não trava é um gate que se aprende a
|
|
66
|
+
ignorar.
|
|
67
|
+
|
|
68
|
+
## Alternativas consideradas
|
|
69
|
+
|
|
70
|
+
- **Manter a auditoria manual** — rejeitada: ela apaga sintomas, não fecha a classe. Reincide na
|
|
71
|
+
próxima renomeação.
|
|
72
|
+
- **Lista literal de comandos do projeto gerado** — rejeitada: é a armadilha do `.gitignore` da
|
|
73
|
+
SPEC-009. Uma lista que não acompanha o gerador vira mentira.
|
|
74
|
+
- **Parsear markdown com um lexer de CommonMark** — rejeitada: peso morto. Precisamos de citações e
|
|
75
|
+
links, não de um AST. Regex + o discriminador `:` bastam.
|
|
76
|
+
- **Gerar a doc a partir do registry** — rejeitada: doc gerada por máquina descreve o *quê*, nunca o
|
|
77
|
+
*porquê*, e o porquê é o que importa. O gate cobra que a explicação exista; não escreve por você.
|
|
78
|
+
- **Escanear `specs/` e `memory/` também** — rejeitada: são registro histórico. Reprovar um ADR por
|
|
79
|
+
citar um comando já removido puniria a memória por lembrar.
|
|
80
|
+
|
|
81
|
+
## Consequências
|
|
82
|
+
|
|
83
|
+
**Positivas**:
|
|
84
|
+
- Renomear um comando vira **ato detectável**: a doc que ficou para trás reprova o CI (o
|
|
85
|
+
`tools:doctor` já é step, ADR-0024) — não espera a próxima auditoria manual.
|
|
86
|
+
- Os quatro comandos-fantasma e os 22 links quebrados da auditoria manual viram zero, verificado a
|
|
87
|
+
cada CI. `memory:extract` (o único órfão) passou a ser documentado.
|
|
88
|
+
- O gate pegou o **próprio autor**: ao corrigir os links, um erro de profundidade relativa
|
|
89
|
+
(`../../` vs `../../../`) foi detectado na hora, antes do commit. É a prova de que ele mede o que
|
|
90
|
+
deve.
|
|
91
|
+
|
|
92
|
+
**Negativas / Trade-offs**:
|
|
93
|
+
- Análise estática conservadora: o `:` como discriminador deixaria escapar um futuro comando sem
|
|
94
|
+
`:`. Aceito — nenhum existe, e falso negativo raro é melhor que falso positivo crítico.
|
|
95
|
+
- Os checks leem todos os `.md` de instrução a cada `tools:doctor`. Barato hoje (< 1s); se crescer,
|
|
96
|
+
vira lazy por mtime. São `scope: repo`, fora do `SessionStart`.
|
|
97
|
+
|
|
98
|
+
## Rastreamento
|
|
99
|
+
|
|
100
|
+
- Implementação: `lib/core/doc-graph.mjs`, `lib/core/health.mjs` (checks `docs-commands`,
|
|
101
|
+
`commands-documented`, `docs-links`), `test/doc-graph.test.js`, `test/health.test.js`
|
|
102
|
+
- Spec: `specs/coerencia-do-sistema/` (SPEC-011)
|
|
103
|
+
- ADRs relacionadas: ADR-0023 (gate do núcleo) e ADR-0024 (gate do tarball) — a mesma família, agora
|
|
104
|
+
na terceira fronteira: a instrução. ADR-0021 (a classe "erra sem avisar"). ADR-0020 (registry como
|
|
105
|
+
fonte da verdade dos comandos).
|
|
@@ -1,66 +1,66 @@
|
|
|
1
|
-
# ADR-0026: Migração TypeScript com runtime duplo (fonte `.ts`, publicado `dist/`)
|
|
2
|
-
|
|
3
|
-
- **Status**: accepted
|
|
4
|
-
- **Data**: 2026-07-19
|
|
5
|
-
- **Autor(es)**: apk
|
|
6
|
-
- **Tags**: typescript, build, runtime, sdd
|
|
7
|
-
|
|
8
|
-
## Contexto
|
|
9
|
-
|
|
10
|
-
A SPEC-012 migrou o framework de `.mjs`/checkJs para TypeScript de verdade. Dois requisitos em
|
|
11
|
-
tensão organizaram todas as decisões:
|
|
12
|
-
|
|
13
|
-
- **NFR inegociável**: o dev roda `sem build`. `node bin/forja.ts <cmd>` tem que funcionar direto,
|
|
14
|
-
ou o loop de desenvolvimento morre.
|
|
15
|
-
- **`engines.node >= 20`**: o pacote publicado precisa rodar em Node 20/21, que **não** executam
|
|
16
|
-
`.ts` (strip-types nativo só existe a partir do Node 22.6).
|
|
17
|
-
|
|
18
|
-
Essas duas verdades não cabem no mesmo artefato: no instante em que a fonte vira `.ts`, um pacote
|
|
19
|
-
publicado sem compilar quebra para quem está em Node 20.
|
|
20
|
-
|
|
21
|
-
## Decisão
|
|
22
|
-
|
|
23
|
-
**Runtime duplo, resolvido por um único ponto.**
|
|
24
|
-
|
|
25
|
-
1. **D1 — Layout plano, `dist/` espelha a árvore.** `tsc rootDir=. outDir=dist` → `dist/bin`,
|
|
26
|
-
`dist/lib`, `dist/scripts`. Não movemos a fonte para `src/`: trocaria todo import, path de
|
|
27
|
-
registry e hook — blast radius enorme, contra o "verde contínuo".
|
|
28
|
-
2. **D2 — Registry + `resolveScript` (o coração).** O registry nomeia os scripts; o `resolveScript`
|
|
29
|
-
tenta as extensões na ordem `['.ts', '.js', '.mjs']`, fazendo strip da extensão declarada. Em dev
|
|
30
|
-
acha o `.ts`; no publicado acha o `dist/*.js`. Um resolver, dois mundos — sem dois registries
|
|
31
|
-
(a divergência que a SPEC-009 matou).
|
|
32
|
-
3. **D3 — Dual runtime.** Dev roda `.ts` nativo (Node ≥22.6, exigência de contribuir); o publicado
|
|
33
|
-
embarca `dist/*.js` (Node ≥20). O acoplamento de Node-floor vive só na fronteira do publicado.
|
|
34
|
-
4. **D4 (revisado) — o gate constrói o `dist/`.** O `release:check` roda `npm run build` **antes de
|
|
35
|
-
empacotar** (quando `files[]` inclui `dist/`). Como `npm publish` empacota o disco e o gate
|
|
36
|
-
empacota o mesmo disco recém-buildado, o tarball provado é o publicado — sem `dist/` no git, sem
|
|
37
|
-
step de build no `ci.yml`, sem janela de staleness. O gate é self-contained.
|
|
38
|
-
5. **D9 — publicar `dist/` desde sempre desacopla o risco.** Enquanto a fonte ainda era `.mjs`, o
|
|
39
|
-
build era uma cópia; quando virou `.ts`, virou compilação. Em ambos os casos o publicado é JS
|
|
40
|
-
runnable, então o `.ts`-não-roda-em-Node-20 nunca morde o usuário final.
|
|
41
|
-
|
|
42
|
-
## Alternativas consideradas
|
|
43
|
-
|
|
44
|
-
- **Guardar `.js` compilado no git e exigir build em dev** — rejeitada: mata o NFR "roda sem build".
|
|
45
|
-
- **Publicar a fonte `.ts` crua** — rejeitada: quebra em Node 20/21; o `release:check` reprovaria.
|
|
46
|
-
- **Dois registries (dev/publicado)** — rejeitada: duas verdades que divergem (defeito da SPEC-009).
|
|
47
|
-
- **Mover a fonte para `src/`** — rejeitada: blast radius desproporcional para ganho estético.
|
|
48
|
-
|
|
49
|
-
## Consequências
|
|
50
|
-
|
|
51
|
-
**Positivas**:
|
|
52
|
-
- Dev roda `.ts` nativo, zero build; usuário final roda `dist/*.js`, Node ≥20. Cada um paga só o seu.
|
|
53
|
-
- Uma máquina (`resolveScript`) resolve os dois mundos; o gate prova o tarball real.
|
|
54
|
-
- `noImplicitAny` ligado ao fim: o ratchet força todo código futuro a ser tipado.
|
|
55
|
-
|
|
56
|
-
**Negativas / Trade-offs**:
|
|
57
|
-
- Contribuir passa a exigir Node ≥22.6; o job `test` do CI cai fora do Node 20 (o suporte a 20 do
|
|
58
|
-
publicado é provado pelo `release-gate`, que instala o tarball `.js`).
|
|
59
|
-
- O `resolveScript` carrega três extensões por dívida histórica (`.mjs` legado) — barato, mas é
|
|
60
|
-
estado que um dia se limpa.
|
|
61
|
-
|
|
62
|
-
## Rastreamento
|
|
63
|
-
- Spec: `specs/ts-migration/` (SPEC-012)
|
|
64
|
-
- Implementação: `lib/core/registry.ts` (resolveScript), `lib/core/release.ts` (gate builda),
|
|
65
|
-
`tsconfig.json` / `tsconfig.build.json`, `.github/workflows/ci.yml`
|
|
66
|
-
- ADRs relacionadas: ADR-0021 (NFR "roda sem build"; classe "dist mente"), ADR-0024 (gate do tarball)
|
|
1
|
+
# ADR-0026: Migração TypeScript com runtime duplo (fonte `.ts`, publicado `dist/`)
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Data**: 2026-07-19
|
|
5
|
+
- **Autor(es)**: apk
|
|
6
|
+
- **Tags**: typescript, build, runtime, sdd
|
|
7
|
+
|
|
8
|
+
## Contexto
|
|
9
|
+
|
|
10
|
+
A SPEC-012 migrou o framework de `.mjs`/checkJs para TypeScript de verdade. Dois requisitos em
|
|
11
|
+
tensão organizaram todas as decisões:
|
|
12
|
+
|
|
13
|
+
- **NFR inegociável**: o dev roda `sem build`. `node bin/forja.ts <cmd>` tem que funcionar direto,
|
|
14
|
+
ou o loop de desenvolvimento morre.
|
|
15
|
+
- **`engines.node >= 20`**: o pacote publicado precisa rodar em Node 20/21, que **não** executam
|
|
16
|
+
`.ts` (strip-types nativo só existe a partir do Node 22.6).
|
|
17
|
+
|
|
18
|
+
Essas duas verdades não cabem no mesmo artefato: no instante em que a fonte vira `.ts`, um pacote
|
|
19
|
+
publicado sem compilar quebra para quem está em Node 20.
|
|
20
|
+
|
|
21
|
+
## Decisão
|
|
22
|
+
|
|
23
|
+
**Runtime duplo, resolvido por um único ponto.**
|
|
24
|
+
|
|
25
|
+
1. **D1 — Layout plano, `dist/` espelha a árvore.** `tsc rootDir=. outDir=dist` → `dist/bin`,
|
|
26
|
+
`dist/lib`, `dist/scripts`. Não movemos a fonte para `src/`: trocaria todo import, path de
|
|
27
|
+
registry e hook — blast radius enorme, contra o "verde contínuo".
|
|
28
|
+
2. **D2 — Registry + `resolveScript` (o coração).** O registry nomeia os scripts; o `resolveScript`
|
|
29
|
+
tenta as extensões na ordem `['.ts', '.js', '.mjs']`, fazendo strip da extensão declarada. Em dev
|
|
30
|
+
acha o `.ts`; no publicado acha o `dist/*.js`. Um resolver, dois mundos — sem dois registries
|
|
31
|
+
(a divergência que a SPEC-009 matou).
|
|
32
|
+
3. **D3 — Dual runtime.** Dev roda `.ts` nativo (Node ≥22.6, exigência de contribuir); o publicado
|
|
33
|
+
embarca `dist/*.js` (Node ≥20). O acoplamento de Node-floor vive só na fronteira do publicado.
|
|
34
|
+
4. **D4 (revisado) — o gate constrói o `dist/`.** O `release:check` roda `npm run build` **antes de
|
|
35
|
+
empacotar** (quando `files[]` inclui `dist/`). Como `npm publish` empacota o disco e o gate
|
|
36
|
+
empacota o mesmo disco recém-buildado, o tarball provado é o publicado — sem `dist/` no git, sem
|
|
37
|
+
step de build no `ci.yml`, sem janela de staleness. O gate é self-contained.
|
|
38
|
+
5. **D9 — publicar `dist/` desde sempre desacopla o risco.** Enquanto a fonte ainda era `.mjs`, o
|
|
39
|
+
build era uma cópia; quando virou `.ts`, virou compilação. Em ambos os casos o publicado é JS
|
|
40
|
+
runnable, então o `.ts`-não-roda-em-Node-20 nunca morde o usuário final.
|
|
41
|
+
|
|
42
|
+
## Alternativas consideradas
|
|
43
|
+
|
|
44
|
+
- **Guardar `.js` compilado no git e exigir build em dev** — rejeitada: mata o NFR "roda sem build".
|
|
45
|
+
- **Publicar a fonte `.ts` crua** — rejeitada: quebra em Node 20/21; o `release:check` reprovaria.
|
|
46
|
+
- **Dois registries (dev/publicado)** — rejeitada: duas verdades que divergem (defeito da SPEC-009).
|
|
47
|
+
- **Mover a fonte para `src/`** — rejeitada: blast radius desproporcional para ganho estético.
|
|
48
|
+
|
|
49
|
+
## Consequências
|
|
50
|
+
|
|
51
|
+
**Positivas**:
|
|
52
|
+
- Dev roda `.ts` nativo, zero build; usuário final roda `dist/*.js`, Node ≥20. Cada um paga só o seu.
|
|
53
|
+
- Uma máquina (`resolveScript`) resolve os dois mundos; o gate prova o tarball real.
|
|
54
|
+
- `noImplicitAny` ligado ao fim: o ratchet força todo código futuro a ser tipado.
|
|
55
|
+
|
|
56
|
+
**Negativas / Trade-offs**:
|
|
57
|
+
- Contribuir passa a exigir Node ≥22.6; o job `test` do CI cai fora do Node 20 (o suporte a 20 do
|
|
58
|
+
publicado é provado pelo `release-gate`, que instala o tarball `.js`).
|
|
59
|
+
- O `resolveScript` carrega três extensões por dívida histórica (`.mjs` legado) — barato, mas é
|
|
60
|
+
estado que um dia se limpa.
|
|
61
|
+
|
|
62
|
+
## Rastreamento
|
|
63
|
+
- Spec: `specs/ts-migration/` (SPEC-012)
|
|
64
|
+
- Implementação: `lib/core/registry.ts` (resolveScript), `lib/core/release.ts` (gate builda),
|
|
65
|
+
`tsconfig.json` / `tsconfig.build.json`, `.github/workflows/ci.yml`
|
|
66
|
+
- ADRs relacionadas: ADR-0021 (NFR "roda sem build"; classe "dist mente"), ADR-0024 (gate do tarball)
|
|
@@ -1,127 +1,127 @@
|
|
|
1
|
-
# ADR-0027: Boilerplate Clean Architecture calibrada
|
|
2
|
-
|
|
3
|
-
- **Status**: accepted
|
|
4
|
-
- **Data**: 2026-07-18
|
|
5
|
-
- **Autor(es)**: Allan Pablo
|
|
6
|
-
- **Tags**: boilerplate, ddd, clean-architecture, token-economy
|
|
7
|
-
|
|
8
|
-
## Contexto
|
|
9
|
-
|
|
10
|
-
Os boilerplates do Forja eram NestJS-flat: o `service` fala direto com a entity do ORM, a regra de
|
|
11
|
-
negócio fica diluída no service acoplada ao framework. Dois preços — manutenção (testar regra exige
|
|
12
|
-
subir o Nest; trocar ORM é cirurgia) e **tokens** (ADR-0009): um agente precisa ler a implementação
|
|
13
|
-
inteira para entender uma feature, porque não há contrato legível separado da execução.
|
|
14
|
-
|
|
15
|
-
A resposta ingênua — "aplicar Clean Architecture" — tem o preço oposto: quatro camadas para um CRUD
|
|
16
|
-
são mais arquivos para ler, não menos. Cargo-cult de arquitetura é o anti-padrão de token com nome
|
|
17
|
-
bonito.
|
|
18
|
-
|
|
19
|
-
## Decisão
|
|
20
|
-
|
|
21
|
-
Um boilerplate (`boilerplates/06-clean-arch`) que demonstra **os dois padrões lado a lado**:
|
|
22
|
-
|
|
23
|
-
- **Fatia rica (Orders)**: 4 camadas (domain / application / infrastructure / presentation) com
|
|
24
|
-
inversão de dependência. Invariantes de negócio (não envia sem pagamento; total derivado; máquina
|
|
25
|
-
de estados) vivem no domínio, em TypeScript puro — **zero `@nestjs`, zero ORM**. Testáveis sem
|
|
26
|
-
subir o Nest.
|
|
27
|
-
- **Caminho enxuto (Products)**: CRUD numa camada, controller→repo direto, sem use-case nem porta.
|
|
28
|
-
- **`WHEN-CLEAN-WHEN-LEAN.md`**: o critério de qual padrão usar. É o coração — a calibração é a
|
|
29
|
-
decisão, não as camadas.
|
|
30
|
-
- **Memória por bounded context** (`memory/30-domains/<ctx>/context.md`): a linguagem ubíqua que o
|
|
31
|
-
agente lê antes do código.
|
|
32
|
-
|
|
33
|
-
Inversão via DI do Nest: a porta é `interface` no domínio + token; o adapter a implementa; o módulo
|
|
34
|
-
faz o bind numa linha. O domínio e a aplicação não sabem que TypeORM existe.
|
|
35
|
-
|
|
36
|
-
## A medição de token — honesta (o que a spec exigiu)
|
|
37
|
-
|
|
38
|
-
A SPEC-013 fez da economia de token a métrica-norte e mandou **reconhecer se não cair, não maquiar**.
|
|
39
|
-
Então:
|
|
40
|
-
|
|
41
|
-
Medida crua (bytes/4) do custo de "ler o domínio para editar uma regra":
|
|
42
|
-
|
|
43
|
-
| | tokens aprox. |
|
|
44
|
-
|---|---|
|
|
45
|
-
| Clean-arch: `context.md` (476) + `order.entity.ts` (690) | **~1167** |
|
|
46
|
-
| Flat 02-saas: `billing.service.ts` (486) + `invoice.entity.ts` (244) | **~730** |
|
|
47
|
-
|
|
48
|
-
**Na contagem crua, Clean-arch não ganha — é maior.** E a comparação é injusta: o domínio de Orders
|
|
49
|
-
tem máquina de estados e invariantes reais; o service de billing é fino. Estamos comparando lógica
|
|
50
|
-
rica com lógica pobre, não arquitetura com arquitetura.
|
|
51
|
-
|
|
52
|
-
**Onde o benefício de token realmente está** (e o que a medida crua não captura):
|
|
53
|
-
|
|
54
|
-
1. **Localização.** Para editar uma regra em Clean-arch, o agente lê o `context.md` (que aponta
|
|
55
|
-
"a regra está em `order.entity.ts`") e o agregado — e **não carrega** infraestrutura, controller
|
|
56
|
-
nem use-cases. No flat, a regra está no service misturada a acesso a dados; para ter certeza de
|
|
57
|
-
achar toda a lógica, o agente varre mais.
|
|
58
|
-
2. **O `context.md` como mapa.** 476 tokens lidos primeiro que substituem exploração. No flat não há
|
|
59
|
-
mapa: o agente greps/lê para descobrir onde a regra vive.
|
|
60
|
-
3. **Ler assinatura, não implementação.** Para *entender* (não editar), o `context.md` + a assinatura
|
|
61
|
-
do use-case bastam; no flat, lê-se o service.
|
|
62
|
-
|
|
63
|
-
**Conclusão honesta**: o ganho é **navegacional** (não recarregar código não-relacionado + o mapa),
|
|
64
|
-
não de tamanho de arquivo. A medida crua feita aqui é um proxy fraco e **não prova** a economia. A
|
|
65
|
-
prova rigorosa precisa do benchmark sobre uma **mesma tarefa**, com a mesma feature nas duas
|
|
66
|
-
arquiteturas — o boilerplate flat não tinha um equivalente rico ao Order, então ficou como follow-up.
|
|
67
|
-
|
|
68
|
-
### Follow-up resolvido — o benchmark same-feature (`forja token:economy`)
|
|
69
|
-
|
|
70
|
-
A dívida acima foi fechada: existe um `benchmarks/clean-vs-flat/orders-flat/` (a MESMA feature —
|
|
71
|
-
place + ship + "não envia sem pagamento" — no estilo flat) e o comando `token:economy` mede **dois
|
|
72
|
-
eixos**, porque a economia de token do Forja tem dois eixos e eles são diferentes:
|
|
73
|
-
|
|
74
|
-
**Eixo 1 — arquitetura (clean vs flat).** Desmente a versão ingênua da claim:
|
|
75
|
-
|
|
76
|
-
| Cenário | Clean | Flat | Clean vs flat |
|
|
77
|
-
|---|---|---|---|
|
|
78
|
-
| Entender a feature inteira | ~3684 tok (12 arq.) | ~1298 tok (3 arq.) | **+184%** |
|
|
79
|
-
| Mudar a regra de envio (contexto mínimo) | ~1419 tok (3 arq.) | ~910 tok (1 arq.) | **+56%** |
|
|
80
|
-
|
|
81
|
-
Para uma feature pequena, **o clean-arch custa MAIS tokens** — inclusive na mudança localizada. A
|
|
82
|
-
camada cobra adiantado e, com dois casos de uso, não se paga. **A justificativa de `orders` em
|
|
83
|
-
camadas passa a ser isolamento e testabilidade, não token.**
|
|
84
|
-
|
|
85
|
-
**Eixo 2 — memória (frio vs quente).** É aqui que a economia real do framework mora (ADR-0009):
|
|
86
|
-
|
|
87
|
-
| Cenário | Quente (com `context.md`) | Frio (sem mapa) | Economia |
|
|
88
|
-
|---|---|---|---|
|
|
89
|
-
| Localizar e mexer numa regra da fatia | ~1419 tok (3 arq.) | ~3684 tok (12 arq.) | **−61%** |
|
|
90
|
-
|
|
91
|
-
O `context.md` é o mapa: com ele, o agente vai direto ao agregado + à máquina de estados; sem ele,
|
|
92
|
-
varre a fatia inteira para descobrir onde a regra vive. **E essa economia COMPÕE**: gerar do zero é
|
|
93
|
-
custo único (o scaffold), mas o mapa poupa a cada tarefa futura, pela vida do projeto. O
|
|
94
|
-
`token:economy` não mede o custo de gerar — mede o regime permanente, depois do projeto levantado.
|
|
95
|
-
|
|
96
|
-
Conclusão corrigida: a economia de token do Forja **não é das camadas — é da memória persistente**,
|
|
97
|
-
amortizada no tempo. As camadas se pagam só a partir de certa escala (tamanho da feature × nº de
|
|
98
|
-
casos de uso); a memória se paga desde a segunda tarefa. Tudo reproduzível: `forja token:economy`.
|
|
99
|
-
|
|
100
|
-
## Alternativas consideradas
|
|
101
|
-
|
|
102
|
-
- **Clean Architecture em tudo** — rejeitada: é o cargo-cult que a calibração existe para evitar. O
|
|
103
|
-
`WHEN-CLEAN-WHEN-LEAN.md` + o Products enxuto são o guardrail.
|
|
104
|
-
- **Clean Architecture no framework Forja** — rejeitada (fora do escopo da SPEC-013): over-engineering
|
|
105
|
-
para um CLI. O framework ganha só modelos de domínio tipados, ride na migração TS (SPEC-012).
|
|
106
|
-
- **Refatorar os boilerplates 01-05** — rejeitada: aditivo, não migração. Os flat servem o CRUD.
|
|
107
|
-
|
|
108
|
-
## Consequências
|
|
109
|
-
|
|
110
|
-
**Positivas**:
|
|
111
|
-
- Um esqueleto onde a regra de negócio é isolada, testável sem framework, e sobrevive a troca de ORM.
|
|
112
|
-
- A calibração é **visível em código** (Orders rico vs. Products enxuto), não só documentada.
|
|
113
|
-
- O guardrail contra token-bloat é explícito e reprovável (o Products *tem* que ser 1 camada).
|
|
114
|
-
|
|
115
|
-
**Negativas / Trade-offs**:
|
|
116
|
-
- A economia de token **não está provada** — está argumentada (navegacional) e medida cruamente com
|
|
117
|
-
resultado inconclusivo. O benchmark real é follow-up. Registrar isto é a honestidade que a spec
|
|
118
|
-
cobrou; claim de vitória não-medida seria maquiar.
|
|
119
|
-
- Mais conceitos para o dev absorver na fatia rica. Mitigado: uma fatia rica só; o resto enxuto.
|
|
120
|
-
|
|
121
|
-
## Rastreamento
|
|
122
|
-
|
|
123
|
-
- Implementação: `boilerplates/06-clean-arch/`
|
|
124
|
-
- Spec: `specs/clean-arch-boilerplate/` (SPEC-013)
|
|
125
|
-
- ADRs relacionadas: ADR-0009 (economia de tokens — a métrica-norte), ADR-0001 (memória por contexto),
|
|
126
|
-
ADR-0016 (harness), SPEC-012 (TS — o domínio tipado)
|
|
127
|
-
- **Follow-up**: benchmark `context:smart` de uma tarefa-tipo, mesma feature nas duas arquiteturas.
|
|
1
|
+
# ADR-0027: Boilerplate Clean Architecture calibrada
|
|
2
|
+
|
|
3
|
+
- **Status**: accepted
|
|
4
|
+
- **Data**: 2026-07-18
|
|
5
|
+
- **Autor(es)**: Allan Pablo
|
|
6
|
+
- **Tags**: boilerplate, ddd, clean-architecture, token-economy
|
|
7
|
+
|
|
8
|
+
## Contexto
|
|
9
|
+
|
|
10
|
+
Os boilerplates do Forja eram NestJS-flat: o `service` fala direto com a entity do ORM, a regra de
|
|
11
|
+
negócio fica diluída no service acoplada ao framework. Dois preços — manutenção (testar regra exige
|
|
12
|
+
subir o Nest; trocar ORM é cirurgia) e **tokens** (ADR-0009): um agente precisa ler a implementação
|
|
13
|
+
inteira para entender uma feature, porque não há contrato legível separado da execução.
|
|
14
|
+
|
|
15
|
+
A resposta ingênua — "aplicar Clean Architecture" — tem o preço oposto: quatro camadas para um CRUD
|
|
16
|
+
são mais arquivos para ler, não menos. Cargo-cult de arquitetura é o anti-padrão de token com nome
|
|
17
|
+
bonito.
|
|
18
|
+
|
|
19
|
+
## Decisão
|
|
20
|
+
|
|
21
|
+
Um boilerplate (`boilerplates/06-clean-arch`) que demonstra **os dois padrões lado a lado**:
|
|
22
|
+
|
|
23
|
+
- **Fatia rica (Orders)**: 4 camadas (domain / application / infrastructure / presentation) com
|
|
24
|
+
inversão de dependência. Invariantes de negócio (não envia sem pagamento; total derivado; máquina
|
|
25
|
+
de estados) vivem no domínio, em TypeScript puro — **zero `@nestjs`, zero ORM**. Testáveis sem
|
|
26
|
+
subir o Nest.
|
|
27
|
+
- **Caminho enxuto (Products)**: CRUD numa camada, controller→repo direto, sem use-case nem porta.
|
|
28
|
+
- **`WHEN-CLEAN-WHEN-LEAN.md`**: o critério de qual padrão usar. É o coração — a calibração é a
|
|
29
|
+
decisão, não as camadas.
|
|
30
|
+
- **Memória por bounded context** (`memory/30-domains/<ctx>/context.md`): a linguagem ubíqua que o
|
|
31
|
+
agente lê antes do código.
|
|
32
|
+
|
|
33
|
+
Inversão via DI do Nest: a porta é `interface` no domínio + token; o adapter a implementa; o módulo
|
|
34
|
+
faz o bind numa linha. O domínio e a aplicação não sabem que TypeORM existe.
|
|
35
|
+
|
|
36
|
+
## A medição de token — honesta (o que a spec exigiu)
|
|
37
|
+
|
|
38
|
+
A SPEC-013 fez da economia de token a métrica-norte e mandou **reconhecer se não cair, não maquiar**.
|
|
39
|
+
Então:
|
|
40
|
+
|
|
41
|
+
Medida crua (bytes/4) do custo de "ler o domínio para editar uma regra":
|
|
42
|
+
|
|
43
|
+
| | tokens aprox. |
|
|
44
|
+
|---|---|
|
|
45
|
+
| Clean-arch: `context.md` (476) + `order.entity.ts` (690) | **~1167** |
|
|
46
|
+
| Flat 02-saas: `billing.service.ts` (486) + `invoice.entity.ts` (244) | **~730** |
|
|
47
|
+
|
|
48
|
+
**Na contagem crua, Clean-arch não ganha — é maior.** E a comparação é injusta: o domínio de Orders
|
|
49
|
+
tem máquina de estados e invariantes reais; o service de billing é fino. Estamos comparando lógica
|
|
50
|
+
rica com lógica pobre, não arquitetura com arquitetura.
|
|
51
|
+
|
|
52
|
+
**Onde o benefício de token realmente está** (e o que a medida crua não captura):
|
|
53
|
+
|
|
54
|
+
1. **Localização.** Para editar uma regra em Clean-arch, o agente lê o `context.md` (que aponta
|
|
55
|
+
"a regra está em `order.entity.ts`") e o agregado — e **não carrega** infraestrutura, controller
|
|
56
|
+
nem use-cases. No flat, a regra está no service misturada a acesso a dados; para ter certeza de
|
|
57
|
+
achar toda a lógica, o agente varre mais.
|
|
58
|
+
2. **O `context.md` como mapa.** 476 tokens lidos primeiro que substituem exploração. No flat não há
|
|
59
|
+
mapa: o agente greps/lê para descobrir onde a regra vive.
|
|
60
|
+
3. **Ler assinatura, não implementação.** Para *entender* (não editar), o `context.md` + a assinatura
|
|
61
|
+
do use-case bastam; no flat, lê-se o service.
|
|
62
|
+
|
|
63
|
+
**Conclusão honesta**: o ganho é **navegacional** (não recarregar código não-relacionado + o mapa),
|
|
64
|
+
não de tamanho de arquivo. A medida crua feita aqui é um proxy fraco e **não prova** a economia. A
|
|
65
|
+
prova rigorosa precisa do benchmark sobre uma **mesma tarefa**, com a mesma feature nas duas
|
|
66
|
+
arquiteturas — o boilerplate flat não tinha um equivalente rico ao Order, então ficou como follow-up.
|
|
67
|
+
|
|
68
|
+
### Follow-up resolvido — o benchmark same-feature (`forja token:economy`)
|
|
69
|
+
|
|
70
|
+
A dívida acima foi fechada: existe um `benchmarks/clean-vs-flat/orders-flat/` (a MESMA feature —
|
|
71
|
+
place + ship + "não envia sem pagamento" — no estilo flat) e o comando `token:economy` mede **dois
|
|
72
|
+
eixos**, porque a economia de token do Forja tem dois eixos e eles são diferentes:
|
|
73
|
+
|
|
74
|
+
**Eixo 1 — arquitetura (clean vs flat).** Desmente a versão ingênua da claim:
|
|
75
|
+
|
|
76
|
+
| Cenário | Clean | Flat | Clean vs flat |
|
|
77
|
+
|---|---|---|---|
|
|
78
|
+
| Entender a feature inteira | ~3684 tok (12 arq.) | ~1298 tok (3 arq.) | **+184%** |
|
|
79
|
+
| Mudar a regra de envio (contexto mínimo) | ~1419 tok (3 arq.) | ~910 tok (1 arq.) | **+56%** |
|
|
80
|
+
|
|
81
|
+
Para uma feature pequena, **o clean-arch custa MAIS tokens** — inclusive na mudança localizada. A
|
|
82
|
+
camada cobra adiantado e, com dois casos de uso, não se paga. **A justificativa de `orders` em
|
|
83
|
+
camadas passa a ser isolamento e testabilidade, não token.**
|
|
84
|
+
|
|
85
|
+
**Eixo 2 — memória (frio vs quente).** É aqui que a economia real do framework mora (ADR-0009):
|
|
86
|
+
|
|
87
|
+
| Cenário | Quente (com `context.md`) | Frio (sem mapa) | Economia |
|
|
88
|
+
|---|---|---|---|
|
|
89
|
+
| Localizar e mexer numa regra da fatia | ~1419 tok (3 arq.) | ~3684 tok (12 arq.) | **−61%** |
|
|
90
|
+
|
|
91
|
+
O `context.md` é o mapa: com ele, o agente vai direto ao agregado + à máquina de estados; sem ele,
|
|
92
|
+
varre a fatia inteira para descobrir onde a regra vive. **E essa economia COMPÕE**: gerar do zero é
|
|
93
|
+
custo único (o scaffold), mas o mapa poupa a cada tarefa futura, pela vida do projeto. O
|
|
94
|
+
`token:economy` não mede o custo de gerar — mede o regime permanente, depois do projeto levantado.
|
|
95
|
+
|
|
96
|
+
Conclusão corrigida: a economia de token do Forja **não é das camadas — é da memória persistente**,
|
|
97
|
+
amortizada no tempo. As camadas se pagam só a partir de certa escala (tamanho da feature × nº de
|
|
98
|
+
casos de uso); a memória se paga desde a segunda tarefa. Tudo reproduzível: `forja token:economy`.
|
|
99
|
+
|
|
100
|
+
## Alternativas consideradas
|
|
101
|
+
|
|
102
|
+
- **Clean Architecture em tudo** — rejeitada: é o cargo-cult que a calibração existe para evitar. O
|
|
103
|
+
`WHEN-CLEAN-WHEN-LEAN.md` + o Products enxuto são o guardrail.
|
|
104
|
+
- **Clean Architecture no framework Forja** — rejeitada (fora do escopo da SPEC-013): over-engineering
|
|
105
|
+
para um CLI. O framework ganha só modelos de domínio tipados, ride na migração TS (SPEC-012).
|
|
106
|
+
- **Refatorar os boilerplates 01-05** — rejeitada: aditivo, não migração. Os flat servem o CRUD.
|
|
107
|
+
|
|
108
|
+
## Consequências
|
|
109
|
+
|
|
110
|
+
**Positivas**:
|
|
111
|
+
- Um esqueleto onde a regra de negócio é isolada, testável sem framework, e sobrevive a troca de ORM.
|
|
112
|
+
- A calibração é **visível em código** (Orders rico vs. Products enxuto), não só documentada.
|
|
113
|
+
- O guardrail contra token-bloat é explícito e reprovável (o Products *tem* que ser 1 camada).
|
|
114
|
+
|
|
115
|
+
**Negativas / Trade-offs**:
|
|
116
|
+
- A economia de token **não está provada** — está argumentada (navegacional) e medida cruamente com
|
|
117
|
+
resultado inconclusivo. O benchmark real é follow-up. Registrar isto é a honestidade que a spec
|
|
118
|
+
cobrou; claim de vitória não-medida seria maquiar.
|
|
119
|
+
- Mais conceitos para o dev absorver na fatia rica. Mitigado: uma fatia rica só; o resto enxuto.
|
|
120
|
+
|
|
121
|
+
## Rastreamento
|
|
122
|
+
|
|
123
|
+
- Implementação: `boilerplates/06-clean-arch/`
|
|
124
|
+
- Spec: `specs/clean-arch-boilerplate/` (SPEC-013)
|
|
125
|
+
- ADRs relacionadas: ADR-0009 (economia de tokens — a métrica-norte), ADR-0001 (memória por contexto),
|
|
126
|
+
ADR-0016 (harness), SPEC-012 (TS — o domínio tipado)
|
|
127
|
+
- **Follow-up**: benchmark `context:smart` de uma tarefa-tipo, mesma feature nas duas arquiteturas.
|