create-mercato-app 0.6.7 → 0.6.8-develop.6874.1.982d6097d8
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/README.md +72 -0
- package/agentic/claude-code/hooks/entity-migration-check.ts +32 -88
- package/agentic/codex/enforcement-rules.md +2 -16
- package/agentic/cursor/hooks/entity-migration-check.mjs +19 -50
- package/agentic/cursor/rules/entity-guard.mdc +9 -21
- package/agentic/cursor/rules/generated-guard.mdc +3 -5
- package/agentic/cursor/rules/open-mercato.mdc +3 -29
- package/agentic/guides/ai-workflows.md +76 -0
- package/agentic/guides/architecture.md +107 -0
- package/agentic/guides/backend-ui.md +80 -0
- package/agentic/guides/contracts.md +92 -0
- package/agentic/guides/extensions.md +121 -0
- package/agentic/guides/integrations.md +81 -0
- package/agentic/guides/module-system.md +12 -127
- package/agentic/guides/spec-delivery.md +22 -0
- package/agentic/guides/testing-debugging.md +80 -0
- package/agentic/shared/AGENTS.md.template +124 -311
- package/agentic/shared/ai/agentic.config.json +2 -0
- package/agentic/shared/ai/harness/README.md +50 -0
- package/agentic/shared/ai/harness/RELEASE.md +57 -0
- package/agentic/shared/ai/harness/cases.json +13680 -0
- package/agentic/shared/ai/harness/cases.schema.json +133 -0
- package/agentic/shared/ai/harness/fixtures/index.json +49 -0
- package/agentic/shared/ai/harness/fixtures/seeds.json +162 -0
- package/agentic/shared/ai/harness/generated-code-review-policy.md +21 -0
- package/agentic/shared/ai/harness/generated-code-review-response.schema.json +96 -0
- package/agentic/shared/ai/harness/generated-code-review-result.schema.json +172 -0
- package/agentic/shared/ai/harness/release-matrix.json +158 -0
- package/agentic/shared/ai/harness/release-result.schema.json +219 -0
- package/agentic/shared/ai/harness/result.schema.json +76 -0
- package/agentic/shared/ai/harness/routing-response.schema.json +12 -0
- package/agentic/shared/ai/harness/target-validation-result.schema.json +73 -0
- package/agentic/shared/ai/harness/validators.json +78 -0
- package/agentic/shared/ai/harness/writable-ast-oracles.mjs +2121 -0
- package/agentic/shared/ai/harness/writable-behavior-oracles.mjs +1096 -0
- package/agentic/shared/ai/lessons/_template.md +16 -0
- package/agentic/shared/ai/lessons.md +26 -3
- package/agentic/shared/ai/review-checklist.md +36 -0
- package/agentic/shared/ai/skills/om-auto-implement-spec/SKILL.md +21 -0
- package/agentic/shared/ai/skills/om-auto-review-pr/SKILL.md +4 -0
- package/agentic/shared/ai/skills/om-auto-upgrade-0.6.6-to-0.6.7/SKILL.md +98 -0
- package/agentic/shared/ai/skills/om-backend-ui-design/SKILL.md +20 -241
- package/agentic/shared/ai/skills/om-backend-ui-design/references/crud-surfaces.md +16 -0
- package/agentic/shared/ai/skills/om-backend-ui-design/references/frontend-and-design-system.md +53 -0
- package/agentic/shared/ai/skills/om-backend-ui-design/references/page-and-navigation.md +13 -0
- package/agentic/shared/ai/skills/om-backend-ui-design/references/quality-states.md +11 -0
- package/agentic/shared/ai/skills/om-build-workflow/SKILL.md +30 -0
- package/agentic/shared/ai/skills/om-build-workflow/references/activity-contracts.md +12 -0
- package/agentic/shared/ai/skills/om-build-workflow/references/durability-and-progress.md +13 -0
- package/agentic/shared/ai/skills/om-build-workflow/references/workflow-design.md +14 -0
- package/agentic/shared/ai/skills/om-create-ai-agent/SKILL.md +28 -0
- package/agentic/shared/ai/skills/om-create-ai-agent/references/attachments-and-overrides.md +12 -0
- package/agentic/shared/ai/skills/om-create-ai-agent/references/module-agents-and-tools.md +22 -0
- package/agentic/shared/ai/skills/om-create-ai-agent/references/orchestrator-agents.md +12 -0
- package/agentic/shared/ai/skills/om-create-ai-agent/references/surface-selector.md +19 -0
- package/agentic/shared/ai/skills/om-data-model-design/SKILL.md +16 -601
- package/agentic/shared/ai/skills/om-data-model-design/references/integrity-and-concurrency.md +19 -0
- package/agentic/shared/ai/skills/om-data-model-design/references/migration-workflow.md +13 -0
- package/agentic/shared/ai/skills/om-data-model-design/references/schema-design.md +14 -0
- package/agentic/shared/ai/skills/om-data-model-design/references/sensitive-data.md +10 -0
- package/agentic/shared/ai/skills/om-eject-and-customize/SKILL.md +14 -310
- package/agentic/shared/ai/skills/om-eject-and-customize/references/decision-and-procedure.md +17 -0
- package/agentic/shared/ai/skills/om-evolve-harness/SKILL.md +29 -0
- package/agentic/shared/ai/skills/om-evolve-harness/references/case-template.md +100 -0
- package/agentic/shared/ai/skills/om-evolve-harness/references/case-workflow.md +16 -0
- package/agentic/shared/ai/skills/om-evolve-harness/references/owner-selection.md +17 -0
- package/agentic/shared/ai/skills/om-framework-context/SKILL.md +25 -0
- package/agentic/shared/ai/skills/om-framework-context/references/resolver-procedure.md +11 -0
- package/agentic/shared/ai/skills/om-framework-context/references/skew-and-escalation.md +13 -0
- package/agentic/shared/ai/skills/om-help/SKILL.md +15 -97
- package/agentic/shared/ai/skills/om-help/references/delivery-workflows.md +18 -0
- package/agentic/shared/ai/skills/om-help/references/task-families.md +20 -0
- package/agentic/shared/ai/skills/om-implement-spec/SKILL.md +33 -152
- package/agentic/shared/ai/skills/om-implement-spec/references/phases-and-gates.md +33 -0
- package/agentic/shared/ai/skills/om-implement-spec/references/planning-and-progress.md +40 -0
- package/agentic/shared/ai/skills/om-implement-spec/references/report-templates.md +27 -0
- package/agentic/shared/ai/skills/om-implement-spec/references/spec-resolution.md +24 -0
- package/agentic/shared/ai/skills/om-integration-builder/SKILL.md +24 -708
- package/agentic/shared/ai/skills/om-integration-builder/references/package-and-activation.md +16 -0
- package/agentic/shared/ai/skills/om-integration-builder/references/provider-families.md +14 -0
- package/agentic/shared/ai/skills/om-integration-builder/references/security-and-reliability.md +15 -0
- package/agentic/shared/ai/skills/om-integration-builder/references/sync-and-files.md +12 -0
- package/agentic/shared/ai/skills/om-judge-agent-session/SKILL.md +34 -0
- package/agentic/shared/ai/skills/om-judge-agent-session/agents/openai.yaml +4 -0
- package/agentic/shared/ai/skills/om-judge-agent-session/references/agentic-setup.md +11 -0
- package/agentic/shared/ai/skills/om-judge-agent-session/references/input-normalization.md +31 -0
- package/agentic/shared/ai/skills/om-judge-agent-session/references/judge-workflow.md +39 -0
- package/agentic/shared/ai/skills/om-judge-agent-session/references/report-template.md +43 -0
- package/agentic/shared/ai/skills/om-judge-agent-session/references/rules.md +11 -0
- package/agentic/shared/ai/skills/om-module-scaffold/SKILL.md +20 -820
- package/agentic/shared/ai/skills/om-module-scaffold/references/api-and-domain.md +19 -0
- package/agentic/shared/ai/skills/om-module-scaffold/references/business-one-shot-blueprints.md +172 -0
- package/agentic/shared/ai/skills/om-module-scaffold/references/data-and-migrations.md +12 -0
- package/agentic/shared/ai/skills/om-module-scaffold/references/discovery-surface-catalog.md +83 -0
- package/agentic/shared/ai/skills/om-module-scaffold/references/module-surfaces.md +21 -0
- package/agentic/shared/ai/skills/om-module-scaffold/references/planning.md +11 -0
- package/agentic/shared/ai/skills/om-module-scaffold/references/runtime-cache-and-queues.md +22 -0
- package/agentic/shared/ai/skills/om-module-scaffold/references/verification.md +13 -0
- package/agentic/shared/ai/skills/om-share-this-session/SKILL.md +41 -0
- package/agentic/shared/ai/skills/om-share-this-session/references/agentic-setup.md +19 -0
- package/agentic/shared/ai/skills/om-share-this-session/references/bundle-preparation.md +44 -0
- package/agentic/shared/ai/skills/om-share-this-session/references/consent-and-review.md +39 -0
- package/agentic/shared/ai/skills/om-share-this-session/references/publication.md +20 -0
- package/agentic/shared/ai/skills/om-share-this-session/references/report-templates.md +57 -0
- package/agentic/shared/ai/skills/om-share-this-session/references/rules.md +11 -0
- package/agentic/shared/ai/skills/om-share-this-session/scripts/prepare-share-bundle.mjs +486 -0
- package/agentic/shared/ai/skills/om-system-extension/SKILL.md +19 -843
- package/agentic/shared/ai/skills/om-system-extension/references/extension-branches.md +18 -0
- package/agentic/shared/ai/skills/om-system-extension/references/mechanism-selector.md +27 -0
- package/agentic/shared/ai/skills/om-system-extension/references/read-write-roundtrip.md +13 -0
- package/agentic/shared/ai/skills/om-system-extension/references/unified-overrides.md +41 -0
- package/agentic/shared/ai/skills/om-system-extension/references/verification.md +11 -0
- package/agentic/shared/ai/skills/om-trim-unused-modules/SKILL.md +15 -63
- package/agentic/shared/ai/skills/om-trim-unused-modules/references/dependency-and-redirect.md +15 -0
- package/agentic/shared/ai/skills/om-troubleshooter/SKILL.md +16 -467
- package/agentic/shared/ai/skills/om-troubleshooter/references/diagnosis-map.md +16 -0
- package/agentic/shared/ai/skills/om-troubleshooter/references/regression-oracles.md +14 -0
- package/agentic/shared/ai/skills/tiers.json +143 -21
- package/agentic/shared/ai/skills/tiers.schema.json +52 -40
- package/agentic/shared/ai/specs/README.md +4 -3
- package/agentic/shared/ai/specs/SPEC-000-template.md +226 -10
- package/agentic/shared/ai/trackers/github.md +108 -4
- package/agentic/shared/scripts/agent-harness-tool-server.mjs +187 -0
- package/agentic/shared/scripts/check-lessons.mjs +178 -0
- package/agentic/shared/scripts/evaluate-agent-harness.mjs +2958 -0
- package/agentic/shared/scripts/execution-sandbox.mjs +329 -0
- package/agentic/shared/scripts/framework-context.mjs +888 -0
- package/agentic/shared/scripts/install-skills.mjs +1029 -0
- package/agentic/shared/scripts/install-skills.sh +4 -694
- package/agentic/shared/scripts/prepare-agent-harness-fixture.mjs +222 -0
- package/agentic/shared/scripts/run-agent-harness-release.mjs +1774 -0
- package/dist/agentic/claude-code/hooks/entity-migration-check.ts +32 -88
- package/dist/agentic/codex/enforcement-rules.md +2 -16
- package/dist/agentic/cursor/hooks/entity-migration-check.mjs +19 -50
- package/dist/agentic/cursor/rules/entity-guard.mdc +9 -21
- package/dist/agentic/cursor/rules/generated-guard.mdc +3 -5
- package/dist/agentic/cursor/rules/open-mercato.mdc +3 -29
- package/dist/agentic/guides/ai-workflows.md +76 -0
- package/dist/agentic/guides/architecture.md +107 -0
- package/dist/agentic/guides/backend-ui.md +80 -0
- package/dist/agentic/guides/contracts.md +92 -0
- package/dist/agentic/guides/extensions.md +121 -0
- package/dist/agentic/guides/framework-extension-points.md +36 -0
- package/dist/agentic/guides/integrations.md +81 -0
- package/dist/agentic/guides/module-facts.json +115537 -3951
- package/dist/agentic/guides/module-system.md +12 -127
- package/dist/agentic/guides/modules/ai_assistant.md +227 -28
- package/dist/agentic/guides/modules/api_docs.md +58 -2
- package/dist/agentic/guides/modules/api_keys.md +92 -7
- package/dist/agentic/guides/modules/attachments.md +119 -14
- package/dist/agentic/guides/modules/audit_logs.md +131 -10
- package/dist/agentic/guides/modules/auth.md +276 -33
- package/dist/agentic/guides/modules/business_rules.md +149 -14
- package/dist/agentic/guides/modules/catalog.md +475 -43
- package/dist/agentic/guides/modules/channel_gmail.md +82 -3
- package/dist/agentic/guides/modules/channel_imap.md +82 -3
- package/dist/agentic/guides/modules/checkout.md +299 -27
- package/dist/agentic/guides/modules/communication_channels.md +315 -33
- package/dist/agentic/guides/modules/configs.md +104 -8
- package/dist/agentic/guides/modules/content.md +57 -2
- package/dist/agentic/guides/modules/currencies.md +152 -17
- package/dist/agentic/guides/modules/customer_accounts.md +387 -45
- package/dist/agentic/guides/modules/customers.md +746 -85
- package/dist/agentic/guides/modules/dashboards.md +155 -10
- package/dist/agentic/guides/modules/data_sync.md +149 -16
- package/dist/agentic/guides/modules/design_system.md +102 -0
- package/dist/agentic/guides/modules/dictionaries.md +107 -12
- package/dist/agentic/guides/modules/directory.md +148 -15
- package/dist/agentic/guides/modules/entities.md +145 -13
- package/dist/agentic/guides/modules/events.md +59 -2
- package/dist/agentic/guides/modules/feature_toggles.md +119 -9
- package/dist/agentic/guides/modules/gateway_stripe.md +92 -4
- package/dist/agentic/guides/modules/generators.md +45 -2
- package/dist/agentic/guides/modules/inbox_ops.md +207 -27
- package/dist/agentic/guides/modules/integrations.md +146 -16
- package/dist/agentic/guides/modules/messages.md +223 -24
- package/dist/agentic/guides/modules/notifications.md +96 -8
- package/dist/agentic/guides/modules/onboarding.md +77 -6
- package/dist/agentic/guides/modules/payment_gateways.md +164 -21
- package/dist/agentic/guides/modules/perspectives.md +77 -7
- package/dist/agentic/guides/modules/planner.md +136 -18
- package/dist/agentic/guides/modules/portal.md +93 -2
- package/dist/agentic/guides/modules/progress.md +104 -14
- package/dist/agentic/guides/modules/query_index.md +154 -15
- package/dist/agentic/guides/modules/record_locks.md +206 -21
- package/dist/agentic/guides/modules/resources.md +197 -30
- package/dist/agentic/guides/modules/sales.md +678 -84
- package/dist/agentic/guides/modules/scheduler.md +133 -14
- package/dist/agentic/guides/modules/search.md +170 -6
- package/dist/agentic/guides/modules/security.md +294 -35
- package/dist/agentic/guides/modules/shipping_carriers.md +134 -18
- package/dist/agentic/guides/modules/sso.md +151 -26
- package/dist/agentic/guides/modules/staff.md +369 -57
- package/dist/agentic/guides/modules/storage_s3.md +95 -5
- package/dist/agentic/guides/modules/sync_akeneo.md +85 -3
- package/dist/agentic/guides/modules/sync_excel.md +75 -6
- package/dist/agentic/guides/modules/system_status_overlays.md +60 -2
- package/dist/agentic/guides/modules/translations.md +104 -10
- package/dist/agentic/guides/modules/webhooks.md +203 -24
- package/dist/agentic/guides/modules/wms.md +441 -46
- package/dist/agentic/guides/modules/workflows.md +302 -43
- package/dist/agentic/guides/spec-delivery.md +22 -0
- package/dist/agentic/guides/testing-debugging.md +80 -0
- package/dist/agentic/guides/upstream/AGENTS.md +299 -0
- package/dist/agentic/guides/upstream/BACKWARD_COMPATIBILITY.md +316 -0
- package/dist/agentic/guides/upstream/manifest.json +8 -0
- package/dist/agentic/shared/AGENTS.md.template +124 -311
- package/dist/agentic/shared/ai/agentic.config.json +2 -0
- package/dist/agentic/shared/ai/harness/README.md +50 -0
- package/dist/agentic/shared/ai/harness/RELEASE.md +57 -0
- package/dist/agentic/shared/ai/harness/cases.json +13680 -0
- package/dist/agentic/shared/ai/harness/cases.schema.json +133 -0
- package/dist/agentic/shared/ai/harness/fixtures/index.json +49 -0
- package/dist/agentic/shared/ai/harness/fixtures/seeds.json +162 -0
- package/dist/agentic/shared/ai/harness/generated-code-review-policy.md +21 -0
- package/dist/agentic/shared/ai/harness/generated-code-review-response.schema.json +96 -0
- package/dist/agentic/shared/ai/harness/generated-code-review-result.schema.json +172 -0
- package/dist/agentic/shared/ai/harness/release-matrix.json +158 -0
- package/dist/agentic/shared/ai/harness/release-result.schema.json +219 -0
- package/dist/agentic/shared/ai/harness/result.schema.json +76 -0
- package/dist/agentic/shared/ai/harness/routing-response.schema.json +12 -0
- package/dist/agentic/shared/ai/harness/target-validation-result.schema.json +73 -0
- package/dist/agentic/shared/ai/harness/validators.json +78 -0
- package/dist/agentic/shared/ai/harness/writable-ast-oracles.mjs +2121 -0
- package/dist/agentic/shared/ai/harness/writable-behavior-oracles.mjs +1096 -0
- package/dist/agentic/shared/ai/lessons/_template.md +16 -0
- package/dist/agentic/shared/ai/lessons.md +26 -3
- package/dist/agentic/shared/ai/review-checklist.md +36 -0
- package/dist/agentic/shared/ai/skills/om-auto-implement-spec/SKILL.md +21 -0
- package/dist/agentic/shared/ai/skills/om-auto-review-pr/SKILL.md +4 -0
- package/dist/agentic/shared/ai/skills/om-auto-upgrade-0.6.6-to-0.6.7/SKILL.md +98 -0
- package/dist/agentic/shared/ai/skills/om-backend-ui-design/SKILL.md +20 -241
- package/dist/agentic/shared/ai/skills/om-backend-ui-design/references/crud-surfaces.md +16 -0
- package/dist/agentic/shared/ai/skills/om-backend-ui-design/references/frontend-and-design-system.md +53 -0
- package/dist/agentic/shared/ai/skills/om-backend-ui-design/references/page-and-navigation.md +13 -0
- package/dist/agentic/shared/ai/skills/om-backend-ui-design/references/quality-states.md +11 -0
- package/dist/agentic/shared/ai/skills/om-build-workflow/SKILL.md +30 -0
- package/dist/agentic/shared/ai/skills/om-build-workflow/references/activity-contracts.md +12 -0
- package/dist/agentic/shared/ai/skills/om-build-workflow/references/durability-and-progress.md +13 -0
- package/dist/agentic/shared/ai/skills/om-build-workflow/references/workflow-design.md +14 -0
- package/dist/agentic/shared/ai/skills/om-create-ai-agent/SKILL.md +28 -0
- package/dist/agentic/shared/ai/skills/om-create-ai-agent/references/attachments-and-overrides.md +12 -0
- package/dist/agentic/shared/ai/skills/om-create-ai-agent/references/module-agents-and-tools.md +22 -0
- package/dist/agentic/shared/ai/skills/om-create-ai-agent/references/orchestrator-agents.md +12 -0
- package/dist/agentic/shared/ai/skills/om-create-ai-agent/references/surface-selector.md +19 -0
- package/dist/agentic/shared/ai/skills/om-data-model-design/SKILL.md +16 -601
- package/dist/agentic/shared/ai/skills/om-data-model-design/references/integrity-and-concurrency.md +19 -0
- package/dist/agentic/shared/ai/skills/om-data-model-design/references/migration-workflow.md +13 -0
- package/dist/agentic/shared/ai/skills/om-data-model-design/references/schema-design.md +14 -0
- package/dist/agentic/shared/ai/skills/om-data-model-design/references/sensitive-data.md +10 -0
- package/dist/agentic/shared/ai/skills/om-eject-and-customize/SKILL.md +14 -310
- package/dist/agentic/shared/ai/skills/om-eject-and-customize/references/decision-and-procedure.md +17 -0
- package/dist/agentic/shared/ai/skills/om-evolve-harness/SKILL.md +29 -0
- package/dist/agentic/shared/ai/skills/om-evolve-harness/references/case-template.md +100 -0
- package/dist/agentic/shared/ai/skills/om-evolve-harness/references/case-workflow.md +16 -0
- package/dist/agentic/shared/ai/skills/om-evolve-harness/references/owner-selection.md +17 -0
- package/dist/agentic/shared/ai/skills/om-framework-context/SKILL.md +25 -0
- package/dist/agentic/shared/ai/skills/om-framework-context/references/resolver-procedure.md +11 -0
- package/dist/agentic/shared/ai/skills/om-framework-context/references/skew-and-escalation.md +13 -0
- package/dist/agentic/shared/ai/skills/om-help/SKILL.md +15 -97
- package/dist/agentic/shared/ai/skills/om-help/references/delivery-workflows.md +18 -0
- package/dist/agentic/shared/ai/skills/om-help/references/task-families.md +20 -0
- package/dist/agentic/shared/ai/skills/om-implement-spec/SKILL.md +33 -152
- package/dist/agentic/shared/ai/skills/om-implement-spec/references/phases-and-gates.md +33 -0
- package/dist/agentic/shared/ai/skills/om-implement-spec/references/planning-and-progress.md +40 -0
- package/dist/agentic/shared/ai/skills/om-implement-spec/references/report-templates.md +27 -0
- package/dist/agentic/shared/ai/skills/om-implement-spec/references/spec-resolution.md +24 -0
- package/dist/agentic/shared/ai/skills/om-integration-builder/SKILL.md +24 -708
- package/dist/agentic/shared/ai/skills/om-integration-builder/references/package-and-activation.md +16 -0
- package/dist/agentic/shared/ai/skills/om-integration-builder/references/provider-families.md +14 -0
- package/dist/agentic/shared/ai/skills/om-integration-builder/references/security-and-reliability.md +15 -0
- package/dist/agentic/shared/ai/skills/om-integration-builder/references/sync-and-files.md +12 -0
- package/dist/agentic/shared/ai/skills/om-judge-agent-session/SKILL.md +34 -0
- package/dist/agentic/shared/ai/skills/om-judge-agent-session/agents/openai.yaml +4 -0
- package/dist/agentic/shared/ai/skills/om-judge-agent-session/references/agentic-setup.md +11 -0
- package/dist/agentic/shared/ai/skills/om-judge-agent-session/references/input-normalization.md +31 -0
- package/dist/agentic/shared/ai/skills/om-judge-agent-session/references/judge-workflow.md +39 -0
- package/dist/agentic/shared/ai/skills/om-judge-agent-session/references/report-template.md +43 -0
- package/dist/agentic/shared/ai/skills/om-judge-agent-session/references/rules.md +11 -0
- package/dist/agentic/shared/ai/skills/om-module-scaffold/SKILL.md +20 -820
- package/dist/agentic/shared/ai/skills/om-module-scaffold/references/api-and-domain.md +19 -0
- package/dist/agentic/shared/ai/skills/om-module-scaffold/references/business-one-shot-blueprints.md +172 -0
- package/dist/agentic/shared/ai/skills/om-module-scaffold/references/data-and-migrations.md +12 -0
- package/dist/agentic/shared/ai/skills/om-module-scaffold/references/discovery-surface-catalog.md +83 -0
- package/dist/agentic/shared/ai/skills/om-module-scaffold/references/module-surfaces.md +21 -0
- package/dist/agentic/shared/ai/skills/om-module-scaffold/references/planning.md +11 -0
- package/dist/agentic/shared/ai/skills/om-module-scaffold/references/runtime-cache-and-queues.md +22 -0
- package/dist/agentic/shared/ai/skills/om-module-scaffold/references/verification.md +13 -0
- package/dist/agentic/shared/ai/skills/om-share-this-session/SKILL.md +41 -0
- package/dist/agentic/shared/ai/skills/om-share-this-session/references/agentic-setup.md +19 -0
- package/dist/agentic/shared/ai/skills/om-share-this-session/references/bundle-preparation.md +44 -0
- package/dist/agentic/shared/ai/skills/om-share-this-session/references/consent-and-review.md +39 -0
- package/dist/agentic/shared/ai/skills/om-share-this-session/references/publication.md +20 -0
- package/dist/agentic/shared/ai/skills/om-share-this-session/references/report-templates.md +57 -0
- package/dist/agentic/shared/ai/skills/om-share-this-session/references/rules.md +11 -0
- package/dist/agentic/shared/ai/skills/om-share-this-session/scripts/prepare-share-bundle.mjs +486 -0
- package/dist/agentic/shared/ai/skills/om-system-extension/SKILL.md +19 -843
- package/dist/agentic/shared/ai/skills/om-system-extension/references/extension-branches.md +18 -0
- package/dist/agentic/shared/ai/skills/om-system-extension/references/mechanism-selector.md +27 -0
- package/dist/agentic/shared/ai/skills/om-system-extension/references/read-write-roundtrip.md +13 -0
- package/dist/agentic/shared/ai/skills/om-system-extension/references/unified-overrides.md +41 -0
- package/dist/agentic/shared/ai/skills/om-system-extension/references/verification.md +11 -0
- package/dist/agentic/shared/ai/skills/om-trim-unused-modules/SKILL.md +15 -63
- package/dist/agentic/shared/ai/skills/om-trim-unused-modules/references/dependency-and-redirect.md +15 -0
- package/dist/agentic/shared/ai/skills/om-troubleshooter/SKILL.md +16 -467
- package/dist/agentic/shared/ai/skills/om-troubleshooter/references/diagnosis-map.md +16 -0
- package/dist/agentic/shared/ai/skills/om-troubleshooter/references/regression-oracles.md +14 -0
- package/dist/agentic/shared/ai/skills/tiers.json +143 -21
- package/dist/agentic/shared/ai/skills/tiers.schema.json +52 -40
- package/dist/agentic/shared/ai/specs/README.md +4 -3
- package/dist/agentic/shared/ai/specs/SPEC-000-template.md +226 -10
- package/dist/agentic/shared/ai/trackers/github.md +108 -4
- package/dist/agentic/shared/scripts/agent-harness-tool-server.mjs +187 -0
- package/dist/agentic/shared/scripts/check-lessons.mjs +178 -0
- package/dist/agentic/shared/scripts/evaluate-agent-harness.mjs +2958 -0
- package/dist/agentic/shared/scripts/execution-sandbox.mjs +329 -0
- package/dist/agentic/shared/scripts/framework-context.mjs +888 -0
- package/dist/agentic/shared/scripts/install-skills.mjs +1029 -0
- package/dist/agentic/shared/scripts/install-skills.sh +4 -694
- package/dist/agentic/shared/scripts/prepare-agent-harness-fixture.mjs +222 -0
- package/dist/agentic/shared/scripts/run-agent-harness-release.mjs +1774 -0
- package/dist/index.js +175 -184
- package/package.json +9 -7
- package/template/.env.example +59 -2
- package/template/.yarnrc.yml.template +9 -0
- package/template/AGENTS.md +93 -663
- package/template/eslint.config.mjs +1 -0
- package/template/gitignore +8 -0
- package/template/jest.config.cjs +2 -1
- package/template/jest.setup.ts +29 -0
- package/template/next.config.ts +55 -0
- package/template/package.json.template +31 -25
- package/template/scripts/dev-memory-monitor.mjs +92 -0
- package/template/scripts/dev-memory-sampler.mjs +464 -0
- package/template/scripts/dev-runtime-log-policy.mjs +33 -0
- package/template/scripts/dev-runtime.mjs +142 -76
- package/template/scripts/dev.mjs +129 -7
- package/template/scripts/evaluate-agent-harness.mjs +4 -0
- package/template/scripts/framework-context.mjs +4 -0
- package/template/scripts/install-skills.mjs +10 -0
- package/template/scripts/install-skills.sh +2 -19
- package/template/scripts/prepare-agent-harness-fixture.mjs +4 -0
- package/template/scripts/run-agent-harness-release.mjs +4 -0
- package/template/src/app/(backend)/backend/__tests__/layout-route-registry.test.tsx +1 -0
- package/template/src/app/(backend)/backend/layout.tsx +5 -3
- package/template/src/app/(frontend)/layout.tsx +1 -1
- package/template/src/app/api/[...slug]/route.ts +9 -0
- package/template/src/app/globals.css +61 -3
- package/template/src/app/layout.tsx +2 -18
- package/template/src/app/page.tsx +4 -1
- package/template/src/components/AppProviders.tsx +4 -1
- package/template/src/components/DemoFeedbackWidget.tsx +1 -1
- package/template/src/components/__tests__/AppProviders.test.tsx +11 -2
- package/template/src/components/__tests__/StartPageContent.test.tsx +69 -0
- package/template/src/components/__tests__/starter-chrome-ds.test.ts +35 -0
- package/template/src/i18n/de.json +21 -1
- package/template/src/i18n/en.json +21 -1
- package/template/src/i18n/es.json +21 -1
- package/template/src/i18n/ko.json +970 -0
- package/template/src/i18n/pl.json +21 -1
- package/template/src/instrumentation.ts +14 -1
- package/template/src/lib/i18n/register-dictionary-loader.ts +2 -0
- package/template/src/modules/example/__integration__/TC-EXAMPLE-001-todo-label-edit.spec.ts +123 -0
- package/template/src/modules/example/__integration__/TC-EXAMPLE-002-query-index-failure.spec.ts +155 -0
- package/template/src/modules/example/__integration__/TC-UMES-003.spec.ts +7 -3
- package/template/src/modules/example/__integration__/TC-UMES-005.spec.ts +7 -1
- package/template/src/modules/example/__integration__/TC-UMES-009.spec.ts +11 -10
- package/template/src/modules/example/__integration__/todo-priority-validation.spec.ts +31 -1
- package/template/src/modules/example/acl.ts +6 -0
- package/template/src/modules/example/backend/mutation-lifecycle/page.meta.ts +1 -9
- package/template/src/modules/example/backend/page.meta.ts +1 -10
- package/template/src/modules/example/backend/payments/page.meta.ts +1 -10
- package/template/src/modules/example/backend/payments/page.tsx +2 -2
- package/template/src/modules/example/backend/todos/create/page.meta.ts +1 -11
- package/template/src/modules/example/backend/todos/page.meta.ts +1 -10
- package/template/src/modules/example/backend/umes-extensions/page.meta.ts +1 -9
- package/template/src/modules/example/backend/umes-handlers/page.meta.ts +1 -10
- package/template/src/modules/example/backend/umes-integrations/page.meta.ts +1 -10
- package/template/src/modules/example/backend/umes-next-phases/page.meta.ts +1 -11
- package/template/src/modules/example/backend/umes-query-extensions/page.meta.ts +1 -11
- package/template/src/modules/example/commands/__tests__/todos.prepare-scope.test.ts +77 -0
- package/template/src/modules/example/commands/todos.ts +47 -2
- package/template/src/modules/example/i18n/ko.json +481 -0
- package/template/src/modules/example/i18n/pl.json +68 -68
- package/template/src/modules/example/lib/__tests__/mock-webhook-endpoint-adapter.test.ts +14 -0
- package/template/src/modules/example_customers_sync/i18n/ko.json +11 -0
- package/template/src/modules.ts +17 -0
- package/template/tsconfig.json +3 -2
- package/agentic/shared/ai/skills/om-auto-continue-pr-loop/SKILL.md +0 -27
- package/agentic/shared/ai/skills/om-auto-create-pr-loop/SKILL.md +0 -27
- package/agentic/shared/ai/skills/om-backend-ui-design/references/ui-components.md +0 -260
- package/agentic/shared/ai/skills/om-data-model-design/references/mikro-orm-cheatsheet.md +0 -146
- package/agentic/shared/ai/skills/om-help/references/skills-catalog.md +0 -84
- package/agentic/shared/ai/skills/om-help/references/workflow-sequences.md +0 -193
- package/agentic/shared/ai/skills/om-integration-builder/STANDALONE.md +0 -34
- package/agentic/shared/ai/skills/om-integration-builder/references/adapter-contracts.md +0 -762
- package/agentic/shared/ai/skills/om-module-scaffold/references/naming-conventions.md +0 -50
- package/agentic/shared/ai/skills/om-module-scaffold/references/navigation-patterns.md +0 -97
- package/agentic/shared/ai/skills/om-system-extension/references/extension-contracts.md +0 -271
- package/agentic/shared/ai/skills/om-troubleshooter/references/diagnostic-commands.md +0 -101
- package/dist/agentic/guides/cache.md +0 -45
- package/dist/agentic/guides/core.md +0 -453
- package/dist/agentic/guides/events.md +0 -117
- package/dist/agentic/guides/queue.md +0 -53
- package/dist/agentic/guides/search.md +0 -115
- package/dist/agentic/guides/shared.md +0 -108
- package/dist/agentic/guides/ui.md +0 -347
- package/dist/agentic/shared/ai/skills/om-auto-continue-pr-loop/SKILL.md +0 -27
- package/dist/agentic/shared/ai/skills/om-auto-create-pr-loop/SKILL.md +0 -27
- package/dist/agentic/shared/ai/skills/om-backend-ui-design/references/ui-components.md +0 -260
- package/dist/agentic/shared/ai/skills/om-data-model-design/references/mikro-orm-cheatsheet.md +0 -146
- package/dist/agentic/shared/ai/skills/om-help/references/skills-catalog.md +0 -84
- package/dist/agentic/shared/ai/skills/om-help/references/workflow-sequences.md +0 -193
- package/dist/agentic/shared/ai/skills/om-integration-builder/STANDALONE.md +0 -34
- package/dist/agentic/shared/ai/skills/om-integration-builder/references/adapter-contracts.md +0 -762
- package/dist/agentic/shared/ai/skills/om-module-scaffold/references/naming-conventions.md +0 -50
- package/dist/agentic/shared/ai/skills/om-module-scaffold/references/navigation-patterns.md +0 -97
- package/dist/agentic/shared/ai/skills/om-system-extension/references/extension-contracts.md +0 -271
- package/dist/agentic/shared/ai/skills/om-troubleshooter/references/diagnostic-commands.md +0 -101
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
# Testing and Root-Cause Debugging
|
|
2
|
+
|
|
3
|
+
Diagnose before editing, fix the smallest knowledge/code owner, and prove the regression through the real runtime path.
|
|
4
|
+
|
|
5
|
+
## Context Restraint
|
|
6
|
+
|
|
7
|
+
Name the areas the failure spans before loading anything, from the SYMPTOM and not only from the cause: a value that will not render, a session/locale/hydration mismatch, or a stale form spans `backend-ui`; wrong or lost records, commands, or events span `module-data`; an installed module's own surface spans `umes`; an external provider call spans `integration`.
|
|
8
|
+
|
|
9
|
+
A fix is always `debugging` plus every area you just named. Proving the fix with a regression oracle is part of `debugging` and does NOT add `testing`; a request that explicitly asks for tests, coverage, or app-level verification also selects `testing`. Load exactly this guide, each named area's guide, and `om-troubleshooter` — that is what selects those routes.
|
|
10
|
+
|
|
11
|
+
Add an area's authoring skill when the fix **introduces or reworks** a contract there — a concurrency header on existing calls, a new field or UI surface, a new command, a new invalidation, a new guard, or a provider's pagination cursor, bounded retry, idempotency, or reconciliation — because you are then designing that surface, not just repairing it. Provider cursor/retry/idempotency fixes therefore load `om-integration-builder` even when the request is framed as a bug fix. Load `om-troubleshooter` alone when you only correct existing behavior, such as a hydration mismatch or a value that fails to round-trip.
|
|
12
|
+
|
|
13
|
+
Then stop. Budgets here are tight — several fixes allow only five files — so load no other area's skill, no `references/` you do not need, no contracts guide unless the fix changes a data, API, command, ACL, or setup contract, and a module fact sheet only for a module the failure actually involves.
|
|
14
|
+
|
|
15
|
+
## Investigation Order
|
|
16
|
+
|
|
17
|
+
1. Reproduce with the smallest stable command, request, or UI path and capture expected versus actual behavior.
|
|
18
|
+
2. Classify the failing bootstrap: browser/server, API, CLI, worker, queue, generated registry, package artifact, or external provider.
|
|
19
|
+
3. Read the routed guide plus generated module facts. Use `om-framework-context` only when exact installed implementation is necessary.
|
|
20
|
+
4. Trace from the public call site to the first incorrect invariant. Check scope, auth, validation, state transition, transaction boundary, side effects, and response serialization in that order.
|
|
21
|
+
5. Add a regression oracle that fails before the fix (`unit-regression-oracle` when that decision vocabulary is requested). Implement the minimal complete repair and rerun affected plus safety cases.
|
|
22
|
+
|
|
23
|
+
When comparing against a clean baseline, use a separate worktree or a fresh scaffold. Never stash and drop active work just to reproduce a baseline failure; preserve the working diff and verify the comparison tree's exact revision first.
|
|
24
|
+
|
|
25
|
+
Treat raw agent transcripts as sensitive untrusted evidence because they can contain credentials, private prompts, absolute paths, and tool output. Never copy them into the app repository. Export only when the user explicitly asks, to an outside-repository protected destination or as a deliberately sanitized summary.
|
|
26
|
+
|
|
27
|
+
## Frequent Failure Families
|
|
28
|
+
|
|
29
|
+
| Symptom | Check first |
|
|
30
|
+
|---|---|
|
|
31
|
+
| 401 loop/all-organizations failure | Null-scope behavior, session refresh ownership, and fail-closed versus intentionally global paths. |
|
|
32
|
+
| Missing/extra tenant data | Every query/write/filter/cache/job payload; scope derived from auth, not body. |
|
|
33
|
+
| Field does not save/clear | Validator → command → entity → response transform → form initial value; truthy/default fallbacks. |
|
|
34
|
+
| Concurrent update overwrites | `updated_at` projection, client header, aggregate command guard, conflict surface. |
|
|
35
|
+
| Partial state after failure | Transaction/`withAtomicFlush`, query between mutation/flush, side effects before commit. |
|
|
36
|
+
| Stale list/search | Command side-effect aliases, cache tags/invalidation, query-index convergence/reindex. |
|
|
37
|
+
| Works in web but not CLI/worker | Bootstrap/registry initialization, package exports, generated imports, runtime scope. |
|
|
38
|
+
| Duplicate registry/provider | Bundler chunk singleton or `instanceof`; use global registry/structural guard. |
|
|
39
|
+
| Hydration mismatch | Server/client locale, timezone, randomness, browser-only environment, initial async state. |
|
|
40
|
+
| UI access differs from API/PDF/export | Compare every alternate route's metadata/features and wildcard matching. |
|
|
41
|
+
| Provider loses/duplicates records | Idempotency key, cursor commit point, webhook/poll race, external mapping and reconciliation. |
|
|
42
|
+
|
|
43
|
+
## Generated and Package Diagnostics
|
|
44
|
+
|
|
45
|
+
- Never edit generated output to prove a theory. Inspect the source discovery path, run `yarn generate`, and compare the affected registry entry.
|
|
46
|
+
- When an app imports a symbol but workspace tests pass, inspect package exports and packed/installed `dist` plus types.
|
|
47
|
+
- Search ignored installed source only through the bounded resolver output. Record resolved package versions and fact stamps.
|
|
48
|
+
- If a stale chunk/cache is suspected, prove the source/generator is correct before using the app's documented reset escape hatch.
|
|
49
|
+
|
|
50
|
+
## Data and Security Regression Oracles
|
|
51
|
+
|
|
52
|
+
- Create fixtures for two tenants and two organizations; assert allowed, denied, null-scope, and wildcard-feature behavior.
|
|
53
|
+
- Inject failure between multi-phase writes; assert no partial rows/state and no premature event/cache/index side effect.
|
|
54
|
+
- Exercise update and delete with current, stale, and missing versions.
|
|
55
|
+
- Test malformed IDs/filters and ensure invalid input cannot widen a query.
|
|
56
|
+
- Test retry, duplicate delivery, cancellation, and worker restart for external/queued operations.
|
|
57
|
+
- Provider failure/retry/idempotency tests use an ephemeral test environment (`ephemeral-test-environment`) with mock effects, assert secrets are absent and diagnostics redacted (`health-retry-redaction`), and surface every real failure (`honest-test-result`).
|
|
58
|
+
|
|
59
|
+
## UI Regression Oracles
|
|
60
|
+
|
|
61
|
+
- Use API-created fixtures and clean them in `finally`; do not depend on demo data.
|
|
62
|
+
- Cover loading, empty, validation, server error, conflict, retry, success, and authorization.
|
|
63
|
+
- Save/reload/edit/clear fields and verify API plus rendered values.
|
|
64
|
+
- Render under at least two locales/timezones when hydration or formatting is involved.
|
|
65
|
+
- Prefer semantic assertions and stable IDs over full DOM/file snapshots.
|
|
66
|
+
|
|
67
|
+
## Validation Ladder
|
|
68
|
+
|
|
69
|
+
Before authoring a test file, read `.ai/skills/om-module-scaffold/references/verification.md` for the scaffold's test-runner contract.
|
|
70
|
+
|
|
71
|
+
1. Focused unit/regression test.
|
|
72
|
+
2. `yarn generate` when discovery is involved.
|
|
73
|
+
3. Focused package/app typecheck or test.
|
|
74
|
+
4. `yarn typecheck`, `yarn lint`, `yarn test`, `yarn build` for broad/contract changes.
|
|
75
|
+
5. `yarn test:integration:ephemeral` or a filtered integration run for affected API/UI paths.
|
|
76
|
+
6. Packed/Verdaccio standalone validation when package exports or compiled discovery are involved.
|
|
77
|
+
|
|
78
|
+
Run validation commands so the reported shell status is the validation command's status. Do not pipe gates through `grep`, `tail`, or a trailing `echo`; when log capture requires a pipeline, enable `pipefail` and explicitly preserve the command's exit code. Any nonzero status remains a failed gate.
|
|
79
|
+
|
|
80
|
+
Do not replace deterministic convergence with sleeps. Do not suppress failing tests, weaken assertions, or call a bug fixed because only one bootstrap path passes.
|
|
@@ -1,315 +1,128 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
|
54
|
-
|
|
55
|
-
|
|
|
56
|
-
|
|
|
57
|
-
|
|
|
58
|
-
|
|
|
59
|
-
|
|
|
60
|
-
|
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
1
|
+
# {{PROJECT_NAME}} — Standalone App Agent Rules
|
|
2
|
+
|
|
3
|
+
Route first; never probe unmatched context.
|
|
4
|
+
|
|
5
|
+
## Always
|
|
6
|
+
|
|
7
|
+
- Route all axes; missing context: `yarn mercato agentic:init --update-harness`.
|
|
8
|
+
- Lessons: scan `.ai/lessons.md` tags; open/update one matching record + row.
|
|
9
|
+
- App code: `src/modules/<id>/`; framework context only for named gaps.
|
|
10
|
+
- Derive trusted `tenantId` + `organizationId` and fail closed. Only an installed contract may use system scope (`organizationId: null`).
|
|
11
|
+
- Use commands/`makeCrudRoute`/`CrudForm`/`DataTable`, DI/events/UMES; effects stay post-commit.
|
|
12
|
+
- Put entities in `src/modules/<id>/data/entities.ts`; API routes need per-method `metadata` + `openApi`.
|
|
13
|
+
- Editable records expose `updated_at`/`updatedAt`; custom update/delete clients send the version and surface 409s.
|
|
14
|
+
- Run `yarn db:generate`, review scoped SQL/snapshot, and ask before applying it.
|
|
15
|
+
- Run `yarn generate` after discovery files, `src/modules.ts`, routes, pages, events, widgets, agents, tools, or workflows change.
|
|
16
|
+
- Contract-surface changes (route/schema/ID/export/seam/signature/event payload/CLI) MUST read `.ai/guides/upstream/BACKWARD_COMPATIBILITY.md`; tenant/org scope alone is not a contract.
|
|
17
|
+
- Localize strings; use shared UI/tokens and cover loading/empty/error/conflict/keyboard/a11y.
|
|
18
|
+
|
|
19
|
+
## Ask First
|
|
20
|
+
|
|
21
|
+
- Ask before scope/architecture/public contracts/dependencies/ejection/canonical primitives; migrations/resets/DB targets; live credentials/providers; or weakening security/concurrency/retries/idempotency/audit/undo.
|
|
22
|
+
|
|
23
|
+
## Never
|
|
24
|
+
|
|
25
|
+
- Never leak tenants, trust payload scope, or treat missing scope as unrestricted.
|
|
26
|
+
- Never edit `node_modules`, `.mercato/generated/**`, generated facts, or shipped migrations.
|
|
27
|
+
- Never use cross-module ORM relations; use IDs/snapshots, events, enrichers, extensions, or optional DI.
|
|
28
|
+
- Never use raw admin `fetch`/`<form>`, ad hoc crypto/cache/queues, role-name guards, or direct mutations when helpers exist.
|
|
29
|
+
- Never hard-code user strings/status colors; expose secrets/transcripts; or guess answerable contracts.
|
|
30
|
+
|
|
31
|
+
## Validation
|
|
32
|
+
|
|
33
|
+
Use the smallest relevant set. Broad: `yarn generate && yarn typecheck && yarn lint && yarn test && yarn build`; integration: `yarn test:integration:ephemeral`. Report failures; never migrate to validate.
|
|
34
|
+
|
|
35
|
+
## Three-Axis Context Assembler
|
|
36
|
+
|
|
37
|
+
Routes are additive: ownership says WHO; other axes say WHAT. Select every match.
|
|
38
|
+
|
|
39
|
+
`debugging` is additive. A scalar-ID/snapshot fix to persisted records or commands linked to an installed record MUST use `module-data` + `umes` and load `om-data-model-design` + `om-system-extension`.
|
|
40
|
+
|
|
41
|
+
`debugging` = reported bug/security/drift, not designed failure UI. Specs use `spec-pr`; implementation owns domain guides. Custom fields/entities = `umes` + `module-data` + `om-data-model-design`; editable round trips add `backend-ui`, requested coverage adds `testing`. Never infer work from specs/PRs.
|
|
42
|
+
|
|
43
|
+
Unified-override audits = `umes` only; add `architecture`/`framework-context` only for unresolved ownership or installed keys. Durable process/activity/user task = `module-data` + `ai-workflow`. Multi-stage waits/cancel/restart are durable; reminders and renewal/batch schedules are `module-data`.
|
|
44
|
+
|
|
45
|
+
`backend-ui`: replacing/wrapping, prop-transforming, menu-editing, or adding visible feedback adds `backend-ui`; merely hiding/toggling/rewiring installed UI does not.
|
|
46
|
+
Staff UI preview/report/bulk = `backend-ui`.
|
|
47
|
+
Existing installed form/table fields, filters, row/bulk actions without app persistence = `umes` + `backend-ui` only: read `crud-surfaces` + `quality-states`; do not load contracts, module-scaffold, or page/navigation.
|
|
48
|
+
|
|
49
|
+
`backend-ui`: UI skill `references/quality-states.md`; public/portal/responsive/a11y adds `frontend-and-design-system.md`.
|
|
50
|
+
|
|
51
|
+
### Axis 1 — Area/Ownership
|
|
52
|
+
|
|
53
|
+
| Route | Match | Context |
|
|
54
|
+
|---|---|---|
|
|
55
|
+
| `architecture` | Capability/ownership/field-vs-history choice, boundary, upgrade, override, or registry failure; routine discovery stays in its area | `.ai/guides/architecture.md` + named facts |
|
|
56
|
+
| `module-data` | App-owned domain/data/API | `src/modules/<id>/` + `.ai/guides/contracts.md`; add architecture only when ownership is unresolved |
|
|
57
|
+
| `umes` | Extend/replace installed behavior | `.ai/guides/extensions.md` + named facts |
|
|
58
|
+
| `backend-ui` | Authored/restyled rendered surface or browser UI state/session bootstrap | `.ai/guides/backend-ui.md` + host facts; host-provided integration credentials/health UI alone does not match |
|
|
59
|
+
| `integration` | Provider, spreadsheet/CSV/file I/O, sync/webhook/storage | `.ai/guides/integrations.md`; imports = `integration`; AI consuming files = `ai-workflow`, NEVER `integration` unless transport/storage changes |
|
|
60
|
+
| `ai-workflow` | Agent/tool/MCP/orchestrator/durable workflow | `.ai/guides/ai-workflows.md` + facts; schedules/queues/workers/retries/progress alone are `module-data` |
|
|
61
|
+
| `debugging` | Bug/security/drift/runtime inconsistency | `.ai/guides/testing-debugging.md` + affected areas |
|
|
62
|
+
|
|
63
|
+
API/command/record/status/event/UI changes/guards = `umes`; app persistence = `module-data`; installed guard without app persistence = `umes` only, so do not load contracts; read-only behavior/auth/dependents/customization = `framework-context` (alone: no extensions guide; report `installed-version`). Facts do not. Providers are published, never `packages/*`.
|
|
64
|
+
|
|
65
|
+
### Axis 2 — Work Units
|
|
66
|
+
|
|
67
|
+
Match every work-unit row; OPEN its skill before selection.
|
|
68
|
+
|
|
69
|
+
| Route | Work unit | Skill/context |
|
|
70
|
+
|---|---|---|
|
|
71
|
+
| `architecture` | Explain/choose module, UMES, package, eject | architecture; `om-help` for an unresolved or comparative choice across these mechanisms |
|
|
72
|
+
| `module-data` | Business slice or multi-seam domain/API/command fix | MUST load `om-module-scaffold` + its exact `.ai/skills/om-module-scaffold/references/business-one-shot-blueprints.md` key, which resolves units inside the slice, not ownership — an ownership/capability outline adds `architecture` |
|
|
73
|
+
| `spec-pr` | Spec/plan | Axis 3; phases+integration coverage (`integration-coverage`); no domain routes |
|
|
74
|
+
| `architecture` | Upgrade audit or disable built-in | troubleshooter + framework context, or trim skill + exact `src/modules.ts`/`package.json` |
|
|
75
|
+
| `architecture` + `integration` + `framework-context` | Provider superseded by installed capability | integration builder + exact framework context |
|
|
76
|
+
| `module-data` | Entity/link/validator/migration/encryption/lock/transaction | `om-data-model-design` + contracts |
|
|
77
|
+
| `module-data` | CRUD/API/command/OpenAPI/ACL/setup/mutation | `om-module-scaffold` + contracts |
|
|
78
|
+
| `backend-ui` | Form/table/page/renderer/middleware/nav/i18n/UI states | `om-backend-ui-design` + backend UI |
|
|
79
|
+
| `module-data` | Search/analytics/event/notification/message/worker/progress/cache/CLI | scaffold + contracts |
|
|
80
|
+
| `umes` | Fields/extension entities/links/enrichers/injection/interceptors/guards/subscribers/DOM/widgets/toggles/overrides | `om-system-extension` + extensions; choices load `mechanism-selector` + `extension-branches` |
|
|
81
|
+
| `integration` | Provider/credentials/health/webhook/files/client/reconciliation/package | `om-integration-builder` + integrations |
|
|
82
|
+
| `ai-workflow` | Agent/tool/MCP/OpenCode/Code Mode/orchestrator/AI file or content drafting/attachment/override | `om-create-ai-agent` + AI/workflows; MCP/OpenCode loads `surface-selector` + `ai_assistant` facts |
|
|
83
|
+
| `ai-workflow` | Workflow/activity/user task/idempotency/output/progress | `om-build-workflow` + AI/workflows |
|
|
84
|
+
| `testing` | REQUEST says test/coverage/prove, or verify by exercising API/browser/screen sizes/keyboard/screen-reader—not a fix's implicit regression duty or review/audit/config check | MUST read `.ai/guides/testing-debugging.md` + external `om-integration-tests` for integration/E2E/app tests |
|
|
85
|
+
| `debugging` | Reproduce/root-cause/minimal fix/regression oracle | `om-troubleshooter` + testing/debugging |
|
|
86
|
+
| `framework-context` | Exact installed contract still unknown | bounded `om-framework-context`, last |
|
|
87
|
+
| `debugging` + `testing` | Add/fix recurring harness case/test | `om-evolve-harness` |
|
|
88
|
+
|
|
89
|
+
`framework-context`: resolve one named module/framework fact first. Use bounded source only for an unresolved exact contract, current behavior, authorization, dependents, or safest customization seam; never for “installed contracts” alone.
|
|
90
|
+
|
|
91
|
+
### Axis 3 — SDLC and Delivery
|
|
92
|
+
|
|
93
|
+
Pinned delivery skills: `yarn install-skills` (refresh: `--update`). Read BOTH `.agents/skills/<id>/SKILL.md` and a matching `.ai/skills/<id>/SKILL.md` override. Commit+ready PR MUST add `spec-pr`, read `.ai/skills/om-auto-create-pr/SKILL.md`, and keep task routes (`delivery-route-preserves-task-routes`).
|
|
94
|
+
|
|
95
|
+
| Route ID | Delivery need | Skill |
|
|
96
|
+
|---|---|---|
|
|
97
|
+
| `spec-pr` | Write/revise spec | MUST invoke `om-spec-writing` (OMH-005) + `.ai/guides/spec-delivery.md` + config specs path |
|
|
98
|
+
| `spec-pr` | Implement approved phases locally | `om-implement-spec` (OMH-006) |
|
|
99
|
+
| `spec-pr` | Whole-spec / commit+ready PR / issue / review | `om-auto-implement-spec` / `om-auto-create-pr` / `om-auto-fix-issue` / `om-auto-review-pr` |
|
|
100
|
+
| `testing` | Integration/E2E/UI QA | `om-integration-tests` / `om-auto-qa-pr` |
|
|
101
|
+
| — | No PR/spec workflow requested | Do not load delivery skills |
|
|
102
|
+
|
|
103
|
+
Absent skill: run `yarn install-skills` once; never substitute.
|
|
104
|
+
|
|
105
|
+
### Token-Efficient Assembly Policy
|
|
106
|
+
|
|
107
|
+
- Load matched guides once, then only needed references/facts.
|
|
108
|
+
- Hard budgets: guide > skill > references; open a reference only for its named subject.
|
|
109
|
+
- Specs: open one match; `spec-pr` reads template via spec-delivery.
|
|
110
|
+
- Inspect app call sites before bounded `framework-context`.
|
|
111
|
+
- Additive page/form/table/conflict UI skips it.
|
|
112
|
+
- Never bulk-read guide, skill, fact, or source trees.
|
|
113
|
+
|
|
114
|
+
## Module-Specific Facts
|
|
115
|
+
|
|
116
|
+
Load facts for every named/targeted module, not incidental use. Mechanisms: events/subscribers→events; long operation/progress→progress; provider settings/health/OAuth→integrations; sync/import→data_sync. Hosts: session/auth→auth; customer/contact/deal/pipeline→customers; product/price/stock/inventory→catalog; currency/money→currencies; cart/checkout/shopper→checkout; portal→portal + customer_accounts; quote/order/invoice/sales assistant→sales; notification→notifications; webhook/callback→webhooks; schedule/reminder→scheduler; workflow/activity/user task→workflows; assistant→ai_assistant; maintained query index/reindex→query_index; search convergence→search. staff/employee≠optional staff; audit/record-who≠audit_logs unless extended. App primitives skip api_docs/search/query_index unless changed.
|
|
65
117
|
|
|
66
118
|
<!-- om:module-guides:start -->
|
|
67
119
|
<!-- om:module-guides:end -->
|
|
68
120
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
| Debug / fix errors | `.ai/skills/om-troubleshooter/SKILL.md` |
|
|
78
|
-
| Review code changes | `om-code-review` (external — `yarn install-skills`) |
|
|
79
|
-
| Write a spec | `om-spec-writing` (external — `yarn install-skills`), `.ai/specs/SPEC-000-template.md` |
|
|
80
|
-
| Implement a spec (or selected phases) | `.ai/skills/om-implement-spec/SKILL.md` |
|
|
81
|
-
| Create / run integration tests | `om-integration-tests` (external — `yarn install-skills`) |
|
|
82
|
-
| Prepare / reuse a local test environment (shared descriptor for QA + integration tests) | `om-prepare-test-env` (external — invoked by `om-integration-tests` when no environment is running) |
|
|
83
|
-
| Configure or re-configure the agent PR pipeline (`.ai/agentic.config.json`, tracker, labels, QA gate) | `om-setup-agent-pipeline` (external) |
|
|
84
|
-
| Sync installed pipeline artifacts after `yarn install-skills` refreshed the collection | `om-apply-upgrade-notes` (external) |
|
|
85
|
-
| Upgrade framework from 0.4.10 to 0.5.0 | `.ai/skills/om-auto-upgrade-0.4.10-to-0.5.0/SKILL.md` |
|
|
86
|
-
|
|
87
|
-
### Agent Automation / Auto-Skills
|
|
88
|
-
|
|
89
|
-
These skills are installed from the shared collection by `yarn install-skills` (referenced by name — your harness loads them from its own skills directory); the matching `.ai/skills/<name>/` folder holds the standalone override they read on top of their workflow.
|
|
90
|
-
|
|
91
|
-
| Task | Load |
|
|
92
|
-
|---|---|
|
|
93
|
-
| Delegate an arbitrary task end-to-end as a PR | `om-auto-create-pr` (external) |
|
|
94
|
-
| Resume an in-progress agent PR | `om-auto-continue-pr` (external) |
|
|
95
|
-
| Run a long multi-step spec implementation with resumable checkpoints | `om-auto-create-pr-loop` (external) |
|
|
96
|
-
| Resume a checkpointed PR started by `om-auto-create-pr-loop` | `om-auto-continue-pr-loop` (external) |
|
|
97
|
-
| Automated code review on a PR (with optional autofix) | `om-auto-review-pr` (external) |
|
|
98
|
-
| Fix a GitHub issue by number and open a PR | `om-auto-fix-issue` (external — drives the chain `om-verify-in-repo` → `om-root-cause` → `om-fix` → `om-open-pr` → `om-auto-review-pr`, all installed alongside it) |
|
|
99
|
-
| Propose disabling unused built-in modules after the user adds a new module (classic-mode slimdown) | `.ai/skills/om-trim-unused-modules/SKILL.md` |
|
|
100
|
-
|
|
101
|
-
Invoke these as slash commands in your agent CLI (Claude Code, Codex, …), for example `/auto-create-pr add rate-limiting to the products API` or `/auto-fix-issue 42`. The skills read `.ai/agentic.config.json` (base branch `auto`, resolved via the tracker descriptor's **default-branch** operation; pipeline labels off by default; the standalone validation-gate command list) and perform every GitHub interaction through the tracker descriptor `.ai/trackers/github.md`. That config ships preconfigured, so the skills work without any setup step — run `/om-setup-agent-pipeline` when you want to tailor it: enable the full label pipeline (`labels.enabled: true` plus the tracker's **ensure-label-taxonomy** operation) and the QA gate, switch tracker, or change the validation commands. After `yarn install-skills` refreshes the external collection, run `/om-apply-upgrade-notes` to bring the installed artifacts (tracker descriptor, config) up to date with the new skill versions.
|
|
102
|
-
|
|
103
|
-
## Module Anatomy
|
|
104
|
-
|
|
105
|
-
Each module in `src/modules/<id>/` is self-contained and auto-discovered:
|
|
106
|
-
|
|
107
|
-
```
|
|
108
|
-
src/modules/<id>/
|
|
109
|
-
├── index.ts # Module metadata
|
|
110
|
-
├── data/
|
|
111
|
-
│ ├── entities.ts # MikroORM entity classes
|
|
112
|
-
│ ├── validators.ts # Zod validation schemas
|
|
113
|
-
│ ├── extensions.ts # Cross-module entity links
|
|
114
|
-
│ └── enrichers.ts # Response enrichers
|
|
115
|
-
├── api/
|
|
116
|
-
│ ├── <resource>/route.ts # REST handlers (auto-discovered by method)
|
|
117
|
-
│ └── interceptors.ts # API route interception hooks
|
|
118
|
-
├── backend/ # Admin UI pages (auto-discovered)
|
|
119
|
-
│ └── page.tsx # → /backend/<module>
|
|
120
|
-
├── frontend/ # Public pages (auto-discovered)
|
|
121
|
-
├── subscribers/ # Event handlers (export metadata + default handler)
|
|
122
|
-
├── workers/ # Background jobs (export metadata + default handler)
|
|
123
|
-
├── widgets/
|
|
124
|
-
│ ├── injection/ # UI widgets injected into other modules
|
|
125
|
-
│ ├── injection-table.ts # Widget-to-slot mappings
|
|
126
|
-
│ └── components.ts # Component replacement/wrapper definitions
|
|
127
|
-
├── di.ts # Awilix DI registrations
|
|
128
|
-
├── acl.ts # Permission features
|
|
129
|
-
├── setup.ts # Tenant init, role features, seed data
|
|
130
|
-
├── events.ts # Typed event declarations
|
|
131
|
-
├── search.ts # Search indexing configuration
|
|
132
|
-
├── ce.ts # Custom entities / custom field sets
|
|
133
|
-
├── translations.ts # Translatable fields per entity
|
|
134
|
-
├── notifications.ts # Notification type definitions
|
|
135
|
-
├── notifications.client.ts # Client-side notification renderers
|
|
136
|
-
└── encryption.ts # Tenant data encryption maps (defaultEncryptionMaps) for sensitive / GDPR fields
|
|
137
|
-
```
|
|
138
|
-
|
|
139
|
-
Register in `src/modules.ts`: `{ id: '<id>', from: '@app' }`
|
|
140
|
-
|
|
141
|
-
## Mandatory Module Mechanisms (every module MUST use these — no DIY substitutes)
|
|
142
|
-
|
|
143
|
-
When the user asks to **create a new application** or a **new module**, do not invent your own routing, auth, persistence, forms, or caching. The framework provides one canonical primitive for each concern. If a feature is not on this list and not in the Task → Context Map, ask before adding it — do not roll your own.
|
|
144
|
-
|
|
145
|
-
| Concern | Canonical mechanism | Where to learn it |
|
|
146
|
-
|---|---|---|
|
|
147
|
-
| Module structure & auto-discovery | `src/modules/<id>/{api,backend,frontend,data,subscribers,workers,widgets}` + `index.ts` + `src/modules.ts` (`from: '@app'`) — discovered by `yarn generate` | `.ai/skills/om-module-scaffold/SKILL.md`, `.ai/guides/core.md` → Module Files; <https://docs.open-mercato.dev/framework/modules/overview> |
|
|
148
|
-
| **Backend admin pages** | Auto-discovered files under `src/modules/<id>/backend/**`, paired `page.meta.ts` with `requireAuth` + `requireFeatures` + `pageGroup`/`pageGroupKey`/`pageOrder` | `.ai/skills/om-backend-ui-design/SKILL.md`, `.ai/skills/om-module-scaffold/references/navigation-patterns.md`; <https://docs.open-mercato.dev/framework/modules/routes-and-pages> |
|
|
149
|
-
| **Frontend public pages** | Auto-discovered files under `src/modules/<id>/frontend/**`. Customer portal pages live under `frontend/[orgSlug]/portal/<path>/page.tsx` with `requireCustomerAuth` / `requireCustomerFeatures` in `page.meta.ts` | `.ai/guides/ui.md` → Portal Extension; <https://docs.open-mercato.dev/framework/modules/routes-and-pages> |
|
|
150
|
-
| **API routes** | Files under `src/modules/<id>/api/**/route.ts` exporting handlers + `metadata` (per-method `requireAuth` / `requireFeatures`) + `openApi`. NEVER write a top-level `export const requireAuth` — the registry no longer recognises it | `.ai/guides/core.md` → API Routes; <https://docs.open-mercato.dev/framework/api/api-development-guide> |
|
|
151
|
-
| **CRUD APIs (factory)** | `makeCrudRoute({ metadata, orm, list, create, update, del, indexer })` from `@open-mercato/shared/lib/crud/factory` (`orm` is required; `list`/`create`/`update`/`del` are the per-operation configs). Always set `indexer` so query-index coverage stays correct. Custom (non-`makeCrudRoute`) write routes MUST use the mutation guard registry: map the route to `create`/`update`/`delete` (action endpoints usually `update`), collect registered guards, append `bridgeLegacyGuard(container)` when present, call `runMutationGuards(...)` with `{ userFeatures }` before the mutation, merge `modifiedPayload`, and run returned `afterSuccessCallbacks` after success while catching/logging callback failures | `.ai/skills/om-module-scaffold/SKILL.md` → Create API Routes; <https://docs.open-mercato.dev/framework/api/crud-factory> |
|
|
152
|
-
| **CRUD forms in admin** | `<CrudForm entityId apiPath mode fields />` from `@open-mercato/ui/backend/CrudForm`; helpers `createCrud` / `updateCrud` / `deleteCrud` from `@open-mercato/ui/backend/utils/crud`; `createCrudFormError` from `@open-mercato/ui/backend/utils/serverErrors`. Never raw `<form>`, never raw `fetch` | `.ai/skills/om-backend-ui-design/SKILL.md`; <https://docs.open-mercato.dev/framework/admin-ui/crud-form> |
|
|
153
|
-
| **DataTables in admin** | `<DataTable entityId apiPath title columns />` from `@open-mercato/ui/backend/DataTable`. Keep `entityId` and `extensionTableId` stable so widget injection (columns, row actions, bulk actions, filters, toolbar) keeps working | `.ai/skills/om-backend-ui-design/SKILL.md`; <https://docs.open-mercato.dev/framework/admin-ui/data-grids> |
|
|
154
|
-
| **Authorization (RBAC)** | Declare features in `<module>/acl.ts`, grant them in `<module>/setup.ts` `defaultRoleFeatures`, gate pages and routes with `requireFeatures` in `metadata` / `page.meta.ts`. NEVER use `requireRoles` (role names mutate). Run `yarn mercato auth sync-role-acls` after adding new features | `.ai/guides/core.md` → Access Control; <https://docs.open-mercato.dev/framework/rbac/overview> |
|
|
155
|
-
| **Multi-tenant scoping (default for every entity)** | Every tenant-scoped entity MUST include indexed `organization_id` and `tenant_id` columns and every read/write MUST filter by them. The CRUD factory injects scope automatically — do NOT bypass it. For ad-hoc queries use `withScopedPayload` from `@open-mercato/shared/lib/api/scoped` | `.ai/skills/om-data-model-design/SKILL.md`; <https://docs.open-mercato.dev/architecture/system-overview> |
|
|
156
|
-
| **Encryption maps for sensitive data** | Declare a module-level `<module>/encryption.ts` exporting `defaultEncryptionMaps: ModuleEncryptionMap[]` from `@open-mercato/shared/modules/encryption`. Read encrypted columns via `findWithDecryption` / `findOneWithDecryption` from `@open-mercato/shared/lib/encryption/find`. NEVER hand-roll AES/KMS, NEVER use `em.find` on encrypted columns | `.ai/skills/om-data-model-design/SKILL.md` → Sensitive Data and Encryption Maps; <https://docs.open-mercato.dev/user-guide/encryption> |
|
|
157
|
-
| **Cache** | Resolve the cache from DI (`container.resolve('cache')`) — never `new Redis(...)` or raw SQLite. Tag with `tenant:<id>` / `org:<id>` and the entity-type tag so invalidation stays tenant-scoped | `.ai/guides/cache.md`; <https://docs.open-mercato.dev/user-guide/cache-management> |
|
|
158
|
-
| **Entity update safety** | Multi-phase scalar + relation mutations use `withAtomicFlush(em, phases, { transaction: true })` from `@open-mercato/shared/lib/commands/flush` — never interleave `em.find`/`em.findOne` between a scalar mutation and `em.flush()`. Keep `emitCrudSideEffects` + cache invalidation OUTSIDE it (they fire after commit) | See **Entity Update Safety** section below |
|
|
159
|
-
| **Background workers** | `src/modules/<id>/workers/*.ts` exporting `metadata: { queue, id?, concurrency? }` + default handler. Never spin up custom queues | `.ai/guides/queue.md`; <https://docs.open-mercato.dev/framework/events/queue-workers> |
|
|
160
|
-
| **Events between modules** | `<module>/events.ts` with `createModuleEvents({ moduleId, events } as const)`. Subscribers in `subscribers/*.ts`. Never call other modules' services directly across module boundaries | `.ai/guides/events.md`; <https://docs.open-mercato.dev/framework/events/overview> |
|
|
161
|
-
| **i18n (every user-facing string)** | `useT()` client-side from `@open-mercato/shared/lib/i18n/context`, `resolveTranslations()` server-side from `@open-mercato/shared/lib/i18n/server`; keys in `src/i18n/<locale>.json`. Never hard-code labels in components | `.ai/guides/shared.md` → i18n |
|
|
162
|
-
|
|
163
|
-
> Rule of thumb: if you find yourself reaching for raw `fetch`, raw `<form>`, ad-hoc `crypto`, ad-hoc `Redis`, or a manual `m2m` join across modules, stop and check the row above — there is a canonical helper.
|
|
164
|
-
|
|
165
|
-
## Entity Update Safety
|
|
166
|
-
|
|
167
|
-
MikroORM v7 can silently discard pending scalar changes when a query (`em.find`, `em.findOne`, sync helper) runs on the same `EntityManager` between a scalar mutation and `em.flush()`. For any command in `{{PROJECT_NAME}}` that mutates entities across multiple phases:
|
|
168
|
-
|
|
169
|
-
- MUST use `withAtomicFlush(em, phases, { transaction: true })` from `@open-mercato/shared/lib/commands/flush`.
|
|
170
|
-
- NEVER interleave `em.find`/`em.findOne`/sync helpers between a scalar mutation and `em.flush()` on the same `EntityManager` without `withAtomicFlush` — the UPDATE is dropped.
|
|
171
|
-
- Keep `emitCrudSideEffects` (and `emitCrudUndoSideEffects`) AND cache invalidation OUTSIDE the `withAtomicFlush` block — they fire only AFTER the DB write commits.
|
|
172
|
-
|
|
173
|
-
```typescript
|
|
174
|
-
import { withAtomicFlush } from '@open-mercato/shared/lib/commands/flush'
|
|
175
|
-
|
|
176
|
-
await withAtomicFlush(em, [
|
|
177
|
-
() => { record.name = 'New Name'; record.status = 'active' },
|
|
178
|
-
() => syncEntityTags(em, record, tags),
|
|
179
|
-
], { transaction: true, label: '<module>.<command>' })
|
|
180
|
-
|
|
181
|
-
// Side effects + cache invalidation AFTER the atomic flush (post-commit)
|
|
182
|
-
await emitCrudSideEffects({ /* ... */ })
|
|
183
|
-
```
|
|
184
|
-
|
|
185
|
-
Because invalidation runs post-commit and the query-index read-projection tail (search tokens, vectors, fulltext, coverage) converges asynchronously, reads can briefly see a convergence window after a write. An opt-in env flag, `OM_CACHE_SAFETY_ALWAYS_CONSISTENT` (default OFF, backward compatible), is planned to make that tail converge synchronously on write at a write-latency cost — treat it as opt-in/forthcoming, not on by default.
|
|
186
|
-
|
|
187
|
-
## CRITICAL rules — always follow without exception
|
|
188
|
-
|
|
189
|
-
1. **Entity classes live in `src/modules/<module>/data/entities.ts` and MUST import decorators from `@mikro-orm/decorators/legacy`.** Start there for every schema change.
|
|
190
|
-
2. **After editing `src/modules.ts`** or any structural module file: run `yarn generate`
|
|
191
|
-
3. **Never edit `.mercato/generated/*`** — auto-generated. Never edit `node_modules/@open-mercato/*` — eject instead.
|
|
192
|
-
4. **After editing `src/modules/<module>/data/entities.ts`**: run `yarn db:generate` as a schema-diff probe. Default to the generated SQL, but if it emits unrelated churn, keep or write only the scoped SQL for your module and update `src/modules/<module>/migrations/.snapshot-open-mercato.json` in the same change.
|
|
193
|
-
5. **Confirm migrations with user** before running `yarn db:migrate`
|
|
194
|
-
6. **API route files MUST export `metadata`.** Every `src/modules/<module>/api/**/route.ts` that exports an HTTP handler (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`) MUST also export a `metadata` object describing per-method auth, otherwise the generator emits the warning `[generate] ⚠ Route file exports handlers but no metadata — auth will default to required` and every method silently falls back to "authentication required". Use the per-method shape:
|
|
195
|
-
```ts
|
|
196
|
-
export const metadata = {
|
|
197
|
-
GET: { requireAuth: true, requireFeatures: ['mymodule.view'] },
|
|
198
|
-
POST: { requireAuth: true, requireFeatures: ['mymodule.manage'] },
|
|
199
|
-
}
|
|
200
|
-
```
|
|
201
|
-
For public endpoints, opt out explicitly with `{ requireAuth: false }`. Do not use the legacy top-level `export const requireAuth` / `export const requireFeatures` — they are no longer recognised.
|
|
202
|
-
7. **Write migrations in one shot.** `yarn dev` auto-applies pending migrations at startup by default (`OM_DEV_AUTO_MIGRATE=1`). Once a migration has been applied, editing the same file usually has no effect — the next migrate pass skips it as already-applied. If `yarn db:generate` shows unrelated churn, manual SQL for the intended module is allowed, but you MUST also update that module's `.snapshot-open-mercato.json`. Never hand-edit a historical migration that has already shipped; add a **new** migration instead.
|
|
203
|
-
8. **After the user adds a new module, offer to trim classic mode.** A fresh `create-mercato-app` scaffold enables every built-in module (classic mode). Once the user has added their own custom module, the defaults are usually dead weight. **Ask the user** (via a short `AskUserQuestion`) whether they want to disable built-in modules that are not needed for their project. If they say yes, invoke the `om-trim-unused-modules` skill — do NOT hand-craft the slimdown inside the AGENTS.md reading flow. If they say no, preserve classic mode silently.
|
|
204
|
-
|
|
205
|
-
**Dashboards fallback rule.** When the user (or the `om-trim-unused-modules` skill) disables the `dashboards` module, you MUST update `src/app/(backend)/backend/page.tsx` so it no longer renders `<DashboardScreen />`. Replace the dashboard render with a `redirect(...)` to the first enabled backend page for the current user — preferring pages already registered in the main sidebar group and respecting the admin/superadmin role of the caller. Otherwise `/backend` will crash at build or request time because the removed module no longer ships `DashboardScreen`. Always fall back to `/backend/profile` only if no other backend page is available.
|
|
206
|
-
9. **New features MUST be visible to default roles immediately.** Every time you add a new feature ID (e.g. `my_module.view`, `my_module.manage`) to `src/modules/<module>/acl.ts`, you MUST also (a) add that feature to `defaultRoleFeatures` in the same module's `setup.ts` so the admin role and any other appropriate default roles get it on every tenant setup; and (b) run `yarn mercato auth sync-role-acls` so existing tenants pick up the new feature without a reinstall. Use `--tenant <tenantId>` only when the user asks to target one tenant. Do this automatically unless the user has explicitly said otherwise — the user should see the features you are building, not stare at a blank admin because their role is missing a grant. Feature IDs are FROZEN once shipped; if a rename is required, add the new ID alongside, grant it, and keep the old one as a deprecated alias.
|
|
207
|
-
10. **Strict Design System alignment for every UI change.** Any UI you add or edit MUST use the Open Mercato design system components and tokens. No hardcoded Tailwind status colors (`text-red-500`, `bg-green-100`, etc.) — use semantic tokens (`text-status-error-text`, `bg-status-success-bg`, …). No arbitrary text sizes (`text-[11px]`, `text-[13px]`) — use the Tailwind scale (`text-xs`, `text-sm`, `text-base`, `text-lg`, `text-xl`, `text-2xl`) or the `text-overline` token for 11px uppercase labels. In PAGE BODY UI, use `lucide-react` icons (never inline `<svg>`). Use `StatusBadge` for entity status, `Alert` for inline feedback, `FormField` for standalone form inputs, `SectionHeader` for detail-page section headings, `CollapsibleSection` for collapsible regions, `LoadingMessage`/`Spinner`/`DataLoader` for async states, and `EmptyState` (or DataTable's `emptyState` prop) for empty lists. For list pages, follow `.ai/skills/om-backend-ui-design/SKILL.md` and prefer the `DataTable` host pattern shown there (`entityId`, `apiPath`, stable `extensionTableId`, and explicit pagination props when you own the data source). Every dialog MUST support `Cmd/Ctrl+Enter` to submit and `Escape` to cancel. Every icon-only button MUST have an `aria-label`. These rules apply to `src/modules/<module>/backend/**` and `src/modules/<module>/frontend/**` alike.
|
|
208
|
-
11. **Sensitive / GDPR fields MUST go through the encryption-maps mechanism — never hand-rolled.** The framework provides per-tenant DEKs, KMS-backed key resolution, and a declarative field-level map. Whenever the user asks for "this field encrypted", "store this securely", "this is PII", "GDPR", "encryption at rest", or you are designing a column that will hold names, addresses, contacts, free-text notes about people, integration secrets/credentials, or any data subject to a data-processing agreement, you MUST:
|
|
209
|
-
- Declare the entity + field list in `src/modules/<module>/encryption.ts` exporting `defaultEncryptionMaps: ModuleEncryptionMap[]` (type imported from `@open-mercato/shared/modules/encryption`).
|
|
210
|
-
- Read those columns via `findWithDecryption` / `findOneWithDecryption` from `@open-mercato/shared/lib/encryption/find` (passing `tenantId` and `organizationId`). Never use raw `em.find` on encrypted columns.
|
|
211
|
-
- For deterministic-lookup fields (e.g., login email), declare a sibling `hashField` in the map so equality lookups still work.
|
|
212
|
-
- Run `yarn mercato entities seed-encryption --tenant <tenantId>` after adding maps so existing tenants pick them up; new tenants get them automatically during `auth:setup`.
|
|
213
|
-
- Treat hand-rolled AES, raw `crypto.subtle`, custom KMS calls, or storing plaintext "for now" as broken — rewrite via the maps. See `.ai/skills/om-data-model-design/SKILL.md` → Sensitive Data and Encryption Maps and <https://docs.open-mercato.dev/user-guide/encryption>.
|
|
214
|
-
12. **BEFORE writing ANY code**, you MUST:
|
|
215
|
-
- Match your task against the **Task → Context Map** above
|
|
216
|
-
- `Read` every file listed in the "Load" column for your task type
|
|
217
|
-
- Read the **Mandatory Module Mechanisms** section above to confirm which canonical primitives apply (CRUD factory, CrudForm, DataTable, RBAC, multi-tenant scoping, encryption maps, cache, events) — do not invent your own substitutes
|
|
218
|
-
- Only then proceed to implementation
|
|
219
|
-
- If your task matches multiple rows, load ALL listed files
|
|
220
|
-
- **Do NOT skip this step.** The guides contain canonical import paths, required patterns, and conventions that CANNOT be reliably inferred from existing code alone. Skipping leads to wrong imports, missing conventions, and rework.
|
|
221
|
-
|
|
222
|
-
## Additional Conventions
|
|
223
|
-
|
|
224
|
-
- Custom modules use `from: '@app'` in `src/modules.ts`
|
|
225
|
-
- Entity classes belong in `src/modules/<module>/data/entities.ts` and use decorators from `@mikro-orm/decorators/legacy`
|
|
226
|
-
- Standalone apps expose `yarn mercato configs cache ...` because the template enables the `configs` module from `@open-mercato/core`
|
|
227
|
-
- `yarn generate` automatically runs a best-effort structural cache purge (`yarn mercato configs cache structural --all-tenants`) after successful generation; if the cache command is unavailable, generation still succeeds
|
|
228
|
-
- Use `yarn dev:reset` only as the stale-Turbopack escape hatch; it clears `.mercato/next/dev` plus legacy `.next` caches.
|
|
229
|
-
- Detail/read-model APIs that expose `customFields` MUST return bare field keys via `normalizeCustomFieldResponse()` (for example `{ priority: 3 }`). Keep `cf_` / `cf:` prefixes for request payloads, filters, and form field IDs only.
|
|
230
|
-
- Sidebar icons MUST use `lucide-react` components — never inline SVG via `React.createElement`
|
|
231
|
-
- `page.meta.ts` MUST include `pageGroup`, `pageGroupKey`, and `pageOrder` for sidebar grouping
|
|
232
|
-
- Settings pages MUST use `pageContext: 'settings' as const` with `navHidden: true`
|
|
233
|
-
- All related pages within a module MUST share the same `pageGroupKey`
|
|
234
|
-
- DataTable hosts MUST keep `extensionTableId` stable; when you own pagination state, wire `page`, `pageSize`, `totalCount`, and `onPageChange`
|
|
235
|
-
|
|
236
|
-
## Naming Conventions
|
|
237
|
-
|
|
238
|
-
- Module IDs: plural, snake_case (`order_items`)
|
|
239
|
-
- Event IDs: `module.entity.action` (singular entity, past tense: `sales.order.created`)
|
|
240
|
-
- DB tables: plural, snake_case with module prefix (`catalog_products`)
|
|
241
|
-
- DB columns: snake_case (`created_at`, `organization_id`)
|
|
242
|
-
- JS/TS identifiers: camelCase
|
|
243
|
-
- Feature IDs: `<module>.<action>` (`my_module.view`, `my_module.create`)
|
|
244
|
-
- UUID primary keys, explicit foreign keys, junction tables for M2M
|
|
245
|
-
|
|
246
|
-
## Key Imports Quick Reference
|
|
247
|
-
|
|
248
|
-
```typescript
|
|
249
|
-
// Translations
|
|
250
|
-
import { useT } from '@open-mercato/shared/lib/i18n/context'
|
|
251
|
-
import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
|
|
252
|
-
|
|
253
|
-
// API calls (MUST use — never raw fetch)
|
|
254
|
-
import { apiCall, apiCallOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
|
|
255
|
-
|
|
256
|
-
// CRUD forms
|
|
257
|
-
import { CrudForm, type CrudField, type CrudFormGroup } from '@open-mercato/ui/backend/CrudForm'
|
|
258
|
-
import { createCrud, updateCrud, deleteCrud } from '@open-mercato/ui/backend/utils/crud'
|
|
259
|
-
import { createCrudFormError } from '@open-mercato/ui/backend/utils/serverErrors'
|
|
260
|
-
|
|
261
|
-
// UI components (MUST use — never raw <button>)
|
|
262
|
-
import { Button } from '@open-mercato/ui/primitives/button'
|
|
263
|
-
import { IconButton } from '@open-mercato/ui/primitives/icon-button'
|
|
264
|
-
import { LoadingMessage, ErrorMessage } from '@open-mercato/ui/backend/detail'
|
|
265
|
-
import { FormHeader, FormFooter } from '@open-mercato/ui/backend/forms'
|
|
266
|
-
import { flash } from '@open-mercato/ui/backend/FlashMessages'
|
|
267
|
-
|
|
268
|
-
// Encrypted queries (MUST use instead of em.find)
|
|
269
|
-
import { findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
|
|
270
|
-
|
|
271
|
-
// Events
|
|
272
|
-
import { createModuleEvents } from '@open-mercato/shared/modules/events'
|
|
273
|
-
|
|
274
|
-
// Widget injection
|
|
275
|
-
import { InjectionPosition } from '@open-mercato/shared/modules/widgets/injection-position'
|
|
276
|
-
|
|
277
|
-
// Types
|
|
278
|
-
import type { ModuleSetupConfig } from '@open-mercato/shared/modules/setup'
|
|
279
|
-
import type { ResponseEnricher } from '@open-mercato/shared/lib/crud/response-enricher'
|
|
280
|
-
import type { ApiInterceptor } from '@open-mercato/shared/lib/crud/api-interceptor'
|
|
281
|
-
```
|
|
282
|
-
|
|
283
|
-
## Key Commands
|
|
284
|
-
|
|
285
|
-
| Command | Purpose |
|
|
286
|
-
|---|---|
|
|
287
|
-
| `yarn dev` | Start compact dev runtime (`d` toggles raw logs) |
|
|
288
|
-
| `yarn dev:verbose` | Start dev runtime with full raw passthrough logs |
|
|
289
|
-
| `yarn generate` | Regenerate `.mercato/generated/` |
|
|
290
|
-
| `yarn mercato configs cache structural --all-tenants` | Manually purge structural navigation/sidebar cache entries |
|
|
291
|
-
| `yarn mercato module add <package>` | Install and enable an official module package |
|
|
292
|
-
| `yarn db:generate` | Probe/create migration SQL for entity changes |
|
|
293
|
-
| `yarn db:migrate` | Apply pending migrations after user confirmation |
|
|
294
|
-
| `yarn initialize` | Bootstrap DB + first admin account |
|
|
295
|
-
| `yarn build` | Build for production |
|
|
296
|
-
| `yarn mercato eject <module>` | Copy a core module into `src/modules/` |
|
|
297
|
-
| `yarn test:integration:ephemeral` | Run Playwright integration tests against a fresh ephemeral app + DB (reuses a healthy running env) — always prefer this over plain `yarn test:integration` |
|
|
298
|
-
| `yarn test:integration:ephemeral:start` | Start the ephemeral app only (manual QA or iterative test loops; admin@acme.com / secret) — the `om-prepare-test-env` skill wraps this and shares the env via `.ai/qa/test-env.json` |
|
|
299
|
-
| `yarn mercato test:integration <filter>` | Run small filtered test batches against the running ephemeral env (fast iteration) |
|
|
300
|
-
| `npx playwright show-report .ai/qa/test-results/html` | Open the HTML integration test report |
|
|
301
|
-
|
|
302
|
-
## Architecture Rules
|
|
303
|
-
|
|
304
|
-
- NO direct ORM relationships between modules — use foreign key IDs
|
|
305
|
-
- Always filter by `organization_id` for tenant-scoped entities
|
|
306
|
-
- Validate all inputs with Zod; derive types via `z.infer`
|
|
307
|
-
- Use DI (Awilix) for services; avoid `new`-ing directly
|
|
308
|
-
- No `any` types — use Zod schemas with `z.infer`, narrow with runtime checks
|
|
309
|
-
- Every dialog: `Cmd/Ctrl+Enter` submit, `Escape` cancel
|
|
310
|
-
- Keep `pageSize` at or below 100
|
|
311
|
-
- Every API route MUST export `openApi`
|
|
312
|
-
|
|
313
|
-
## Stack
|
|
314
|
-
|
|
315
|
-
Next.js App Router, TypeScript, MikroORM, Awilix DI, Zod
|
|
121
|
+
## Working Sequence
|
|
122
|
+
|
|
123
|
+
1. `spec-pr`: list `.ai/specs` once; open one match; plan-only skips specs.
|
|
124
|
+
2. Route; load only matched guides/skills/facts.
|
|
125
|
+
3. Implement the smallest complete slice through real call sites.
|
|
126
|
+
4. Discovery change: run `yarn generate`; then the smallest gate/integration paths.
|
|
127
|
+
|
|
128
|
+
Precedence: root → BC → installed `AGENTS.md` → facts; stop on skew/conflict; never guess.
|
|
@@ -36,6 +36,7 @@
|
|
|
36
36
|
"qa-approved",
|
|
37
37
|
"qa-self-verified",
|
|
38
38
|
"in-progress",
|
|
39
|
+
"ci-monitoring",
|
|
39
40
|
"screenshots"
|
|
40
41
|
],
|
|
41
42
|
"priority": [
|
|
@@ -51,6 +52,7 @@
|
|
|
51
52
|
]
|
|
52
53
|
},
|
|
53
54
|
"qaGate": false,
|
|
55
|
+
"reviewChecklist": ".ai/review-checklist.md",
|
|
54
56
|
"paths": {
|
|
55
57
|
"runs": ".ai/runs",
|
|
56
58
|
"analysis": ".ai/analysis",
|