@open-mercato/cli 0.7.1-develop.7191.1.3c9346566b → 0.7.1-develop.7194.1.ab4fc81f82

package/src/lib/generators/__tests__/agent-files-extension.test.ts

@@ -0,0 +1,477 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import type { ModuleScanContext } from '../extension'
+import { createAgentFilesExtension } from '../extensions/agent-files'
+
+/**
+ * Build a fake repo root with `docker/opencode` + `packages` markers (so the
+ * extension's `findRepoRoot` resolves it) and a module whose `agents/<id>/`
+ * fixture lives under `appBase`.
+ */
+function makeRepoFixture(): { repoRoot: string; appBase: string; pkgBase: string } {
+  const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-files-repo-'))
+  fs.mkdirSync(path.join(repoRoot, 'docker', 'opencode'), { recursive: true })
+  fs.mkdirSync(path.join(repoRoot, 'packages'), { recursive: true })
+
+  const appBase = path.join(repoRoot, 'apps', 'mercato', 'src', 'modules', 'agent_examples')
+  const pkgBase = path.join(repoRoot, 'packages', 'core', 'src', 'modules', 'agent_examples')
+  const agentDir = path.join(appBase, 'agents', 'deals_health_check')
+  fs.mkdirSync(agentDir, { recursive: true })
+
+  fs.writeFileSync(
+    path.join(agentDir, 'AGENT.md'),
+    [
+      '---',
+      'id: deals.health_check',
+      'label: Deal health check',
+      'description: Assess a deal.',
+      'maxSteps: 12',
+      '---',
+      'You assess a deal.',
+    ].join('\n'),
+    'utf8',
+  )
+  fs.writeFileSync(
+    path.join(agentDir, 'OUTCOME.md'),
+    [
+      '---',
+      'kind: proposal',
+      '---',
+      '```json',
+      JSON.stringify({
+        type: 'object',
+        required: ['confidence'],
+        properties: { confidence: { type: 'number', minimum: 0, maximum: 1 } },
+      }),
+      '```',
+    ].join('\n'),
+    'utf8',
+  )
+
+  return { repoRoot, appBase, pkgBase }
+}
+
+function createScanContext(moduleId: string, appBase: string, pkgBase: string): ModuleScanContext {
+  return {
+    moduleId,
+    roots: { appBase, pkgBase },
+    imps: { appBase: `@/modules/${moduleId}`, pkgBase: `@open-mercato/core/modules/${moduleId}` },
+    importIdRef: { value: 0 },
+    sharedImports: [],
+    resolveModuleFile: (() => null) as ModuleScanContext['resolveModuleFile'],
+    resolveFirstModuleFile: (() => null) as ModuleScanContext['resolveFirstModuleFile'],
+    processStandaloneConfig: () => null,
+    sanitizeGeneratedModuleSpecifier: (importPath) => importPath,
+  }
+}
+
+describe('createAgentFilesExtension', () => {
+  let repoRoot = ''
+  afterEach(() => {
+    if (repoRoot) fs.rmSync(repoRoot, { recursive: true, force: true })
+    repoRoot = ''
+  })
+
+  it('discovers agents/<id>/ and emits the manifest + docker agent file', () => {
+    const fixture = makeRepoFixture()
+    repoRoot = fixture.repoRoot
+
+    const extension = createAgentFilesExtension()
+    expect(extension.id).toBe('registry.agent-files')
+
+    extension.scanModule(createScanContext('agent_examples', fixture.appBase, fixture.pkgBase))
+    const output = extension.generateOutput()
+    expect(output.size).toBe(0)
+
+    const manifestPath = path.join(
+      repoRoot,
+      'packages/enterprise/src/modules/agent_orchestrator/generated/file-agents.generated.ts',
+    )
+    expect(fs.existsSync(manifestPath)).toBe(true)
+    const manifest = fs.readFileSync(manifestPath, 'utf8')
+    expect(manifest).toContain('AUTO-GENERATED by mercato generate registry')
+    expect(manifest).toContain("id: \"deals.health_check\"")
+    expect(manifest).toContain("openCodeAgentName: \"deals_health_check\"")
+    expect(manifest).toContain('export const fileAgentDescriptors')
+
+    const dockerFile = path.join(repoRoot, 'docker/opencode/agents/deals_health_check.md')
+    expect(fs.existsSync(dockerFile)).toBe(true)
+    const dockerContent = fs.readFileSync(dockerFile, 'utf8')
+    expect(dockerContent).toContain('mode: primary')
+    expect(dockerContent).toContain('open-mercato_agent_orchestrator_submit_outcome')
+    expect(dockerContent).toContain('write: deny')
+    // No sub-agents declared → `task` denied and no delegate tool (unchanged).
+    expect(dockerContent).toContain('task: deny')
+    expect(dockerContent).not.toContain('delegate_agent')
+  })
+
+  it('routes file-agent delegation through delegate_agent instead of the task tool', () => {
+    const fixture = makeRepoFixture()
+    repoRoot = fixture.repoRoot
+    const agentDir = path.join(fixture.appBase, 'agents', 'deals_health_check')
+
+    // Declare a sub-agent under sub-agents/<subid>/ (researcher + non-delegating).
+    fs.writeFileSync(
+      path.join(agentDir, 'AGENT.md'),
+      [
+        '---',
+        'id: deals.health_check',
+        'label: Deal health check',
+        'description: Assess a deal.',
+        '---',
+        'You assess a deal.',
+      ].join('\n'),
+      'utf8',
+    )
+    const subDir = path.join(agentDir, 'sub-agents', 'company_researcher')
+    fs.mkdirSync(subDir, { recursive: true })
+    fs.writeFileSync(
+      path.join(subDir, 'AGENT.md'),
+      [
+        '---',
+        'id: deals.company_researcher',
+        'label: Company researcher',
+        'description: Research a company.',
+        '---',
+        'You research a company.',
+      ].join('\n'),
+      'utf8',
+    )
+    fs.writeFileSync(
+      path.join(subDir, 'OUTCOME.md'),
+      [
+        '---',
+        'kind: research',
+        '---',
+        '```json',
+        JSON.stringify({ type: 'object', properties: { summary: { type: 'string' } } }),
+        '```',
+      ].join('\n'),
+      'utf8',
+    )
+
+    const extension = createAgentFilesExtension()
+    extension.scanModule(createScanContext('agent_examples', fixture.appBase, fixture.pkgBase))
+    extension.generateOutput()
+
+    const primary = fs.readFileSync(
+      path.join(repoRoot, 'docker/opencode/agents/deals_health_check.md'),
+      'utf8',
+    )
+    // The orchestrator gains the delegate_agent MCP tool, denies `task`, and
+    // never grants the built-in task tool.
+    expect(primary).toContain('open-mercato_agent_orchestrator_delegate_agent')
+    expect(primary).toContain('task: deny')
+    expect(primary).not.toContain('"task": true')
+    // The prompt delegates through delegate_agent (not `task`) using the FULL
+    // sub-agent id.
+    expect(primary).toContain('## Sub-agents')
+    expect(primary).toContain('delegate_agent')
+    expect(primary).toContain('deals.company_researcher')
+    expect(primary).not.toContain('by calling the `task` tool')
+
+    // The sub-agent file gets neither the delegate tool nor `task` (depth cap = 1).
+    const sub = fs.readFileSync(
+      path.join(repoRoot, 'docker/opencode/agents/deals_company_researcher.md'),
+      'utf8',
+    )
+    expect(sub).toContain('mode: subagent')
+    expect(sub).toContain('task: deny')
+    expect(sub).not.toContain('delegate_agent')
+  })
+
+  it('emits an agent SAMPLE.json into the manifest as sampleInput', () => {
+    const fixture = makeRepoFixture()
+    repoRoot = fixture.repoRoot
+    const agentDir = path.join(fixture.appBase, 'agents', 'deals_health_check')
+    fs.writeFileSync(
+      path.join(agentDir, 'SAMPLE.json'),
+      JSON.stringify({ deal: { id: 'demo-deal-1', stage: 'Proposal' } }),
+      'utf8',
+    )
+
+    const extension = createAgentFilesExtension()
+    extension.scanModule(createScanContext('agent_examples', fixture.appBase, fixture.pkgBase))
+    extension.generateOutput()
+
+    const manifest = fs.readFileSync(
+      path.join(repoRoot, 'packages/enterprise/src/modules/agent_orchestrator/generated/file-agents.generated.ts'),
+      'utf8',
+    )
+    expect(manifest).toContain('sampleInput: {"deal":{"id":"demo-deal-1","stage":"Proposal"}}')
+  })
+
+  it('fails generation on a malformed SAMPLE.json', () => {
+    const fixture = makeRepoFixture()
+    repoRoot = fixture.repoRoot
+    const agentDir = path.join(fixture.appBase, 'agents', 'deals_health_check')
+    fs.writeFileSync(path.join(agentDir, 'SAMPLE.json'), '{ not valid json', 'utf8')
+
+    const extension = createAgentFilesExtension()
+    expect(() =>
+      extension.scanModule(createScanContext('agent_examples', fixture.appBase, fixture.pkgBase)),
+    ).toThrow(/malformed SAMPLE\.json/)
+  })
+
+  it('emits an agent FACTS.json into the manifest as facts', () => {
+    const fixture = makeRepoFixture()
+    repoRoot = fixture.repoRoot
+    const agentDir = path.join(fixture.appBase, 'agents', 'deals_health_check')
+    fs.writeFileSync(
+      path.join(agentDir, 'FACTS.json'),
+      JSON.stringify({
+        facts: [
+          { label: 'Stage', source: 'input', path: 'deal.stage' },
+          { label: 'Confidence', source: 'payload', path: 'confidence', format: 'percent' },
+        ],
+      }),
+      'utf8',
+    )
+
+    const extension = createAgentFilesExtension()
+    extension.scanModule(createScanContext('agent_examples', fixture.appBase, fixture.pkgBase))
+    extension.generateOutput()
+
+    const manifest = fs.readFileSync(
+      path.join(repoRoot, 'packages/enterprise/src/modules/agent_orchestrator/generated/file-agents.generated.ts'),
+      'utf8',
+    )
+    expect(manifest).toContain(
+      'facts: [{"label":"Stage","source":"input","path":"deal.stage"},{"label":"Confidence","source":"payload","path":"confidence","format":"percent"}]',
+    )
+    expect(manifest).toContain('export type FileAgentFact')
+  })
+
+  it('fails generation on a FACTS.json entry missing label/source/path', () => {
+    const fixture = makeRepoFixture()
+    repoRoot = fixture.repoRoot
+    const agentDir = path.join(fixture.appBase, 'agents', 'deals_health_check')
+    fs.writeFileSync(
+      path.join(agentDir, 'FACTS.json'),
+      JSON.stringify({ facts: [{ label: 'Stage', source: 'nowhere', path: 'deal.stage' }] }),
+      'utf8',
+    )
+
+    const extension = createAgentFilesExtension()
+    expect(() =>
+      extension.scanModule(createScanContext('agent_examples', fixture.appBase, fixture.pkgBase)),
+    ).toThrow(/malformed FACTS\.json/)
+  })
+
+  it('fails generation on a malformed agent dir (missing OUTCOME.md)', () => {
+    const fixture = makeRepoFixture()
+    repoRoot = fixture.repoRoot
+    // Remove OUTCOME.md to make the dir malformed.
+    fs.rmSync(path.join(fixture.appBase, 'agents', 'deals_health_check', 'OUTCOME.md'))
+
+    const extension = createAgentFilesExtension()
+    expect(() =>
+      extension.scanModule(createScanContext('agent_examples', fixture.appBase, fixture.pkgBase)),
+    ).toThrow(/malformed file agent/)
+  })
+
+  it('emits native SKILL.md, unions skill tools, and writes skillsContent to the manifest', () => {
+    const fixture = makeRepoFixture()
+    repoRoot = fixture.repoRoot
+    const agentDir = path.join(fixture.appBase, 'agents', 'deals_health_check')
+
+    // Reference a skill in AGENT.md and author it under skills/<skill_id>/.
+    fs.writeFileSync(
+      path.join(agentDir, 'AGENT.md'),
+      [
+        '---',
+        'id: deals.health_check',
+        'label: Deal health check',
+        'description: Assess a deal.',
+        'skills: [stage_playbook]',
+        'tools: [customers.get_deal]',
+        '---',
+        'You assess a deal.',
+      ].join('\n'),
+      'utf8',
+    )
+    const skillDir = path.join(agentDir, 'skills', 'stage_playbook')
+    fs.mkdirSync(path.join(skillDir, 'examples'), { recursive: true })
+    fs.writeFileSync(
+      path.join(skillDir, 'SKILL.md'),
+      [
+        '---',
+        'id: stage_playbook',
+        'label: Stage playbook',
+        'description: Pick the next stage.',
+        'tools: [customers.analyze_deals]',
+        '---',
+        'STAGE_PLAYBOOK_BODY',
+      ].join('\n'),
+      'utf8',
+    )
+    fs.writeFileSync(path.join(skillDir, 'TEMPLATE.md'), 'TEMPLATE_BODY', 'utf8')
+    fs.writeFileSync(path.join(skillDir, 'examples', 'a.md'), 'EXAMPLE_ONE', 'utf8')
+
+    const extension = createAgentFilesExtension()
+    extension.scanModule(createScanContext('agent_examples', fixture.appBase, fixture.pkgBase))
+    extension.generateOutput()
+
+    // Native OpenCode skill file (sanitized dir name: stage_playbook → stage-playbook).
+    const nativeSkill = path.join(repoRoot, 'docker/opencode/skills/stage-playbook/SKILL.md')
+    expect(fs.existsSync(nativeSkill)).toBe(true)
+    const nativeContent = fs.readFileSync(nativeSkill, 'utf8')
+    expect(nativeContent).toContain('name: stage-playbook')
+    expect(nativeContent).toContain('STAGE_PLAYBOOK_BODY')
+
+    // Manifest carries skillsContent and the unioned tool allowlist.
+    const manifest = fs.readFileSync(
+      path.join(repoRoot, 'packages/enterprise/src/modules/agent_orchestrator/generated/file-agents.generated.ts'),
+      'utf8',
+    )
+    expect(manifest).toContain('skillsContent')
+    expect(manifest).toContain('STAGE_PLAYBOOK_BODY')
+    expect(manifest).toContain('TEMPLATE_BODY')
+    expect(manifest).toContain('EXAMPLE_ONE')
+    expect(manifest).toContain('customers.analyze_deals')
+
+    // The docker agent file's tools block includes the skill tool too.
+    const dockerAgent = fs.readFileSync(
+      path.join(repoRoot, 'docker/opencode/agents/deals_health_check.md'),
+      'utf8',
+    )
+    // Declared OM tool ids are mapped to OpenCode's MCP tool id form in the allowlist.
+    expect(dockerAgent).toContain('open-mercato_customers_analyze_deals')
+  })
+
+  it('fails generation on a malformed SKILL.md (no frontmatter)', () => {
+    const fixture = makeRepoFixture()
+    repoRoot = fixture.repoRoot
+    const agentDir = path.join(fixture.appBase, 'agents', 'deals_health_check')
+    fs.writeFileSync(
+      path.join(agentDir, 'AGENT.md'),
+      [
+        '---',
+        'id: deals.health_check',
+        'label: Deal health check',
+        'description: Assess a deal.',
+        'skills: [stage_playbook]',
+        '---',
+        'You assess a deal.',
+      ].join('\n'),
+      'utf8',
+    )
+    const skillDir = path.join(agentDir, 'skills', 'stage_playbook')
+    fs.mkdirSync(skillDir, { recursive: true })
+    fs.writeFileSync(path.join(skillDir, 'SKILL.md'), 'no frontmatter at all', 'utf8')
+
+    const extension = createAgentFilesExtension()
+    expect(() =>
+      extension.scanModule(createScanContext('agent_examples', fixture.appBase, fixture.pkgBase)),
+    ).toThrow(/malformed SKILL\.md/)
+  })
+
+  it('fails generation when an OUTCOME.md schema is outside the supported subset (M2)', () => {
+    const fixture = makeRepoFixture()
+    const agentDir = path.join(fixture.appBase, 'agents', 'deals_health_check')
+    // `oneOf` parses as valid JSON but cannot compile to Zod — must fail at scan,
+    // not silently parse and get dropped at load.
+    fs.writeFileSync(
+      path.join(agentDir, 'OUTCOME.md'),
+      [
+        '---',
+        'kind: proposal',
+        '---',
+        '```json',
+        JSON.stringify({ type: 'object', properties: { x: { oneOf: [{ type: 'string' }] } } }),
+        '```',
+      ].join('\n'),
+      'utf8',
+    )
+    const extension = createAgentFilesExtension()
+    expect(() =>
+      extension.scanModule(createScanContext('agent_examples', fixture.appBase, fixture.pkgBase)),
+    ).toThrow(/unsupported keyword "oneOf"/)
+  })
+
+  it('fails generation when an OUTCOME.md schema node has no supported type (M2)', () => {
+    const fixture = makeRepoFixture()
+    const agentDir = path.join(fixture.appBase, 'agents', 'deals_health_check')
+    fs.writeFileSync(
+      path.join(agentDir, 'OUTCOME.md'),
+      [
+        '---',
+        'kind: research',
+        '---',
+        '```json',
+        JSON.stringify({ type: 'object', properties: { x: { minimum: 0 } } }),
+        '```',
+      ].join('\n'),
+      'utf8',
+    )
+    const extension = createAgentFilesExtension()
+    expect(() =>
+      extension.scanModule(createScanContext('agent_examples', fixture.appBase, fixture.pkgBase)),
+    ).toThrow(/missing\/unsupported "type"/)
+  })
+
+  it('keeps committed agent artifacts when neither the orchestrator nor an agent module is enabled', () => {
+    const fixture = makeRepoFixture()
+    repoRoot = fixture.repoRoot
+    const manifestPath = path.join(
+      repoRoot,
+      'packages/enterprise/src/modules/agent_orchestrator/generated/file-agents.generated.ts',
+    )
+    const dockerFile = path.join(repoRoot, 'docker/opencode/agents/deals_health_check.md')
+    const skillFile = path.join(repoRoot, 'docker/opencode/skills/stage-playbook/SKILL.md')
+    fs.mkdirSync(path.dirname(manifestPath), { recursive: true })
+    fs.mkdirSync(path.dirname(dockerFile), { recursive: true })
+    fs.mkdirSync(path.dirname(skillFile), { recursive: true })
+    fs.writeFileSync(manifestPath, 'committed manifest', 'utf8')
+    fs.writeFileSync(dockerFile, 'committed agent file', 'utf8')
+    fs.writeFileSync(skillFile, 'committed skill file', 'utf8')
+
+    const extension = createAgentFilesExtension()
+    // A module with no `agents/` tree, standing in for a run with the
+    // enterprise agents flag off.
+    const otherBase = path.join(repoRoot, 'packages', 'core', 'src', 'modules', 'customers')
+    fs.mkdirSync(otherBase, { recursive: true })
+    extension.scanModule(createScanContext('customers', otherBase, otherBase))
+    extension.generateOutput()
+
+    expect(fs.readFileSync(manifestPath, 'utf8')).toBe('committed manifest')
+    expect(fs.readFileSync(dockerFile, 'utf8')).toBe('committed agent file')
+    expect(fs.readFileSync(skillFile, 'utf8')).toBe('committed skill file')
+  })
+
+  it('still prunes stale artifacts when the orchestrator is enabled without any agent', () => {
+    const fixture = makeRepoFixture()
+    repoRoot = fixture.repoRoot
+    const dockerFile = path.join(repoRoot, 'docker/opencode/agents/deals_health_check.md')
+    const skillDir = path.join(repoRoot, 'docker/opencode/skills/stage-playbook')
+    fs.mkdirSync(path.dirname(dockerFile), { recursive: true })
+    fs.mkdirSync(skillDir, { recursive: true })
+    fs.writeFileSync(dockerFile, 'stale agent file', 'utf8')
+    fs.writeFileSync(path.join(skillDir, 'SKILL.md'), 'stale skill file', 'utf8')
+
+    const extension = createAgentFilesExtension()
+    const orchestratorBase = path.join(
+      repoRoot,
+      'packages',
+      'enterprise',
+      'src',
+      'modules',
+      'agent_orchestrator',
+    )
+    fs.mkdirSync(orchestratorBase, { recursive: true })
+    extension.scanModule(createScanContext('agent_orchestrator', orchestratorBase, orchestratorBase))
+    extension.generateOutput()
+
+    expect(fs.existsSync(dockerFile)).toBe(false)
+    expect(fs.existsSync(skillDir)).toBe(false)
+    const manifest = fs.readFileSync(
+      path.join(
+        repoRoot,
+        'packages/enterprise/src/modules/agent_orchestrator/generated/file-agents.generated.ts',
+      ),
+      'utf8',
+    )
+    expect(manifest).toContain('export const fileAgentDescriptors: FileAgentDescriptor[] = []')
+  })
+})

