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,108 +1,108 @@
|
|
|
1
|
-
# Spec: orchestrate — o motor de orquestração (exploratória, 2.0)
|
|
2
|
-
|
|
3
|
-
- **ID**: SPEC-021
|
|
4
|
-
- **Status**: done
|
|
5
|
-
- **Owner**: apk
|
|
6
|
-
- **ADRs relacionadas**: ADR-0005 (handoff 7 campos), ADR-0019 (workspace), ADR-0020 (core/registry), SPEC-019 (topologia coerente), ADR-0023/0024/0029 (os gates), ADR-0009 (memória)
|
|
7
|
-
|
|
8
|
-
> **Exploratória.** O objetivo desta spec não é fechar o escopo — é tornar o conceito concreto o
|
|
9
|
-
> bastante para decidir o formato, e expor as decisões duras antes de virar plano. As perguntas
|
|
10
|
-
> abertas da §8 são o coração; as respostas remodelam o resto.
|
|
11
|
-
|
|
12
|
-
## 1. Problema
|
|
13
|
-
|
|
14
|
-
O nome do framework é **orquestração multiagente**. A SPEC-019 provou que a topologia é *coerente* —
|
|
15
|
-
mas orquestração coerente não é orquestração que **acontece**. Hoje um fluxo multi-papel (product →
|
|
16
|
-
architect → worker → governance) vive em três lugares soltos: a prosa do `AGENTS.md`, os handoffs
|
|
17
|
-
avulsos do `agent-router` (cada um independente, sem noção de cadeia), e a disciplina de quem lembra
|
|
18
|
-
de rodar `spec:check` entre uma etapa e outra. **Não existe uma cadeia que roda, gate a gate.** O
|
|
19
|
-
namesake é a última grande superfície que ainda vive por disciplina.
|
|
20
|
-
|
|
21
|
-
## 2. A tensão central (a decisão que organiza tudo)
|
|
22
|
-
|
|
23
|
-
**O framework não roda IA autonomamente.** Ele não pode "chamar o Claude e mandar implementar". Quem
|
|
24
|
-
executa o *trabalho* de cada papel é um agente de IA (sub-agent do Claude Code) ou um humano.
|
|
25
|
-
|
|
26
|
-
Então "orquestração que executa" **não** pode significar "o framework faz o trabalho". Significa:
|
|
27
|
-
|
|
28
|
-
> O framework é a **máquina de estados da cadeia de handoffs**, com **transições guardadas por
|
|
29
|
-
> gates**. Ele decompõe o objetivo, abre o handoff certo, roda o gate quando a etapa fecha, e — se o
|
|
30
|
-
> gate passa — abre a próxima; se falha, trava com o parecer. O *trabalho* dentro de cada etapa é de
|
|
31
|
-
> quem pega o handoff. **O framework orquestra e guarda; o agente executa.**
|
|
32
|
-
|
|
33
|
-
Isto é honesto (não finge autonomia de IA) e ainda assim é um motor de execução real: a cadeia
|
|
34
|
-
progride dirigida por **veredito de gate**, não por memória. É o pipeline SDD/GSD virado máquina.
|
|
35
|
-
|
|
36
|
-
## 3. Proposta de valor
|
|
37
|
-
|
|
38
|
-
Um objetivo vira uma **cadeia auditável e guardada**: cada etapa só abre quando a anterior passou no
|
|
39
|
-
seu gate. A pergunta "o processo foi seguido?" deixa de ser uma promessa e vira o estado de uma
|
|
40
|
-
máquina — e a governança do Forja chega ao próprio ato de orquestrar.
|
|
41
|
-
|
|
42
|
-
## 4. Formato proposto (v1 — a discutir)
|
|
43
|
-
|
|
44
|
-
```bash
|
|
45
|
-
forja orchestrate "adicionar pagamento pix" --slug pagamentos-pix
|
|
46
|
-
# → decompõe numa cadeia de handoffs (o runbook), abre a 1ª etapa
|
|
47
|
-
|
|
48
|
-
forja orchestrate:status pagamentos-pix
|
|
49
|
-
# → o estado da máquina: etapa aberta, feitas, bloqueadas, último veredito de gate
|
|
50
|
-
|
|
51
|
-
forja orchestrate:advance pagamentos-pix
|
|
52
|
-
# → o dono da etapa atual fez o trabalho; roda o GATE da etapa;
|
|
53
|
-
# verde → fecha o handoff + abre o próximo; vermelho → trava com o parecer
|
|
54
|
-
```
|
|
55
|
-
|
|
56
|
-
**A cadeia (v1, determinística — o pipeline SDD/GSD):**
|
|
57
|
-
|
|
58
|
-
| # | Papel | Etapa | Gate da transição |
|
|
59
|
-
|---|---|---|---|
|
|
60
|
-
| 1 | product | `spec` | `spec:check` (spec aprovada) |
|
|
61
|
-
| 2 | sdd-architect | `plan` | `spec:check` (plan aprovado) |
|
|
62
|
-
| 3 | sdd-architect | `tasks` | `spec:check` (tasks aprovado) |
|
|
63
|
-
| 4 | worker | `implement` | `project:check` / `code:check` |
|
|
64
|
-
| 5 | governance | `review` | `check:all` |
|
|
65
|
-
|
|
66
|
-
Cada transição é um handoff ADR-0005 (7 campos) gravado pelo `agent-router`, e cada `advance` é uma
|
|
67
|
-
linha na trilha de auditoria. A topologia coerente da SPEC-019 é o grafo que a máquina percorre.
|
|
68
|
-
|
|
69
|
-
## 5. Escopo
|
|
70
|
-
|
|
71
|
-
**Dentro (v1)**:
|
|
72
|
-
- A máquina de estados da cadeia (decompor → abrir → gate → avançar/travar), sobre o `agent-router`.
|
|
73
|
-
- Gates como transições: a etapa não avança sem o gate verde.
|
|
74
|
-
- `orchestrate` / `orchestrate:status` / `orchestrate:advance` no registry; tudo auditado.
|
|
75
|
-
|
|
76
|
-
**Fora (explícito — a fronteira honesta)**:
|
|
77
|
-
- **Rodar a IA que faz o trabalho de cada etapa.** Isso é o Claude Code (ou o humano) que pega o
|
|
78
|
-
handoff aberto. O framework abre a etapa e a guarda; não a executa.
|
|
79
|
-
- **Decomposição por LLM.** v1 usa a cadeia determinística do SDD/GSD — provável e auditável. Um
|
|
80
|
-
planejador de IA que monta cadeias sob medida é evolução, não a base.
|
|
81
|
-
- Paralelismo / cadeias ramificadas — v1 é linear. Ramos e fan-out ficam para depois.
|
|
82
|
-
|
|
83
|
-
## 6. Riscos
|
|
84
|
-
|
|
85
|
-
| Risco | Prob. | Impacto | Mitigação |
|
|
86
|
-
|---|---|---|---|
|
|
87
|
-
| Virar "só um wrapper do agent-router + gates" (pouco valor) | M | A | o valor é a **transição guardada** — a etapa que não avança sem o gate; isso não existe hoje |
|
|
88
|
-
| Acoplar ao Claude Code e ferir a promessa multi-IA | M | M | o motor é agnóstico: abre handoffs; *quem* os pega (Claude/humano/outra IA) é externo |
|
|
89
|
-
| Reimplementar o que o SDD já faz | B | M | compõe `spec:check`/`project:check`/`check:all` — não reimplementa gate nenhum |
|
|
90
|
-
|
|
91
|
-
## 7. Métricas de sucesso
|
|
92
|
-
|
|
93
|
-
Um objetivo levado do `orchestrate` até o `review` com **cada transição guardada por um gate verde**,
|
|
94
|
-
a corrida inteira reconstruível a partir do `forja-runs.jsonl` — e uma tentativa de pular etapa
|
|
95
|
-
(avançar com o gate vermelho) **bloqueada** pela máquina. A orquestração deixa de ser prosa.
|
|
96
|
-
|
|
97
|
-
## 8. Decisões (aprovadas)
|
|
98
|
-
|
|
99
|
-
1. **`advance` manual.** O dono da etapa roda `orchestrate:advance` quando terminou; o motor roda o
|
|
100
|
-
gate e decide. Acionar o sub-agent automaticamente fica para uma iteração futura — decidida com os
|
|
101
|
-
dados do uso manual.
|
|
102
|
-
2. **Roda onde é invocado (`cwd`).** Framework primeiro como dogfood; por construção da 1.6.2 (o
|
|
103
|
-
dispatcher propaga o cwd), o mesmo motor funciona num projeto consumidor sem código extra. O
|
|
104
|
-
estado vive em `<cwd>/.context/orchestrate-<slug>.json`, ao lado dos runbooks GSD.
|
|
105
|
-
3. **Cadeia determinística SDD/GSD no v1.** Auditável e provável. Planejador de IA é evolução.
|
|
106
|
-
4. **O motor é a v1.7.0** (aditivo, não quebra nada). O 2.0 fica para a limpeza breaking
|
|
107
|
-
(`dashboard/`, `projects/`, Node ≥22.6 formal) + o salto de identidade escolhido com os dados do
|
|
108
|
-
motor em uso.
|
|
1
|
+
# Spec: orchestrate — o motor de orquestração (exploratória, 2.0)
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-021
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Owner**: apk
|
|
6
|
+
- **ADRs relacionadas**: ADR-0005 (handoff 7 campos), ADR-0019 (workspace), ADR-0020 (core/registry), SPEC-019 (topologia coerente), ADR-0023/0024/0029 (os gates), ADR-0009 (memória)
|
|
7
|
+
|
|
8
|
+
> **Exploratória.** O objetivo desta spec não é fechar o escopo — é tornar o conceito concreto o
|
|
9
|
+
> bastante para decidir o formato, e expor as decisões duras antes de virar plano. As perguntas
|
|
10
|
+
> abertas da §8 são o coração; as respostas remodelam o resto.
|
|
11
|
+
|
|
12
|
+
## 1. Problema
|
|
13
|
+
|
|
14
|
+
O nome do framework é **orquestração multiagente**. A SPEC-019 provou que a topologia é *coerente* —
|
|
15
|
+
mas orquestração coerente não é orquestração que **acontece**. Hoje um fluxo multi-papel (product →
|
|
16
|
+
architect → worker → governance) vive em três lugares soltos: a prosa do `AGENTS.md`, os handoffs
|
|
17
|
+
avulsos do `agent-router` (cada um independente, sem noção de cadeia), e a disciplina de quem lembra
|
|
18
|
+
de rodar `spec:check` entre uma etapa e outra. **Não existe uma cadeia que roda, gate a gate.** O
|
|
19
|
+
namesake é a última grande superfície que ainda vive por disciplina.
|
|
20
|
+
|
|
21
|
+
## 2. A tensão central (a decisão que organiza tudo)
|
|
22
|
+
|
|
23
|
+
**O framework não roda IA autonomamente.** Ele não pode "chamar o Claude e mandar implementar". Quem
|
|
24
|
+
executa o *trabalho* de cada papel é um agente de IA (sub-agent do Claude Code) ou um humano.
|
|
25
|
+
|
|
26
|
+
Então "orquestração que executa" **não** pode significar "o framework faz o trabalho". Significa:
|
|
27
|
+
|
|
28
|
+
> O framework é a **máquina de estados da cadeia de handoffs**, com **transições guardadas por
|
|
29
|
+
> gates**. Ele decompõe o objetivo, abre o handoff certo, roda o gate quando a etapa fecha, e — se o
|
|
30
|
+
> gate passa — abre a próxima; se falha, trava com o parecer. O *trabalho* dentro de cada etapa é de
|
|
31
|
+
> quem pega o handoff. **O framework orquestra e guarda; o agente executa.**
|
|
32
|
+
|
|
33
|
+
Isto é honesto (não finge autonomia de IA) e ainda assim é um motor de execução real: a cadeia
|
|
34
|
+
progride dirigida por **veredito de gate**, não por memória. É o pipeline SDD/GSD virado máquina.
|
|
35
|
+
|
|
36
|
+
## 3. Proposta de valor
|
|
37
|
+
|
|
38
|
+
Um objetivo vira uma **cadeia auditável e guardada**: cada etapa só abre quando a anterior passou no
|
|
39
|
+
seu gate. A pergunta "o processo foi seguido?" deixa de ser uma promessa e vira o estado de uma
|
|
40
|
+
máquina — e a governança do Forja chega ao próprio ato de orquestrar.
|
|
41
|
+
|
|
42
|
+
## 4. Formato proposto (v1 — a discutir)
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
forja orchestrate "adicionar pagamento pix" --slug pagamentos-pix
|
|
46
|
+
# → decompõe numa cadeia de handoffs (o runbook), abre a 1ª etapa
|
|
47
|
+
|
|
48
|
+
forja orchestrate:status pagamentos-pix
|
|
49
|
+
# → o estado da máquina: etapa aberta, feitas, bloqueadas, último veredito de gate
|
|
50
|
+
|
|
51
|
+
forja orchestrate:advance pagamentos-pix
|
|
52
|
+
# → o dono da etapa atual fez o trabalho; roda o GATE da etapa;
|
|
53
|
+
# verde → fecha o handoff + abre o próximo; vermelho → trava com o parecer
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
**A cadeia (v1, determinística — o pipeline SDD/GSD):**
|
|
57
|
+
|
|
58
|
+
| # | Papel | Etapa | Gate da transição |
|
|
59
|
+
|---|---|---|---|
|
|
60
|
+
| 1 | product | `spec` | `spec:check` (spec aprovada) |
|
|
61
|
+
| 2 | sdd-architect | `plan` | `spec:check` (plan aprovado) |
|
|
62
|
+
| 3 | sdd-architect | `tasks` | `spec:check` (tasks aprovado) |
|
|
63
|
+
| 4 | worker | `implement` | `project:check` / `code:check` |
|
|
64
|
+
| 5 | governance | `review` | `check:all` |
|
|
65
|
+
|
|
66
|
+
Cada transição é um handoff ADR-0005 (7 campos) gravado pelo `agent-router`, e cada `advance` é uma
|
|
67
|
+
linha na trilha de auditoria. A topologia coerente da SPEC-019 é o grafo que a máquina percorre.
|
|
68
|
+
|
|
69
|
+
## 5. Escopo
|
|
70
|
+
|
|
71
|
+
**Dentro (v1)**:
|
|
72
|
+
- A máquina de estados da cadeia (decompor → abrir → gate → avançar/travar), sobre o `agent-router`.
|
|
73
|
+
- Gates como transições: a etapa não avança sem o gate verde.
|
|
74
|
+
- `orchestrate` / `orchestrate:status` / `orchestrate:advance` no registry; tudo auditado.
|
|
75
|
+
|
|
76
|
+
**Fora (explícito — a fronteira honesta)**:
|
|
77
|
+
- **Rodar a IA que faz o trabalho de cada etapa.** Isso é o Claude Code (ou o humano) que pega o
|
|
78
|
+
handoff aberto. O framework abre a etapa e a guarda; não a executa.
|
|
79
|
+
- **Decomposição por LLM.** v1 usa a cadeia determinística do SDD/GSD — provável e auditável. Um
|
|
80
|
+
planejador de IA que monta cadeias sob medida é evolução, não a base.
|
|
81
|
+
- Paralelismo / cadeias ramificadas — v1 é linear. Ramos e fan-out ficam para depois.
|
|
82
|
+
|
|
83
|
+
## 6. Riscos
|
|
84
|
+
|
|
85
|
+
| Risco | Prob. | Impacto | Mitigação |
|
|
86
|
+
|---|---|---|---|
|
|
87
|
+
| Virar "só um wrapper do agent-router + gates" (pouco valor) | M | A | o valor é a **transição guardada** — a etapa que não avança sem o gate; isso não existe hoje |
|
|
88
|
+
| Acoplar ao Claude Code e ferir a promessa multi-IA | M | M | o motor é agnóstico: abre handoffs; *quem* os pega (Claude/humano/outra IA) é externo |
|
|
89
|
+
| Reimplementar o que o SDD já faz | B | M | compõe `spec:check`/`project:check`/`check:all` — não reimplementa gate nenhum |
|
|
90
|
+
|
|
91
|
+
## 7. Métricas de sucesso
|
|
92
|
+
|
|
93
|
+
Um objetivo levado do `orchestrate` até o `review` com **cada transição guardada por um gate verde**,
|
|
94
|
+
a corrida inteira reconstruível a partir do `forja-runs.jsonl` — e uma tentativa de pular etapa
|
|
95
|
+
(avançar com o gate vermelho) **bloqueada** pela máquina. A orquestração deixa de ser prosa.
|
|
96
|
+
|
|
97
|
+
## 8. Decisões (aprovadas)
|
|
98
|
+
|
|
99
|
+
1. **`advance` manual.** O dono da etapa roda `orchestrate:advance` quando terminou; o motor roda o
|
|
100
|
+
gate e decide. Acionar o sub-agent automaticamente fica para uma iteração futura — decidida com os
|
|
101
|
+
dados do uso manual.
|
|
102
|
+
2. **Roda onde é invocado (`cwd`).** Framework primeiro como dogfood; por construção da 1.6.2 (o
|
|
103
|
+
dispatcher propaga o cwd), o mesmo motor funciona num projeto consumidor sem código extra. O
|
|
104
|
+
estado vive em `<cwd>/.context/orchestrate-<slug>.json`, ao lado dos runbooks GSD.
|
|
105
|
+
3. **Cadeia determinística SDD/GSD no v1.** Auditável e provável. Planejador de IA é evolução.
|
|
106
|
+
4. **O motor é a v1.7.0** (aditivo, não quebra nada). O 2.0 fica para a limpeza breaking
|
|
107
|
+
(`dashboard/`, `projects/`, Node ≥22.6 formal) + o salto de identidade escolhido com os dados do
|
|
108
|
+
motor em uso.
|
|
@@ -1,95 +1,95 @@
|
|
|
1
|
-
# Spec: orchestration-coherent
|
|
2
|
-
|
|
3
|
-
- **ID**: SPEC-019
|
|
4
|
-
- **Status**: done
|
|
5
|
-
- **Owner**: apk
|
|
6
|
-
- **ADRs relacionadas**: ADR-0021 (invariante > disciplina), ADR-0025 (coerência da doc — a mesma classe), ADR-0005 (handoff 7 campos), ADR-0020 (core/registry)
|
|
7
|
-
|
|
8
|
-
## 1. Problema
|
|
9
|
-
|
|
10
|
-
O nome do repositório é **orquestração multiagente** — e é a parte **menos harnessed** do framework.
|
|
11
|
-
A topologia de quem-orquestra-quem é descrita em **três lugares independentes**, e nada garante que
|
|
12
|
-
concordem:
|
|
13
|
-
|
|
14
|
-
1. `AGENTS.md` — a prosa: os papéis e a topologia.
|
|
15
|
-
2. `scripts/agent-router.ts` (`VALID_AGENTS`) — o código: para quem um handoff pode ser roteado.
|
|
16
|
-
3. `.claude/agents/*.md` — os sub-agents executáveis: quem, de fato, faz o trabalho.
|
|
17
|
-
|
|
18
|
-
Três descrições da mesma coisa divergem em silêncio. **E já divergem hoje** (medido antes de escrever
|
|
19
|
-
esta spec — a mesma prova que o `adr-refs` deu):
|
|
20
|
-
|
|
21
|
-
- **`worker`** está no `VALID_AGENTS` e no `AGENTS.md`, mas **não tem** `.claude/agent`. Um papel que
|
|
22
|
-
recebe handoff sem definição executável — prosa que o código não implementa.
|
|
23
|
-
- **`release-auditor`** é um sub-agent executável, mas **não está** no `VALID_AGENTS`. Um agente para
|
|
24
|
-
o qual o router não consegue rotear — implementação que a orquestração não alcança.
|
|
25
|
-
- **`architect`** (AGENTS.md) vs **`sdd-architect`** (router/agents) — o mesmo papel com dois nomes.
|
|
26
|
-
|
|
27
|
-
Pelo critério do ADR-0021, isto não é orquestração: é sugestão. A topologia vive por disciplina, e
|
|
28
|
-
está silenciosamente incoerente **agora**. Não é conhecimento que falta — é execução.
|
|
29
|
-
|
|
30
|
-
## 2. Proposta de valor
|
|
31
|
-
|
|
32
|
-
A topologia de agentes deixa de poder divergir em silêncio: **as três fontes de verdade
|
|
33
|
-
(AGENTS.md ↔ router ↔ .claude/agents) são conferidas por um gate**. Um papel sem agente executável,
|
|
34
|
-
um agente sem rota, um nome divergente — tudo reprova. A orquestração descrita passa a ser a
|
|
35
|
-
orquestração implementada.
|
|
36
|
-
|
|
37
|
-
## 3. User stories
|
|
38
|
-
|
|
39
|
-
- **Como** mantenedor, **quero** que um papel citado na topologia sem sub-agent executável **reprove**,
|
|
40
|
-
**para que** a orquestração não prometa um agente que não existe.
|
|
41
|
-
- **Como** mantenedor, **quero** que um sub-agent para o qual o router não roteia seja apontado,
|
|
42
|
-
**para que** eu não tenha implementação órfã que a orquestração nunca aciona.
|
|
43
|
-
- **Como** governança, **quero** rodar isso no `tools:doctor`, **para que** a coerência da topologia
|
|
44
|
-
seja um artefato verificável, não uma afirmação no README.
|
|
45
|
-
|
|
46
|
-
## 4. Critérios de aceite (Definition of Done)
|
|
47
|
-
|
|
48
|
-
- [ ] AC-1: Um check `agent-topology` (no catálogo do `tools:doctor`, via runner de `checks.ts`)
|
|
49
|
-
cruza as três fontes e **reprova** (ou avisa) quando divergem:
|
|
50
|
-
- papel roteável (`VALID_AGENTS`, menos `user`) **sem** `.claude/agents/<papel>.md` → o router
|
|
51
|
-
promete um destino que não tem executor;
|
|
52
|
-
- `.claude/agents/<x>.md` que **não** está em `VALID_AGENTS` → agente executável que ninguém roteia;
|
|
53
|
-
- papel citado no `AGENTS.md` que não bate com nenhuma das outras fontes → prosa órfã.
|
|
54
|
-
- [ ] AC-2: `user` é reconhecido como destino válido de handoff **sem** exigir um agent (é o humano —
|
|
55
|
-
não tem `.claude/agent`, e tudo bem).
|
|
56
|
-
- [ ] AC-3: O check roda no `tools:doctor` e reporta as divergências reais que já existem hoje
|
|
57
|
-
(`worker`, `release-auditor`, `architect`/`sdd-architect`) — a prova de que a fronteira estava
|
|
58
|
-
descoberta.
|
|
59
|
-
- [ ] AC-4: Fechada a incoerência: cada divergência resolvida (criar o agent, ajustar o router, ou
|
|
60
|
-
alinhar o nome) até o check ficar verde — decidido caso a caso, não no atacado.
|
|
61
|
-
- [ ] AC-5: Lógica pura e testável (extrai a topologia de fontes injetáveis; testes com fixtures).
|
|
62
|
-
|
|
63
|
-
## 5. Escopo
|
|
64
|
-
|
|
65
|
-
**Dentro**: conferir a **coerência estrutural** da topologia — os nomes de papéis/agentes batem entre
|
|
66
|
-
as três fontes.
|
|
67
|
-
|
|
68
|
-
**Fora** (explícito — a fronteira honesta):
|
|
69
|
-
- **Rodar os agentes de IA autonomamente.** O framework não executa um loop de IA; quem aciona os
|
|
70
|
-
sub-agents é o Claude Code, no uso. Este gate prova que a topologia é *coerente e acionável*, não
|
|
71
|
-
que a IA fez um bom trabalho. "Provar que a orquestração produz bom output" não é harness — é
|
|
72
|
-
julgamento, e fica fora.
|
|
73
|
-
- Validar o *conteúdo* de cada `.claude/agent` (o prompt está bom?) — é qualidade, não topologia.
|
|
74
|
-
- Um motor de execução de handoffs em cadeia (state machine que dirige o fluxo) — pode ser SPEC
|
|
75
|
-
futura; esta fecha a **coerência**, o pré-requisito de qualquer execução.
|
|
76
|
-
|
|
77
|
-
## 6. NFRs / restrições
|
|
78
|
-
|
|
79
|
-
- **Compatibilidade**: só lê as três fontes; não muda o comportamento do router nem dos agents.
|
|
80
|
-
- **Severidade honesta**: divergência que quebra a orquestração (papel roteável sem executor) =
|
|
81
|
-
provável `critical`/`warn` a decidir no plan; nome divergente = `warn`. A calibração fica para o
|
|
82
|
-
plan, à luz do que as divergências reais pedem.
|
|
83
|
-
|
|
84
|
-
## 7. Riscos e mitigação
|
|
85
|
-
|
|
86
|
-
| Risco | Prob. | Impacto | Mitigação |
|
|
87
|
-
|---|---|---|---|
|
|
88
|
-
| O check vira ruído (muitos avisos aceitáveis) | M | M | severidade calibrada no plan; `user` e casos legítimos isentos (AC-2) |
|
|
89
|
-
| Alinhar os nomes quebra referências em prosa | B | M | AC-4 resolve caso a caso, com o gate confirmando cada passo |
|
|
90
|
-
|
|
91
|
-
## 8. Métricas de sucesso
|
|
92
|
-
|
|
93
|
-
As três divergências de hoje (`worker`, `release-auditor`, `architect`/`sdd-architect`) resolvidas, o
|
|
94
|
-
`agent-topology` verde no `tools:doctor`, e uma futura divergência (um agent novo sem rota, um papel
|
|
95
|
-
renomeado) pega pelo gate antes do merge. A orquestração descrita = a orquestração implementada.
|
|
1
|
+
# Spec: orchestration-coherent
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-019
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Owner**: apk
|
|
6
|
+
- **ADRs relacionadas**: ADR-0021 (invariante > disciplina), ADR-0025 (coerência da doc — a mesma classe), ADR-0005 (handoff 7 campos), ADR-0020 (core/registry)
|
|
7
|
+
|
|
8
|
+
## 1. Problema
|
|
9
|
+
|
|
10
|
+
O nome do repositório é **orquestração multiagente** — e é a parte **menos harnessed** do framework.
|
|
11
|
+
A topologia de quem-orquestra-quem é descrita em **três lugares independentes**, e nada garante que
|
|
12
|
+
concordem:
|
|
13
|
+
|
|
14
|
+
1. `AGENTS.md` — a prosa: os papéis e a topologia.
|
|
15
|
+
2. `scripts/agent-router.ts` (`VALID_AGENTS`) — o código: para quem um handoff pode ser roteado.
|
|
16
|
+
3. `.claude/agents/*.md` — os sub-agents executáveis: quem, de fato, faz o trabalho.
|
|
17
|
+
|
|
18
|
+
Três descrições da mesma coisa divergem em silêncio. **E já divergem hoje** (medido antes de escrever
|
|
19
|
+
esta spec — a mesma prova que o `adr-refs` deu):
|
|
20
|
+
|
|
21
|
+
- **`worker`** está no `VALID_AGENTS` e no `AGENTS.md`, mas **não tem** `.claude/agent`. Um papel que
|
|
22
|
+
recebe handoff sem definição executável — prosa que o código não implementa.
|
|
23
|
+
- **`release-auditor`** é um sub-agent executável, mas **não está** no `VALID_AGENTS`. Um agente para
|
|
24
|
+
o qual o router não consegue rotear — implementação que a orquestração não alcança.
|
|
25
|
+
- **`architect`** (AGENTS.md) vs **`sdd-architect`** (router/agents) — o mesmo papel com dois nomes.
|
|
26
|
+
|
|
27
|
+
Pelo critério do ADR-0021, isto não é orquestração: é sugestão. A topologia vive por disciplina, e
|
|
28
|
+
está silenciosamente incoerente **agora**. Não é conhecimento que falta — é execução.
|
|
29
|
+
|
|
30
|
+
## 2. Proposta de valor
|
|
31
|
+
|
|
32
|
+
A topologia de agentes deixa de poder divergir em silêncio: **as três fontes de verdade
|
|
33
|
+
(AGENTS.md ↔ router ↔ .claude/agents) são conferidas por um gate**. Um papel sem agente executável,
|
|
34
|
+
um agente sem rota, um nome divergente — tudo reprova. A orquestração descrita passa a ser a
|
|
35
|
+
orquestração implementada.
|
|
36
|
+
|
|
37
|
+
## 3. User stories
|
|
38
|
+
|
|
39
|
+
- **Como** mantenedor, **quero** que um papel citado na topologia sem sub-agent executável **reprove**,
|
|
40
|
+
**para que** a orquestração não prometa um agente que não existe.
|
|
41
|
+
- **Como** mantenedor, **quero** que um sub-agent para o qual o router não roteia seja apontado,
|
|
42
|
+
**para que** eu não tenha implementação órfã que a orquestração nunca aciona.
|
|
43
|
+
- **Como** governança, **quero** rodar isso no `tools:doctor`, **para que** a coerência da topologia
|
|
44
|
+
seja um artefato verificável, não uma afirmação no README.
|
|
45
|
+
|
|
46
|
+
## 4. Critérios de aceite (Definition of Done)
|
|
47
|
+
|
|
48
|
+
- [ ] AC-1: Um check `agent-topology` (no catálogo do `tools:doctor`, via runner de `checks.ts`)
|
|
49
|
+
cruza as três fontes e **reprova** (ou avisa) quando divergem:
|
|
50
|
+
- papel roteável (`VALID_AGENTS`, menos `user`) **sem** `.claude/agents/<papel>.md` → o router
|
|
51
|
+
promete um destino que não tem executor;
|
|
52
|
+
- `.claude/agents/<x>.md` que **não** está em `VALID_AGENTS` → agente executável que ninguém roteia;
|
|
53
|
+
- papel citado no `AGENTS.md` que não bate com nenhuma das outras fontes → prosa órfã.
|
|
54
|
+
- [ ] AC-2: `user` é reconhecido como destino válido de handoff **sem** exigir um agent (é o humano —
|
|
55
|
+
não tem `.claude/agent`, e tudo bem).
|
|
56
|
+
- [ ] AC-3: O check roda no `tools:doctor` e reporta as divergências reais que já existem hoje
|
|
57
|
+
(`worker`, `release-auditor`, `architect`/`sdd-architect`) — a prova de que a fronteira estava
|
|
58
|
+
descoberta.
|
|
59
|
+
- [ ] AC-4: Fechada a incoerência: cada divergência resolvida (criar o agent, ajustar o router, ou
|
|
60
|
+
alinhar o nome) até o check ficar verde — decidido caso a caso, não no atacado.
|
|
61
|
+
- [ ] AC-5: Lógica pura e testável (extrai a topologia de fontes injetáveis; testes com fixtures).
|
|
62
|
+
|
|
63
|
+
## 5. Escopo
|
|
64
|
+
|
|
65
|
+
**Dentro**: conferir a **coerência estrutural** da topologia — os nomes de papéis/agentes batem entre
|
|
66
|
+
as três fontes.
|
|
67
|
+
|
|
68
|
+
**Fora** (explícito — a fronteira honesta):
|
|
69
|
+
- **Rodar os agentes de IA autonomamente.** O framework não executa um loop de IA; quem aciona os
|
|
70
|
+
sub-agents é o Claude Code, no uso. Este gate prova que a topologia é *coerente e acionável*, não
|
|
71
|
+
que a IA fez um bom trabalho. "Provar que a orquestração produz bom output" não é harness — é
|
|
72
|
+
julgamento, e fica fora.
|
|
73
|
+
- Validar o *conteúdo* de cada `.claude/agent` (o prompt está bom?) — é qualidade, não topologia.
|
|
74
|
+
- Um motor de execução de handoffs em cadeia (state machine que dirige o fluxo) — pode ser SPEC
|
|
75
|
+
futura; esta fecha a **coerência**, o pré-requisito de qualquer execução.
|
|
76
|
+
|
|
77
|
+
## 6. NFRs / restrições
|
|
78
|
+
|
|
79
|
+
- **Compatibilidade**: só lê as três fontes; não muda o comportamento do router nem dos agents.
|
|
80
|
+
- **Severidade honesta**: divergência que quebra a orquestração (papel roteável sem executor) =
|
|
81
|
+
provável `critical`/`warn` a decidir no plan; nome divergente = `warn`. A calibração fica para o
|
|
82
|
+
plan, à luz do que as divergências reais pedem.
|
|
83
|
+
|
|
84
|
+
## 7. Riscos e mitigação
|
|
85
|
+
|
|
86
|
+
| Risco | Prob. | Impacto | Mitigação |
|
|
87
|
+
|---|---|---|---|
|
|
88
|
+
| O check vira ruído (muitos avisos aceitáveis) | M | M | severidade calibrada no plan; `user` e casos legítimos isentos (AC-2) |
|
|
89
|
+
| Alinhar os nomes quebra referências em prosa | B | M | AC-4 resolve caso a caso, com o gate confirmando cada passo |
|
|
90
|
+
|
|
91
|
+
## 8. Métricas de sucesso
|
|
92
|
+
|
|
93
|
+
As três divergências de hoje (`worker`, `release-auditor`, `architect`/`sdd-architect`) resolvidas, o
|
|
94
|
+
`agent-topology` verde no `tools:doctor`, e uma futura divergência (um agent novo sem rota, um papel
|
|
95
|
+
renomeado) pega pelo gate antes do merge. A orquestração descrita = a orquestração implementada.
|
|
@@ -1,61 +1,61 @@
|
|
|
1
|
-
# Spec: pipeline-sdd-e-orquestracao
|
|
2
|
-
|
|
3
|
-
- **ID**: SPEC-001
|
|
4
|
-
- **Status**: done
|
|
5
|
-
- **Owner**: framework-team
|
|
6
|
-
- **Criado em**: 2026-05-10
|
|
7
|
-
- **Sprint alvo**: refator-2026-05
|
|
8
|
-
- **ADRs relacionadas**: ADR-0007 (SDD), ADR-0008 (sub-agents executáveis)
|
|
9
|
-
|
|
10
|
-
## 1. Problema
|
|
11
|
-
O framework declara "spec-driven" e "orquestração" no AGENTS.md mas não há mecânica: nenhum comando força spec antes de código, e os 6 papéis de AGENTS.md não têm sub-agents executáveis em `.claude/agents/`. Handoffs vivem como markdown manual em `memory/50-orchestration/handoffs/`. Resultado: cada agente reinventa formato, retrabalho alto, decisões perdidas.
|
|
12
|
-
|
|
13
|
-
## 2. Proposta de valor
|
|
14
|
-
Toda feature não-trivial passa por `spec → plan → tasks` validado por CLI, e tarefas são roteadas para sub-agents Claude com handoff rastreável em SQLite. Spec-driven e orquestração deixam de ser slogans.
|
|
15
|
-
|
|
16
|
-
## 3. User stories
|
|
17
|
-
- **Como** Product Agent, **quero** rascunhar uma spec em 5 min com template, **para que** o backlog tenha entrada estruturada
|
|
18
|
-
- **Como** SDD Architect, **quero** que `spec:plan` só funcione com spec aprovada, **para que** ninguém pule etapa
|
|
19
|
-
- **Como** Worker, **quero** receber handoff com 7 campos via tabela SQLite, **para que** eu não pesque contexto em markdown
|
|
20
|
-
- **Como** Governance Agent, **quero** rodar `project:check` que falha se há código novo sem spec ativa, **para que** dívida não se acumule
|
|
21
|
-
|
|
22
|
-
## 4. Critérios de aceite
|
|
23
|
-
- [x] AC-1: `npm run spec:new <feature>` cria diretório com spec.md preenchido a partir do template
|
|
24
|
-
- [x] AC-2: `npm run spec:plan` e `spec:tasks` só rodam se a fase anterior está `approved+`
|
|
25
|
-
- [x] AC-3: `npm run spec:check` lista status de todas as features e falha com exit≠0 se inconsistente
|
|
26
|
-
- [ ] AC-4: `.claude/agents/*.md` para 6 papéis funcionando como sub-agents
|
|
27
|
-
- [ ] AC-5: handoffs registrados em tabela SQLite (`universal.db.handoffs`) com 7 campos da ADR-0005
|
|
28
|
-
- [ ] AC-6: `agent:route` aceita handoff e dispara sub-agent correspondente
|
|
29
|
-
- [ ] AC-7: hook `UserPromptSubmit` injeta smart-context automaticamente
|
|
30
|
-
|
|
31
|
-
## 5. Escopo
|
|
32
|
-
**Dentro**:
|
|
33
|
-
- CLI `spec-cli.mjs` (new/plan/tasks/check)
|
|
34
|
-
- Templates em `specs/_templates/`
|
|
35
|
-
- 6 sub-agents em `.claude/agents/`
|
|
36
|
-
- Tabela `handoffs` no `universal.db` + script `agent-router.mjs`
|
|
37
|
-
- Hooks em `.claude/settings.json`
|
|
38
|
-
|
|
39
|
-
**Fora**:
|
|
40
|
-
- Embeddings semânticos (mantém FTS5)
|
|
41
|
-
- UI/dashboard interativo de specs
|
|
42
|
-
- Migrar handoffs antigos em markdown — só novos
|
|
43
|
-
- Sub-agents para outros provedores (Copilot, Gemini) — só Claude nesta rodada
|
|
44
|
-
|
|
45
|
-
## 6. NFRs
|
|
46
|
-
- Performance: `spec:check` < 500ms em 100 specs
|
|
47
|
-
- Compatibilidade: scripts npm existentes não quebram
|
|
48
|
-
- Segurança: nenhum script gera token/secret embedido
|
|
49
|
-
- Observabilidade: cada invocação de sub-agent loga em `60-runs/`
|
|
50
|
-
|
|
51
|
-
## 7. Riscos
|
|
52
|
-
| Risco | P | I | Mitigação |
|
|
53
|
-
|---|---|---|---|
|
|
54
|
-
| Hook UserPromptSubmit causa latência | M | M | Cache por hash do prompt + cap de bytes |
|
|
55
|
-
| Sub-agents disputam contexto | B | A | Roteamento explícito via handoff, sem broadcast |
|
|
56
|
-
| SDD vira burocracia | M | A | Lista clara em README de "quando NÃO precisa de spec" |
|
|
57
|
-
|
|
58
|
-
## 8. Métricas de sucesso (30d)
|
|
59
|
-
- ≥80% das features novas atravessam o pipeline completo
|
|
60
|
-
- 0 PRs mergeados com `spec:check` falhando
|
|
61
|
-
- Tempo médio spec→tasks < 1 dia
|
|
1
|
+
# Spec: pipeline-sdd-e-orquestracao
|
|
2
|
+
|
|
3
|
+
- **ID**: SPEC-001
|
|
4
|
+
- **Status**: done
|
|
5
|
+
- **Owner**: framework-team
|
|
6
|
+
- **Criado em**: 2026-05-10
|
|
7
|
+
- **Sprint alvo**: refator-2026-05
|
|
8
|
+
- **ADRs relacionadas**: ADR-0007 (SDD), ADR-0008 (sub-agents executáveis)
|
|
9
|
+
|
|
10
|
+
## 1. Problema
|
|
11
|
+
O framework declara "spec-driven" e "orquestração" no AGENTS.md mas não há mecânica: nenhum comando força spec antes de código, e os 6 papéis de AGENTS.md não têm sub-agents executáveis em `.claude/agents/`. Handoffs vivem como markdown manual em `memory/50-orchestration/handoffs/`. Resultado: cada agente reinventa formato, retrabalho alto, decisões perdidas.
|
|
12
|
+
|
|
13
|
+
## 2. Proposta de valor
|
|
14
|
+
Toda feature não-trivial passa por `spec → plan → tasks` validado por CLI, e tarefas são roteadas para sub-agents Claude com handoff rastreável em SQLite. Spec-driven e orquestração deixam de ser slogans.
|
|
15
|
+
|
|
16
|
+
## 3. User stories
|
|
17
|
+
- **Como** Product Agent, **quero** rascunhar uma spec em 5 min com template, **para que** o backlog tenha entrada estruturada
|
|
18
|
+
- **Como** SDD Architect, **quero** que `spec:plan` só funcione com spec aprovada, **para que** ninguém pule etapa
|
|
19
|
+
- **Como** Worker, **quero** receber handoff com 7 campos via tabela SQLite, **para que** eu não pesque contexto em markdown
|
|
20
|
+
- **Como** Governance Agent, **quero** rodar `project:check` que falha se há código novo sem spec ativa, **para que** dívida não se acumule
|
|
21
|
+
|
|
22
|
+
## 4. Critérios de aceite
|
|
23
|
+
- [x] AC-1: `npm run spec:new <feature>` cria diretório com spec.md preenchido a partir do template
|
|
24
|
+
- [x] AC-2: `npm run spec:plan` e `spec:tasks` só rodam se a fase anterior está `approved+`
|
|
25
|
+
- [x] AC-3: `npm run spec:check` lista status de todas as features e falha com exit≠0 se inconsistente
|
|
26
|
+
- [ ] AC-4: `.claude/agents/*.md` para 6 papéis funcionando como sub-agents
|
|
27
|
+
- [ ] AC-5: handoffs registrados em tabela SQLite (`universal.db.handoffs`) com 7 campos da ADR-0005
|
|
28
|
+
- [ ] AC-6: `agent:route` aceita handoff e dispara sub-agent correspondente
|
|
29
|
+
- [ ] AC-7: hook `UserPromptSubmit` injeta smart-context automaticamente
|
|
30
|
+
|
|
31
|
+
## 5. Escopo
|
|
32
|
+
**Dentro**:
|
|
33
|
+
- CLI `spec-cli.mjs` (new/plan/tasks/check)
|
|
34
|
+
- Templates em `specs/_templates/`
|
|
35
|
+
- 6 sub-agents em `.claude/agents/`
|
|
36
|
+
- Tabela `handoffs` no `universal.db` + script `agent-router.mjs`
|
|
37
|
+
- Hooks em `.claude/settings.json`
|
|
38
|
+
|
|
39
|
+
**Fora**:
|
|
40
|
+
- Embeddings semânticos (mantém FTS5)
|
|
41
|
+
- UI/dashboard interativo de specs
|
|
42
|
+
- Migrar handoffs antigos em markdown — só novos
|
|
43
|
+
- Sub-agents para outros provedores (Copilot, Gemini) — só Claude nesta rodada
|
|
44
|
+
|
|
45
|
+
## 6. NFRs
|
|
46
|
+
- Performance: `spec:check` < 500ms em 100 specs
|
|
47
|
+
- Compatibilidade: scripts npm existentes não quebram
|
|
48
|
+
- Segurança: nenhum script gera token/secret embedido
|
|
49
|
+
- Observabilidade: cada invocação de sub-agent loga em `60-runs/`
|
|
50
|
+
|
|
51
|
+
## 7. Riscos
|
|
52
|
+
| Risco | P | I | Mitigação |
|
|
53
|
+
|---|---|---|---|
|
|
54
|
+
| Hook UserPromptSubmit causa latência | M | M | Cache por hash do prompt + cap de bytes |
|
|
55
|
+
| Sub-agents disputam contexto | B | A | Roteamento explícito via handoff, sem broadcast |
|
|
56
|
+
| SDD vira burocracia | M | A | Lista clara em README de "quando NÃO precisa de spec" |
|
|
57
|
+
|
|
58
|
+
## 8. Métricas de sucesso (30d)
|
|
59
|
+
- ≥80% das features novas atravessam o pipeline completo
|
|
60
|
+
- 0 PRs mergeados com `spec:check` falhando
|
|
61
|
+
- Tempo médio spec→tasks < 1 dia
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
# Plan: Predictive Change Simulation
|
|
2
|
+
|
|
3
|
+
- **Spec**: ./spec.md
|
|
4
|
+
- **Status**: approved
|
|
5
|
+
- **Criado em**: 2026-09-01
|
|
6
|
+
|
|
7
|
+
## 1. Abordagem técnica
|
|
8
|
+
|
|
9
|
+
`scripts/simulate.ts`, adapter puro de composição (mesmo padrão de `scripts/engineer.ts`) — nenhum
|
|
10
|
+
pacote novo em `packages/engineering`, porque não há lógica de domínio nova aqui, só orquestração
|
|
11
|
+
de engines já existentes (`SandboxEngine`, `checkConstitution`, `assessRisk`).
|
|
12
|
+
|
|
13
|
+
Ciclo do sandbox usado (D1): `create({sourceRef: ref})` → `prepare` → `execute(testCommand)` →
|
|
14
|
+
`reject` → `destroy`. **Não** usa `validate`/`diff`/`promote` do `SandboxEngine` — esses passos
|
|
15
|
+
existem pra "modifiquei o worktree, quero decidir se aplico as mudanças na árvore real"; aqui o
|
|
16
|
+
worktree já nasce checked out no `ref` (nada é modificado depois), e a árvore real nunca deveria
|
|
17
|
+
receber nada desta simulação. `reject()` aceita o estado `'validating'` (onde a sessão fica logo
|
|
18
|
+
após `execute()`) — não precisa passar por `validate()` pra chegar lá. Isso torna
|
|
19
|
+
"nunca promove" uma propriedade estrutural do código (a função `promote()` simplesmente nunca é
|
|
20
|
+
chamada em lugar nenhum deste arquivo), não uma disciplina que dependeria de lembrar de não chamar.
|
|
21
|
+
|
|
22
|
+
## 2. Módulos afetados
|
|
23
|
+
|
|
24
|
+
| Caminho | Mudança | Risco |
|
|
25
|
+
|---|---|---|
|
|
26
|
+
| `scripts/simulate.ts` | novo — `forja simulate <ref>` | Médio — orquestra sandbox real + grafo temporário, mas cada peça já existe e testada |
|
|
27
|
+
| `lib/core/registry.ts` | 1 comando novo | Baixo |
|
|
28
|
+
| `test/simulate-cli.test.js` (novo) | fixture git isolada, verifica não-promoção e destruição do worktree | — |
|
|
29
|
+
|
|
30
|
+
## 3. Diagrama de fluxo
|
|
31
|
+
|
|
32
|
+
```text
|
|
33
|
+
forja simulate <ref> [--command "npm test"]
|
|
34
|
+
│
|
|
35
|
+
├─► SandboxEngine.create({sourceRef: ref}) — GitWorktreeBackend, worktree isolado real
|
|
36
|
+
├─► SandboxEngine.prepare
|
|
37
|
+
├─► SandboxEngine.execute({command}) — roda o teste DENTRO do worktree
|
|
38
|
+
│ │
|
|
39
|
+
│ ▼ (sessão em 'validating')
|
|
40
|
+
├─► SqliteMigrationRunner sobre um SQLite TEMPORÁRIO (mkdtemp, não getWorkspaceDbPath)
|
|
41
|
+
├─► GraphIndexer.sync(GitGraphDocumentSource(session.root)) — indexa o worktree isolado
|
|
42
|
+
├─► checkConstitution(constitution.json do worktree, arestas do grafo temporário)
|
|
43
|
+
├─► buildRiskInput(changedFiles, database-temporário) + assessRisk
|
|
44
|
+
│
|
|
45
|
+
├─► SandboxEngine.reject(session.id) — nunca promote()
|
|
46
|
+
└─► SandboxEngine.destroy(session.id) — sempre, mesmo em erro (try/finally)
|
|
47
|
+
│
|
|
48
|
+
▼
|
|
49
|
+
SimulationReport { testResult, architectureCheck, risk, recommendation }
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## 4. Contratos (CLI/Schema)
|
|
53
|
+
|
|
54
|
+
```ts
|
|
55
|
+
// scripts/simulate.ts
|
|
56
|
+
interface SimulationReport {
|
|
57
|
+
readonly ref: string;
|
|
58
|
+
readonly changedFiles: readonly string[];
|
|
59
|
+
readonly testCommand: string;
|
|
60
|
+
readonly testResult: { readonly exitCode: number; readonly durationMs: number; readonly passed: boolean };
|
|
61
|
+
readonly architectureCheck: ArchitectureCheckReport | { readonly note: string };
|
|
62
|
+
readonly risk: ChangeRiskAssessment;
|
|
63
|
+
readonly recommendation: 'promote' | 'review' | 'discard';
|
|
64
|
+
}
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
simulate <ref> [--command "npm test"] [--json]
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
## 5. Decisões e alternativas
|
|
72
|
+
|
|
73
|
+
**D1**: ciclo `create→prepare→execute→reject→destroy`, sem `validate`/`diff`/`promote` — ver §1.
|
|
74
|
+
Alternativa considerada: usar o ciclo completo de `runSandboxedCapability` — rejeitada porque esse
|
|
75
|
+
helper foi desenhado pra capabilities que **modificam** o worktree via `work()` e depois decidem
|
|
76
|
+
promover; aqui o "trabalho" é só checkout+teste, sem modificação, e a promoção nunca deveria
|
|
77
|
+
acontecer — usar o ciclo completo introduziria um caminho de código (`promote`) que não deveria
|
|
78
|
+
nunca ser exercitado, risco desnecessário pro que AC-3 exige.
|
|
79
|
+
|
|
80
|
+
**D2**: `changedFiles` vem de `git diff --name-only HEAD <ref>` (reaproveita
|
|
81
|
+
`lib/core/risk-collect.ts.changedFiles`, mesma função de `risk:assess`/`forja engineer`) — rodado
|
|
82
|
+
**antes** de criar o sandbox, contra a árvore real (só leitura, `git diff` não modifica nada).
|
|
83
|
+
|
|
84
|
+
**D3**: grafo + banco da simulação são **completamente isolados** do workspace real — SQLite em
|
|
85
|
+
`fs.mkdtempSync`, apontando `FORJA_GRAPH_ROOT` pro `session.root` só durante a chamada de
|
|
86
|
+
`buildRiskInput`/`checkConstitution` (restaurado no `finally`, mesmo em exceção). Alternativa
|
|
87
|
+
rejeitada: reaproveitar `getWorkspaceDbPath()` — violaria AC-2/NFR explicitamente (contaminaria o
|
|
88
|
+
grafo persistente com o estado de um ref que pode nunca ser integrado).
|
|
89
|
+
|
|
90
|
+
**D4**: `recommendation` — `discard` se o teste falhar (hard gate); senão `review` se houver
|
|
91
|
+
violação de arquitetura `active` OU `risk.autonomyBand` for `supervised`/`human_in_the_loop`;
|
|
92
|
+
senão `promote`. Mesma filosofia de "informa, não decide" de `RiskEngine` (SPEC-034 D3) —
|
|
93
|
+
`forja simulate` nunca aplica a mudança sozinho independente da recomendação.
|
|
94
|
+
|
|
95
|
+
## 6. Dependências
|
|
96
|
+
|
|
97
|
+
- SPEC-033 (`checkConstitution`), SPEC-034 (`assessRisk`/`buildRiskInput`, `lib/core/risk-collect.ts`)
|
|
98
|
+
— reaproveitados sem mudança.
|
|
99
|
+
- `packages/sandbox.SandboxEngine`/`packages/adapter-git.GitWorktreeBackend` — já existentes.
|
|
100
|
+
|
|
101
|
+
## 7. Rollout
|
|
102
|
+
|
|
103
|
+
Sem migração, sem feature flag — comando novo, opt-in.
|
|
104
|
+
|
|
105
|
+
## 8. Kill criteria
|
|
106
|
+
|
|
107
|
+
Se a recomendação não corresponder a julgamento humano sobre um ref real (§8 do spec), os pesos de
|
|
108
|
+
D4 são revisados antes de qualquer consumo automático futuro (fora de escopo desta spec de
|
|
109
|
+
qualquer forma, §5 "Fora").
|