forjajs 2.0.3 → 2.0.4
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 +68 -59
- 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 +134 -134
- package/CHANGELOG.md +566 -550
- package/CONTRIBUTING.md +32 -32
- package/DOC-MAP.md +65 -60
- package/LICENSE +21 -21
- package/README.md +358 -339
- package/README.pt-BR.md +345 -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/dashboard-client.jsx +10 -10
- package/dist/bin/create-memory-nest-kit.js +17 -17
- package/dist/bin/forja.js +14 -2
- package/dist/bin/init-project.js +38 -38
- package/dist/lib/audit.js +7 -7
- package/dist/lib/context-builder.js +32 -32
- package/dist/lib/core/doc-graph.js +6 -4
- package/dist/lib/core/registry.d.ts +54 -0
- package/dist/lib/core/registry.js +55 -0
- package/dist/lib/core/release.d.ts +53 -0
- package/dist/lib/core/release.js +5 -1
- package/dist/lib/generators/memory-generator.js +700 -698
- package/dist/lib/generators/nest-generator.js +398 -398
- package/dist/lib/generators/readme-generator.js +180 -180
- package/dist/lib/governance-report.js +39 -39
- package/dist/lib/project-upgrade.js +1 -1
- package/dist/lib/workspace.d.ts +7 -0
- package/dist/lib/workspace.js +63 -34
- package/dist/packages/adapter-sqlite/src/index.js +12 -12
- package/dist/packages/llm/src/index.d.ts +43 -0
- package/dist/packages/llm/src/index.js +108 -0
- package/dist/scripts/agent-harness.js +66 -64
- package/dist/scripts/agent-router.js +20 -20
- 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/demo-autonomy.js +2 -2
- package/dist/scripts/demo-workspace.d.ts +6 -0
- package/dist/scripts/demo-workspace.js +101 -0
- package/dist/scripts/dev.js +13 -13
- package/dist/scripts/extract-global-knowledge.js +5 -5
- package/dist/scripts/generate-dashboard.js +11 -11
- package/dist/scripts/llm-fit.js +131 -0
- package/dist/scripts/memory-schema.js +48 -48
- package/dist/scripts/query-universal-memory.js +13 -13
- package/dist/scripts/sprint-manager.js +39 -39
- package/dist/scripts/sync-universal-memory.js +63 -50
- 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/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/llm-fit-loop.md +41 -0
- package/docs/manual-operacional-cli-sdd-gsd.md +1014 -1014
- package/docs/modos-de-operacao.md +52 -0
- 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/produto/factsheet-marketing.md +151 -0
- package/docs/produto/roteiro-demo.md +47 -0
- 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 +23 -26
- 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/0074-llm-fit-loop-cli-adapters.md +51 -0
- package/memory/90-decisions/0075-workspace-demo-isolado.md +43 -0
- package/memory/90-decisions/0076-modos-embedded-e-studio.md +43 -0
- package/memory/90-decisions/_template.md +28 -28
- package/package.json +157 -150
- 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/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/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/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/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/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/plan.md +88 -0
- package/specs/release-auditor-health/spec.md +82 -0
- package/specs/release-auditor-health/tasks.md +72 -0
- 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/ts-migration/plan.md +200 -200
- package/specs/ts-migration/spec.md +119 -119
- package/specs/ts-migration/tasks.md +110 -110
- package/dist/scripts/server-persistence-probe.d.ts +0 -1
- package/dist/scripts/server-persistence-probe.js +0 -52
- package/dist/scripts/server-persistence-probe.mjs +0 -52
- /package/dist/scripts/{server-persistence-probe.d.mts → llm-fit.d.ts} +0 -0
|
@@ -1,155 +1,155 @@
|
|
|
1
|
-
# Plan: coerencia-do-sistema
|
|
2
|
-
|
|
3
|
-
- **Spec**: ./spec.md
|
|
4
|
-
- **Status**: done
|
|
5
|
-
- **Criado em**: 2026-07-15
|
|
6
|
-
|
|
7
|
-
> Como vamos construir o que a spec define. Sem código aqui — só estrutura e decisões.
|
|
8
|
-
|
|
9
|
-
## 1. Abordagem técnica
|
|
10
|
-
|
|
11
|
-
Três checks novos no catálogo de `health.mjs`, no molde dos que já existem (`runtime-deps`,
|
|
12
|
-
`mcp-json`): `scope: repo`, guardados por `isFrameworkRepo(env)`, cada um nomeando arquivo, linha e
|
|
13
|
-
correção. **Nenhuma máquina nova** — o runner de `checks.mjs` já roda tudo isso.
|
|
14
|
-
|
|
15
|
-
O que é genuinamente novo é a **leitura da documentação como dado**. Hoje o `health.mjs` lê código
|
|
16
|
-
(imports, `package.json`, `.mcp.json`); agora precisa ler os `.md` e extrair duas coisas: comandos
|
|
17
|
-
citados e links relativos. Isso vira `lib/core/doc-graph.mjs` — um scanner puro, sem opinião sobre
|
|
18
|
-
severidade, testável isoladamente. Os três checks são finos: chamam o scanner e comparam com a
|
|
19
|
-
verdade (o registry, o sistema de arquivos).
|
|
20
|
-
|
|
21
|
-
O ponto que decide se a spec vale a pena é o **AC-2**: a allowlist de comandos do projeto gerado
|
|
22
|
-
tem que ser *derivada*, não escrita. Confirmei em campo que dá: parsear o bloco `"scripts"` dos
|
|
23
|
-
`lib/generators/*.js` produz exatamente `start:dev`, `test:cov`, `memory:db:*` etc. — os 7 falsos
|
|
24
|
-
positivos que a auditoria manual pegou. Lista manual mente com o tempo; a derivada acompanha o
|
|
25
|
-
gerador sozinha.
|
|
26
|
-
|
|
27
|
-
## 2. Módulos afetados
|
|
28
|
-
|
|
29
|
-
| Caminho | Mudança | Risco |
|
|
30
|
-
|---|---|---|
|
|
31
|
-
| `lib/core/doc-graph.mjs` | **criar** — scanner puro: cita comandos, coleta links, deriva allowlist | M |
|
|
32
|
-
| `lib/core/health.mjs` | editar — 3 checks novos no `CHECKS[]` | B |
|
|
33
|
-
| `test/doc-graph.test.js` | **criar** — o scanner, isolado | B |
|
|
34
|
-
| `test/health.test.js` | editar — os 3 checks nos dois estados, incluindo o falso positivo do AC-2 | B |
|
|
35
|
-
| `docs/token-optimization.md` etc. | corrigir o que o check acusar (já limpo na v1.1.4, mas o gate é quem confirma) | B |
|
|
36
|
-
| `README`/`docs` | documentar `memory:extract` (AC-10) | B |
|
|
37
|
-
| `memory/90-decisions/0025-*.md` | **criar** — ADR | B |
|
|
38
|
-
|
|
39
|
-
Risco no `doc-graph.mjs`, não no `health.mjs`: os checks são triviais; a dificuldade toda é o
|
|
40
|
-
scanner não gerar falso positivo. Um `docs-commands` que acusa demais reprova a documentação
|
|
41
|
-
inteira e é desligado no primeiro dia — pior que não existir.
|
|
42
|
-
|
|
43
|
-
## 3. Diagrama de fluxo
|
|
44
|
-
|
|
45
|
-
```
|
|
46
|
-
tools:doctor (scope: repo)
|
|
47
|
-
│
|
|
48
|
-
▼
|
|
49
|
-
┌──────────────── lib/core/doc-graph.mjs ────────────────┐
|
|
50
|
-
│ scanDocs(env) → [{ file, line, command }] │ citações forja/npm run
|
|
51
|
-
│ scanLinks(env) → [{ file, line, target }] │ links markdown relativos
|
|
52
|
-
│ projectCommands(env) → Set<string> │ derivada de lib/generators/
|
|
53
|
-
└────────────────────────────────────────────────────────┘
|
|
54
|
-
│ │ │
|
|
55
|
-
▼ ▼ ▼
|
|
56
|
-
docs-commands docs-links commands-documented
|
|
57
|
-
(critical) (warn) (warn)
|
|
58
|
-
citado ∈ registry target existe registry ⊆ citados
|
|
59
|
-
∪ projectCommands nos .md
|
|
60
|
-
│ │ │
|
|
61
|
-
└──────────── Result[] { file, line, detail, fix } ──────────┘
|
|
62
|
-
```
|
|
63
|
-
|
|
64
|
-
## 4. Contratos (API/CLI/Schema)
|
|
65
|
-
|
|
66
|
-
```js
|
|
67
|
-
// lib/core/doc-graph.mjs — leitura pura, sem juízo de severidade
|
|
68
|
-
|
|
69
|
-
/** Superfícies de instrução escaneadas. docs/archive, boilerplates e specs ficam de fora (§5 D3). */
|
|
70
|
-
export const DOC_SURFACES; // ['docs', 'prompts', '.claude/agents', 'AGENTS.md', 'CLAUDE.md', 'README.md', 'README.en.md', 'DOC-MAP.md']
|
|
71
|
-
|
|
72
|
-
/** Comandos citados como `forja x:y` ou `npm run x:y` em bloco de código. { file, line, command } */
|
|
73
|
-
export function scanCommands(env);
|
|
74
|
-
|
|
75
|
-
/** Links markdown relativos (não http, âncora ignorada). { file, line, target } */
|
|
76
|
-
export function scanLinks(env);
|
|
77
|
-
|
|
78
|
-
/** Allowlist DERIVADA: keys do bloco "scripts" dos geradores. Nunca uma lista literal. */
|
|
79
|
-
export function projectCommands(env); // -> Set<string>
|
|
80
|
-
```
|
|
81
|
-
|
|
82
|
-
**Regex de comando** — casa `(?:forja |npm run )` seguido de um token **com ao menos um `:`**
|
|
83
|
-
(`spec:new`, `code:impact`). O `:` é o discriminador: todo comando do registry o tem, e nenhuma
|
|
84
|
-
prosa (`"forja does X"`) o casa por acidente. Só dentro de bloco/span de código — prosa livre.
|
|
85
|
-
|
|
86
|
-
**Contrato dos checks** (severidade honesta, AC-6):
|
|
87
|
-
|
|
88
|
-
| Check | Severity | Reprova quando | Fix prescrito |
|
|
89
|
-
|---|---|---|---|
|
|
90
|
-
| `docs-commands` | critical | comando citado ∉ registry ∪ `projectCommands` | "renomeie para `<x>` ou remova a citação em `file:line`" |
|
|
91
|
-
| `commands-documented` | warn | comando do registry citado em nenhum `.md` | "documente `<cmd>` em algum `.md` (ou remova do registry)" |
|
|
92
|
-
| `docs-links` | warn | link relativo aponta para inexistente | "crie o alvo ou corrija o link em `file:line`" |
|
|
93
|
-
|
|
94
|
-
## 5. Decisões e alternativas
|
|
95
|
-
|
|
96
|
-
**D1: Scanner puro separado dos checks.** `doc-graph.mjs` lê e devolve dados; os checks julgam.
|
|
97
|
-
Permite testar o parsing (a parte difícil) sem montar o ambiente do doctor, e permite que um quarto
|
|
98
|
-
consumidor use o mesmo scan amanhã. Alternativa rejeitada: lógica de parsing embutida em cada check
|
|
99
|
-
— foi assim que o `runtime-deps` e o `release.mjs` acabaram com dois parsers de import quase iguais.
|
|
100
|
-
|
|
101
|
-
**D2: Allowlist derivada dos geradores (AC-2).** A prova de fogo da spec. `projectCommands(env)`
|
|
102
|
-
parseia o bloco `"scripts"` dos `lib/generators/*.js`. Alternativa rejeitada: lista literal no
|
|
103
|
-
código — é a armadilha do `.gitignore` da SPEC-009, onde a allow-list manual engoliu uma spec em
|
|
104
|
-
silêncio. Uma lista que não acompanha o gerador vira mentira no primeiro comando novo do boilerplate.
|
|
105
|
-
|
|
106
|
-
**D3: Escopo do scan — instrução, não histórico.** Escaneia `docs/` (menos `archive/`), `prompts/`,
|
|
107
|
-
`.claude/agents/` e os `.md` de raiz. **Fora**: `docs/archive/` (legado, off-limits), `boilerplates/`
|
|
108
|
-
(é conteúdo do projeto gerado — cita comandos do projeto, não do Forja), `specs/` e `memory/90-*`
|
|
109
|
-
(registro histórico: uma spec ou ADR pode legitimamente citar um comando proposto ou já removido).
|
|
110
|
-
O gate protege o que instrui o agente *agora*, não o que registrou o passado.
|
|
111
|
-
|
|
112
|
-
**D4: `:` como discriminador de comando.** Em vez de tentar entender a gramática do CLI, exijo o
|
|
113
|
-
`:`. Simples, e cobre 42/42 do registry. Um comando futuro sem `:` escaparia — mas hoje nenhum
|
|
114
|
-
existe, e inventar parser de gramática para um caso inexistente é criar o problema que não temos.
|
|
115
|
-
|
|
116
|
-
**D5: `docs-commands` é o único crítico.** Comando fantasma faz o agente agir errado — trava.
|
|
117
|
-
Comando não-documentado e link quebrado atrapalham mas não param ninguém: `warn`. Reprovar release
|
|
118
|
-
por um link quebrado num doc é como o `deps-unused` seria se fosse crítico — ensina o time a ignorar
|
|
119
|
-
o gate.
|
|
120
|
-
|
|
121
|
-
**D6: `memory:extract` — decisão adiada para as tasks.** É o único órfão real. Documentar ou remover
|
|
122
|
-
é chamada de quem conhece o uso dele; o plano não força a mão. O que o plano garante é que, depois,
|
|
123
|
-
o `commands-documented` não deixa nascer um órfão novo.
|
|
124
|
-
|
|
125
|
-
D1, D2 e D3 são estruturais → **ADR-0025**, referenciando ADR-0023/0024 (mesma família de gate,
|
|
126
|
-
terceira fronteira: a instrução) e ADR-0021 (a classe "erra sem avisar").
|
|
127
|
-
|
|
128
|
-
## 6. Dependências
|
|
129
|
-
|
|
130
|
-
- **Specs**: SPEC-009 (`health.mjs`/`checks.mjs` são a base). Já `done`.
|
|
131
|
-
- **Pacotes npm**: **nenhum novo.** `node:fs` e regex. Parsear markdown com um lexer completo seria
|
|
132
|
-
peso morto — precisamos de citações em code-span e links, não de um AST de CommonMark.
|
|
133
|
-
- **Migrações**: nenhuma.
|
|
134
|
-
|
|
135
|
-
## 7. Rollout
|
|
136
|
-
|
|
137
|
-
- [ ] **Ordem**: `doc-graph.mjs` + seus testes primeiro (nada o consome ainda) → os 3 checks →
|
|
138
|
-
rodar o doctor e **corrigir o que ele acusar** → CI já pega de graça (o doctor já é step, ADR-0024).
|
|
139
|
-
- [x] Doc/persona: governança ganha mais um critério; nenhuma persona muda de fluxo.
|
|
140
|
-
- [ ] **Validar o AC-2 de verdade**: adicionar um `"foo:bar"` temporário aos scripts de um gerador e
|
|
141
|
-
confirmar que `docs-commands` **não** passa a exigir `foo:bar` na doc. Se exigir, a derivação
|
|
142
|
-
não está pegando o gerador certo.
|
|
143
|
-
- [ ] O primeiro `npm run tools:doctor` depois disto é o teste real: ele deve passar (a doc já foi
|
|
144
|
-
limpa na v1.1.4), provando que o gate concorda com a correção manual — não inventa trabalho.
|
|
145
|
-
|
|
146
|
-
## 8. Sinais de fracasso (kill criteria)
|
|
147
|
-
|
|
148
|
-
- **`docs-commands` gera um falso positivo crítico.** Se acontecer uma vez com comando legítimo, ele
|
|
149
|
-
é rebaixado a `warn` até o scanner ser corrigido — um crítico que mente é pior que um warning
|
|
150
|
-
honesto, e aqui ele bloquearia o CI de todo mundo.
|
|
151
|
-
- **O scanner fica caro.** Se ler os `.md` todos passar de ~1s, o scan vira lazy/cacheado por mtime —
|
|
152
|
-
mas os checks são `scope: repo`, fora do `SessionStart`, então a folga é grande.
|
|
153
|
-
- **A regra vira desincentivo a documentar.** Se alguém parar de escrever doc para não "brigar com o
|
|
154
|
-
gate", erramos: o gate só cobre citação de *comando*, e isso precisa estar claro na mensagem de
|
|
155
|
-
erro (que aponta a linha e diz "renomeie ou remova a citação", nunca "não escreva").
|
|
1
|
+
# Plan: coerencia-do-sistema
|
|
2
|
+
|
|
3
|
+
- **Spec**: ./spec.md
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Criado em**: 2026-07-15
|
|
6
|
+
|
|
7
|
+
> Como vamos construir o que a spec define. Sem código aqui — só estrutura e decisões.
|
|
8
|
+
|
|
9
|
+
## 1. Abordagem técnica
|
|
10
|
+
|
|
11
|
+
Três checks novos no catálogo de `health.mjs`, no molde dos que já existem (`runtime-deps`,
|
|
12
|
+
`mcp-json`): `scope: repo`, guardados por `isFrameworkRepo(env)`, cada um nomeando arquivo, linha e
|
|
13
|
+
correção. **Nenhuma máquina nova** — o runner de `checks.mjs` já roda tudo isso.
|
|
14
|
+
|
|
15
|
+
O que é genuinamente novo é a **leitura da documentação como dado**. Hoje o `health.mjs` lê código
|
|
16
|
+
(imports, `package.json`, `.mcp.json`); agora precisa ler os `.md` e extrair duas coisas: comandos
|
|
17
|
+
citados e links relativos. Isso vira `lib/core/doc-graph.mjs` — um scanner puro, sem opinião sobre
|
|
18
|
+
severidade, testável isoladamente. Os três checks são finos: chamam o scanner e comparam com a
|
|
19
|
+
verdade (o registry, o sistema de arquivos).
|
|
20
|
+
|
|
21
|
+
O ponto que decide se a spec vale a pena é o **AC-2**: a allowlist de comandos do projeto gerado
|
|
22
|
+
tem que ser *derivada*, não escrita. Confirmei em campo que dá: parsear o bloco `"scripts"` dos
|
|
23
|
+
`lib/generators/*.js` produz exatamente `start:dev`, `test:cov`, `memory:db:*` etc. — os 7 falsos
|
|
24
|
+
positivos que a auditoria manual pegou. Lista manual mente com o tempo; a derivada acompanha o
|
|
25
|
+
gerador sozinha.
|
|
26
|
+
|
|
27
|
+
## 2. Módulos afetados
|
|
28
|
+
|
|
29
|
+
| Caminho | Mudança | Risco |
|
|
30
|
+
|---|---|---|
|
|
31
|
+
| `lib/core/doc-graph.mjs` | **criar** — scanner puro: cita comandos, coleta links, deriva allowlist | M |
|
|
32
|
+
| `lib/core/health.mjs` | editar — 3 checks novos no `CHECKS[]` | B |
|
|
33
|
+
| `test/doc-graph.test.js` | **criar** — o scanner, isolado | B |
|
|
34
|
+
| `test/health.test.js` | editar — os 3 checks nos dois estados, incluindo o falso positivo do AC-2 | B |
|
|
35
|
+
| `docs/token-optimization.md` etc. | corrigir o que o check acusar (já limpo na v1.1.4, mas o gate é quem confirma) | B |
|
|
36
|
+
| `README`/`docs` | documentar `memory:extract` (AC-10) | B |
|
|
37
|
+
| `memory/90-decisions/0025-*.md` | **criar** — ADR | B |
|
|
38
|
+
|
|
39
|
+
Risco no `doc-graph.mjs`, não no `health.mjs`: os checks são triviais; a dificuldade toda é o
|
|
40
|
+
scanner não gerar falso positivo. Um `docs-commands` que acusa demais reprova a documentação
|
|
41
|
+
inteira e é desligado no primeiro dia — pior que não existir.
|
|
42
|
+
|
|
43
|
+
## 3. Diagrama de fluxo
|
|
44
|
+
|
|
45
|
+
```
|
|
46
|
+
tools:doctor (scope: repo)
|
|
47
|
+
│
|
|
48
|
+
▼
|
|
49
|
+
┌──────────────── lib/core/doc-graph.mjs ────────────────┐
|
|
50
|
+
│ scanDocs(env) → [{ file, line, command }] │ citações forja/npm run
|
|
51
|
+
│ scanLinks(env) → [{ file, line, target }] │ links markdown relativos
|
|
52
|
+
│ projectCommands(env) → Set<string> │ derivada de lib/generators/
|
|
53
|
+
└────────────────────────────────────────────────────────┘
|
|
54
|
+
│ │ │
|
|
55
|
+
▼ ▼ ▼
|
|
56
|
+
docs-commands docs-links commands-documented
|
|
57
|
+
(critical) (warn) (warn)
|
|
58
|
+
citado ∈ registry target existe registry ⊆ citados
|
|
59
|
+
∪ projectCommands nos .md
|
|
60
|
+
│ │ │
|
|
61
|
+
└──────────── Result[] { file, line, detail, fix } ──────────┘
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## 4. Contratos (API/CLI/Schema)
|
|
65
|
+
|
|
66
|
+
```js
|
|
67
|
+
// lib/core/doc-graph.mjs — leitura pura, sem juízo de severidade
|
|
68
|
+
|
|
69
|
+
/** Superfícies de instrução escaneadas. docs/archive, boilerplates e specs ficam de fora (§5 D3). */
|
|
70
|
+
export const DOC_SURFACES; // ['docs', 'prompts', '.claude/agents', 'AGENTS.md', 'CLAUDE.md', 'README.md', 'README.en.md', 'DOC-MAP.md']
|
|
71
|
+
|
|
72
|
+
/** Comandos citados como `forja x:y` ou `npm run x:y` em bloco de código. { file, line, command } */
|
|
73
|
+
export function scanCommands(env);
|
|
74
|
+
|
|
75
|
+
/** Links markdown relativos (não http, âncora ignorada). { file, line, target } */
|
|
76
|
+
export function scanLinks(env);
|
|
77
|
+
|
|
78
|
+
/** Allowlist DERIVADA: keys do bloco "scripts" dos geradores. Nunca uma lista literal. */
|
|
79
|
+
export function projectCommands(env); // -> Set<string>
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
**Regex de comando** — casa `(?:forja |npm run )` seguido de um token **com ao menos um `:`**
|
|
83
|
+
(`spec:new`, `code:impact`). O `:` é o discriminador: todo comando do registry o tem, e nenhuma
|
|
84
|
+
prosa (`"forja does X"`) o casa por acidente. Só dentro de bloco/span de código — prosa livre.
|
|
85
|
+
|
|
86
|
+
**Contrato dos checks** (severidade honesta, AC-6):
|
|
87
|
+
|
|
88
|
+
| Check | Severity | Reprova quando | Fix prescrito |
|
|
89
|
+
|---|---|---|---|
|
|
90
|
+
| `docs-commands` | critical | comando citado ∉ registry ∪ `projectCommands` | "renomeie para `<x>` ou remova a citação em `file:line`" |
|
|
91
|
+
| `commands-documented` | warn | comando do registry citado em nenhum `.md` | "documente `<cmd>` em algum `.md` (ou remova do registry)" |
|
|
92
|
+
| `docs-links` | warn | link relativo aponta para inexistente | "crie o alvo ou corrija o link em `file:line`" |
|
|
93
|
+
|
|
94
|
+
## 5. Decisões e alternativas
|
|
95
|
+
|
|
96
|
+
**D1: Scanner puro separado dos checks.** `doc-graph.mjs` lê e devolve dados; os checks julgam.
|
|
97
|
+
Permite testar o parsing (a parte difícil) sem montar o ambiente do doctor, e permite que um quarto
|
|
98
|
+
consumidor use o mesmo scan amanhã. Alternativa rejeitada: lógica de parsing embutida em cada check
|
|
99
|
+
— foi assim que o `runtime-deps` e o `release.mjs` acabaram com dois parsers de import quase iguais.
|
|
100
|
+
|
|
101
|
+
**D2: Allowlist derivada dos geradores (AC-2).** A prova de fogo da spec. `projectCommands(env)`
|
|
102
|
+
parseia o bloco `"scripts"` dos `lib/generators/*.js`. Alternativa rejeitada: lista literal no
|
|
103
|
+
código — é a armadilha do `.gitignore` da SPEC-009, onde a allow-list manual engoliu uma spec em
|
|
104
|
+
silêncio. Uma lista que não acompanha o gerador vira mentira no primeiro comando novo do boilerplate.
|
|
105
|
+
|
|
106
|
+
**D3: Escopo do scan — instrução, não histórico.** Escaneia `docs/` (menos `archive/`), `prompts/`,
|
|
107
|
+
`.claude/agents/` e os `.md` de raiz. **Fora**: `docs/archive/` (legado, off-limits), `boilerplates/`
|
|
108
|
+
(é conteúdo do projeto gerado — cita comandos do projeto, não do Forja), `specs/` e `memory/90-*`
|
|
109
|
+
(registro histórico: uma spec ou ADR pode legitimamente citar um comando proposto ou já removido).
|
|
110
|
+
O gate protege o que instrui o agente *agora*, não o que registrou o passado.
|
|
111
|
+
|
|
112
|
+
**D4: `:` como discriminador de comando.** Em vez de tentar entender a gramática do CLI, exijo o
|
|
113
|
+
`:`. Simples, e cobre 42/42 do registry. Um comando futuro sem `:` escaparia — mas hoje nenhum
|
|
114
|
+
existe, e inventar parser de gramática para um caso inexistente é criar o problema que não temos.
|
|
115
|
+
|
|
116
|
+
**D5: `docs-commands` é o único crítico.** Comando fantasma faz o agente agir errado — trava.
|
|
117
|
+
Comando não-documentado e link quebrado atrapalham mas não param ninguém: `warn`. Reprovar release
|
|
118
|
+
por um link quebrado num doc é como o `deps-unused` seria se fosse crítico — ensina o time a ignorar
|
|
119
|
+
o gate.
|
|
120
|
+
|
|
121
|
+
**D6: `memory:extract` — decisão adiada para as tasks.** É o único órfão real. Documentar ou remover
|
|
122
|
+
é chamada de quem conhece o uso dele; o plano não força a mão. O que o plano garante é que, depois,
|
|
123
|
+
o `commands-documented` não deixa nascer um órfão novo.
|
|
124
|
+
|
|
125
|
+
D1, D2 e D3 são estruturais → **ADR-0025**, referenciando ADR-0023/0024 (mesma família de gate,
|
|
126
|
+
terceira fronteira: a instrução) e ADR-0021 (a classe "erra sem avisar").
|
|
127
|
+
|
|
128
|
+
## 6. Dependências
|
|
129
|
+
|
|
130
|
+
- **Specs**: SPEC-009 (`health.mjs`/`checks.mjs` são a base). Já `done`.
|
|
131
|
+
- **Pacotes npm**: **nenhum novo.** `node:fs` e regex. Parsear markdown com um lexer completo seria
|
|
132
|
+
peso morto — precisamos de citações em code-span e links, não de um AST de CommonMark.
|
|
133
|
+
- **Migrações**: nenhuma.
|
|
134
|
+
|
|
135
|
+
## 7. Rollout
|
|
136
|
+
|
|
137
|
+
- [ ] **Ordem**: `doc-graph.mjs` + seus testes primeiro (nada o consome ainda) → os 3 checks →
|
|
138
|
+
rodar o doctor e **corrigir o que ele acusar** → CI já pega de graça (o doctor já é step, ADR-0024).
|
|
139
|
+
- [x] Doc/persona: governança ganha mais um critério; nenhuma persona muda de fluxo.
|
|
140
|
+
- [ ] **Validar o AC-2 de verdade**: adicionar um `"foo:bar"` temporário aos scripts de um gerador e
|
|
141
|
+
confirmar que `docs-commands` **não** passa a exigir `foo:bar` na doc. Se exigir, a derivação
|
|
142
|
+
não está pegando o gerador certo.
|
|
143
|
+
- [ ] O primeiro `npm run tools:doctor` depois disto é o teste real: ele deve passar (a doc já foi
|
|
144
|
+
limpa na v1.1.4), provando que o gate concorda com a correção manual — não inventa trabalho.
|
|
145
|
+
|
|
146
|
+
## 8. Sinais de fracasso (kill criteria)
|
|
147
|
+
|
|
148
|
+
- **`docs-commands` gera um falso positivo crítico.** Se acontecer uma vez com comando legítimo, ele
|
|
149
|
+
é rebaixado a `warn` até o scanner ser corrigido — um crítico que mente é pior que um warning
|
|
150
|
+
honesto, e aqui ele bloquearia o CI de todo mundo.
|
|
151
|
+
- **O scanner fica caro.** Se ler os `.md` todos passar de ~1s, o scan vira lazy/cacheado por mtime —
|
|
152
|
+
mas os checks são `scope: repo`, fora do `SessionStart`, então a folga é grande.
|
|
153
|
+
- **A regra vira desincentivo a documentar.** Se alguém parar de escrever doc para não "brigar com o
|
|
154
|
+
gate", erramos: o gate só cobre citação de *comando*, e isso precisa estar claro na mensagem de
|
|
155
|
+
erro (que aponta a linha e diz "renomeie ou remova a citação", nunca "não escreva").
|
|
@@ -1,123 +1,123 @@
|
|
|
1
|
-
# Spec: coerencia-do-sistema
|
|
2
|
-
|
|
3
|
-
- **ID**: SPEC-011
|
|
4
|
-
- **Status**: done
|
|
5
|
-
- **Owner**: apk
|
|
6
|
-
- **Criado em**: 2026-07-14
|
|
7
|
-
- **Sprint alvo**: S?
|
|
8
|
-
- **ADRs relacionadas**: [ADR-0024](../../memory/90-decisions/0024-gate-do-tarball.md) (gate do tarball), [ADR-0023](../../memory/90-decisions/0023-doctor-como-gate-do-nucleo.md) (gate do núcleo), [ADR-0021](../../memory/90-decisions/0021-guardrails-de-harness.md) (guardrails), [ADR-0020](../../memory/90-decisions/0020-forja-core-cli-unica.md) (registry), [ADR-0009](../../memory/90-decisions/0009-claude-hooks-token-economy.md) (economia de tokens)
|
|
9
|
-
|
|
10
|
-
## 1. Problema
|
|
11
|
-
|
|
12
|
-
**Nenhum step do sistema pode ser obscuro.** O Forja é operado por agentes que leem a documentação
|
|
13
|
-
e executam o que ela manda. Quando a doc e o código divergem, o agente não erra por burrice — erra
|
|
14
|
-
por obediência.
|
|
15
|
-
|
|
16
|
-
Em 2026-07-14, uma auditoria manual encontrou:
|
|
17
|
-
|
|
18
|
-
| O que | Onde | Consequência |
|
|
19
|
-
|---|---|---|
|
|
20
|
-
| `context:build`, `memory:db:reindex`, `memory:db:stats`, `cache:clear` — **quatro comandos que não existem em lugar nenhum** | `docs/token-optimization.md` | É o documento que ensina a **economia de tokens** (ADR-0009), o mecanismo central do framework. Um agente obediente executa comandos fantasma |
|
|
21
|
-
| Link para `docs/DEPLOYMENT.md`, que nunca existiu | idem | — |
|
|
22
|
-
| `tools:doctor` descrito como *"saber quais gates opcionais estão disponíveis"* | `.claude/agents/governance.md`, `prompts/governance-agent.md` | É a definição de **antes** do ADR-0023. O papel que reprova merges não sabia que o gate reprova |
|
|
23
|
-
| `release:check` desconhecido pelo Governance | idem | Criamos o gate do tarball e não contamos a quem deveria usá-lo |
|
|
24
|
-
| 2 comandos do registry **nunca mencionados** em doc, prompt, agente ou ADR | `workspace:project:check`, `memory:extract` | Existem e ninguém sabe para quê. Capacidade obscura é capacidade morta |
|
|
25
|
-
|
|
26
|
-
Nada disso quebrou um teste. Nada apareceu no `git status`. É a classe que o ADR-0021 nomeia —
|
|
27
|
-
*erra sem avisar* — aplicada à **camada de instrução**: o sistema descreve a si mesmo de forma
|
|
28
|
-
incorreta, e quem age sobre essa descrição produz trabalho errado com aparência de trabalho certo.
|
|
29
|
-
|
|
30
|
-
Os ADRs 0023 e 0024 fecharam essa classe no núcleo e no tarball. Falta a fronteira onde ela é mais
|
|
31
|
-
barata de introduzir e mais cara de perceber: **a palavra escrita.** Toda vez que um comando é
|
|
32
|
-
renomeado, um gate muda de contrato ou uma capacidade nasce, a documentação pode silenciosamente
|
|
33
|
-
passar a mentir — e hoje nada percebe.
|
|
34
|
-
|
|
35
|
-
## 2. Proposta de valor
|
|
36
|
-
|
|
37
|
-
**O sistema é obrigado a explicar a si mesmo, e a explicação é verificada.** Comando citado existe;
|
|
38
|
-
comando que existe é citado; gate que reprova diz como corrigir. Divergência entre o que o Forja
|
|
39
|
-
faz e o que ele diz que faz passa a reprovar o gate — em vez de virar armadilha para o próximo
|
|
40
|
-
agente.
|
|
41
|
-
|
|
42
|
-
## 3. User stories
|
|
43
|
-
|
|
44
|
-
- **Como** agente lendo a documentação, **quero** que todo comando citado exista de verdade,
|
|
45
|
-
**para que** eu não execute um fantasma e conclua que o ambiente está quebrado.
|
|
46
|
-
- **Como** operador, **quero** que toda capacidade do registry esteja explicada em algum lugar,
|
|
47
|
-
**para que** eu não descubra por acaso que o framework já fazia o que fui construir à mão.
|
|
48
|
-
- **Como** governança, **quero** que a mudança de contrato de um gate **quebre** a doc que o
|
|
49
|
-
descreve errado, **para que** o `tools:doctor` não fique mais um dia sendo apresentado como
|
|
50
|
-
"inventário de ferramentas opcionais" depois de virar gate.
|
|
51
|
-
- **Como** quem mantém o framework, **quero** que renomear um comando seja um ato **detectável**,
|
|
52
|
-
**para que** a renomeação não deixe um rastro de documentação morta.
|
|
53
|
-
|
|
54
|
-
## 4. Critérios de aceite (Definition of Done)
|
|
55
|
-
|
|
56
|
-
- [x] AC-1: Check `docs-commands` (`scope: repo`, catálogo de `health.mjs`): todo `npm run <cmd>` /
|
|
57
|
-
`forja <cmd>` citado em `docs/`, `prompts/`, `.claude/agents/`, `AGENTS.md`, `CLAUDE.md` e
|
|
58
|
-
`README.md` existe no registry (ADR-0020).
|
|
59
|
-
- [x] AC-2: **Comandos do projeto gerado não contam.** `start:dev`, `test:cov`, `memory:db:*` e
|
|
60
|
-
afins são do NestJS/Jest do projeto que o Forja **gera**, não do Forja. A allowlist é derivada
|
|
61
|
-
dos geradores, **não escrita à mão** — uma lista manual mente com o tempo (foi a lição do
|
|
62
|
-
`.gitignore` na SPEC-009). 7 dos 11 "fantasmas" da auditoria eram isto.
|
|
63
|
-
- [x] AC-3: Check `commands-documented` (**warn**, `scope: repo`): todo comando do registry é
|
|
64
|
-
mencionado em pelo menos um `.md` versionado. Hoje 1 de 42 não é (`memory:extract`) — a
|
|
65
|
-
reescrita canônica do README na v1.1.5 já documentou `workspace:project:check`.
|
|
66
|
-
- [x] AC-4: Check `docs-links` (**warn**, `scope: repo`): todo link markdown relativo entre arquivos
|
|
67
|
-
versionados resolve. `docs/DEPLOYMENT.md` era link para o nada.
|
|
68
|
-
- [x] AC-5: Os três checks entram no `tools:doctor` e, por consequência, no CI — que já roda o
|
|
69
|
-
doctor na matriz (ADR-0024).
|
|
70
|
-
- [x] AC-6: **Severidades honestas.** `docs-commands` é `critical` (comando fantasma faz o agente
|
|
71
|
-
agir errado). `commands-documented` e `docs-links` são `warn` (atrapalham, não impedem). Um
|
|
72
|
-
gate que reprova o que não impede trabalho é um gate que se aprende a ignorar.
|
|
73
|
-
- [x] AC-7: Toda reprovação nomeia **arquivo e linha** e prescreve a correção. O gate que diz "algo
|
|
74
|
-
está errado" sem dizer onde é só mais um step obscuro.
|
|
75
|
-
- [x] AC-8: Testes com fixture para cada check nos dois estados, incluindo o falso positivo do AC-2.
|
|
76
|
-
- [x] AC-9: ADR-0025 registrando a decisão.
|
|
77
|
-
- [x] AC-10: O comando órfão restante (`memory:extract`) é documentado — ou removido do registry,
|
|
78
|
-
se não servir mais. Capacidade obscura é capacidade morta.
|
|
79
|
-
|
|
80
|
-
## 5. Escopo
|
|
81
|
-
|
|
82
|
-
**Dentro**:
|
|
83
|
-
- `lib/core/health.mjs` — os três checks novos (o catálogo do repo).
|
|
84
|
-
- `lib/core/doc-graph.mjs` — varredura dos `.md` versionados: comandos citados, links relativos.
|
|
85
|
-
- Derivação automática da allowlist de comandos do projeto gerado, a partir de `lib/generators/`.
|
|
86
|
-
- Documentar o comando órfão restante (`memory:extract`), ou removê-lo.
|
|
87
|
-
- ADR-0025 + testes.
|
|
88
|
-
|
|
89
|
-
**Fora** (explícito):
|
|
90
|
-
- **Lint de prosa** (estilo, ortografia, tamanho de linha). Isto é `markdownlint`, já previsto no
|
|
91
|
-
ADR-0018 como ferramenta opcional. Aqui só verificamos o que é **verificável contra o código**.
|
|
92
|
-
- Validar links **externos** (http). Rede no gate é flakiness garantida.
|
|
93
|
-
- Gerar documentação automaticamente a partir do registry. Doc gerada por máquina não explica o
|
|
94
|
-
*porquê*, e o porquê é a parte que importa — o gate cobra que exista, não escreve por você.
|
|
95
|
-
- Traduzir os docs em inglês (`token-optimization.md` está em inglês; outros em português). É dívida
|
|
96
|
-
real, mas é outra spec.
|
|
97
|
-
|
|
98
|
-
## 6. NFRs / restrições
|
|
99
|
-
|
|
100
|
-
- **Performance**: os três checks são `scope: repo` e só leem `.md` — ficam fora do `SessionStart`
|
|
101
|
-
(que roda `scope: runtime`). O doctor completo continua < 2s.
|
|
102
|
-
- **Zero falso positivo crítico**: o AC-2 é a prova de fogo. A auditoria manual acusou 11 comandos,
|
|
103
|
-
e 7 eram legítimos. Um `docs-commands` ingênuo teria "corrigido" a documentação de onboarding
|
|
104
|
-
inteira — pior que não ter check nenhum.
|
|
105
|
-
- **Compatibilidade**: aditivo. Nenhum comando existente muda de contrato.
|
|
106
|
-
|
|
107
|
-
## 7. Riscos e mitigação
|
|
108
|
-
|
|
109
|
-
| Risco | Probabilidade | Impacto | Mitigação |
|
|
110
|
-
|---|---|---|---|
|
|
111
|
-
| Falso positivo com comandos do projeto gerado | **A** | A | AC-2: allowlist **derivada** dos geradores, nunca manual. Já observado: 7 de 11 |
|
|
112
|
-
| Regex casa comando dentro de bloco de exemplo hipotético | M | M | Só `npm run x` / `forja x` em bloco de código. Prosa não conta |
|
|
113
|
-
| `commands-documented` vira ruído a cada comando novo | M | B | É `warn`. E documentar comando novo é o comportamento desejado |
|
|
114
|
-
| O gate engessa a doc e desestimula escrever | B | M | Ele só cobra referências a **código**; prosa é livre |
|
|
115
|
-
|
|
116
|
-
## 8. Métricas de sucesso
|
|
117
|
-
|
|
118
|
-
- **Zero** comandos fantasma na documentação, verificado a cada CI — em vez de a cada auditoria
|
|
119
|
-
manual que alguém lembrar de fazer.
|
|
120
|
-
- Renomear um comando passa a **quebrar o CI** enquanto a doc não acompanhar. Hoje renomear é grátis
|
|
121
|
-
e a doc apodrece calada.
|
|
122
|
-
- Os 42 comandos do registry passam a ter, cada um, ao menos um lugar onde o sistema explica o que
|
|
123
|
-
ele faz. Nenhum step obscuro.
|
|
1
|
+
# Spec: coerencia-do-sistema
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-011
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Owner**: apk
|
|
6
|
+
- **Criado em**: 2026-07-14
|
|
7
|
+
- **Sprint alvo**: S?
|
|
8
|
+
- **ADRs relacionadas**: [ADR-0024](../../memory/90-decisions/0024-gate-do-tarball.md) (gate do tarball), [ADR-0023](../../memory/90-decisions/0023-doctor-como-gate-do-nucleo.md) (gate do núcleo), [ADR-0021](../../memory/90-decisions/0021-guardrails-de-harness.md) (guardrails), [ADR-0020](../../memory/90-decisions/0020-forja-core-cli-unica.md) (registry), [ADR-0009](../../memory/90-decisions/0009-claude-hooks-token-economy.md) (economia de tokens)
|
|
9
|
+
|
|
10
|
+
## 1. Problema
|
|
11
|
+
|
|
12
|
+
**Nenhum step do sistema pode ser obscuro.** O Forja é operado por agentes que leem a documentação
|
|
13
|
+
e executam o que ela manda. Quando a doc e o código divergem, o agente não erra por burrice — erra
|
|
14
|
+
por obediência.
|
|
15
|
+
|
|
16
|
+
Em 2026-07-14, uma auditoria manual encontrou:
|
|
17
|
+
|
|
18
|
+
| O que | Onde | Consequência |
|
|
19
|
+
|---|---|---|
|
|
20
|
+
| `context:build`, `memory:db:reindex`, `memory:db:stats`, `cache:clear` — **quatro comandos que não existem em lugar nenhum** | `docs/token-optimization.md` | É o documento que ensina a **economia de tokens** (ADR-0009), o mecanismo central do framework. Um agente obediente executa comandos fantasma |
|
|
21
|
+
| Link para `docs/DEPLOYMENT.md`, que nunca existiu | idem | — |
|
|
22
|
+
| `tools:doctor` descrito como *"saber quais gates opcionais estão disponíveis"* | `.claude/agents/governance.md`, `prompts/governance-agent.md` | É a definição de **antes** do ADR-0023. O papel que reprova merges não sabia que o gate reprova |
|
|
23
|
+
| `release:check` desconhecido pelo Governance | idem | Criamos o gate do tarball e não contamos a quem deveria usá-lo |
|
|
24
|
+
| 2 comandos do registry **nunca mencionados** em doc, prompt, agente ou ADR | `workspace:project:check`, `memory:extract` | Existem e ninguém sabe para quê. Capacidade obscura é capacidade morta |
|
|
25
|
+
|
|
26
|
+
Nada disso quebrou um teste. Nada apareceu no `git status`. É a classe que o ADR-0021 nomeia —
|
|
27
|
+
*erra sem avisar* — aplicada à **camada de instrução**: o sistema descreve a si mesmo de forma
|
|
28
|
+
incorreta, e quem age sobre essa descrição produz trabalho errado com aparência de trabalho certo.
|
|
29
|
+
|
|
30
|
+
Os ADRs 0023 e 0024 fecharam essa classe no núcleo e no tarball. Falta a fronteira onde ela é mais
|
|
31
|
+
barata de introduzir e mais cara de perceber: **a palavra escrita.** Toda vez que um comando é
|
|
32
|
+
renomeado, um gate muda de contrato ou uma capacidade nasce, a documentação pode silenciosamente
|
|
33
|
+
passar a mentir — e hoje nada percebe.
|
|
34
|
+
|
|
35
|
+
## 2. Proposta de valor
|
|
36
|
+
|
|
37
|
+
**O sistema é obrigado a explicar a si mesmo, e a explicação é verificada.** Comando citado existe;
|
|
38
|
+
comando que existe é citado; gate que reprova diz como corrigir. Divergência entre o que o Forja
|
|
39
|
+
faz e o que ele diz que faz passa a reprovar o gate — em vez de virar armadilha para o próximo
|
|
40
|
+
agente.
|
|
41
|
+
|
|
42
|
+
## 3. User stories
|
|
43
|
+
|
|
44
|
+
- **Como** agente lendo a documentação, **quero** que todo comando citado exista de verdade,
|
|
45
|
+
**para que** eu não execute um fantasma e conclua que o ambiente está quebrado.
|
|
46
|
+
- **Como** operador, **quero** que toda capacidade do registry esteja explicada em algum lugar,
|
|
47
|
+
**para que** eu não descubra por acaso que o framework já fazia o que fui construir à mão.
|
|
48
|
+
- **Como** governança, **quero** que a mudança de contrato de um gate **quebre** a doc que o
|
|
49
|
+
descreve errado, **para que** o `tools:doctor` não fique mais um dia sendo apresentado como
|
|
50
|
+
"inventário de ferramentas opcionais" depois de virar gate.
|
|
51
|
+
- **Como** quem mantém o framework, **quero** que renomear um comando seja um ato **detectável**,
|
|
52
|
+
**para que** a renomeação não deixe um rastro de documentação morta.
|
|
53
|
+
|
|
54
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
55
|
+
|
|
56
|
+
- [x] AC-1: Check `docs-commands` (`scope: repo`, catálogo de `health.mjs`): todo `npm run <cmd>` /
|
|
57
|
+
`forja <cmd>` citado em `docs/`, `prompts/`, `.claude/agents/`, `AGENTS.md`, `CLAUDE.md` e
|
|
58
|
+
`README.md` existe no registry (ADR-0020).
|
|
59
|
+
- [x] AC-2: **Comandos do projeto gerado não contam.** `start:dev`, `test:cov`, `memory:db:*` e
|
|
60
|
+
afins são do NestJS/Jest do projeto que o Forja **gera**, não do Forja. A allowlist é derivada
|
|
61
|
+
dos geradores, **não escrita à mão** — uma lista manual mente com o tempo (foi a lição do
|
|
62
|
+
`.gitignore` na SPEC-009). 7 dos 11 "fantasmas" da auditoria eram isto.
|
|
63
|
+
- [x] AC-3: Check `commands-documented` (**warn**, `scope: repo`): todo comando do registry é
|
|
64
|
+
mencionado em pelo menos um `.md` versionado. Hoje 1 de 42 não é (`memory:extract`) — a
|
|
65
|
+
reescrita canônica do README na v1.1.5 já documentou `workspace:project:check`.
|
|
66
|
+
- [x] AC-4: Check `docs-links` (**warn**, `scope: repo`): todo link markdown relativo entre arquivos
|
|
67
|
+
versionados resolve. `docs/DEPLOYMENT.md` era link para o nada.
|
|
68
|
+
- [x] AC-5: Os três checks entram no `tools:doctor` e, por consequência, no CI — que já roda o
|
|
69
|
+
doctor na matriz (ADR-0024).
|
|
70
|
+
- [x] AC-6: **Severidades honestas.** `docs-commands` é `critical` (comando fantasma faz o agente
|
|
71
|
+
agir errado). `commands-documented` e `docs-links` são `warn` (atrapalham, não impedem). Um
|
|
72
|
+
gate que reprova o que não impede trabalho é um gate que se aprende a ignorar.
|
|
73
|
+
- [x] AC-7: Toda reprovação nomeia **arquivo e linha** e prescreve a correção. O gate que diz "algo
|
|
74
|
+
está errado" sem dizer onde é só mais um step obscuro.
|
|
75
|
+
- [x] AC-8: Testes com fixture para cada check nos dois estados, incluindo o falso positivo do AC-2.
|
|
76
|
+
- [x] AC-9: ADR-0025 registrando a decisão.
|
|
77
|
+
- [x] AC-10: O comando órfão restante (`memory:extract`) é documentado — ou removido do registry,
|
|
78
|
+
se não servir mais. Capacidade obscura é capacidade morta.
|
|
79
|
+
|
|
80
|
+
## 5. Escopo
|
|
81
|
+
|
|
82
|
+
**Dentro**:
|
|
83
|
+
- `lib/core/health.mjs` — os três checks novos (o catálogo do repo).
|
|
84
|
+
- `lib/core/doc-graph.mjs` — varredura dos `.md` versionados: comandos citados, links relativos.
|
|
85
|
+
- Derivação automática da allowlist de comandos do projeto gerado, a partir de `lib/generators/`.
|
|
86
|
+
- Documentar o comando órfão restante (`memory:extract`), ou removê-lo.
|
|
87
|
+
- ADR-0025 + testes.
|
|
88
|
+
|
|
89
|
+
**Fora** (explícito):
|
|
90
|
+
- **Lint de prosa** (estilo, ortografia, tamanho de linha). Isto é `markdownlint`, já previsto no
|
|
91
|
+
ADR-0018 como ferramenta opcional. Aqui só verificamos o que é **verificável contra o código**.
|
|
92
|
+
- Validar links **externos** (http). Rede no gate é flakiness garantida.
|
|
93
|
+
- Gerar documentação automaticamente a partir do registry. Doc gerada por máquina não explica o
|
|
94
|
+
*porquê*, e o porquê é a parte que importa — o gate cobra que exista, não escreve por você.
|
|
95
|
+
- Traduzir os docs em inglês (`token-optimization.md` está em inglês; outros em português). É dívida
|
|
96
|
+
real, mas é outra spec.
|
|
97
|
+
|
|
98
|
+
## 6. NFRs / restrições
|
|
99
|
+
|
|
100
|
+
- **Performance**: os três checks são `scope: repo` e só leem `.md` — ficam fora do `SessionStart`
|
|
101
|
+
(que roda `scope: runtime`). O doctor completo continua < 2s.
|
|
102
|
+
- **Zero falso positivo crítico**: o AC-2 é a prova de fogo. A auditoria manual acusou 11 comandos,
|
|
103
|
+
e 7 eram legítimos. Um `docs-commands` ingênuo teria "corrigido" a documentação de onboarding
|
|
104
|
+
inteira — pior que não ter check nenhum.
|
|
105
|
+
- **Compatibilidade**: aditivo. Nenhum comando existente muda de contrato.
|
|
106
|
+
|
|
107
|
+
## 7. Riscos e mitigação
|
|
108
|
+
|
|
109
|
+
| Risco | Probabilidade | Impacto | Mitigação |
|
|
110
|
+
|---|---|---|---|
|
|
111
|
+
| Falso positivo com comandos do projeto gerado | **A** | A | AC-2: allowlist **derivada** dos geradores, nunca manual. Já observado: 7 de 11 |
|
|
112
|
+
| Regex casa comando dentro de bloco de exemplo hipotético | M | M | Só `npm run x` / `forja x` em bloco de código. Prosa não conta |
|
|
113
|
+
| `commands-documented` vira ruído a cada comando novo | M | B | É `warn`. E documentar comando novo é o comportamento desejado |
|
|
114
|
+
| O gate engessa a doc e desestimula escrever | B | M | Ele só cobra referências a **código**; prosa é livre |
|
|
115
|
+
|
|
116
|
+
## 8. Métricas de sucesso
|
|
117
|
+
|
|
118
|
+
- **Zero** comandos fantasma na documentação, verificado a cada CI — em vez de a cada auditoria
|
|
119
|
+
manual que alguém lembrar de fazer.
|
|
120
|
+
- Renomear um comando passa a **quebrar o CI** enquanto a doc não acompanhar. Hoje renomear é grátis
|
|
121
|
+
e a doc apodrece calada.
|
|
122
|
+
- Os 42 comandos do registry passam a ter, cada um, ao menos um lugar onde o sistema explica o que
|
|
123
|
+
ele faz. Nenhum step obscuro.
|