@open-mercato/cli 0.6.7 → 0.6.8-develop.6874.1.982d6097d8

package/.turbo/turbo-build.log

@@ -1,6 +1,5 @@
-[build:cli] found 96 entry points
+[build:cli] found 101 entry points
 Copied create-app/agentic/ → dist/agentic/
-Discovered 7 standalone guides → dist/agentic/guides/
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for ai_assistant
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for channel_gmail
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for channel_imap
@@ -20,14 +19,13 @@ Discovered 7 standalone guides → dist/agentic/guides/
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for customers
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for dashboards
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for data_sync
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for design_system
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for dictionaries
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for directory
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for entities
-Generated 54 module fact-sheets → dist/agentic/guides/modules/
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for feature_toggles
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for inbox_ops
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for integrations
-[build:cli] built successfully
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for messages
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for notifications
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for payment_gateways
@@ -57,3 +55,5 @@ Generated 54 module fact-sheets → dist/agentic/guides/modules/
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for storage_s3
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for sync_akeneo
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for webhooks
+Generated 55 module fact-sheets → dist/agentic/guides/modules/
+[build:cli] built successfully

package/build.mjs

@@ -1,4 +1,5 @@
 import { chmodSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { createHash } from 'node:crypto'
 import { dirname, join } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import { atomicWriteFileSync } from '../../scripts/lib/add-js-extension.mjs'
@@ -26,11 +27,26 @@ await buildPackage(packageDir, {
     // Copy agentic source files from create-app so generators can read them at runtime.
     const agenticSrc = join(packageDir, '..', 'create-app', 'agentic')
     if (existsSync(agenticSrc)) {
+      rmSync(join(outdir, 'agentic'), { recursive: true, force: true })
       cpSync(agenticSrc, join(outdir, 'agentic'), { recursive: true })
       console.log('Copied create-app/agentic/ → dist/agentic/')
     }
 
-    // Discover standalone guides across sibling packages.
+    const repositoryRoot = join(packageDir, '..', '..')
+    const upstreamDir = join(outdir, 'agentic', 'guides', 'upstream')
+    mkdirSync(upstreamDir, { recursive: true })
+    const cliVersion = JSON.parse(readFileSync(join(packageDir, 'package.json'), 'utf8')).version ?? null
+    const upstreamManifest = { version: 1, generator: `@open-mercato/cli@${cliVersion ?? 'unknown'}`, files: {} }
+    for (const file of ['AGENTS.md', 'BACKWARD_COMPATIBILITY.md']) {
+      const source = join(repositoryRoot, file)
+      const destination = join(upstreamDir, file)
+      cpSync(source, destination)
+      upstreamManifest.files[file] = createHash('sha256').update(readFileSync(source)).digest('hex')
+    }
+    writeFileSync(join(upstreamDir, 'manifest.json'), `${JSON.stringify(upstreamManifest, null, 2)}\n`)
+
+    // Discover module-specific standalone guides across sibling packages. Package-level
+    // guides are intentionally not shipped because they duplicate routed conceptual guides.
     const packagesDir = join(packageDir, '..')
     const guidesDestDir = join(outdir, 'agentic', 'guides')
     mkdirSync(guidesDestDir, { recursive: true })
@@ -39,8 +55,7 @@ await buildPackage(packageDir, {
     // retains a removed module's full guide or fact-sheet. The legacy `core.<module>.md`
     // redirect stubs are no longer emitted (#3754); this purge also deletes any that linger
     // in an incremental `dist/` from an older build. Mirrors packages/create-app/build.mjs;
-    // the conceptual `module-system.md` and the single-dot package guides are
-    // re-copied/re-discovered below.
+    // conceptual guides remain while stale single-dot package guides are removed below.
     rmSync(join(guidesDestDir, 'modules'), { recursive: true, force: true })
     for (const entry of readdirSync(guidesDestDir)) {
       if (/^core\..+\.md$/.test(entry)) {
@@ -50,10 +65,11 @@ await buildPackage(packageDir, {
 
     let guidesFound = 0
     for (const pkg of readdirSync(packagesDir)) {
+      // Package-level source guides remain for monorepo context, but standalone apps route
+      // through conceptual and module-level guides, so remove their stale emitted copies.
       const guideSource = join(packagesDir, pkg, 'agentic', 'standalone-guide.md')
       if (existsSync(guideSource)) {
-        cpSync(guideSource, join(guidesDestDir, `${pkg}.md`))
-        guidesFound++
+        rmSync(join(guidesDestDir, `${pkg}.md`), { force: true })
       }
 
       const modulesDir = join(packagesDir, pkg, 'src', 'modules')
@@ -76,7 +92,7 @@ await buildPackage(packageDir, {
     // the freshly built ts-morph extractor + resolver-routed discovery, so
     // `mercato agentic:init` bundles the same guides as a create-mercato-app scaffold
     // (packages/create-app/build.mjs). Discovery goes through the resolver, never a
-    // hardcoded packages/* path (.ai/lessons.md §161-169).
+    // hardcoded packages/* path (.ai/lessons/standalone-scaffolding-and-generators-must-not-assume.md).
     const { extractAllModuleFacts, renderModuleFactsJson } = await import(
       pathToFileURL(join(outdir, 'lib', 'generators', 'module-facts.js')).href
     )
@@ -95,7 +111,7 @@ await buildPackage(packageDir, {
         coreVersion = null
       }
 
-      const { factsByModule, markdownByModule, warnings } = extractAllModuleFacts({
+      const { factsByModule, markdownByModule, frameworkMarkdown, warnings } = extractAllModuleFacts({
         sources,
         registryPath: existsSync(registryPath) ? registryPath : null,
         coreVersion,
@@ -107,6 +123,7 @@ await buildPackage(packageDir, {
         writeFileSync(join(modulesGuidesDir, `${moduleId}.md`), markdown)
       }
       writeFileSync(join(guidesDestDir, 'module-facts.json'), renderModuleFactsJson(factsByModule))
+      writeFileSync(join(guidesDestDir, 'framework-extension-points.md'), frameworkMarkdown)
 
       for (const warning of warnings) console.warn(warning)
       console.log(`Generated ${Object.keys(markdownByModule).length} module fact-sheets → dist/agentic/guides/modules/`)

package/dist/agentic/claude-code/hooks/entity-migration-check.ts

@@ -1,121 +1,65 @@
-/**
- * Claude Code PostToolUse hook: entity-migration-check
- *
- * Fires after Write/Edit/MultiEdit. Detects entity file modifications
- * without an accompanying migration and blocks the agent with a reminder.
- *
- * Three-state logic:
- * 1. Migration file was written → exit 0 (agent is already on it)
- * 2. Not an entity file → exit 0 (not relevant)
- * 3. Entity written, no fresh migration → block with migration instructions
- */
-
+/** Remind Claude Code to generate and review a schema diff after entity edits. */
 import { readdirSync, statSync } from 'node:fs'
 import { join, relative } from 'node:path'
 
-const ENTITY_PATTERN = /^src\/modules\/([^/]+)\/entities\/.*\.ts$/
-const MIGRATION_PATTERN = /^src\/modules\/([^/]+)\/migrations\/.*\.ts$/
+const ENTITY_PATTERN = /^src\/modules\/([^/]+)\/data\/entities\.ts$/
+const MIGRATION_PATTERN = /^src\/modules\/([^/]+)\/migrations\/[^/]+\.ts$/
 
 interface PostToolUseInput {
-  tool_input?: {
-    file_path?: string
-    content?: string
-  }
-  tool_name?: string
+  tool_input?: { file_path?: string }
 }
 
-function getRelativePath(filePath: string): string {
-  const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd()
-  if (filePath.startsWith('/')) {
-    return relative(projectDir, filePath)
-  }
-  return filePath
+function projectDir(): string {
+  return process.env.CLAUDE_PROJECT_DIR || process.cwd()
 }
 
-function hasFreshMigration(moduleId: string): boolean {
-  const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd()
-  const migrationsDir = join(projectDir, 'src', 'modules', moduleId, 'migrations')
+function normalizedRelative(filePath: string): string {
+  const value = filePath.startsWith('/') ? relative(projectDir(), filePath) : filePath
+  return value.replaceAll('\\', '/')
+}
 
+function hasFreshMigration(moduleId: string): boolean {
+  const migrationsDir = join(projectDir(), 'src', 'modules', moduleId, 'migrations')
   try {
-    const files = readdirSync(migrationsDir)
-    const now = Date.now()
-    const thirtySecondsAgo = now - 30_000
-
-    for (const file of files) {
-      if (!file.endsWith('.ts')) continue
-      const stat = statSync(join(migrationsDir, file))
-      if (stat.mtimeMs > thirtySecondsAgo) {
-        return true
-      }
-    }
+    const cutoff = Date.now() - 30_000
+    return readdirSync(migrationsDir).some((file) =>
+      file.endsWith('.ts') && statSync(join(migrationsDir, file)).mtimeMs > cutoff,
+    )
   } catch {
-    // migrations directory doesn't exist yet — that's fine
+    return false
   }
-
-  return false
 }
 
 async function main(): Promise<void> {
   let input = ''
-  for await (const chunk of process.stdin) {
-    input += chunk
-  }
-
-  if (!input.trim()) {
-    process.exit(0)
-  }
+  for await (const chunk of process.stdin) input += chunk
+  if (!input.trim()) return
 
   let data: PostToolUseInput
   try {
     data = JSON.parse(input)
   } catch {
-    process.exit(0)
+    return
   }
 
   const filePath = data.tool_input?.file_path
-  if (!filePath) {
-    process.exit(0)
-  }
+  if (!filePath) return
+  const rel = normalizedRelative(filePath)
+  if (MIGRATION_PATTERN.test(rel)) return
 
-  const rel = getRelativePath(filePath)
+  const match = rel.match(ENTITY_PATTERN)
+  if (!match || hasFreshMigration(match[1])) return
 
-  // State 1: Migration file was written → agent is already handling it
-  if (MIGRATION_PATTERN.test(rel)) {
-    process.exit(0)
-  }
-
-  // State 2: Not an entity file → not relevant
-  const entityMatch = rel.match(ENTITY_PATTERN)
-  if (!entityMatch) {
-    process.exit(0)
-  }
-
-  const moduleId = entityMatch[1]
-
-  // State 3: Entity written — check for fresh migration
-  if (hasFreshMigration(moduleId)) {
-    process.exit(0)
-  }
-
-  // Block: entity modified without migration
-  const result = {
+  process.stdout.write(JSON.stringify({
     decision: 'block',
     reason: [
-      `Entity file modified: ${rel}`,
-      '',
-      `Affected module: ${moduleId}`,
-      '',
-      'A database migration is likely needed. Ask the user whether to run:',
-      '  yarn db:generate',
+      `Entity contract changed: ${rel}`,
       '',
-      'Then regenerate registries:',
-      '  yarn generate',
-      '',
-      'Do NOT run migrations automatically — always confirm with the user first.',
+      'Run `yarn db:generate` as a schema-diff probe and review only the scoped migration plus module snapshot.',
+      'Run `yarn generate` when discovery changed.',
+      'Do not apply the migration with `yarn db:migrate` without explicit user approval.',
     ].join('\n'),
-  }
-
-  process.stdout.write(JSON.stringify(result))
+  }))
 }
 
-main()
+void main()

package/dist/agentic/codex/enforcement-rules.md

@@ -1,20 +1,6 @@
 <!-- CODEX_ENFORCEMENT_RULES_START -->
-## CRITICAL rules — always follow without exception
+## Codex enforcement
 
-1. **After editing any entity file** (`src/modules/<id>/entities/*.ts`):
-   - STOP immediately before any further action
-   - Tell the user: "I modified an entity in module <id>. Should I create a migration?"
-   - If yes: run `yarn mercato db generate`
-   - Show the generated migration to the user before applying
-   - Ask for confirmation, then run `yarn mercato db migrate`
-   - Run `yarn generate` after migration is applied
+Read and route through the rest of this file; its `Always`, `Never`, and Task Router sections are the authority for Codex too. They are stated once below rather than duplicated here, so this prelude costs the router no budget.
 
-2. **After editing `src/modules.ts`**: immediately run `yarn generate`
-
-3. **Never edit `.mercato/generated/*`**: edit the source and run `yarn generate` instead
-
-4. **Before significant features**: check `.ai/specs/` for an existing spec.
-   If none exists, ask the user whether to create one first.
-
----
 <!-- CODEX_ENFORCEMENT_RULES_END -->

package/dist/agentic/cursor/hooks/entity-migration-check.mjs

@@ -1,69 +1,38 @@
-/**
- * Cursor afterFileEdit hook: entity-migration-check
- *
- * Detects entity file modifications without an accompanying migration
- * and exits non-zero to block the agent with a reminder.
- *
- * Three-state logic:
- * 1. Migration file was written → exit 0 (agent is already on it)
- * 2. Not an entity file → exit 0 (not relevant)
- * 3. Entity written, no fresh migration → exit 1 with warning
- */
-
+/** Remind Cursor to generate and review a schema diff after entity edits. */
 import { readdirSync, statSync } from 'node:fs'
-import { join, resolve } from 'node:path'
+import { join, relative, resolve } from 'node:path'
 
-const ENTITY_RE = /^src\/modules\/([^/]+)\/entities\/.*\.ts$/
-const MIGRATION_RE = /^src\/modules\/([^/]+)\/migrations\/.*\.ts$/
+const ENTITY_RE = /^src\/modules\/([^/]+)\/data\/entities\.ts$/
+const MIGRATION_RE = /^src\/modules\/([^/]+)\/migrations\/[^/]+\.ts$/
 
 function hasFreshMigration(projectDir, moduleId) {
   const migrationsDir = join(projectDir, 'src', 'modules', moduleId, 'migrations')
   try {
-    const files = readdirSync(migrationsDir)
     const cutoff = Date.now() - 30_000
-    for (const file of files) {
-      if (!file.endsWith('.ts')) continue
-      const stat = statSync(join(migrationsDir, file))
-      if (stat.mtimeMs > cutoff) return true
-    }
+    return readdirSync(migrationsDir).some((file) =>
+      file.endsWith('.ts') && statSync(join(migrationsDir, file)).mtimeMs > cutoff,
+    )
   } catch {
-    // migrations directory doesn't exist yet
+    return false
   }
-  return false
 }
 
 const filePath = process.argv[2]
 if (!filePath) process.exit(0)
 
 const projectDir = resolve('.')
-const rel = filePath.startsWith('/') ? filePath.slice(projectDir.length + 1) : filePath
-
-// State 1: Migration file written
+const rel = (filePath.startsWith('/') ? relative(projectDir, filePath) : filePath).replaceAll('\\', '/')
 if (MIGRATION_RE.test(rel)) process.exit(0)
 
-// State 2: Not an entity file
 const match = rel.match(ENTITY_RE)
-if (!match) process.exit(0)
-
-const moduleId = match[1]
-
-// State 3: Entity file without fresh migration
-if (hasFreshMigration(projectDir, moduleId)) process.exit(0)
-
-process.stderr.write(
-  [
-    `Entity file modified: ${rel}`,
-    '',
-    `Affected module: ${moduleId}`,
-    '',
-    'A database migration is likely needed. Ask the user whether to run:',
-    '  yarn db:generate',
-    '',
-    'Then regenerate registries:',
-    '  yarn generate',
-    '',
-    'Do NOT run migrations automatically — always confirm with the user first.',
-    '',
-  ].join('\n'),
-)
+if (!match || hasFreshMigration(projectDir, match[1])) process.exit(0)
+
+process.stderr.write([
+  `Entity contract changed: ${rel}`,
+  '',
+  'Run `yarn db:generate` as a schema-diff probe and review only the scoped migration plus module snapshot.',
+  'Run `yarn generate` when discovery changed.',
+  'Do not apply the migration with `yarn db:migrate` without explicit user approval.',
+  '',
+].join('\n'))
 process.exit(1)

package/dist/agentic/cursor/rules/entity-guard.mdc

@@ -1,29 +1,17 @@
 ---
-description: Entity modification guard — triggers migration workflow
+description: Entity schema-diff guard for the canonical standalone entity file
 globs:
-  - src/modules/*/entities/**/*.ts
+  - src/modules/*/data/entities.ts
 alwaysApply: false
 ---
 
-# Entity Modification — Migration Required
+# Entity Schema Change
 
-You are editing an entity file. After saving, you MUST:
+Follow root `AGENTS.md` and `om-data-model-design`:
 
-1. **Create a migration** — ask the user before running:
-   ```
-   yarn db:generate
-   ```
+1. Run `yarn db:generate` as a schema-diff probe.
+2. Review and keep only scoped migration SQL plus the touched module snapshot.
+3. Run `yarn generate` when discovery changed.
+4. Ask before applying with `yarn db:migrate`.
 
-2. **Show the migration** to the user and wait for confirmation before applying
-
-3. **Apply the migration** (only after user confirms):
-   ```
-   yarn db:migrate
-   ```
-
-4. **Regenerate registries**:
-   ```
-   yarn generate
-   ```
-
-Do NOT skip any step. Do NOT run migrations without user confirmation.
+Never edit a shipped migration or generated registry.

package/dist/agentic/cursor/rules/generated-guard.mdc

@@ -1,12 +1,10 @@
 ---
-description: Prevent editing auto-generated files
+description: Prevent edits to generated application registries
 globs:
   - .mercato/generated/**
 alwaysApply: false
 ---
 
-# NEVER Edit Generated Files
+# Generated File
 
-This file is auto-generated by `yarn generate`. Any manual edits will be overwritten.
-
-To change generated output, edit the source modules in `src/modules/` and run `yarn generate`.
+Do not edit this file. Change the app module source and run `yarn generate`; follow root `AGENTS.md` for the routed contract.

package/dist/agentic/cursor/rules/open-mercato.mdc

@@ -1,34 +1,8 @@
 ---
-description: Core Open Mercato conventions for standalone app development
+description: Route every standalone app task through the root agent rules
 alwaysApply: true
 ---
 
-# {{PROJECT_NAME}} — Project Rules
+# {{PROJECT_NAME}} — Cursor Entry Point
 
-## What this project is
-
-A standalone Open Mercato application. Build domain features ON TOP of the framework.
-To customise a core module beyond the extension system: `yarn mercato eject <module>`.
-Never edit node_modules/@open-mercato/* directly.
-
-## Task routing
-
-Read AGENTS.md before starting any task — it maps task types to the minimum files to load.
-
-## Module system
-
-Modules in `src/modules/<id>/`. Register with `from: '@app'` in `src/modules.ts`.
-Run `yarn generate` after any module or entity change. Never edit `.mercato/generated/*`.
-
-## Entity and migration rule
-
-After editing any entity in `src/modules/<id>/entities/`:
-1. Create migration: `yarn db:generate`
-2. Show migration to user, confirm before applying
-3. Apply: `yarn db:migrate`
-4. Regenerate: `yarn generate`
-
-## Spec-driven development
-
-Check `.ai/specs/` before any significant feature. If no spec exists, ask the user
-whether to create one first.
+Read `AGENTS.md`, match every applicable Task Router row, and load only the routed guides, skills, and module facts. The root file owns architecture, safety, writable paths, migrations, generation, and validation; do not duplicate or override it here.

package/dist/agentic/guides/ai-workflows.md

@@ -0,0 +1,76 @@
+# AI Agents, Orchestrators, and Workflows
+
+Use typed module contracts for product AI and the workflow engine for durable business processes. Keep model/tool execution, mutation approval, scope, storage, and retries explicit.
+
+## Choose the Surface
+
+| Need | Use |
+|---|---|
+| In-app conversational or structured domain assistant | Module `ai-agents.ts` plus `ai-tools.ts`. |
+| Low-level MCP/OpenCode or Code Mode work | `ai_assistant` installed contract: `registerMcpTool`, MCP server, OpenCode handlers/config, or the `search`/`execute` Code Mode tools. Do not conflate this with a typed product agent. |
+| Add a few tools/prompt/suggestions to an installed agent | `aiAgentExtensions`. |
+| Replace or disable an installed agent/tool | `aiAgentOverrides` / `aiToolOverrides` or module entry override. |
+| Coding-agent orchestration with files, outcomes, samples, embedded skill, or subagents | Orchestrator file-agent contract; resolve its installed package guide first. |
+| Durable business process, human task, timer, signal, compensation, or event trigger | Workflows module and `om-build-workflow`. |
+| One background AI extraction | Object-mode agent invoked from a scoped command/worker. |
+
+## Typed Module Agents and Tools
+
+- Put `ai-agents.ts` and `ai-tools.ts` at the module root. Export typed arrays and run `yarn generate`.
+- Give agent IDs `<module>.<agent>` and tool names stable namespaced IDs. Declare provider/model defaults through the framework registry/model factory, not provider SDK singletons.
+- Every data tool has a Zod input schema, tenant/org scope, wildcard-aware `requiredFeatures`, bounded output, and a serializable result.
+- Mark writes `isMutation: true`. Pair mutation-capable agents with `readOnly: false` and a confirmation policy.
+- A write tool calls `prepareMutation`; the durable execute callback performs a command-based, optimistic-lock-aware mutation. Never write directly before approval.
+- Use declarative loop controls/budgets. The wrapper-owned approval guard remains active on every step and execution engine.
+- Validate attachments by type/size/scope. Store outputs through authorized artifact/attachment services with retention and encrypted sensitive metadata.
+
+## MCP, OpenCode, and Code Mode
+
+- Prefer `defineAiTool` in discovered `ai-tools.ts` for product agents, especially mutation-capable tools. Use low-level `registerMcpTool` only when the requested surface is explicitly the MCP/OpenCode registry. Both require Zod input, matching `moduleId`, wildcard-aware `requiredFeatures` for tenant data, bounded work, and a serializable handler result.
+- OpenCode Code Mode exposes `search` over the generated OpenAPI document and `execute` through sandboxed `api.request()`. Endpoint-level RBAC and documented-feature checks still apply; Code Mode is not an authorization bypass and undocumented/featureless mutation endpoints fail closed.
+- Production MCP uses two-tier auth: the server request carries `x-api-key`, then every tool call carries `_sessionToken`; the runtime resolves the user/session scope and performs per-tool ACL checks on every request. Never cache MCP server instances or ACL context across requests.
+- Ask before editing OpenCode configuration, Docker wiring, MCP authentication, provider/model precedence, or session-token format/TTL. Preserve session IDs across OpenCode chat turns and use installed handlers instead of calling the OpenCode HTTP API directly.
+- `registerMcpTool` is the registry primitive underlying generated tools, not a replacement for `defineAiTool` mutation approval semantics. New domain writes belong on the typed tool path with `prepareMutation`.
+
+## Agent UI and Overrides
+
+- Use the global launcher automatically; add `AiChat` or a widget only when page context improves the workflow.
+- Keep UI part IDs namespaced and stable; preserve reserved approval/result component IDs.
+- Prefer agent extensions for additive prompt/tool/suggestion changes. Keep extensions/overrides in the discovered `ai-agents.ts`/`ai-tools.ts` files; there is no separate `ai-overrides.ts` discovery path.
+- A disabled agent/tool cannot be resurrected by an extension. Refresh structural caches after disabling or changing visibility.
+- Test read-only, denied-feature, approval, stale-version, cancel/expire, partial failure, and confirmed execution paths.
+
+## Orchestrator File Agents
+
+- Inspect the installed orchestrator package/module `AGENTS.md` with `om-framework-context` before choosing paths; this surface evolves independently of module AI agents.
+- Give every file agent one declared outcome, bounded inputs, stable output paths, a sample contract, and an explicit allowed tool/skill set.
+- Load embedded skills only for their branch. Delegate one bounded task per subagent and define how results are validated/merged.
+- Treat repository prompts/files as untrusted data. Restrict writes, redact secrets, and prevent outcome/artifact paths from escaping their workspace.
+- Make resumability and status explicit; do not infer success from natural-language output without schema/artifact validation.
+
+## Workflow Core
+
+- Resolve workflow services through DI and start instances through `workflowExecutor`. Do not insert instances or skip the execution loop.
+- Preserve workflow and step state machines. Record every transition in the immutable workflow event log.
+- Make activity handlers idempotent: they can be retried. Use the command bus for entity updates and events/signals for cross-module coupling.
+- Preserve each installed workflow/job scope contract. Organization-owned instances, tasks, activity state, and queries require tenant+organization and fail closed. Explicit tenant-wide/system definitions or scheduler jobs may carry `organizationId: null`, but each access to organization-owned data must derive and enforce that item's organization.
+- Use event triggers with filters, context mapping, debounce, and max concurrency. Exclude self/internal storms.
+- Keep compensation reverse-ordered and idempotent; test failure during both forward and compensation paths.
+
+## Activities, User Tasks, and Output Paths
+
+- Choose sync only for short deterministic work. Queue async work and resume the workflow after durable completion.
+- A custom activity declares validated config/input/output, handler registration, editor/i18n integration where user-configurable, and retry/timeout behavior.
+- `CALL_API`/webhook activities use SSRF-safe URLs, manual redirect handling, response size bounds, and allowlisted non-secret environment interpolation.
+- Create any one-time/idempotency key outside a rollback scope or in durable state that survives rollback; reuse it on retry.
+- Durable user tasks require assignment/features, due dates, authorized completion, immutable activity history, and no secret values in task payloads.
+- Write outputs to stable declared activity/artifact paths. Validate path containment and access; clean temporary files while retaining declared deliverables.
+- Emit progress/events for long work and render them through shared progress/UI contracts rather than unbounded polling.
+
+## Verification
+
+1. Run `yarn generate` and confirm agent/tool/workflow registrations.
+2. Test missing provider/configuration, denied ACL, missing scope, timeout, retry, duplicate, and cancellation.
+3. For AI writes, prove no domain write occurs before approval and a stale approval cannot overwrite newer data.
+4. For workflows, prove event log/state transitions and idempotency across worker restart and injected rollback.
+5. For orchestrators, validate output schema/artifacts and allowed-write boundaries, not just prose.