forjajs 2.0.3 → 2.0.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude/agents/context-engineer.md +25 -25
- package/.claude/agents/governance.md +55 -55
- package/.claude/agents/marketing.md +24 -24
- package/.claude/agents/orchestrator.md +31 -31
- package/.claude/agents/product.md +26 -26
- package/.claude/agents/release-auditor.md +68 -59
- package/.claude/agents/sdd-architect.md +34 -34
- package/.claude/settings.json +76 -76
- package/.claude/skills/new-adr/SKILL.md +61 -61
- package/.claude/skills/new-command/SKILL.md +67 -67
- package/.gemini-instructions.md +87 -87
- package/.github/copilot-instructions.md +87 -87
- package/.memoryrc.json +104 -104
- package/.openai-instructions.md +87 -87
- package/AGENTS.md +134 -134
- package/CHANGELOG.md +566 -550
- package/CONTRIBUTING.md +32 -32
- package/DOC-MAP.md +65 -60
- package/LICENSE +21 -21
- package/README.md +358 -339
- package/README.pt-BR.md +345 -345
- package/boilerplates/01-api-rest/README.md +336 -336
- package/boilerplates/01-api-rest/boilerplate.manifest.json +41 -41
- package/boilerplates/02-saas-starter/.env.example +25 -25
- package/boilerplates/02-saas-starter/CHECKLIST-CRIACAO.md +190 -190
- package/boilerplates/02-saas-starter/INFO.md +252 -252
- package/boilerplates/02-saas-starter/QUICK_START.md +194 -194
- package/boilerplates/02-saas-starter/README.md +305 -305
- package/boilerplates/02-saas-starter/START-HERE.md +259 -259
- package/boilerplates/02-saas-starter/backend/package.json +87 -87
- package/boilerplates/02-saas-starter/backend/src/app.module.ts +27 -27
- package/boilerplates/02-saas-starter/backend/src/common/decorators/roles.decorator.ts +3 -3
- package/boilerplates/02-saas-starter/backend/src/common/decorators/tenant.decorator.ts +6 -6
- package/boilerplates/02-saas-starter/backend/src/common/middleware/roles.guard.ts +23 -23
- package/boilerplates/02-saas-starter/backend/src/config/database.ts +26 -26
- package/boilerplates/02-saas-starter/backend/src/main.ts +26 -26
- package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.controller.ts +46 -46
- package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.module.ts +25 -25
- package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.service.ts +145 -145
- package/boilerplates/02-saas-starter/backend/src/modules/auth/dto/auth.dto.ts +30 -30
- package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/jwt.strategy.ts +24 -24
- package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/local.strategy.ts +19 -19
- package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.controller.ts +42 -42
- package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.module.ts +13 -13
- package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.service.ts +67 -67
- package/boilerplates/02-saas-starter/backend/src/modules/billing/entities/invoice.entity.ts +52 -52
- package/boilerplates/02-saas-starter/backend/src/modules/organizations/entities/organization.entity.ts +36 -36
- package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.controller.ts +16 -16
- package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.module.ts +13 -13
- package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.service.ts +34 -34
- package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/entities/subscription.entity.ts +40 -40
- package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.controller.ts +36 -36
- package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.module.ts +13 -13
- package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.service.ts +91 -91
- package/boilerplates/02-saas-starter/backend/src/modules/users/entities/user.entity.ts +42 -42
- package/boilerplates/02-saas-starter/backend/src/modules/users/users.controller.ts +14 -14
- package/boilerplates/02-saas-starter/backend/src/modules/users/users.module.ts +13 -13
- package/boilerplates/02-saas-starter/backend/src/modules/users/users.service.ts +48 -48
- package/boilerplates/02-saas-starter/backend/tsconfig.json +28 -28
- package/boilerplates/02-saas-starter/boilerplate.manifest.json +42 -42
- package/boilerplates/02-saas-starter/docker-compose.yml +34 -34
- package/boilerplates/02-saas-starter/memory/00-global/agent-contract.md +227 -227
- package/boilerplates/02-saas-starter/memory/00-global/context-policy.md +141 -141
- package/boilerplates/02-saas-starter/memory/00-global/index.md +133 -133
- package/boilerplates/02-saas-starter/memory/00-global/mission.md +45 -45
- package/boilerplates/02-saas-starter/memory/00-global/patterns.md +223 -223
- package/boilerplates/02-saas-starter/memory/10-product/business-rules.md +240 -240
- package/boilerplates/02-saas-starter/memory/10-product/nfrs.md +239 -239
- package/boilerplates/02-saas-starter/memory/10-product/personas.md +195 -195
- package/boilerplates/02-saas-starter/memory/10-product/vision.md +63 -63
- package/boilerplates/02-saas-starter/memory/20-architecture/overview.md +232 -232
- package/boilerplates/02-saas-starter/memory/30-domains/auth/api.md +186 -186
- package/boilerplates/02-saas-starter/memory/30-domains/auth/context.md +85 -85
- package/boilerplates/02-saas-starter/memory/30-domains/billing/api.md +262 -262
- package/boilerplates/02-saas-starter/memory/30-domains/billing/context.md +137 -137
- package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/api.md +176 -176
- package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/context.md +100 -100
- package/boilerplates/02-saas-starter/memory/40-delivery/backlog.md +81 -81
- package/boilerplates/02-saas-starter/memory/40-delivery/roadmap.md +97 -97
- package/boilerplates/02-saas-starter/memory/40-delivery/sprint-atual.md +57 -57
- package/boilerplates/02-saas-starter/memory/50-orchestration/topology.md +90 -90
- package/boilerplates/02-saas-starter/memory/60-runs/index.md +54 -54
- package/boilerplates/02-saas-starter/memory/70-summaries/global.md +50 -50
- package/boilerplates/02-saas-starter/memory/80-data/schema.md +185 -185
- package/boilerplates/02-saas-starter/memory/90-decisions/adr-template.md +75 -75
- package/boilerplates/03-ecommerce-starter/FLOW_EXEMPLOS.md +599 -599
- package/boilerplates/03-ecommerce-starter/GUIA_RAPIDO.md +322 -322
- package/boilerplates/03-ecommerce-starter/MANIFEST.md +463 -463
- package/boilerplates/03-ecommerce-starter/README.md +465 -465
- package/boilerplates/03-ecommerce-starter/backend/.env.example +121 -121
- package/boilerplates/03-ecommerce-starter/backend/Dockerfile +15 -15
- package/boilerplates/03-ecommerce-starter/backend/docker-compose.yml +56 -56
- package/boilerplates/03-ecommerce-starter/backend/jest.config.js +16 -16
- package/boilerplates/03-ecommerce-starter/backend/package.json +71 -71
- package/boilerplates/03-ecommerce-starter/backend/src/app.controller.ts +12 -12
- package/boilerplates/03-ecommerce-starter/backend/src/app.module.ts +48 -48
- package/boilerplates/03-ecommerce-starter/backend/src/app.service.ts +12 -12
- package/boilerplates/03-ecommerce-starter/backend/src/main.ts +51 -51
- package/boilerplates/03-ecommerce-starter/backend/src/modules/auth/auth.module.ts +8 -8
- package/boilerplates/03-ecommerce-starter/backend/src/modules/cart/cart.module.ts +8 -8
- package/boilerplates/03-ecommerce-starter/backend/src/modules/coupons/coupons.module.ts +8 -8
- package/boilerplates/03-ecommerce-starter/backend/src/modules/inventory/inventory.module.ts +8 -8
- package/boilerplates/03-ecommerce-starter/backend/src/modules/orders/orders.module.ts +10 -10
- package/boilerplates/03-ecommerce-starter/backend/src/modules/payments/payments.module.ts +8 -8
- package/boilerplates/03-ecommerce-starter/backend/src/modules/products/dto/create-product.dto.ts +34 -34
- package/boilerplates/03-ecommerce-starter/backend/src/modules/products/entities/category.entity.ts +47 -47
- package/boilerplates/03-ecommerce-starter/backend/src/modules/products/entities/product.entity.ts +66 -66
- package/boilerplates/03-ecommerce-starter/backend/src/modules/products/products.controller.ts +78 -78
- package/boilerplates/03-ecommerce-starter/backend/src/modules/products/products.module.ts +14 -14
- package/boilerplates/03-ecommerce-starter/backend/src/modules/products/products.service.ts +112 -112
- package/boilerplates/03-ecommerce-starter/backend/src/modules/reviews/entities/review.entity.ts +32 -32
- package/boilerplates/03-ecommerce-starter/backend/src/modules/reviews/reviews.module.ts +11 -11
- package/boilerplates/03-ecommerce-starter/backend/test/health.e2e-spec.ts +31 -31
- package/boilerplates/03-ecommerce-starter/backend/test/jest-e2e.json +12 -12
- package/boilerplates/03-ecommerce-starter/backend/tsconfig.json +23 -23
- package/boilerplates/03-ecommerce-starter/boilerplate.manifest.json +42 -42
- package/boilerplates/03-ecommerce-starter/boilerplate.md +128 -128
- package/boilerplates/03-ecommerce-starter/memory/00-global/agent-contract.md +53 -53
- package/boilerplates/03-ecommerce-starter/memory/00-global/context-index.md +55 -55
- package/boilerplates/03-ecommerce-starter/memory/00-global/context-policy.md +31 -31
- package/boilerplates/03-ecommerce-starter/memory/00-global/mission.md +25 -25
- package/boilerplates/03-ecommerce-starter/memory/00-global/standards.md +45 -45
- package/boilerplates/03-ecommerce-starter/memory/10-product/business-rules.md +62 -62
- package/boilerplates/03-ecommerce-starter/memory/10-product/nfrs.md +62 -62
- package/boilerplates/03-ecommerce-starter/memory/10-product/vision.md +124 -124
- package/boilerplates/03-ecommerce-starter/memory/20-architecture/backend.md +253 -253
- package/boilerplates/03-ecommerce-starter/memory/20-architecture/observability.md +319 -319
- package/boilerplates/03-ecommerce-starter/memory/20-architecture/overview.md +133 -133
- package/boilerplates/03-ecommerce-starter/memory/20-architecture/security.md +227 -227
- package/boilerplates/03-ecommerce-starter/memory/30-domains/catalog/context.md +210 -210
- package/boilerplates/03-ecommerce-starter/memory/30-domains/inventory/context.md +233 -233
- package/boilerplates/03-ecommerce-starter/memory/30-domains/orders/context.md +210 -210
- package/boilerplates/03-ecommerce-starter/memory/30-domains/payments/context.md +168 -168
- package/boilerplates/03-ecommerce-starter/memory/80-data/sqlite.md +260 -260
- package/boilerplates/03-ecommerce-starter/memory/90-decisions/ADR-TEMPLATE.md +223 -223
- package/boilerplates/04-microservices-starter/.env.example +43 -43
- package/boilerplates/04-microservices-starter/API-EXAMPLES.md +609 -609
- package/boilerplates/04-microservices-starter/ARCHITECTURE.md +512 -512
- package/boilerplates/04-microservices-starter/GETTING-STARTED.md +246 -246
- package/boilerplates/04-microservices-starter/INDEX.md +377 -377
- package/boilerplates/04-microservices-starter/MANIFEST.md +456 -456
- package/boilerplates/04-microservices-starter/README.md +466 -466
- package/boilerplates/04-microservices-starter/SUMMARY.md +386 -386
- package/boilerplates/04-microservices-starter/backend/api-gateway/Dockerfile +14 -14
- package/boilerplates/04-microservices-starter/backend/api-gateway/package.json +29 -29
- package/boilerplates/04-microservices-starter/backend/api-gateway/src/app.module.ts +9 -9
- package/boilerplates/04-microservices-starter/backend/api-gateway/src/gateway.controller.ts +45 -45
- package/boilerplates/04-microservices-starter/backend/api-gateway/src/gateway.service.ts +114 -114
- package/boilerplates/04-microservices-starter/backend/api-gateway/src/main.ts +9 -9
- package/boilerplates/04-microservices-starter/backend/api-gateway/tsconfig.json +20 -20
- package/boilerplates/04-microservices-starter/backend/services/auth-service/Dockerfile +14 -14
- package/boilerplates/04-microservices-starter/backend/services/auth-service/package.json +42 -42
- package/boilerplates/04-microservices-starter/backend/services/auth-service/src/app.module.ts +7 -7
- package/boilerplates/04-microservices-starter/backend/services/auth-service/src/main.ts +9 -9
- package/boilerplates/04-microservices-starter/backend/services/auth-service/src/modules/auth/auth.controller.ts +130 -130
- package/boilerplates/04-microservices-starter/backend/services/auth-service/src/modules/auth/auth.module.ts +21 -21
- package/boilerplates/04-microservices-starter/backend/services/auth-service/src/modules/auth/auth.service.ts +159 -159
- package/boilerplates/04-microservices-starter/backend/services/auth-service/src/modules/auth/jwt.strategy.ts +19 -19
- package/boilerplates/04-microservices-starter/backend/services/auth-service/src/modules/auth/local.strategy.ts +18 -18
- package/boilerplates/04-microservices-starter/backend/services/auth-service/tsconfig.json +21 -21
- package/boilerplates/04-microservices-starter/backend/services/notification-service/Dockerfile +14 -14
- package/boilerplates/04-microservices-starter/backend/services/notification-service/package.json +25 -25
- package/boilerplates/04-microservices-starter/backend/services/notification-service/src/app.module.ts +7 -7
- package/boilerplates/04-microservices-starter/backend/services/notification-service/src/main.ts +9 -9
- package/boilerplates/04-microservices-starter/backend/services/notification-service/src/modules/notification/notification.controller.ts +160 -160
- package/boilerplates/04-microservices-starter/backend/services/notification-service/src/modules/notification/notification.module.ts +10 -10
- package/boilerplates/04-microservices-starter/backend/services/notification-service/src/modules/notification/notification.service.ts +92 -92
- package/boilerplates/04-microservices-starter/backend/services/notification-service/tsconfig.json +20 -20
- package/boilerplates/04-microservices-starter/backend/services/user-service/Dockerfile +14 -14
- package/boilerplates/04-microservices-starter/backend/services/user-service/package.json +25 -25
- package/boilerplates/04-microservices-starter/backend/services/user-service/src/app.module.ts +7 -7
- package/boilerplates/04-microservices-starter/backend/services/user-service/src/main.ts +9 -9
- package/boilerplates/04-microservices-starter/backend/services/user-service/src/modules/user/user.controller.ts +122 -122
- package/boilerplates/04-microservices-starter/backend/services/user-service/src/modules/user/user.module.ts +10 -10
- package/boilerplates/04-microservices-starter/backend/services/user-service/src/modules/user/user.service.ts +161 -161
- package/boilerplates/04-microservices-starter/backend/services/user-service/tsconfig.json +20 -20
- package/boilerplates/04-microservices-starter/backend/shared/package.json +15 -15
- package/boilerplates/04-microservices-starter/backend/shared/src/constants/index.ts +84 -84
- package/boilerplates/04-microservices-starter/backend/shared/src/decorators/index.ts +12 -12
- package/boilerplates/04-microservices-starter/backend/shared/src/index.ts +4 -4
- package/boilerplates/04-microservices-starter/backend/shared/src/interfaces/index.ts +152 -152
- package/boilerplates/04-microservices-starter/backend/shared/src/utils/index.ts +54 -54
- package/boilerplates/04-microservices-starter/backend/shared/tsconfig.json +20 -20
- package/boilerplates/04-microservices-starter/boilerplate.manifest.json +41 -41
- package/boilerplates/04-microservices-starter/docker-compose.yml +164 -164
- package/boilerplates/04-microservices-starter/memory/00-global/agent-contract.md +171 -171
- package/boilerplates/04-microservices-starter/memory/00-global/context-policy.md +89 -89
- package/boilerplates/04-microservices-starter/memory/00-global/index.md +102 -102
- package/boilerplates/04-microservices-starter/memory/00-global/mission.md +44 -44
- package/boilerplates/04-microservices-starter/memory/00-global/patterns.md +106 -106
- package/boilerplates/04-microservices-starter/memory/10-product/vision.md +76 -76
- package/boilerplates/04-microservices-starter/memory/20-architecture/overview.md +247 -247
- package/boilerplates/04-microservices-starter/memory/30-domains/auth-service/api.md +293 -293
- package/boilerplates/04-microservices-starter/memory/30-domains/auth-service/context.md +108 -108
- package/boilerplates/04-microservices-starter/memory/30-domains/notification-service/api.md +333 -333
- package/boilerplates/04-microservices-starter/memory/30-domains/notification-service/context.md +121 -121
- package/boilerplates/04-microservices-starter/memory/30-domains/user-service/api.md +308 -308
- package/boilerplates/04-microservices-starter/memory/30-domains/user-service/context.md +120 -120
- package/boilerplates/04-microservices-starter/memory/50-orchestration/topology.md +216 -216
- package/boilerplates/04-microservices-starter/package.json +21 -21
- package/boilerplates/05-monorepo-starter/.env.example +1 -1
- package/boilerplates/05-monorepo-starter/BOILERPLATE_SUMMARY.md +193 -193
- package/boilerplates/05-monorepo-starter/DEVELOPMENT.md +481 -481
- package/boilerplates/05-monorepo-starter/Dockerfile +35 -35
- package/boilerplates/05-monorepo-starter/README.md +318 -318
- package/boilerplates/05-monorepo-starter/boilerplate.manifest.json +43 -43
- package/boilerplates/05-monorepo-starter/docker-compose.yml +36 -36
- package/boilerplates/05-monorepo-starter/memory/00-global/agent-contract.md +28 -28
- package/boilerplates/05-monorepo-starter/memory/00-global/context-policy.md +21 -21
- package/boilerplates/05-monorepo-starter/memory/00-global/index.md +44 -44
- package/boilerplates/05-monorepo-starter/memory/00-global/mission.md +17 -17
- package/boilerplates/05-monorepo-starter/memory/00-global/patterns.md +48 -48
- package/boilerplates/05-monorepo-starter/memory/10-product/business-rules.md +24 -24
- package/boilerplates/05-monorepo-starter/memory/10-product/nfrs.md +39 -39
- package/boilerplates/05-monorepo-starter/memory/10-product/personas.md +25 -25
- package/boilerplates/05-monorepo-starter/memory/10-product/vision.md +22 -22
- package/boilerplates/05-monorepo-starter/memory/20-architecture/backend.md +85 -85
- package/boilerplates/05-monorepo-starter/memory/20-architecture/data.md +66 -66
- package/boilerplates/05-monorepo-starter/memory/20-architecture/frontend.md +58 -58
- package/boilerplates/05-monorepo-starter/memory/20-architecture/overview.md +86 -86
- package/boilerplates/05-monorepo-starter/memory/20-architecture/security.md +58 -58
- package/boilerplates/05-monorepo-starter/memory/30-domains/order/api.md +81 -81
- package/boilerplates/05-monorepo-starter/memory/30-domains/order/context.md +63 -63
- package/boilerplates/05-monorepo-starter/memory/30-domains/product/api.md +81 -81
- package/boilerplates/05-monorepo-starter/memory/30-domains/product/context.md +56 -56
- package/boilerplates/05-monorepo-starter/memory/30-domains/user/api.md +99 -99
- package/boilerplates/05-monorepo-starter/memory/30-domains/user/context.md +58 -58
- package/boilerplates/05-monorepo-starter/package.json +30 -30
- package/boilerplates/05-monorepo-starter/packages/apps/backend/.env.example +15 -15
- package/boilerplates/05-monorepo-starter/packages/apps/backend/README.md +28 -28
- package/boilerplates/05-monorepo-starter/packages/apps/backend/package.json +53 -53
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/app.module.ts +40 -40
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/common/exceptions/global.exception.ts +32 -32
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/common/guards/jwt.guard.ts +5 -5
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/common/guards/jwt.strategy.ts +11 -11
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/common/guards/roles.guard.ts +17 -17
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/common/health.controller.ts +13 -13
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/main.ts +28 -28
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/orders/dto/index.ts +23 -23
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/orders/entities/order.entity.ts +48 -48
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/orders/orders.controller.ts +51 -51
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/orders/orders.module.ts +13 -13
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/orders/orders.service.ts +123 -123
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/products/dto/index.ts +35 -35
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/products/entities/product.entity.ts +28 -28
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/products/products.controller.ts +49 -49
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/products/products.module.ts +12 -12
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/products/products.service.ts +79 -79
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/users/dto/index.ts +24 -24
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/users/entities/user.entity.ts +28 -28
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/users/users.controller.ts +29 -29
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/users/users.module.ts +15 -15
- package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/users/users.service.ts +78 -78
- package/boilerplates/05-monorepo-starter/packages/apps/backend/tsconfig.json +25 -25
- package/boilerplates/05-monorepo-starter/packages/apps/frontend/.env.example +1 -1
- package/boilerplates/05-monorepo-starter/packages/apps/frontend/README.md +30 -30
- package/boilerplates/05-monorepo-starter/packages/apps/frontend/app/dashboard/page.tsx +39 -39
- package/boilerplates/05-monorepo-starter/packages/apps/frontend/app/layout.tsx +15 -15
- package/boilerplates/05-monorepo-starter/packages/apps/frontend/app/page.tsx +47 -47
- package/boilerplates/05-monorepo-starter/packages/apps/frontend/app/products/page.tsx +51 -51
- package/boilerplates/05-monorepo-starter/packages/apps/frontend/components/features/product-card.tsx +19 -19
- package/boilerplates/05-monorepo-starter/packages/apps/frontend/components/layout/footer.tsx +10 -10
- package/boilerplates/05-monorepo-starter/packages/apps/frontend/components/layout/header.tsx +24 -24
- package/boilerplates/05-monorepo-starter/packages/apps/frontend/components/layout/layout.tsx +13 -13
- package/boilerplates/05-monorepo-starter/packages/apps/frontend/lib/api-client.ts +34 -34
- package/boilerplates/05-monorepo-starter/packages/apps/frontend/lib/auth.ts +35 -35
- package/boilerplates/05-monorepo-starter/packages/apps/frontend/lib/orders.ts +28 -28
- package/boilerplates/05-monorepo-starter/packages/apps/frontend/lib/products.ts +28 -28
- package/boilerplates/05-monorepo-starter/packages/apps/frontend/next.config.js +15 -15
- package/boilerplates/05-monorepo-starter/packages/apps/frontend/package.json +31 -31
- package/boilerplates/05-monorepo-starter/packages/apps/frontend/postcss.config.js +3 -3
- package/boilerplates/05-monorepo-starter/packages/apps/frontend/styles/globals.css +7 -7
- package/boilerplates/05-monorepo-starter/packages/apps/frontend/tailwind.config.js +7 -7
- package/boilerplates/05-monorepo-starter/packages/apps/frontend/tsconfig.json +14 -14
- package/boilerplates/05-monorepo-starter/packages/packages/shared-types/README.md +35 -35
- package/boilerplates/05-monorepo-starter/packages/packages/shared-types/package.json +17 -17
- package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/api/common.ts +18 -18
- package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/api/order.ts +38 -38
- package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/api/product.ts +33 -33
- package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/api/user.ts +32 -32
- package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/domain/index.ts +41 -41
- package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/errors/index.ts +46 -46
- package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/index.ts +7 -7
- package/boilerplates/05-monorepo-starter/packages/packages/shared-types/tsconfig.json +8 -8
- package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/README.md +30 -30
- package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/package.json +17 -17
- package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/constants/index.ts +45 -45
- package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/index.ts +4 -4
- package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/utils/index.ts +3 -3
- package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/utils/math.ts +30 -30
- package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/utils/string.ts +48 -48
- package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/validators/index.ts +44 -44
- package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/tsconfig.json +8 -8
- package/boilerplates/05-monorepo-starter/tsconfig.json +23 -23
- package/boilerplates/05-monorepo-starter/turbo.json +35 -35
- package/boilerplates/06-clean-arch/README.md +48 -48
- package/boilerplates/06-clean-arch/WHEN-CLEAN-WHEN-LEAN.md +71 -71
- package/boilerplates/06-clean-arch/backend/package.json +43 -43
- package/boilerplates/06-clean-arch/backend/src/app.module.ts +20 -20
- package/boilerplates/06-clean-arch/backend/src/main.ts +10 -10
- package/boilerplates/06-clean-arch/backend/src/modules/orders/application/place-order.usecase.ts +47 -47
- package/boilerplates/06-clean-arch/backend/src/modules/orders/application/ship-order.usecase.ts +28 -28
- package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/money.vo.ts +30 -30
- package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order-status.vo.ts +36 -36
- package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.entity.ts +85 -85
- package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.repository.ts +17 -17
- package/boilerplates/06-clean-arch/backend/src/modules/orders/infrastructure/order.orm-entity.ts +24 -24
- package/boilerplates/06-clean-arch/backend/src/modules/orders/infrastructure/typeorm-order.repository.ts +57 -57
- package/boilerplates/06-clean-arch/backend/src/modules/orders/orders.module.ts +28 -28
- package/boilerplates/06-clean-arch/backend/src/modules/orders/presentation/orders.controller.ts +31 -31
- package/boilerplates/06-clean-arch/backend/src/modules/orders/presentation/orders.http.dto.ts +30 -30
- package/boilerplates/06-clean-arch/backend/src/modules/products/product.entity.ts +20 -20
- package/boilerplates/06-clean-arch/backend/src/modules/products/products.controller.ts +43 -43
- package/boilerplates/06-clean-arch/backend/src/modules/products/products.module.ts +11 -11
- package/boilerplates/06-clean-arch/backend/src/shared/result.ts +32 -32
- package/boilerplates/06-clean-arch/backend/test/orders/place-order.spec.ts +46 -46
- package/boilerplates/06-clean-arch/backend/tsconfig.json +16 -16
- package/boilerplates/06-clean-arch/boilerplate.manifest.json +43 -43
- package/boilerplates/06-clean-arch/memory/30-domains/orders/context.md +39 -39
- package/boilerplates/06-clean-arch/memory/30-domains/products/context.md +23 -23
- package/boilerplates/README.md +427 -427
- package/design-md/BRIEF-TEMPLATE.md +47 -47
- package/design-md/INDEX.md +35 -35
- package/design-md/MATRIX.md +24 -24
- package/design-md/PLAYBOOK.md +35 -35
- package/design-md/examples/agent-console-brief.md +48 -48
- package/dist/apps/dashboard/app/dashboard-client.jsx +10 -10
- package/dist/bin/create-memory-nest-kit.js +17 -17
- package/dist/bin/forja.js +14 -2
- package/dist/bin/init-project.js +38 -38
- package/dist/lib/audit.js +7 -7
- package/dist/lib/context-builder.js +32 -32
- package/dist/lib/core/doc-graph.js +6 -4
- package/dist/lib/core/registry.d.ts +54 -0
- package/dist/lib/core/registry.js +55 -0
- package/dist/lib/core/release.d.ts +53 -0
- package/dist/lib/core/release.js +5 -1
- package/dist/lib/generators/memory-generator.js +700 -698
- package/dist/lib/generators/nest-generator.js +398 -398
- package/dist/lib/generators/readme-generator.js +180 -180
- package/dist/lib/governance-report.js +39 -39
- package/dist/lib/project-upgrade.js +1 -1
- package/dist/lib/workspace.d.ts +7 -0
- package/dist/lib/workspace.js +63 -34
- package/dist/packages/adapter-sqlite/src/index.js +12 -12
- package/dist/packages/llm/src/index.d.ts +43 -0
- package/dist/packages/llm/src/index.js +108 -0
- package/dist/scripts/agent-harness.js +66 -64
- package/dist/scripts/agent-router.js +20 -20
- package/dist/scripts/build-smart-context.js +22 -22
- package/dist/scripts/compress-memory.js +8 -8
- package/dist/scripts/context-ops.js +29 -29
- package/dist/scripts/demo-autonomy.js +2 -2
- package/dist/scripts/demo-workspace.d.ts +6 -0
- package/dist/scripts/demo-workspace.js +101 -0
- package/dist/scripts/dev.js +13 -13
- package/dist/scripts/extract-global-knowledge.js +5 -5
- package/dist/scripts/generate-dashboard.js +11 -11
- package/dist/scripts/llm-fit.js +131 -0
- package/dist/scripts/memory-schema.js +48 -48
- package/dist/scripts/query-universal-memory.js +13 -13
- package/dist/scripts/sprint-manager.js +39 -39
- package/dist/scripts/sync-universal-memory.js +63 -50
- package/docs/2x/CLI-CAPABILITIES.md +35 -35
- package/docs/2x/IMPLEMENTATION-AUDIT.md +40 -40
- package/docs/2x/SPRINT-1-CLI-CAPABILITY-PLAN.md +53 -53
- package/docs/2x/SPRINT-10-GRAPH-SYNC-PLAN.md +54 -54
- package/docs/2x/SPRINT-11-GRAPH-SYNC-CLI-MCP-PLAN.md +38 -38
- package/docs/2x/SPRINT-12-REAL-AUTONOMY-PLAN.md +40 -40
- package/docs/2x/SPRINT-13-MCP-STDIO-PLAN.md +26 -26
- package/docs/2x/SPRINT-14-SERVER-RESTART-PLAN.md +28 -28
- package/docs/2x/SPRINT-15-CHAOS-SECURITY-PLAN.md +22 -22
- package/docs/2x/SPRINT-16-LAST-MILE-PLAN.md +25 -25
- package/docs/2x/SPRINT-2-CLI-CAPABILITY-PLAN.md +39 -39
- package/docs/2x/SPRINT-3-RUNTIME-PERSISTENCE-PLAN.md +42 -42
- package/docs/2x/SPRINT-4-MCP-REGISTRY-PLAN.md +35 -35
- package/docs/2x/SPRINT-5-SERVER-APPROVALS-AUDIT-PLAN.md +31 -31
- package/docs/2x/SPRINT-6-EVENTS-E2E-PLAN.md +55 -55
- package/docs/2x/SPRINT-7-GRAPHLOOP-PERSISTENCE-PLAN.md +60 -60
- package/docs/2x/SPRINT-8-CONTEXT-GRAPH-PLAN.md +64 -64
- package/docs/2x/SPRINT-9-DETERMINISTIC-EXTRACTORS-PLAN.md +51 -51
- package/docs/GUIA-ONBOARDING-EXECUTIVO.md +63 -63
- package/docs/GUIA-ONBOARDING-OPERACIONAL-PAPEIS.md +136 -136
- package/docs/GUIA-ONBOARDING-PROJETO.md +279 -279
- package/docs/agent-harnesses.md +149 -149
- package/docs/architecture/FORJA-2.0-ARCHITECTURE.md +109 -109
- package/docs/architecture/FORJA-2.0-IMPACT-FOUNDATION.md +273 -273
- package/docs/archive/CHECKLIST-FINAL.md +295 -295
- package/docs/archive/FASE2-SUMMARY.md +263 -263
- package/docs/archive/FASE3-PROGRESS.md +355 -355
- package/docs/archive/IMPLEMENTACAO-FASE1.md +476 -476
- package/docs/archive/INDICE-MASTER.md +282 -282
- package/docs/archive/PROJETO-COMPLETO.md +363 -363
- package/docs/archive/README-REFINAMENTO.md +293 -293
- package/docs/archive/REFERENCIA-RAPIDA.md +324 -324
- package/docs/archive/REFINAMENTO-v1.0.md +565 -565
- package/docs/archive/RELATORIO-TESTES-INTEGRACAO.md +223 -223
- package/docs/archive/START-HERE.md +319 -319
- package/docs/archive/SUMARIO-EXECUTIVO.md +268 -268
- package/docs/archive/examples/v1/AGENTS.md +10 -10
- package/docs/archive/examples/v1/README.md +36 -36
- package/docs/archive/examples/v1/backend/jest-e2e.json +9 -9
- package/docs/archive/examples/v1/backend/nest-cli.json +4 -4
- package/docs/archive/examples/v1/backend/package.json +42 -42
- package/docs/archive/examples/v1/backend/src/app.controller.ts +12 -12
- package/docs/archive/examples/v1/backend/src/app.module.ts +10 -10
- package/docs/archive/examples/v1/backend/src/app.service.ts +8 -8
- package/docs/archive/examples/v1/backend/src/main.ts +10 -10
- package/docs/archive/examples/v1/backend/test/app.e2e-spec.ts +24 -24
- package/docs/archive/examples/v1/backend/tsconfig.build.json +4 -4
- package/docs/archive/examples/v1/backend/tsconfig.json +17 -17
- package/docs/archive/examples/v1/memory/00-global/glossary.md +5 -5
- package/docs/archive/examples/v1/memory/00-global/mission.md +9 -9
- package/docs/archive/examples/v1/memory/00-global/standards.md +12 -12
- package/docs/archive/examples/v1/memory/00-global/tooling.md +10 -10
- package/docs/archive/examples/v1/memory/10-product/business-rules.md +3 -3
- package/docs/archive/examples/v1/memory/10-product/nfrs.md +6 -6
- package/docs/archive/examples/v1/memory/10-product/personas.md +3 -3
- package/docs/archive/examples/v1/memory/10-product/vision.md +3 -3
- package/docs/archive/examples/v1/memory/20-architecture/backend.md +10 -10
- package/docs/archive/examples/v1/memory/20-architecture/data.md +3 -3
- package/docs/archive/examples/v1/memory/20-architecture/frontend.md +3 -3
- package/docs/archive/examples/v1/memory/20-architecture/observability.md +5 -5
- package/docs/archive/examples/v1/memory/20-architecture/security.md +6 -6
- package/docs/archive/examples/v1/memory/20-architecture/system-overview.md +3 -3
- package/docs/archive/examples/v1/memory/30-domains/auth/api.md +3 -3
- package/docs/archive/examples/v1/memory/30-domains/auth/context.md +3 -3
- package/docs/archive/examples/v1/memory/30-domains/auth/rules.md +3 -3
- package/docs/archive/examples/v1/memory/30-domains/billing/api.md +3 -3
- package/docs/archive/examples/v1/memory/30-domains/billing/context.md +3 -3
- package/docs/archive/examples/v1/memory/30-domains/billing/rules.md +3 -3
- package/docs/archive/examples/v1/memory/40-delivery/backlog.md +3 -3
- package/docs/archive/examples/v1/memory/40-delivery/current-sprint.md +10 -10
- package/docs/archive/examples/v1/memory/40-delivery/roadmap.md +3 -3
- package/docs/archive/examples/v1/memory/90-decisions/ADR-0001-template.md +9 -9
- package/docs/archive/examples/v1/prompts/project-prompt-base.md +19 -19
- package/docs/archive/examples/v2/.memoryrc.json +8 -8
- package/docs/archive/examples/v2/AGENTS.md +16 -16
- package/docs/archive/examples/v2/README.md +35 -35
- package/docs/archive/examples/v2/agents/README.md +3 -3
- package/docs/archive/examples/v2/agents/backend-nest.md +9 -9
- package/docs/archive/examples/v2/agents/dba.md +4 -4
- package/docs/archive/examples/v2/agents/frontend.md +4 -4
- package/docs/archive/examples/v2/agents/orchestrator.md +9 -9
- package/docs/archive/examples/v2/agents/reviewer.md +6 -6
- package/docs/archive/examples/v2/agents/security.md +4 -4
- package/docs/archive/examples/v2/backend/jest-e2e.json +9 -9
- package/docs/archive/examples/v2/backend/nest-cli.json +4 -4
- package/docs/archive/examples/v2/backend/package.json +42 -42
- package/docs/archive/examples/v2/backend/src/app.controller.ts +12 -12
- package/docs/archive/examples/v2/backend/src/app.module.ts +10 -10
- package/docs/archive/examples/v2/backend/src/app.service.ts +8 -8
- package/docs/archive/examples/v2/backend/src/main.ts +10 -10
- package/docs/archive/examples/v2/backend/test/app.e2e-spec.ts +24 -24
- package/docs/archive/examples/v2/backend/tsconfig.build.json +4 -4
- package/docs/archive/examples/v2/backend/tsconfig.json +17 -17
- package/docs/archive/examples/v2/memory/00-global/agent-contract.md +15 -15
- package/docs/archive/examples/v2/memory/00-global/context-index.md +12 -12
- package/docs/archive/examples/v2/memory/00-global/context-policy.md +14 -14
- package/docs/archive/examples/v2/memory/00-global/mission.md +9 -9
- package/docs/archive/examples/v2/memory/00-global/standards.md +12 -12
- package/docs/archive/examples/v2/memory/10-product/business-rules.md +3 -3
- package/docs/archive/examples/v2/memory/10-product/nfrs.md +6 -6
- package/docs/archive/examples/v2/memory/10-product/personas.md +3 -3
- package/docs/archive/examples/v2/memory/10-product/vision.md +3 -3
- package/docs/archive/examples/v2/memory/20-architecture/backend.md +10 -10
- package/docs/archive/examples/v2/memory/20-architecture/data.md +3 -3
- package/docs/archive/examples/v2/memory/20-architecture/frontend.md +3 -3
- package/docs/archive/examples/v2/memory/20-architecture/observability.md +5 -5
- package/docs/archive/examples/v2/memory/20-architecture/security.md +6 -6
- package/docs/archive/examples/v2/memory/20-architecture/system-overview.md +3 -3
- package/docs/archive/examples/v2/memory/30-domains/auth/api.md +3 -3
- package/docs/archive/examples/v2/memory/30-domains/auth/context.md +3 -3
- package/docs/archive/examples/v2/memory/30-domains/auth/rules.md +3 -3
- package/docs/archive/examples/v2/memory/30-domains/billing/api.md +3 -3
- package/docs/archive/examples/v2/memory/30-domains/billing/context.md +3 -3
- package/docs/archive/examples/v2/memory/30-domains/billing/rules.md +3 -3
- package/docs/archive/examples/v2/memory/40-delivery/backlog.md +3 -3
- package/docs/archive/examples/v2/memory/40-delivery/current-sprint.md +10 -10
- package/docs/archive/examples/v2/memory/40-delivery/roadmap.md +3 -3
- package/docs/archive/examples/v2/memory/50-orchestration/handoff-protocol.md +8 -8
- package/docs/archive/examples/v2/memory/50-orchestration/handoffs/2026-04-18T18-40-10.517Z_orchestrator_para_backend-nest.md +19 -19
- package/docs/archive/examples/v2/memory/50-orchestration/handoffs/README.md +4 -4
- package/docs/archive/examples/v2/memory/50-orchestration/parallel-playbook.md +9 -9
- package/docs/archive/examples/v2/memory/50-orchestration/routing.md +10 -10
- package/docs/archive/examples/v2/memory/50-orchestration/topology.md +15 -15
- package/docs/archive/examples/v2/memory/60-runs/README.md +3 -3
- package/docs/archive/examples/v2/memory/70-summaries/domain-summary.md +3 -3
- package/docs/archive/examples/v2/memory/70-summaries/global-summary.md +6 -6
- package/docs/archive/examples/v2/memory/90-decisions/ADR-0001-template.md +9 -9
- package/docs/archive/examples/v2/memory/README.md +8 -8
- package/docs/archive/examples/v2/prompts/multi-agent-orchestrator.md +12 -12
- package/docs/archive/examples/v2/prompts/project-prompt-base.md +21 -21
- package/docs/archive/examples/v2/prompts/worker-task-template.md +10 -10
- package/docs/archive/examples/v2/scripts/append-handoff.mjs +25 -25
- package/docs/archive/examples/v2/scripts/build-context-pack.mjs +31 -31
- package/docs/archive/examples/v2/skills/context-compaction/SKILL.md +9 -9
- package/docs/archive/examples/v2/skills/handoff/SKILL.md +8 -8
- package/docs/archive/examples/v2/skills/nest-api/SKILL.md +7 -7
- package/docs/archive/examples/v2/skills/triage-task/SKILL.md +10 -10
- package/docs/archive/legacy-bin/create-memory-nest-kit-monolith.js +1486 -1486
- package/docs/capacidades-externas.md +86 -86
- package/docs/cli-first-operacao.md +74 -74
- package/docs/dev-workflow.md +421 -421
- package/docs/examples.md +546 -546
- package/docs/fluxo.md +103 -103
- package/docs/glossary.md +453 -453
- package/docs/init-project.md +457 -457
- package/docs/llm-fit-loop.md +41 -0
- package/docs/manual-operacional-cli-sdd-gsd.md +1014 -1014
- package/docs/modos-de-operacao.md +52 -0
- package/docs/personas/architect/README.md +333 -333
- package/docs/personas/developer/README.md +371 -371
- package/docs/personas/executive/README.md +172 -172
- package/docs/personas/qa/README.md +350 -350
- package/docs/processo-projeto.md +138 -138
- package/docs/produto/factsheet-marketing.md +151 -0
- package/docs/produto/roteiro-demo.md +47 -0
- package/docs/publishing.md +377 -377
- package/docs/quick-reference.md +409 -409
- package/docs/security/FORJA-2.0-RELEASE-AUDIT-2026-08-01.md +95 -95
- package/docs/structure.md +360 -360
- package/docs/token-optimization.md +502 -502
- package/docs/vision/FORJA-2.0-VISION.md +72 -72
- package/memory/00-global/mission.md +15 -15
- package/memory/00-global/shared-knowledge.md +8 -8
- package/memory/00-global/standards.md +47 -47
- package/memory/10-product/personas.md +21 -21
- package/memory/10-product/vision.md +27 -27
- package/memory/30-projects/README.md +15 -15
- package/memory/40-delivery/backlog.md +15 -15
- package/memory/40-delivery/current-sprint.md +23 -26
- package/memory/50-orchestration/gsd-harness.md +55 -55
- package/memory/50-orchestration/handoffs/2026-07-31_architect_foundation-contracts.md +15 -15
- package/memory/50-orchestration/handoffs/2026-07-31_backend-nest.md +22 -22
- package/memory/50-orchestration/handoffs/2026-07-31_context-engine.md +16 -16
- package/memory/50-orchestration/handoffs/2026-07-31_control-plane.md +28 -28
- package/memory/50-orchestration/handoffs/2026-07-31_core-capability-registry.md +15 -15
- package/memory/50-orchestration/handoffs/2026-07-31_evals-plugin-sdk.md +22 -22
- package/memory/50-orchestration/handoffs/2026-07-31_events-scheduler.md +16 -16
- package/memory/50-orchestration/handoffs/2026-07-31_graphloop.md +16 -16
- package/memory/50-orchestration/handoffs/2026-07-31_mcp.md +21 -21
- package/memory/50-orchestration/handoffs/2026-07-31_nest-bootstrap.md +28 -28
- package/memory/50-orchestration/handoffs/2026-07-31_next-dashboard.md +22 -22
- package/memory/50-orchestration/handoffs/2026-07-31_observability.md +27 -27
- package/memory/50-orchestration/handoffs/2026-07-31_orchestration.md +21 -21
- package/memory/50-orchestration/handoffs/2026-07-31_planner-validator.md +16 -16
- package/memory/50-orchestration/handoffs/2026-07-31_policy-engine.md +14 -14
- package/memory/50-orchestration/handoffs/2026-07-31_runtime-control-plane.md +23 -23
- package/memory/50-orchestration/handoffs/2026-07-31_runtime-controlado.md +15 -15
- package/memory/50-orchestration/handoffs/2026-07-31_sandbox.md +21 -21
- package/memory/50-orchestration/handoffs/2026-07-31_sdk.md +27 -27
- package/memory/50-orchestration/handoffs/2026-07-31_sqlite-adapter.md +21 -21
- package/memory/50-orchestration/handoffs/2026-07-31_worker-dashboard-boundary.md +23 -23
- package/memory/50-orchestration/handoffs/2026-08-01_approval-server-identity.md +23 -23
- package/memory/50-orchestration/handoffs/2026-08-01_dashboard-auth-query.md +24 -24
- package/memory/50-orchestration/handoffs/2026-08-01_graphloop-approvals.md +23 -23
- package/memory/50-orchestration/handoffs/2026-08-01_sprint-1-cli-capabilities.md +41 -41
- package/memory/50-orchestration/handoffs/2026-08-01_sprint-10-graph-sync.md +23 -23
- package/memory/50-orchestration/handoffs/2026-08-01_sprint-11-graph-sync-cli-mcp.md +22 -22
- package/memory/50-orchestration/handoffs/2026-08-01_sprint-12-real-autonomy.md +16 -16
- package/memory/50-orchestration/handoffs/2026-08-01_sprint-2-cli-capabilities.md +30 -30
- package/memory/50-orchestration/handoffs/2026-08-01_sprint-3-runtime-persistence.md +29 -29
- package/memory/50-orchestration/handoffs/2026-08-01_sprint-4-mcp.md +29 -29
- package/memory/50-orchestration/handoffs/2026-08-01_sprint-5-server-approvals-audit.md +22 -22
- package/memory/50-orchestration/handoffs/2026-08-01_sprint-6-events-e2e.md +25 -25
- package/memory/50-orchestration/handoffs/2026-08-01_sprint-7-graphloop.md +23 -23
- package/memory/50-orchestration/handoffs/2026-08-01_sprint-8-context-graph.md +23 -23
- package/memory/50-orchestration/handoffs/2026-08-01_sprint-9-extractors.md +21 -21
- package/memory/50-orchestration/handoffs/2026-08-02_sprint-13-mcp-stdio.md +14 -14
- package/memory/50-orchestration/handoffs/2026-08-02_sprint-14-server-restart.md +15 -15
- package/memory/50-orchestration/handoffs/2026-08-02_sprint-15-chaos-security.md +13 -13
- package/memory/50-orchestration/handoffs/2026-08-02_sprint-16-last-mile.md +11 -11
- package/memory/90-decisions/0001-memoria-hierarquica.md +38 -38
- package/memory/90-decisions/0002-sqlite-fts5-busca.md +25 -25
- package/memory/90-decisions/0003-smart-context-3-modos.md +31 -31
- package/memory/90-decisions/0004-validacao-obrigatoria-nest.md +27 -27
- package/memory/90-decisions/0005-handoff-7-campos.md +32 -32
- package/memory/90-decisions/0006-docs-por-persona.md +23 -23
- package/memory/90-decisions/0007-sdd-pipeline.md +33 -33
- package/memory/90-decisions/0008-sub-agents-claude-handoff-sqlite.md +36 -36
- package/memory/90-decisions/0009-claude-hooks-token-economy.md +43 -43
- package/memory/90-decisions/0010-banco-postgres.md +30 -30
- package/memory/90-decisions/0011-adrs-de-produto-realocadas.md +19 -19
- package/memory/90-decisions/0016-integracao-capacidades-externas.md +64 -64
- package/memory/90-decisions/0017-codegraph-no-harness-gsd.md +40 -40
- package/memory/90-decisions/0018-ferramentas-de-processo.md +46 -46
- package/memory/90-decisions/0019-workspace-separado.md +45 -45
- package/memory/90-decisions/0020-forja-core-cli-unica.md +45 -45
- package/memory/90-decisions/0021-guardrails-de-harness.md +111 -111
- package/memory/90-decisions/0022-congelar-dashboard-web.md +101 -101
- package/memory/90-decisions/0023-doctor-como-gate-do-nucleo.md +114 -114
- package/memory/90-decisions/0024-gate-do-tarball.md +103 -103
- package/memory/90-decisions/0025-coerencia-da-documentacao.md +105 -105
- package/memory/90-decisions/0026-migracao-typescript-runtime-duplo.md +66 -66
- package/memory/90-decisions/0027-clean-arch-calibrada.md +127 -127
- package/memory/90-decisions/0028-governanca-visivel.md +84 -84
- package/memory/90-decisions/0029-gate-do-projeto-gerado.md +59 -59
- package/memory/90-decisions/0030-projeto-gerado-herda-os-gates.md +53 -53
- package/memory/90-decisions/0031-motor-de-orquestracao.md +55 -55
- package/memory/90-decisions/0032-superficies-do-projeto-usam-cwd.md +63 -63
- package/memory/90-decisions/0033-doctor-distingue-permissao-de-corrupcao.md +64 -64
- package/memory/90-decisions/0034-forja-2-core-e-contratos.md +29 -29
- package/memory/90-decisions/0035-forja-2-local-first-e-autonomia.md +23 -23
- package/memory/90-decisions/0036-forja-2-capability-registry.md +30 -30
- package/memory/90-decisions/0037-forja-2-policy-engine-obrigatorio.md +28 -28
- package/memory/90-decisions/0038-forja-2-runtime-controlado.md +28 -28
- package/memory/90-decisions/0039-forja-2-event-bus-scheduler-local-first.md +31 -31
- package/memory/90-decisions/0040-forja-2-context-engine-budget-cache.md +32 -32
- package/memory/90-decisions/0041-forja-2-graphloop-separado-codegraph.md +32 -32
- package/memory/90-decisions/0042-forja-2-planner-validator-independentes.md +29 -29
- package/memory/90-decisions/0043-forja-2-orchestration-entities.md +16 -16
- package/memory/90-decisions/0044-forja-2-sandbox-worktree.md +19 -19
- package/memory/90-decisions/0045-forja-2-sqlite-adapter.md +19 -19
- package/memory/90-decisions/0046-forja-2-mcp-adapter.md +18 -18
- package/memory/90-decisions/0047-forja-2-backend-nest-adapter.md +19 -19
- package/memory/90-decisions/0048-forja-2-sdk-transport.md +18 -18
- package/memory/90-decisions/0049-forja-2-observability-control-plane.md +18 -18
- package/memory/90-decisions/0050-forja-2-control-plane-application-ports.md +18 -18
- package/memory/90-decisions/0051-forja-2-runtime-control-plane-composition.md +18 -18
- package/memory/90-decisions/0052-forja-2-deterministic-evaluation.md +15 -15
- package/memory/90-decisions/0053-forja-2-plugin-sdk-permissionado.md +16 -16
- package/memory/90-decisions/0054-forja-2-worker-dashboard-boundary.md +15 -15
- package/memory/90-decisions/0055-forja-2-next-dashboard-distribution.md +16 -16
- package/memory/90-decisions/0056-forja-2-dashboard-proxy-auth-query.md +16 -16
- package/memory/90-decisions/0057-forja-2-graphloop-approvals-dashboard.md +15 -15
- package/memory/90-decisions/0058-forja-2-approval-server-identity.md +15 -15
- package/memory/90-decisions/0059-cli-adapter-capability-registry.md +17 -17
- package/memory/90-decisions/0060-runtime-persistence-port.md +17 -17
- package/memory/90-decisions/0061-mcp-dynamic-registry-stdio.md +16 -16
- package/memory/90-decisions/0062-server-catalog-approval-audit.md +17 -17
- package/memory/90-decisions/0063-events-persistent-e2e.md +19 -19
- package/memory/90-decisions/0064-graphloop-sqlite-store.md +20 -20
- package/memory/90-decisions/0065-context-graph-source-cache.md +20 -20
- package/memory/90-decisions/0066-graph-deterministic-extractors.md +16 -16
- package/memory/90-decisions/0067-graph-sync-capability.md +17 -17
- package/memory/90-decisions/0068-graph-sync-cli-mcp.md +17 -17
- package/memory/90-decisions/0069-real-autonomy-demo.md +16 -16
- package/memory/90-decisions/0070-mcp-stdio-real.md +11 -11
- package/memory/90-decisions/0071-server-persistence-composition.md +12 -12
- package/memory/90-decisions/0072-sandbox-security-boundaries.md +9 -9
- package/memory/90-decisions/0073-last-mile-rollback-benchmark-plugins.md +17 -17
- package/memory/90-decisions/0074-llm-fit-loop-cli-adapters.md +51 -0
- package/memory/90-decisions/0075-workspace-demo-isolado.md +43 -0
- package/memory/90-decisions/0076-modos-embedded-e-studio.md +43 -0
- package/memory/90-decisions/_template.md +28 -28
- package/package.json +157 -150
- package/prompts/context-engineer-agent.md +19 -19
- package/prompts/governance-agent.md +16 -16
- package/prompts/marketing-agent.md +13 -13
- package/prompts/orchestrator-agent.md +18 -18
- package/prompts/product-agent.md +13 -13
- package/prompts/sdd-architect-agent.md +20 -20
- package/specs/README.md +70 -70
- package/specs/_templates/plan.md +43 -43
- package/specs/_templates/spec.md +43 -43
- package/specs/_templates/tasks.md +32 -32
- package/specs/clean-arch-boilerplate/plan.md +137 -137
- package/specs/clean-arch-boilerplate/spec.md +121 -121
- package/specs/clean-arch-boilerplate/tasks.md +70 -70
- package/specs/cli-first-operacao/plan.md +53 -53
- package/specs/cli-first-operacao/spec.md +53 -53
- package/specs/cli-first-operacao/tasks.md +53 -53
- package/specs/code-context/spec.md +56 -56
- package/specs/coerencia-do-sistema/plan.md +155 -155
- package/specs/coerencia-do-sistema/spec.md +123 -123
- package/specs/coerencia-do-sistema/tasks.md +115 -115
- package/specs/dev-token-assets-db/plan.md +71 -71
- package/specs/dev-token-assets-db/spec.md +58 -58
- package/specs/dev-token-assets-db/tasks.md +58 -58
- package/specs/doctor-do-nucleo/plan.md +165 -165
- package/specs/doctor-do-nucleo/spec.md +139 -139
- package/specs/doctor-do-nucleo/tasks.md +172 -172
- package/specs/forja-core/spec.md +71 -71
- package/specs/gates/spec.md +63 -63
- package/specs/governanca-visivel/plan.md +122 -122
- package/specs/governanca-visivel/spec.md +112 -112
- package/specs/governanca-visivel/tasks.md +60 -60
- package/specs/harness-codegraph/spec.md +71 -71
- package/specs/memory-audit/spec.md +54 -54
- package/specs/orchestrate/spec.md +108 -108
- package/specs/orchestration-coherent/spec.md +95 -95
- package/specs/pipeline-sdd-e-orquestracao/spec.md +61 -61
- package/specs/project-smoke/spec.md +96 -96
- package/specs/project-upgrade/spec.md +58 -58
- package/specs/reestruturacao-forja-v2/plan.md +95 -95
- package/specs/reestruturacao-forja-v2/spec.md +74 -74
- package/specs/reestruturacao-forja-v2/tasks.md +113 -113
- package/specs/release-auditor-health/plan.md +88 -0
- package/specs/release-auditor-health/spec.md +82 -0
- package/specs/release-auditor-health/tasks.md +72 -0
- package/specs/release-gate/plan.md +174 -174
- package/specs/release-gate/spec.md +122 -122
- package/specs/release-gate/tasks.md +183 -183
- package/specs/ts-migration/plan.md +200 -200
- package/specs/ts-migration/spec.md +119 -119
- package/specs/ts-migration/tasks.md +110 -110
- package/dist/scripts/server-persistence-probe.d.ts +0 -1
- package/dist/scripts/server-persistence-probe.js +0 -52
- package/dist/scripts/server-persistence-probe.mjs +0 -52
- /package/dist/scripts/{server-persistence-probe.d.mts → llm-fit.d.ts} +0 -0
|
@@ -1,502 +1,502 @@
|
|
|
1
|
-
# 🎯 Token Optimization Guide
|
|
2
|
-
|
|
3
|
-
**Target**: 40-60% reduction in tokens per agent session through smart context, caching, and compression.
|
|
4
|
-
|
|
5
|
-
## Hooks ativos (ADR-0009)
|
|
6
|
-
|
|
7
|
-
| Hook | Quando dispara | O que faz |
|
|
8
|
-
|---|---|---|
|
|
9
|
-
| `SessionStart` → `scripts/hook-session-start.mjs` | Início da sessão Claude Code | Injeta status de specs e handoffs abertos (`additionalContext`) |
|
|
10
|
-
| `UserPromptSubmit` → `scripts/hook-user-prompt.mjs` | A cada prompt do usuário | **Opt-in**: só roda com `FRAMEWORK_HOOK_INJECT=1` e prompt casando triggers (`implement`, `refactor`, `spec:`, …). Cache TTL 30min |
|
|
11
|
-
| `pre-commit` (passos 6-7) | Antes de cada commit | `spec:check` + `check-standards`; bloqueia se inconsistente |
|
|
12
|
-
|
|
13
|
-
Para ativar a injeção automática de smart-context:
|
|
14
|
-
|
|
15
|
-
```bash
|
|
16
|
-
export FRAMEWORK_HOOK_INJECT=1
|
|
17
|
-
```
|
|
18
|
-
|
|
19
|
-
Caps em `.memoryrc.json::hooks.userPromptCap` (default 4KB). Cache em `/tmp/framework-hook-cache/`.
|
|
20
|
-
|
|
21
|
-
---
|
|
22
|
-
|
|
23
|
-
## 📊 Current State Analysis
|
|
24
|
-
|
|
25
|
-
### Baseline Metrics (Before Optimization)
|
|
26
|
-
|
|
27
|
-
| Metric | Value | Impact |
|
|
28
|
-
|--------|-------|--------|
|
|
29
|
-
| Average context size | 150-200 KB | High token cost |
|
|
30
|
-
| Files loaded per session | 30-50 | Redundant data |
|
|
31
|
-
| Cache hit rate | 0% | No reuse |
|
|
32
|
-
| Database size | 2.1 MB | Includes old logs |
|
|
33
|
-
| Compression | None | No optimization |
|
|
34
|
-
|
|
35
|
-
### Target After Optimization
|
|
36
|
-
|
|
37
|
-
| Metric | Current | Target | Savings |
|
|
38
|
-
|--------|---------|--------|---------|
|
|
39
|
-
| Context size | 150 KB | 60 KB | 60% ✅ |
|
|
40
|
-
| Files loaded | 40 | 15-20 | 50% |
|
|
41
|
-
| Cache hit rate | 0% | 70% | - |
|
|
42
|
-
| Database size | 2.1 MB | < 1 MB | 50% |
|
|
43
|
-
| Token cost | $0.015 | $0.006 | 60% ✅ |
|
|
44
|
-
|
|
45
|
-
---
|
|
46
|
-
|
|
47
|
-
## 🔧 3-Mode Context Strategy
|
|
48
|
-
|
|
49
|
-
### Mode 1: Global (Fastest - 2KB, ~500 tokens)
|
|
50
|
-
|
|
51
|
-
**Use case**: Startup, configuration decisions, standards
|
|
52
|
-
|
|
53
|
-
**Loads**:
|
|
54
|
-
- `mission.md` — Project mission
|
|
55
|
-
- `standards.md` — Code/doc standards
|
|
56
|
-
- `ADR-*` — Last 3 architecture decisions
|
|
57
|
-
- `.memoryrc.json` — Config
|
|
58
|
-
|
|
59
|
-
**Cost**: $0.0001 per request
|
|
60
|
-
|
|
61
|
-
```bash
|
|
62
|
-
node lib/context-builder.js global my-project
|
|
63
|
-
```
|
|
64
|
-
|
|
65
|
-
---
|
|
66
|
-
|
|
67
|
-
### Mode 2: Domain (Standard - 20KB, ~5000 tokens)
|
|
68
|
-
|
|
69
|
-
**Use case**: Feature development, architectural work
|
|
70
|
-
|
|
71
|
-
**Loads**:
|
|
72
|
-
- All from **Global**
|
|
73
|
-
- `vision.md` — Product vision
|
|
74
|
-
- `design-md/INDEX.md` — Design decisions
|
|
75
|
-
- `rules.md` — Business rules
|
|
76
|
-
- `[domain]/api.md` — Domain-specific API
|
|
77
|
-
- Recent `summary.md` files
|
|
78
|
-
|
|
79
|
-
**Cost**: $0.005 per request
|
|
80
|
-
|
|
81
|
-
```bash
|
|
82
|
-
node lib/context-builder.js domain my-project
|
|
83
|
-
```
|
|
84
|
-
|
|
85
|
-
---
|
|
86
|
-
|
|
87
|
-
### Mode 3: Task (Optimized - 30-40KB, ~8000 tokens)
|
|
88
|
-
|
|
89
|
-
**Use case**: Specific features, debugging, handoffs
|
|
90
|
-
|
|
91
|
-
**Loads**:
|
|
92
|
-
- All from **Domain**
|
|
93
|
-
- FTS5 search results for keyword
|
|
94
|
-
- Deduplicates overlaps
|
|
95
|
-
- Prunes unused sections
|
|
96
|
-
|
|
97
|
-
**Cost**: $0.008 per request
|
|
98
|
-
|
|
99
|
-
```bash
|
|
100
|
-
node lib/context-builder.js task my-project "auth backend"
|
|
101
|
-
```
|
|
102
|
-
|
|
103
|
-
---
|
|
104
|
-
|
|
105
|
-
## 🧠 Smart Context - How It Works
|
|
106
|
-
|
|
107
|
-
```
|
|
108
|
-
┌─────────────────────────────────────┐
|
|
109
|
-
│ User Query: "Implement JWT auth" │
|
|
110
|
-
└────────────┬────────────────────────┘
|
|
111
|
-
│
|
|
112
|
-
▼
|
|
113
|
-
┌─────────────────────────────────────┐
|
|
114
|
-
│ 1. Parse keyword: "JWT", "auth" │
|
|
115
|
-
└────────────┬────────────────────────┘
|
|
116
|
-
│
|
|
117
|
-
▼
|
|
118
|
-
┌─────────────────────────────────────┐
|
|
119
|
-
│ 2. Check cache: Hit? → Return │
|
|
120
|
-
│ Miss? → Continue │
|
|
121
|
-
└────────────┬────────────────────────┘
|
|
122
|
-
│
|
|
123
|
-
▼
|
|
124
|
-
┌─────────────────────────────────────┐
|
|
125
|
-
│ 3. FTS5 search in memory_nodes │
|
|
126
|
-
│ Find: auth-service, jwt-spec, │
|
|
127
|
-
│ security-adr, etc (10 files) │
|
|
128
|
-
└────────────┬────────────────────────┘
|
|
129
|
-
│
|
|
130
|
-
▼
|
|
131
|
-
┌─────────────────────────────────────┐
|
|
132
|
-
│ 4. Add domain + global context │
|
|
133
|
-
│ Total: ~20 files (deduped) │
|
|
134
|
-
└────────────┬────────────────────────┘
|
|
135
|
-
│
|
|
136
|
-
▼
|
|
137
|
-
┌─────────────────────────────────────┐
|
|
138
|
-
│ 5. Rank by relevance + recency │
|
|
139
|
-
│ Keep top 15 (by token budget) │
|
|
140
|
-
└────────────┬────────────────────────┘
|
|
141
|
-
│
|
|
142
|
-
▼
|
|
143
|
-
┌─────────────────────────────────────┐
|
|
144
|
-
│ 6. Generate markdown + cache │
|
|
145
|
-
│ ~30KB context (8000 tokens) │
|
|
146
|
-
└────────────┬────────────────────────┘
|
|
147
|
-
│
|
|
148
|
-
▼
|
|
149
|
-
┌─────────────────────────────────────┐
|
|
150
|
-
│ 7. Send to agent (from cache ✅) │
|
|
151
|
-
└─────────────────────────────────────┘
|
|
152
|
-
```
|
|
153
|
-
|
|
154
|
-
---
|
|
155
|
-
|
|
156
|
-
## 📦 Compression Strategy
|
|
157
|
-
|
|
158
|
-
### Step 1: Archive Old Logs (30 days)
|
|
159
|
-
|
|
160
|
-
```bash
|
|
161
|
-
npm run memory:vacuum
|
|
162
|
-
```
|
|
163
|
-
|
|
164
|
-
**What happens**:
|
|
165
|
-
- Logs > 30 days moved to `.memory/archive/`
|
|
166
|
-
- Deleted from active DB
|
|
167
|
-
- Database VACUUM'd
|
|
168
|
-
|
|
169
|
-
**Expected savings**: 30-40% of DB size
|
|
170
|
-
|
|
171
|
-
### Step 2: Clean Cache (7-day TTL)
|
|
172
|
-
|
|
173
|
-
```bash
|
|
174
|
-
node scripts/compress-memory.mjs
|
|
175
|
-
```
|
|
176
|
-
|
|
177
|
-
**What happens**:
|
|
178
|
-
- Expired cache files deleted
|
|
179
|
-
- Empty nodes removed
|
|
180
|
-
- Index rebuilt
|
|
181
|
-
|
|
182
|
-
**Expected savings**: 20-30% more
|
|
183
|
-
|
|
184
|
-
### Step 3: Optimize Memory Runs
|
|
185
|
-
|
|
186
|
-
**Manual audit**:
|
|
187
|
-
```bash
|
|
188
|
-
# Find biggest runs
|
|
189
|
-
du -sh .memory/runs/* | sort -h | tail -10
|
|
190
|
-
|
|
191
|
-
# Archive manually if needed
|
|
192
|
-
mv .memory/runs/old-run-* .memory/archive/
|
|
193
|
-
```
|
|
194
|
-
|
|
195
|
-
---
|
|
196
|
-
|
|
197
|
-
## 💾 Configuration (.memoryrc.json)
|
|
198
|
-
|
|
199
|
-
### Set Token Limits
|
|
200
|
-
|
|
201
|
-
```json
|
|
202
|
-
{
|
|
203
|
-
"tokenLimits": {
|
|
204
|
-
"global": 2000,
|
|
205
|
-
"domain": 5000,
|
|
206
|
-
"task": 8000,
|
|
207
|
-
"buffer": 500
|
|
208
|
-
}
|
|
209
|
-
}
|
|
210
|
-
```
|
|
211
|
-
|
|
212
|
-
### Compression Settings
|
|
213
|
-
|
|
214
|
-
```json
|
|
215
|
-
{
|
|
216
|
-
"compression": {
|
|
217
|
-
"archiveAge": 30,
|
|
218
|
-
"maxDbSize": 50,
|
|
219
|
-
"cacheTtl": 7,
|
|
220
|
-
"vacuumInterval": 86400000
|
|
221
|
-
}
|
|
222
|
-
}
|
|
223
|
-
```
|
|
224
|
-
|
|
225
|
-
### Cache Strategy
|
|
226
|
-
|
|
227
|
-
```json
|
|
228
|
-
{
|
|
229
|
-
"context": {
|
|
230
|
-
"cache": {
|
|
231
|
-
"enabled": true,
|
|
232
|
-
"ttl": 604800000,
|
|
233
|
-
"location": ".context/cache",
|
|
234
|
-
"strategy": "lru"
|
|
235
|
-
}
|
|
236
|
-
}
|
|
237
|
-
}
|
|
238
|
-
```
|
|
239
|
-
|
|
240
|
-
---
|
|
241
|
-
|
|
242
|
-
## 📈 Benchmarking
|
|
243
|
-
|
|
244
|
-
### Run Benchmark
|
|
245
|
-
|
|
246
|
-
```bash
|
|
247
|
-
npm run token:benchmark
|
|
248
|
-
```
|
|
249
|
-
|
|
250
|
-
**What it does**:
|
|
251
|
-
1. Generate all 3 context modes
|
|
252
|
-
2. Measure size, token count, generation time
|
|
253
|
-
3. Compare with baseline
|
|
254
|
-
4. Report savings %
|
|
255
|
-
|
|
256
|
-
**Output example**:
|
|
257
|
-
```
|
|
258
|
-
📊 Token Economy Benchmark
|
|
259
|
-
|
|
260
|
-
Mode: global
|
|
261
|
-
Size: 2.1 KB
|
|
262
|
-
Tokens: 525
|
|
263
|
-
Time: 45ms
|
|
264
|
-
|
|
265
|
-
Mode: domain
|
|
266
|
-
Size: 18.5 KB
|
|
267
|
-
Tokens: 4625
|
|
268
|
-
Time: 120ms
|
|
269
|
-
|
|
270
|
-
Mode: task (keyword: "auth")
|
|
271
|
-
Size: 31.2 KB
|
|
272
|
-
Tokens: 7800
|
|
273
|
-
Time: 180ms
|
|
274
|
-
|
|
275
|
-
Summary:
|
|
276
|
-
✅ 52% reduction vs original (full context)
|
|
277
|
-
✅ 70% cache hit rate
|
|
278
|
-
✅ Average generation: 115ms
|
|
279
|
-
💰 Cost savings: $0.009/request
|
|
280
|
-
```
|
|
281
|
-
|
|
282
|
-
---
|
|
283
|
-
|
|
284
|
-
## 🎯 Optimization Techniques
|
|
285
|
-
|
|
286
|
-
### 1. Deduplication
|
|
287
|
-
|
|
288
|
-
**Problem**: Same files loaded in multiple modes.
|
|
289
|
-
|
|
290
|
-
**Solution**:
|
|
291
|
-
```javascript
|
|
292
|
-
const seenPaths = new Set();
|
|
293
|
-
for (const node of nodes) {
|
|
294
|
-
if (seenPaths.has(node.path)) continue; // Skip
|
|
295
|
-
seenPaths.add(node.path);
|
|
296
|
-
// Add to context
|
|
297
|
-
}
|
|
298
|
-
```
|
|
299
|
-
|
|
300
|
-
**Savings**: 20-30%
|
|
301
|
-
|
|
302
|
-
---
|
|
303
|
-
|
|
304
|
-
### 2. Priority Weighting
|
|
305
|
-
|
|
306
|
-
**Problem**: Not all files equally important.
|
|
307
|
-
|
|
308
|
-
**Solution**:
|
|
309
|
-
```javascript
|
|
310
|
-
const priorities = {
|
|
311
|
-
'mission.md': 10,
|
|
312
|
-
'vision.md': 8,
|
|
313
|
-
'rules.md': 6,
|
|
314
|
-
'design-md/': 5,
|
|
315
|
-
'implementation/': 2
|
|
316
|
-
};
|
|
317
|
-
```
|
|
318
|
-
|
|
319
|
-
**Savings**: 15-25%
|
|
320
|
-
|
|
321
|
-
---
|
|
322
|
-
|
|
323
|
-
### 3. Time Decay
|
|
324
|
-
|
|
325
|
-
**Problem**: Old files still included equally.
|
|
326
|
-
|
|
327
|
-
**Solution**:
|
|
328
|
-
```javascript
|
|
329
|
-
const age = (now - node.updatedAt) / (1000 * 60 * 60 * 24); // days
|
|
330
|
-
const weight = Math.exp(-age / 30); // Decay over 30 days
|
|
331
|
-
if (weight < 0.1) skip(); // Drop very old files
|
|
332
|
-
```
|
|
333
|
-
|
|
334
|
-
**Savings**: 10-20%
|
|
335
|
-
|
|
336
|
-
---
|
|
337
|
-
|
|
338
|
-
### 4. Relevance Ranking
|
|
339
|
-
|
|
340
|
-
**Problem**: FTS5 results not always ranked best.
|
|
341
|
-
|
|
342
|
-
**Solution**:
|
|
343
|
-
```javascript
|
|
344
|
-
const relevanceScore =
|
|
345
|
-
(titleMatch * 3) +
|
|
346
|
-
(contentMatch * 1) +
|
|
347
|
-
(recencyBoost * 0.5) +
|
|
348
|
-
(domainMatch * 2);
|
|
349
|
-
|
|
350
|
-
nodes.sort((a, b) => b.score - a.score);
|
|
351
|
-
nodes = nodes.slice(0, maxFiles); // Keep top N
|
|
352
|
-
```
|
|
353
|
-
|
|
354
|
-
**Savings**: 25-40%
|
|
355
|
-
|
|
356
|
-
---
|
|
357
|
-
|
|
358
|
-
## 🚀 Integration with Agent Workflow
|
|
359
|
-
|
|
360
|
-
### For Backend Worker
|
|
361
|
-
|
|
362
|
-
```javascript
|
|
363
|
-
import ContextBuilder from '../lib/context-builder.js';
|
|
364
|
-
|
|
365
|
-
// On task start
|
|
366
|
-
const builder = new ContextBuilder(process.cwd(), dbPath);
|
|
367
|
-
const context = builder.build('task', 'my-project', 'backend auth');
|
|
368
|
-
const stats = builder.stats('task', 'my-project', 'backend auth');
|
|
369
|
-
|
|
370
|
-
console.log(`📊 Using ${stats.tokens} tokens (cost: $${stats.estimatedCost})`);
|
|
371
|
-
|
|
372
|
-
// Send context to agent
|
|
373
|
-
await agent.exec(task, context);
|
|
374
|
-
|
|
375
|
-
builder.close();
|
|
376
|
-
```
|
|
377
|
-
|
|
378
|
-
### For Frontend Worker
|
|
379
|
-
|
|
380
|
-
```javascript
|
|
381
|
-
// More domain-focused
|
|
382
|
-
const context = builder.build('domain', 'my-project');
|
|
383
|
-
```
|
|
384
|
-
|
|
385
|
-
### For Orchestrator
|
|
386
|
-
|
|
387
|
-
```javascript
|
|
388
|
-
// Global context only (faster handoff)
|
|
389
|
-
const context = builder.build('global', 'my-project');
|
|
390
|
-
```
|
|
391
|
-
|
|
392
|
-
---
|
|
393
|
-
|
|
394
|
-
## 📋 Pre-Flight Checklist
|
|
395
|
-
|
|
396
|
-
- [ ] `.memoryrc.json` created with token limits
|
|
397
|
-
- [ ] `lib/context-builder.js` integrated
|
|
398
|
-
- [ ] `scripts/compress-memory.mjs` tested
|
|
399
|
-
- [ ] Cache directory created: `.context/cache/`
|
|
400
|
-
- [ ] Archive directory created: `.memory/archive/`
|
|
401
|
-
- [ ] FTS5 index enabled in universal.db
|
|
402
|
-
- [ ] Benchmark run: `npm run token:benchmark`
|
|
403
|
-
- [ ] Savings > 40%? Deploy!
|
|
404
|
-
|
|
405
|
-
---
|
|
406
|
-
|
|
407
|
-
## 🎓 Common Patterns
|
|
408
|
-
|
|
409
|
-
### Scenario 1: Feature Development
|
|
410
|
-
|
|
411
|
-
```bash
|
|
412
|
-
# Developer needs feature context
|
|
413
|
-
npm run context:smart -- task my-project "payment feature"
|
|
414
|
-
# Uses cached domain + task-specific files
|
|
415
|
-
# Result: ~30KB, ~7500 tokens, $0.0075
|
|
416
|
-
```
|
|
417
|
-
|
|
418
|
-
### Scenario 2: Security Review
|
|
419
|
-
|
|
420
|
-
```bash
|
|
421
|
-
# Security agent needs all related context
|
|
422
|
-
npm run context:smart -- domain my-project
|
|
423
|
-
# Adds security rules, ADRs, design docs
|
|
424
|
-
# Result: ~20KB, ~5000 tokens, $0.005
|
|
425
|
-
```
|
|
426
|
-
|
|
427
|
-
### Scenario 3: Onboarding New Developer
|
|
428
|
-
|
|
429
|
-
```bash
|
|
430
|
-
# New dev needs big picture
|
|
431
|
-
npm run context:smart -- global my-project
|
|
432
|
-
# Just mission, standards, recent ADRs
|
|
433
|
-
# Result: ~2KB, ~500 tokens, $0.0005
|
|
434
|
-
```
|
|
435
|
-
|
|
436
|
-
---
|
|
437
|
-
|
|
438
|
-
## 📞 Troubleshooting
|
|
439
|
-
|
|
440
|
-
### Context Too Large?
|
|
441
|
-
|
|
442
|
-
```bash
|
|
443
|
-
# Try smaller mode
|
|
444
|
-
npm run context:smart -- global # Instead of domain
|
|
445
|
-
|
|
446
|
-
# Or prune manually
|
|
447
|
-
npm run memory:compress
|
|
448
|
-
npm run memory:vacuum
|
|
449
|
-
```
|
|
450
|
-
|
|
451
|
-
### FTS5 Queries Slow or Stale?
|
|
452
|
-
|
|
453
|
-
```bash
|
|
454
|
-
# Rebuild the index (it is also what fixes a stale index)
|
|
455
|
-
npm run sync:universal
|
|
456
|
-
|
|
457
|
-
# The doctor tells you when the index is behind memory/ — it is the
|
|
458
|
-
# failure that costs the most and shows the least (ADR-0023).
|
|
459
|
-
npm run tools:doctor
|
|
460
|
-
```
|
|
461
|
-
|
|
462
|
-
### Cache Not Working?
|
|
463
|
-
|
|
464
|
-
```bash
|
|
465
|
-
# Clear cache
|
|
466
|
-
rm -rf .context/cache
|
|
467
|
-
|
|
468
|
-
# Verify cache enabled in .memoryrc.json
|
|
469
|
-
cat .memoryrc.json | grep cache -A 5
|
|
470
|
-
```
|
|
471
|
-
|
|
472
|
-
---
|
|
473
|
-
|
|
474
|
-
## 📚 Related Commands
|
|
475
|
-
|
|
476
|
-
Todos passam pelo core (`bin/forja.mjs`, ADR-0020). Se um comando não está aqui, ele está no
|
|
477
|
-
registry — `node bin/forja.mjs` lista todos.
|
|
478
|
-
|
|
479
|
-
```bash
|
|
480
|
-
# Buscar antes de ler: é o primeiro passo da economia de tokens (ADR-0009)
|
|
481
|
-
npm run query:universal "auth"
|
|
482
|
-
|
|
483
|
-
# Montar o pacote de contexto mínimo-suficiente (global | domain | task)
|
|
484
|
-
npm run context:smart -- task my-project "payment feature"
|
|
485
|
-
|
|
486
|
-
# Reindexar a memória — também é o que corrige um índice defasado
|
|
487
|
-
npm run sync:universal
|
|
488
|
-
|
|
489
|
-
# Comprimir memória antiga e recuperar espaço
|
|
490
|
-
npm run memory:compress
|
|
491
|
-
npm run memory:vacuum
|
|
492
|
-
|
|
493
|
-
# Medir a economia
|
|
494
|
-
npm run token:benchmark
|
|
495
|
-
|
|
496
|
-
# Índice defasado responde sobre memória velha, calado. O doctor avisa (ADR-0023)
|
|
497
|
-
npm run tools:doctor
|
|
498
|
-
```
|
|
499
|
-
|
|
500
|
-
---
|
|
501
|
-
|
|
502
|
-
**Próximo**: [`docs/agent-harnesses.md`](agent-harnesses.md) — os gates e as ferramentas de processo.
|
|
1
|
+
# 🎯 Token Optimization Guide
|
|
2
|
+
|
|
3
|
+
**Target**: 40-60% reduction in tokens per agent session through smart context, caching, and compression.
|
|
4
|
+
|
|
5
|
+
## Hooks ativos (ADR-0009)
|
|
6
|
+
|
|
7
|
+
| Hook | Quando dispara | O que faz |
|
|
8
|
+
|---|---|---|
|
|
9
|
+
| `SessionStart` → `scripts/hook-session-start.mjs` | Início da sessão Claude Code | Injeta status de specs e handoffs abertos (`additionalContext`) |
|
|
10
|
+
| `UserPromptSubmit` → `scripts/hook-user-prompt.mjs` | A cada prompt do usuário | **Opt-in**: só roda com `FRAMEWORK_HOOK_INJECT=1` e prompt casando triggers (`implement`, `refactor`, `spec:`, …). Cache TTL 30min |
|
|
11
|
+
| `pre-commit` (passos 6-7) | Antes de cada commit | `spec:check` + `check-standards`; bloqueia se inconsistente |
|
|
12
|
+
|
|
13
|
+
Para ativar a injeção automática de smart-context:
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
export FRAMEWORK_HOOK_INJECT=1
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Caps em `.memoryrc.json::hooks.userPromptCap` (default 4KB). Cache em `/tmp/framework-hook-cache/`.
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## 📊 Current State Analysis
|
|
24
|
+
|
|
25
|
+
### Baseline Metrics (Before Optimization)
|
|
26
|
+
|
|
27
|
+
| Metric | Value | Impact |
|
|
28
|
+
|--------|-------|--------|
|
|
29
|
+
| Average context size | 150-200 KB | High token cost |
|
|
30
|
+
| Files loaded per session | 30-50 | Redundant data |
|
|
31
|
+
| Cache hit rate | 0% | No reuse |
|
|
32
|
+
| Database size | 2.1 MB | Includes old logs |
|
|
33
|
+
| Compression | None | No optimization |
|
|
34
|
+
|
|
35
|
+
### Target After Optimization
|
|
36
|
+
|
|
37
|
+
| Metric | Current | Target | Savings |
|
|
38
|
+
|--------|---------|--------|---------|
|
|
39
|
+
| Context size | 150 KB | 60 KB | 60% ✅ |
|
|
40
|
+
| Files loaded | 40 | 15-20 | 50% |
|
|
41
|
+
| Cache hit rate | 0% | 70% | - |
|
|
42
|
+
| Database size | 2.1 MB | < 1 MB | 50% |
|
|
43
|
+
| Token cost | $0.015 | $0.006 | 60% ✅ |
|
|
44
|
+
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
## 🔧 3-Mode Context Strategy
|
|
48
|
+
|
|
49
|
+
### Mode 1: Global (Fastest - 2KB, ~500 tokens)
|
|
50
|
+
|
|
51
|
+
**Use case**: Startup, configuration decisions, standards
|
|
52
|
+
|
|
53
|
+
**Loads**:
|
|
54
|
+
- `mission.md` — Project mission
|
|
55
|
+
- `standards.md` — Code/doc standards
|
|
56
|
+
- `ADR-*` — Last 3 architecture decisions
|
|
57
|
+
- `.memoryrc.json` — Config
|
|
58
|
+
|
|
59
|
+
**Cost**: $0.0001 per request
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
node lib/context-builder.js global my-project
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
---
|
|
66
|
+
|
|
67
|
+
### Mode 2: Domain (Standard - 20KB, ~5000 tokens)
|
|
68
|
+
|
|
69
|
+
**Use case**: Feature development, architectural work
|
|
70
|
+
|
|
71
|
+
**Loads**:
|
|
72
|
+
- All from **Global**
|
|
73
|
+
- `vision.md` — Product vision
|
|
74
|
+
- `design-md/INDEX.md` — Design decisions
|
|
75
|
+
- `rules.md` — Business rules
|
|
76
|
+
- `[domain]/api.md` — Domain-specific API
|
|
77
|
+
- Recent `summary.md` files
|
|
78
|
+
|
|
79
|
+
**Cost**: $0.005 per request
|
|
80
|
+
|
|
81
|
+
```bash
|
|
82
|
+
node lib/context-builder.js domain my-project
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
---
|
|
86
|
+
|
|
87
|
+
### Mode 3: Task (Optimized - 30-40KB, ~8000 tokens)
|
|
88
|
+
|
|
89
|
+
**Use case**: Specific features, debugging, handoffs
|
|
90
|
+
|
|
91
|
+
**Loads**:
|
|
92
|
+
- All from **Domain**
|
|
93
|
+
- FTS5 search results for keyword
|
|
94
|
+
- Deduplicates overlaps
|
|
95
|
+
- Prunes unused sections
|
|
96
|
+
|
|
97
|
+
**Cost**: $0.008 per request
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
node lib/context-builder.js task my-project "auth backend"
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
---
|
|
104
|
+
|
|
105
|
+
## 🧠 Smart Context - How It Works
|
|
106
|
+
|
|
107
|
+
```
|
|
108
|
+
┌─────────────────────────────────────┐
|
|
109
|
+
│ User Query: "Implement JWT auth" │
|
|
110
|
+
└────────────┬────────────────────────┘
|
|
111
|
+
│
|
|
112
|
+
▼
|
|
113
|
+
┌─────────────────────────────────────┐
|
|
114
|
+
│ 1. Parse keyword: "JWT", "auth" │
|
|
115
|
+
└────────────┬────────────────────────┘
|
|
116
|
+
│
|
|
117
|
+
▼
|
|
118
|
+
┌─────────────────────────────────────┐
|
|
119
|
+
│ 2. Check cache: Hit? → Return │
|
|
120
|
+
│ Miss? → Continue │
|
|
121
|
+
└────────────┬────────────────────────┘
|
|
122
|
+
│
|
|
123
|
+
▼
|
|
124
|
+
┌─────────────────────────────────────┐
|
|
125
|
+
│ 3. FTS5 search in memory_nodes │
|
|
126
|
+
│ Find: auth-service, jwt-spec, │
|
|
127
|
+
│ security-adr, etc (10 files) │
|
|
128
|
+
└────────────┬────────────────────────┘
|
|
129
|
+
│
|
|
130
|
+
▼
|
|
131
|
+
┌─────────────────────────────────────┐
|
|
132
|
+
│ 4. Add domain + global context │
|
|
133
|
+
│ Total: ~20 files (deduped) │
|
|
134
|
+
└────────────┬────────────────────────┘
|
|
135
|
+
│
|
|
136
|
+
▼
|
|
137
|
+
┌─────────────────────────────────────┐
|
|
138
|
+
│ 5. Rank by relevance + recency │
|
|
139
|
+
│ Keep top 15 (by token budget) │
|
|
140
|
+
└────────────┬────────────────────────┘
|
|
141
|
+
│
|
|
142
|
+
▼
|
|
143
|
+
┌─────────────────────────────────────┐
|
|
144
|
+
│ 6. Generate markdown + cache │
|
|
145
|
+
│ ~30KB context (8000 tokens) │
|
|
146
|
+
└────────────┬────────────────────────┘
|
|
147
|
+
│
|
|
148
|
+
▼
|
|
149
|
+
┌─────────────────────────────────────┐
|
|
150
|
+
│ 7. Send to agent (from cache ✅) │
|
|
151
|
+
└─────────────────────────────────────┘
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
---
|
|
155
|
+
|
|
156
|
+
## 📦 Compression Strategy
|
|
157
|
+
|
|
158
|
+
### Step 1: Archive Old Logs (30 days)
|
|
159
|
+
|
|
160
|
+
```bash
|
|
161
|
+
npm run memory:vacuum
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
**What happens**:
|
|
165
|
+
- Logs > 30 days moved to `.memory/archive/`
|
|
166
|
+
- Deleted from active DB
|
|
167
|
+
- Database VACUUM'd
|
|
168
|
+
|
|
169
|
+
**Expected savings**: 30-40% of DB size
|
|
170
|
+
|
|
171
|
+
### Step 2: Clean Cache (7-day TTL)
|
|
172
|
+
|
|
173
|
+
```bash
|
|
174
|
+
node scripts/compress-memory.mjs
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
**What happens**:
|
|
178
|
+
- Expired cache files deleted
|
|
179
|
+
- Empty nodes removed
|
|
180
|
+
- Index rebuilt
|
|
181
|
+
|
|
182
|
+
**Expected savings**: 20-30% more
|
|
183
|
+
|
|
184
|
+
### Step 3: Optimize Memory Runs
|
|
185
|
+
|
|
186
|
+
**Manual audit**:
|
|
187
|
+
```bash
|
|
188
|
+
# Find biggest runs
|
|
189
|
+
du -sh .memory/runs/* | sort -h | tail -10
|
|
190
|
+
|
|
191
|
+
# Archive manually if needed
|
|
192
|
+
mv .memory/runs/old-run-* .memory/archive/
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
---
|
|
196
|
+
|
|
197
|
+
## 💾 Configuration (.memoryrc.json)
|
|
198
|
+
|
|
199
|
+
### Set Token Limits
|
|
200
|
+
|
|
201
|
+
```json
|
|
202
|
+
{
|
|
203
|
+
"tokenLimits": {
|
|
204
|
+
"global": 2000,
|
|
205
|
+
"domain": 5000,
|
|
206
|
+
"task": 8000,
|
|
207
|
+
"buffer": 500
|
|
208
|
+
}
|
|
209
|
+
}
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
### Compression Settings
|
|
213
|
+
|
|
214
|
+
```json
|
|
215
|
+
{
|
|
216
|
+
"compression": {
|
|
217
|
+
"archiveAge": 30,
|
|
218
|
+
"maxDbSize": 50,
|
|
219
|
+
"cacheTtl": 7,
|
|
220
|
+
"vacuumInterval": 86400000
|
|
221
|
+
}
|
|
222
|
+
}
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
### Cache Strategy
|
|
226
|
+
|
|
227
|
+
```json
|
|
228
|
+
{
|
|
229
|
+
"context": {
|
|
230
|
+
"cache": {
|
|
231
|
+
"enabled": true,
|
|
232
|
+
"ttl": 604800000,
|
|
233
|
+
"location": ".context/cache",
|
|
234
|
+
"strategy": "lru"
|
|
235
|
+
}
|
|
236
|
+
}
|
|
237
|
+
}
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
---
|
|
241
|
+
|
|
242
|
+
## 📈 Benchmarking
|
|
243
|
+
|
|
244
|
+
### Run Benchmark
|
|
245
|
+
|
|
246
|
+
```bash
|
|
247
|
+
npm run token:benchmark
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
**What it does**:
|
|
251
|
+
1. Generate all 3 context modes
|
|
252
|
+
2. Measure size, token count, generation time
|
|
253
|
+
3. Compare with baseline
|
|
254
|
+
4. Report savings %
|
|
255
|
+
|
|
256
|
+
**Output example**:
|
|
257
|
+
```
|
|
258
|
+
📊 Token Economy Benchmark
|
|
259
|
+
|
|
260
|
+
Mode: global
|
|
261
|
+
Size: 2.1 KB
|
|
262
|
+
Tokens: 525
|
|
263
|
+
Time: 45ms
|
|
264
|
+
|
|
265
|
+
Mode: domain
|
|
266
|
+
Size: 18.5 KB
|
|
267
|
+
Tokens: 4625
|
|
268
|
+
Time: 120ms
|
|
269
|
+
|
|
270
|
+
Mode: task (keyword: "auth")
|
|
271
|
+
Size: 31.2 KB
|
|
272
|
+
Tokens: 7800
|
|
273
|
+
Time: 180ms
|
|
274
|
+
|
|
275
|
+
Summary:
|
|
276
|
+
✅ 52% reduction vs original (full context)
|
|
277
|
+
✅ 70% cache hit rate
|
|
278
|
+
✅ Average generation: 115ms
|
|
279
|
+
💰 Cost savings: $0.009/request
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
---
|
|
283
|
+
|
|
284
|
+
## 🎯 Optimization Techniques
|
|
285
|
+
|
|
286
|
+
### 1. Deduplication
|
|
287
|
+
|
|
288
|
+
**Problem**: Same files loaded in multiple modes.
|
|
289
|
+
|
|
290
|
+
**Solution**:
|
|
291
|
+
```javascript
|
|
292
|
+
const seenPaths = new Set();
|
|
293
|
+
for (const node of nodes) {
|
|
294
|
+
if (seenPaths.has(node.path)) continue; // Skip
|
|
295
|
+
seenPaths.add(node.path);
|
|
296
|
+
// Add to context
|
|
297
|
+
}
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
**Savings**: 20-30%
|
|
301
|
+
|
|
302
|
+
---
|
|
303
|
+
|
|
304
|
+
### 2. Priority Weighting
|
|
305
|
+
|
|
306
|
+
**Problem**: Not all files equally important.
|
|
307
|
+
|
|
308
|
+
**Solution**:
|
|
309
|
+
```javascript
|
|
310
|
+
const priorities = {
|
|
311
|
+
'mission.md': 10,
|
|
312
|
+
'vision.md': 8,
|
|
313
|
+
'rules.md': 6,
|
|
314
|
+
'design-md/': 5,
|
|
315
|
+
'implementation/': 2
|
|
316
|
+
};
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
**Savings**: 15-25%
|
|
320
|
+
|
|
321
|
+
---
|
|
322
|
+
|
|
323
|
+
### 3. Time Decay
|
|
324
|
+
|
|
325
|
+
**Problem**: Old files still included equally.
|
|
326
|
+
|
|
327
|
+
**Solution**:
|
|
328
|
+
```javascript
|
|
329
|
+
const age = (now - node.updatedAt) / (1000 * 60 * 60 * 24); // days
|
|
330
|
+
const weight = Math.exp(-age / 30); // Decay over 30 days
|
|
331
|
+
if (weight < 0.1) skip(); // Drop very old files
|
|
332
|
+
```
|
|
333
|
+
|
|
334
|
+
**Savings**: 10-20%
|
|
335
|
+
|
|
336
|
+
---
|
|
337
|
+
|
|
338
|
+
### 4. Relevance Ranking
|
|
339
|
+
|
|
340
|
+
**Problem**: FTS5 results not always ranked best.
|
|
341
|
+
|
|
342
|
+
**Solution**:
|
|
343
|
+
```javascript
|
|
344
|
+
const relevanceScore =
|
|
345
|
+
(titleMatch * 3) +
|
|
346
|
+
(contentMatch * 1) +
|
|
347
|
+
(recencyBoost * 0.5) +
|
|
348
|
+
(domainMatch * 2);
|
|
349
|
+
|
|
350
|
+
nodes.sort((a, b) => b.score - a.score);
|
|
351
|
+
nodes = nodes.slice(0, maxFiles); // Keep top N
|
|
352
|
+
```
|
|
353
|
+
|
|
354
|
+
**Savings**: 25-40%
|
|
355
|
+
|
|
356
|
+
---
|
|
357
|
+
|
|
358
|
+
## 🚀 Integration with Agent Workflow
|
|
359
|
+
|
|
360
|
+
### For Backend Worker
|
|
361
|
+
|
|
362
|
+
```javascript
|
|
363
|
+
import ContextBuilder from '../lib/context-builder.js';
|
|
364
|
+
|
|
365
|
+
// On task start
|
|
366
|
+
const builder = new ContextBuilder(process.cwd(), dbPath);
|
|
367
|
+
const context = builder.build('task', 'my-project', 'backend auth');
|
|
368
|
+
const stats = builder.stats('task', 'my-project', 'backend auth');
|
|
369
|
+
|
|
370
|
+
console.log(`📊 Using ${stats.tokens} tokens (cost: $${stats.estimatedCost})`);
|
|
371
|
+
|
|
372
|
+
// Send context to agent
|
|
373
|
+
await agent.exec(task, context);
|
|
374
|
+
|
|
375
|
+
builder.close();
|
|
376
|
+
```
|
|
377
|
+
|
|
378
|
+
### For Frontend Worker
|
|
379
|
+
|
|
380
|
+
```javascript
|
|
381
|
+
// More domain-focused
|
|
382
|
+
const context = builder.build('domain', 'my-project');
|
|
383
|
+
```
|
|
384
|
+
|
|
385
|
+
### For Orchestrator
|
|
386
|
+
|
|
387
|
+
```javascript
|
|
388
|
+
// Global context only (faster handoff)
|
|
389
|
+
const context = builder.build('global', 'my-project');
|
|
390
|
+
```
|
|
391
|
+
|
|
392
|
+
---
|
|
393
|
+
|
|
394
|
+
## 📋 Pre-Flight Checklist
|
|
395
|
+
|
|
396
|
+
- [ ] `.memoryrc.json` created with token limits
|
|
397
|
+
- [ ] `lib/context-builder.js` integrated
|
|
398
|
+
- [ ] `scripts/compress-memory.mjs` tested
|
|
399
|
+
- [ ] Cache directory created: `.context/cache/`
|
|
400
|
+
- [ ] Archive directory created: `.memory/archive/`
|
|
401
|
+
- [ ] FTS5 index enabled in universal.db
|
|
402
|
+
- [ ] Benchmark run: `npm run token:benchmark`
|
|
403
|
+
- [ ] Savings > 40%? Deploy!
|
|
404
|
+
|
|
405
|
+
---
|
|
406
|
+
|
|
407
|
+
## 🎓 Common Patterns
|
|
408
|
+
|
|
409
|
+
### Scenario 1: Feature Development
|
|
410
|
+
|
|
411
|
+
```bash
|
|
412
|
+
# Developer needs feature context
|
|
413
|
+
npm run context:smart -- task my-project "payment feature"
|
|
414
|
+
# Uses cached domain + task-specific files
|
|
415
|
+
# Result: ~30KB, ~7500 tokens, $0.0075
|
|
416
|
+
```
|
|
417
|
+
|
|
418
|
+
### Scenario 2: Security Review
|
|
419
|
+
|
|
420
|
+
```bash
|
|
421
|
+
# Security agent needs all related context
|
|
422
|
+
npm run context:smart -- domain my-project
|
|
423
|
+
# Adds security rules, ADRs, design docs
|
|
424
|
+
# Result: ~20KB, ~5000 tokens, $0.005
|
|
425
|
+
```
|
|
426
|
+
|
|
427
|
+
### Scenario 3: Onboarding New Developer
|
|
428
|
+
|
|
429
|
+
```bash
|
|
430
|
+
# New dev needs big picture
|
|
431
|
+
npm run context:smart -- global my-project
|
|
432
|
+
# Just mission, standards, recent ADRs
|
|
433
|
+
# Result: ~2KB, ~500 tokens, $0.0005
|
|
434
|
+
```
|
|
435
|
+
|
|
436
|
+
---
|
|
437
|
+
|
|
438
|
+
## 📞 Troubleshooting
|
|
439
|
+
|
|
440
|
+
### Context Too Large?
|
|
441
|
+
|
|
442
|
+
```bash
|
|
443
|
+
# Try smaller mode
|
|
444
|
+
npm run context:smart -- global # Instead of domain
|
|
445
|
+
|
|
446
|
+
# Or prune manually
|
|
447
|
+
npm run memory:compress
|
|
448
|
+
npm run memory:vacuum
|
|
449
|
+
```
|
|
450
|
+
|
|
451
|
+
### FTS5 Queries Slow or Stale?
|
|
452
|
+
|
|
453
|
+
```bash
|
|
454
|
+
# Rebuild the index (it is also what fixes a stale index)
|
|
455
|
+
npm run sync:universal
|
|
456
|
+
|
|
457
|
+
# The doctor tells you when the index is behind memory/ — it is the
|
|
458
|
+
# failure that costs the most and shows the least (ADR-0023).
|
|
459
|
+
npm run tools:doctor
|
|
460
|
+
```
|
|
461
|
+
|
|
462
|
+
### Cache Not Working?
|
|
463
|
+
|
|
464
|
+
```bash
|
|
465
|
+
# Clear cache
|
|
466
|
+
rm -rf .context/cache
|
|
467
|
+
|
|
468
|
+
# Verify cache enabled in .memoryrc.json
|
|
469
|
+
cat .memoryrc.json | grep cache -A 5
|
|
470
|
+
```
|
|
471
|
+
|
|
472
|
+
---
|
|
473
|
+
|
|
474
|
+
## 📚 Related Commands
|
|
475
|
+
|
|
476
|
+
Todos passam pelo core (`bin/forja.mjs`, ADR-0020). Se um comando não está aqui, ele está no
|
|
477
|
+
registry — `node bin/forja.mjs` lista todos.
|
|
478
|
+
|
|
479
|
+
```bash
|
|
480
|
+
# Buscar antes de ler: é o primeiro passo da economia de tokens (ADR-0009)
|
|
481
|
+
npm run query:universal "auth"
|
|
482
|
+
|
|
483
|
+
# Montar o pacote de contexto mínimo-suficiente (global | domain | task)
|
|
484
|
+
npm run context:smart -- task my-project "payment feature"
|
|
485
|
+
|
|
486
|
+
# Reindexar a memória — também é o que corrige um índice defasado
|
|
487
|
+
npm run sync:universal
|
|
488
|
+
|
|
489
|
+
# Comprimir memória antiga e recuperar espaço
|
|
490
|
+
npm run memory:compress
|
|
491
|
+
npm run memory:vacuum
|
|
492
|
+
|
|
493
|
+
# Medir a economia
|
|
494
|
+
npm run token:benchmark
|
|
495
|
+
|
|
496
|
+
# Índice defasado responde sobre memória velha, calado. O doctor avisa (ADR-0023)
|
|
497
|
+
npm run tools:doctor
|
|
498
|
+
```
|
|
499
|
+
|
|
500
|
+
---
|
|
501
|
+
|
|
502
|
+
**Próximo**: [`docs/agent-harnesses.md`](agent-harnesses.md) — os gates e as ferramentas de processo.
|