package/src/lib/generators/__tests__/module-facts.bc-guard.test.ts

@@ -182,20 +182,37 @@ describe('module-facts BC resolve guard (T2)', () => {
     // facts, plus query-lifecycle, portal-page and strategy-registry hosts that
     // exist only in the v2 surface. Same linear, one-module growth the block
     // above describes -- the caps below are re-measured on the merged tree.
-    expect(Buffer.byteLength(completeJson)).toBeLessThan(4_700_000)
+    //
+    // Re-measured once more on the agent_orchestrator union (#5718). The caps
+    // above were measured on `develop`'s tree, and `develop`'s tree does not
+    // contain `agent_orchestrator`, the expanded `workflows` surface or the
+    // `web-research*` packages — so three of the four sat below the union, which
+    // is the "neither side's cap covers the union" case the note above names.
+    //
+    // The growth is linear and it is checkable: all four measures grew by very
+    // nearly the same proportion (+17.1% / +17.6% / +16.8% / +16.2%), which is
+    // what a union of two additive module sets produces. A real blow-up is
+    // multiplicative and would move one measure far out of step with the others,
+    // so uniform growth across all four is the evidence that this is repo size,
+    // not a duplicated payload. The headroom ratio is kept at the ~1.15 the
+    // previous raise used, so the guard keeps the same detection power it had.
+    expect(Buffer.byteLength(completeJson)).toBeLessThan(5_550_000)
     // Measured on the merged tree (`yarn jest module-facts.bc-guard`):
-    //   completeJson 4,120,374 · legacy delta 1,795,214 · markdown 1,558,590 ·
-    //   directory markdown 1,709,511.
-    // The delta cap is raised alongside the JSON one for the same reason: at
-    // 1,800,000 it sat 0.27% above the measurement, which is not a guard.
-    expect(Buffer.byteLength(completeJson) - Buffer.byteLength(legacyJson)).toBeLessThan(2_050_000)
+    //   completeJson 4,823,226 · legacy delta 2,111,784 · markdown 1,820,787 ·
+    //   directory markdown 1,985,779.
+    // (Previous, on develop's tree: 4,120,374 · 1,795,214 · 1,558,590 · 1,709,511.)
+    expect(Buffer.byteLength(completeJson) - Buffer.byteLength(legacyJson)).toBeLessThan(2_430_000)
     // Markdown cap raised with the source-link contract: entities, events, ACL
     // features, DI tokens, search entities, notifications, UMES hosts and UMES
     // contributions all render a resolved Source cell, and contribution
     // resolutions render as their own source-linked section — plus the additive
     // `channel_discord` module's own render, per the growth note above.
-    expect(markdownBytes).toBeLessThan(1_800_000)
-    expect(directoryMarkdownBytes).toBeLessThan(2_050_000)
+    expect(markdownBytes).toBeLessThan(2_100_000)
+    // Raised even though it was still passing: at 2,050,000 it sat 3.2% above
+    // the union measurement, and a cap that close has stopped detecting blow-ups
+    // and started rejecting the next additive module — the failure mode the note
+    // above warns about, one merge away.
+    expect(directoryMarkdownBytes).toBeLessThan(2_290_000)
   })
 
   it('keeps every shipped directory section resumable and every advertised subsection anchor exact', () => {

package/src/lib/generators/__tests__/route-collisions.test.ts

@@ -0,0 +1,155 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import os from 'node:os'
+import type { PackageResolver, ModuleEntry } from '../../resolver'
+import { generateModuleRegistry } from '../module-registry'
+import { detectBackendRouteCollisions } from '../route-collisions'
+
+let tmpDir: string
+
+const PAGE_CONTENT = `export default function Page() { return null }
+`
+
+function createTmpDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'route-collisions-test-'))
+}
+
+function touchFile(filePath: string, content = ''): void {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true })
+  fs.writeFileSync(filePath, content)
+}
+
+function scaffoldBackendPage(tmpDir: string, modId: string, location: 'pkg' | 'app', pageSubPath: string): void {
+  const base =
+    location === 'pkg'
+      ? path.join(tmpDir, 'packages', 'core', 'src', 'modules', modId)
+      : path.join(tmpDir, 'app', 'src', 'modules', modId)
+  touchFile(path.join(base, 'backend', pageSubPath), PAGE_CONTENT)
+}
+
+function createMockResolver(tmpDir: string, enabled: ModuleEntry[]): PackageResolver {
+  const outputDir = path.join(tmpDir, 'output', 'generated')
+  fs.mkdirSync(outputDir, { recursive: true })
+
+  return {
+    isMonorepo: () => true,
+    getRootDir: () => tmpDir,
+    getAppDir: () => path.join(tmpDir, 'app'),
+    getOutputDir: () => outputDir,
+    getModulesConfigPath: () => path.join(tmpDir, 'app', 'src', 'modules.ts'),
+    discoverPackages: () => [],
+    loadEnabledModules: () => enabled,
+    getModulePaths: (entry: ModuleEntry) => ({
+      appBase: path.join(tmpDir, 'app', 'src', 'modules', entry.id),
+      pkgBase: path.join(tmpDir, 'packages', 'core', 'src', 'modules', entry.id),
+    }),
+    getModuleImportBase: (entry: ModuleEntry) => ({
+      appBase: `@/modules/${entry.id}`,
+      pkgBase: `@open-mercato/core/modules/${entry.id}`,
+    }),
+    getPackageOutputDir: () => outputDir,
+    getPackageRoot: () => path.join(tmpDir, 'packages', 'core'),
+  }
+}
+
+beforeEach(() => {
+  tmpDir = createTmpDir()
+})
+
+afterEach(() => {
+  fs.rmSync(tmpDir, { recursive: true, force: true })
+})
+
+describe('detectBackendRouteCollisions', () => {
+  it('errors when two package modules register the same backend path, naming both and the path', () => {
+    const result = detectBackendRouteCollisions([
+      { routePath: '/backend/tasks', moduleId: 'workflows', packageSourced: true },
+      { routePath: '/backend/tasks', moduleId: 'agent_orchestrator', packageSourced: true },
+    ])
+    expect(result.errors).toHaveLength(1)
+    expect(result.errors[0]).toContain('/backend/tasks')
+    expect(result.errors[0]).toContain('"workflows"')
+    expect(result.errors[0]).toContain('"agent_orchestrator"')
+    expect(result.notes).toHaveLength(0)
+  })
+
+  it('emits an informational note (no error) when an app module shadows a package module path', () => {
+    const result = detectBackendRouteCollisions([
+      { routePath: '/backend/orders', moduleId: 'sales', packageSourced: true },
+      { routePath: '/backend/orders', moduleId: 'my_overrides', packageSourced: false },
+    ])
+    expect(result.errors).toHaveLength(0)
+    expect(result.notes).toHaveLength(1)
+    expect(result.notes[0]).toContain('/backend/orders')
+    expect(result.notes[0]).toContain('"sales"')
+    expect(result.notes[0]).toContain('"my_overrides"')
+  })
+
+  it('ignores duplicate registrations from a single module (app override of its own package page)', () => {
+    const result = detectBackendRouteCollisions([
+      { routePath: '/backend/orders', moduleId: 'sales', packageSourced: true },
+      { routePath: '/backend/orders', moduleId: 'sales', packageSourced: false },
+    ])
+    expect(result.errors).toHaveLength(0)
+    expect(result.notes).toHaveLength(0)
+  })
+
+  it('stays silent when there is no collision', () => {
+    const result = detectBackendRouteCollisions([
+      { routePath: '/backend/tasks', moduleId: 'workflows', packageSourced: true },
+      { routePath: '/backend/agentic-tasks', moduleId: 'agent_orchestrator', packageSourced: true },
+    ])
+    expect(result.errors).toHaveLength(0)
+    expect(result.notes).toHaveLength(0)
+  })
+})
+
+describe('generateModuleRegistry backend route collision guard', () => {
+  it('fails generation when two package modules register the same backend path', async () => {
+    scaffoldBackendPage(tmpDir, 'workflows_like', 'pkg', 'tasks/page.tsx')
+    scaffoldBackendPage(tmpDir, 'launcher_like', 'pkg', 'tasks/page.tsx')
+    const resolver = createMockResolver(tmpDir, [
+      { id: 'workflows_like', from: '@open-mercato/core' },
+      { id: 'launcher_like', from: '@open-mercato/core' },
+    ])
+
+    const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => {})
+    try {
+      // Two package modules are refused by whichever guard sees the pattern
+      // first: the per-pattern assertion during generation, or the aggregate
+      // sweep that runs after it. Accept either message so the test asserts the
+      // refusal rather than which guard won the race.
+      await expect(generateModuleRegistry({ resolver, quiet: true })).rejects.toThrow(
+        /Backend route collision|Duplicate backend route pattern/,
+      )
+      const printed = consoleErrorSpy.mock.calls.map((call) => call.join(' ')).join('\n')
+      expect(printed).toContain('/backend/tasks')
+      expect(printed).toContain('"workflows_like"')
+      expect(printed).toContain('"launcher_like"')
+    } finally {
+      consoleErrorSpy.mockRestore()
+    }
+  })
+
+  it('allows an app module to shadow a package module page', async () => {
+    scaffoldBackendPage(tmpDir, 'workflows_like', 'pkg', 'tasks/page.tsx')
+    scaffoldBackendPage(tmpDir, 'app_overrides', 'app', 'tasks/page.tsx')
+    const resolver = createMockResolver(tmpDir, [
+      { id: 'workflows_like', from: '@open-mercato/core' },
+      { id: 'app_overrides', from: '@app' },
+    ])
+
+    await expect(generateModuleRegistry({ resolver, quiet: true })).resolves.toBeDefined()
+  })
+
+  it('passes when package modules register distinct backend paths', async () => {
+    scaffoldBackendPage(tmpDir, 'workflows_like', 'pkg', 'tasks/page.tsx')
+    scaffoldBackendPage(tmpDir, 'launcher_like', 'pkg', 'agentic-tasks/page.tsx')
+    const resolver = createMockResolver(tmpDir, [
+      { id: 'workflows_like', from: '@open-mercato/core' },
+      { id: 'launcher_like', from: '@open-mercato/core' },
+    ])
+
+    await expect(generateModuleRegistry({ resolver, quiet: true })).resolves.toBeDefined()
+  })
+})