@elevasis/core 0.23.0 → 0.24.0

package/src/reference/glossary.md

@@ -1,76 +1,76 @@
----
-title: Glossary
-description: Terminology disambiguation for Organization OS concepts used in the template scaffold, core package, and published packages.
----
-
-# Glossary
-
-## Terms
-
-**AdminGuard** -- route-level admin wrapper from `@elevasis/ui/features/auth`. Must nest inside `ProtectedRoute`.
-
-**Contract** -- the publishable boundary a consumer depends on: Zod schemas, TypeScript types, provider props, resource definitions, or workflow I/O schemas.
-
-**DeploymentSpec** -- runtime/deploy assembly for one organization: workflows, agents, triggers, integrations, relationships, external resources, and human checkpoints. It assembles executable behavior around Organization Model resource descriptors; it is not the source of resource identity.
-
-**Feature** -- legacy or UI-package wording for a platform capability area. In the current Organization Model, use **System** for semantic ownership and **navigation surface** for shell placement. Keep "feature" only when referring to existing UI package folders, exported manifest names, or legacy compatibility recipes.
-
-**SystemGuard** -- route-level System gate from `@elevasis/ui/features/auth`.
-
-**SystemModule** -- manifest contract a shell module provides to `ElevasisSystemsProvider`. Key fields are `key`, optional `systemId`, optional `routePrefixes`, optional `capabilityIds`, optional `icon`, optional `sidebar`, optional `sidebarWidth`, and optional graph bridge metadata.
-
-**systemId** -- the `SystemModule` field that points to an `OrganizationModel.systems` entry. Navigation-only app modules may omit it and use route prefixes/surface metadata instead.
-
-**Foundations** -- local adapter layer in external projects that exports `canonicalOrganizationModel`, `organizationModel`, and workflow I/O schemas.
-
-**Graph node ID** -- kind-prefixed cross-collection identifier such as `system:sales.crm`, `integration:instantly`, or `resource:lead-import`.
-
-**Manifest** -- a runtime declaration for a feature or resource collection.
-
-**MembershipFeatureConfig** -- legacy per-member feature override config. Current System visibility is resolved through Organization Model lifecycle/access metadata and provider compatibility layers.
-
-**OrganizationModel** -- top-level semantic contract for an organization. Current primary fields include `version`, `domainMetadata`, `branding`, `navigation`, `sales`, `prospecting`, `projects`, `identity`, `customers`, `offerings`, `roles`, `goals`, `systems`, `resources`, `actions`, `entities`, `policies`, `statuses`, and `knowledge`.
-
-**OrganizationModelSystemEntry** -- System node in `OrganizationModel.systems`. Fields include `id`, `label`, `description`, `parentSystemId`, `subsystems`, `lifecycle`, `ui`, `requiresAdmin`, `devOnly`, `responsibleRoleId`, `governedByKnowledge`, `drivesGoals`, `actions`, `content`, and `order`.
-
-**Provider / ElevasisSystemsProvider** -- runtime that registers System modules, resolves System access against the org model, projects sidebar navigation, and exposes shell helpers through `useElevasisSystems()`.
-
-**Resource** -- governance-only descriptor in `OrganizationModel.resources` for a workflow, agent, integration, or script. Runtime code derives `resourceId` and kind from the descriptor, then attaches executable behavior in operations.
-
-**Resource descriptor** -- OM entry with canonical `id`, required `systemPath`, governance `status`, and optional role ownership. Workflow descriptors may mirror `actionKey`; agent descriptors carry `agentKind`, `sessionCapable`, and optional `actsAsRoleId`; integration descriptors name a provider.
-
-**System** -- tenant-defined bounded context in `OrganizationModel.systems.systems` that groups operational resources and carries governance metadata such as responsible role, governing knowledge, driven goals, kind, and status.
-
-**ResourceCategory** -- resource metadata category: `production`, `diagnostic`, `internal`, or `testing`.
-
-**ResourceLink** -- graph binding on resource metadata: `{ nodeId, kind }`.
-
-**Settings asymmetry** -- Settings is a navigation/app surface whose individual pages are normally governed by admin checks rather than user-facing System toggles.
-
-**Shell model** -- provider output used by sidebars and breadcrumbs. Includes `systems`, `childrenOf`, `ancestorsOf`, `parentOf`, `topLevel`, `findByPath`, `requiresAdminFor`, and `devOnlyFor`.
-
-**Subshell / Sidebar** -- System- or route-prefix-scoped UI region rendered when the current route matches a module whose manifest supplies a sidebar.
-
-**Topology** -- runtime resource relationships declared in `DeploymentSpec.relationships`.
-
-## Package Boundary
-
-**`@elevasis/core`**
-
-- `OrganizationModel`, `OrganizationModelSystemEntry`
-- `SystemEntry`, `ResourceEntry`
-- `resolveOrganizationModel`, `defineOrganizationModel`, `DEFAULT_ORGANIZATION_MODEL`
-- `MembershipFeatureConfig`
-- `DeploymentSpec`, `ResourceLink`, `ResourceCategory`
-
-**`@elevasis/ui`**
-
-- `SystemModule`
-- `SystemGuard`, `AdminGuard`, `ProtectedRoute`
-- `ElevasisSystemsProvider`, `ElevasisCoreProvider`, `useElevasisSystems`
-
-**External project source**
-
-- `canonicalOrganizationModel`
-- `organizationModel`
-- workflow I/O schemas
+---
+title: Glossary
+description: Terminology disambiguation for Organization OS concepts used in the template scaffold, core package, and published packages.
+---
+
+# Glossary
+
+## Terms
+
+**AdminGuard** -- route-level admin wrapper from `@elevasis/ui/features/auth`. Must nest inside `ProtectedRoute`.
+
+**Contract** -- the publishable boundary a consumer depends on: Zod schemas, TypeScript types, provider props, resource definitions, or workflow I/O schemas.
+
+**DeploymentSpec** -- runtime/deploy assembly for one organization: workflows, agents, triggers, integrations, relationships, external resources, and human checkpoints. It assembles executable behavior around Organization Model resource descriptors; it is not the source of resource identity.
+
+**Feature** -- legacy or UI-package wording for a platform capability area. In the current Organization Model, use **System** for semantic ownership and **navigation surface** for shell placement. Keep "feature" only when referring to existing UI package folders, exported manifest names, or legacy compatibility recipes.
+
+**SystemGuard** -- route-level System gate from `@elevasis/ui/features/auth`.
+
+**SystemModule** -- manifest contract a shell module provides to `ElevasisSystemsProvider`. Key fields are `key`, optional `systemId`, optional `routePrefixes`, optional `capabilityIds`, optional `icon`, optional `sidebar`, and optional `sidebarWidth`. Graph bridge metadata is compatibility-only; new semantic bindings belong in the Organization Model System, ontology, navigation, and Resource descriptors.
+
+**systemId** -- the `SystemModule` field that points to an `OrganizationModel.systems` entry. Navigation-only app modules may omit it and use route prefixes/surface metadata instead.
+
+**Foundations** -- local adapter layer in external projects that exports `canonicalOrganizationModel`, `organizationModel`, and workflow I/O schemas.
+
+**Graph node ID** -- kind-prefixed cross-collection identifier such as `system:sales.crm`, `integration:instantly`, or `resource:lead-import`.
+
+**Manifest** -- a runtime declaration for a feature or resource collection.
+
+**MembershipFeatureConfig** -- legacy per-member feature override config. Current System visibility should be authored through Organization Model System lifecycle/access metadata and resolved through provider compatibility layers for older consumers.
+
+**OrganizationModel** -- top-level semantic contract for an organization. Current primary fields include `version`, `domainMetadata`, `branding`, `navigation`, `ontology`, `systems`, `resources`, `identity`, `customers`, `offerings`, `roles`, `goals`, `policies`, `statuses`, and `knowledge`. Legacy domain keys such as `sales`, `prospecting`, `projects`, `actions`, and `entities` remain compatibility inputs while projects migrate to System-owned ontology/config/resource contracts.
+
+**OrganizationModelSystemEntry** -- System node in `OrganizationModel.systems`. Primary authoring fields include `id`, `label`, `description`, `parentSystemId`, `systems`, `lifecycle`, `ui`, `requiresAdmin`, `devOnly`, `responsibleRoleId`, `governedByKnowledge`, `drivesGoals`, `actions`, `policies`, `ontology`, `config`, and `order`. `subsystems` and `content` are retained compatibility inputs for older projects and should not be used for new recursive Systems, schemas, catalogs, or config.
+
+**Provider / ElevasisSystemsProvider** -- runtime that registers System modules, resolves System access against the org model, projects sidebar navigation, and exposes shell helpers through `useElevasisSystems()`.
+
+**Resource** -- governance-only descriptor in `OrganizationModel.resources` for a workflow, agent, integration, or script. Runtime code derives `resourceId` and kind from the descriptor, then attaches executable behavior in operations.
+
+**Resource descriptor** -- OM entry with canonical `id`, required `systemPath`, governance `status`, optional role ownership, optional `actionKey`, `codeRefs`, and nested `ontology` bindings for implemented actions, read/write objects, used catalogs, and emitted events. Top-level `emits` remains a compatibility mirror for older descriptors.
+
+**System** -- tenant-defined bounded context in `OrganizationModel.systems` that groups operational resources and carries governance metadata such as responsible role, governing knowledge, driven goals, kind, lifecycle, System-local ontology, and System-local config.
+
+**ResourceCategory** -- resource metadata category: `production`, `diagnostic`, `internal`, or `testing`.
+
+**ResourceLink** -- graph binding on resource metadata: `{ nodeId, kind }`.
+
+**Settings asymmetry** -- Settings is a navigation/app surface whose individual pages are normally governed by admin checks rather than user-facing System toggles.
+
+**Shell model** -- provider output used by sidebars and breadcrumbs. Includes `systems`, `childrenOf`, `ancestorsOf`, `parentOf`, `topLevel`, `findByPath`, `requiresAdminFor`, and `devOnlyFor`.
+
+**Subshell / Sidebar** -- System- or route-prefix-scoped UI region rendered when the current route matches a module whose manifest supplies a sidebar.
+
+**Topology** -- runtime resource relationships declared in `DeploymentSpec.relationships`.
+
+## Package Boundary
+
+**`@elevasis/core`**
+
+- `OrganizationModel`, `OrganizationModelSystemEntry`
+- `SystemEntry`, `ResourceEntry`
+- `resolveOrganizationModel`, `defineOrganizationModel`, `DEFAULT_ORGANIZATION_MODEL`
+- `MembershipFeatureConfig`
+- `DeploymentSpec`, `ResourceLink`, `ResourceCategory`
+
+**`@elevasis/ui`**
+
+- `SystemModule`
+- `SystemGuard`, `AdminGuard`, `ProtectedRoute`
+- `ElevasisSystemsProvider`, `ElevasisCoreProvider`, `useElevasisSystems`
+
+**External project source**
+
+- `canonicalOrganizationModel`
+- `organizationModel`
+- workflow I/O schemas

package/src/scaffold-registry/__tests__/index.test.ts

@@ -1,206 +1,206 @@
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import path from 'node:path'
-import { afterEach, describe, expect, it } from 'vitest'
-import {
-  findEmptySourcePatterns,
-  findMatchingEntries,
-  findMissingDependentPaths,
-  loadScaffoldRegistryFast,
-  normalizeScaffoldPath,
-  scaffoldPathMatchesPattern
-} from '../index'
-import type { ScaffoldRegistry, ScaffoldRegistryEntry } from '../schema'
-
-function makeEntry(id: string, sources: string[]): ScaffoldRegistryEntry {
-  return {
-    id,
-    kind: 'manual-scaffold',
-    owner: 'packages/core',
-    sources,
-    dependents: [{ path: 'packages/core/package.json', regen: 'manual', hint: 'h' }]
-  }
-}
-
-function registryFromEntries(entries: ScaffoldRegistryEntry[]): ScaffoldRegistry {
-  return { version: '1', entries }
-}
-
-function matchedIds(registry: ScaffoldRegistry, filePath: string): string[] {
-  return findMatchingEntries(registry, filePath).map((e) => e.id)
-}
-
-let tempRoots: string[] = []
-
-function makeTempRoot(): string {
-  const root = mkdtempSync(path.join(tmpdir(), 'scaffold-registry-'))
-  tempRoots.push(root)
-  return root
-}
-
-afterEach(() => {
-  for (const root of tempRoots) {
-    rmSync(root, { recursive: true, force: true })
-  }
-  tempRoots = []
-})
-
-describe('loadScaffoldRegistryFast', () => {
-  it('preserves external sync metadata from the compiled registry', () => {
-    const registry = loadScaffoldRegistryFast()
-    const entry = registry.entries.find((candidate) => candidate.id === 'external-sync-managed-claude')
-
-    expect(entry).toBeDefined()
-    expect(entry).toMatchObject({
-      owner: 'template',
-      category: 'replace',
-      strategy: 'replace-all',
-      delete_policy: 'manifest-only'
-    })
-  })
-})
-
-describe('findMissingDependentPaths', () => {
-  const baseEntry = {
-    id: 'fake-entry',
-    kind: 'manual-scaffold' as const,
-    owner: 'packages/core',
-    sources: ['packages/core/src/**'],
-    dependents: [{ path: 'packages/core/this-file-does-not-exist.ts', regen: 'manual', hint: 'h' }]
-  }
-
-  it('flags dependents whose paths are missing on disk', () => {
-    const registry: ScaffoldRegistry = { version: '1', entries: [baseEntry] }
-    const missing = findMissingDependentPaths(registry, process.cwd())
-    expect(missing).toEqual([{ entryId: 'fake-entry', path: 'packages/core/this-file-does-not-exist.ts' }])
-  })
-
-  it('skips symbolic targets, globs, and (self)', () => {
-    const registry: ScaffoldRegistry = {
-      version: '1',
-      entries: [
-        {
-          ...baseEntry,
-          dependents: [
-            { path: 'docs: sync-preservation-matrix', regen: 'manual', hint: 'h' },
-            { path: 'autogen-target:foo', regen: 'manual', hint: 'h' },
-            { path: 'packages/core/src/**/*.ts', regen: 'manual', hint: 'h' },
-            { path: '(self)', regen: 'manual', hint: 'h' }
-          ]
-        }
-      ]
-    }
-    expect(findMissingDependentPaths(registry, process.cwd())).toEqual([])
-  })
-
-  it('skips sync-preservation entries (their paths target derived external projects)', () => {
-    const registry: ScaffoldRegistry = {
-      version: '1',
-      entries: [
-        {
-          id: 'sync-entry',
-          kind: 'sync-preservation',
-          owner: '@elevasis/core',
-          category: 'merge',
-          strategy: 'merge-regions',
-          delete_policy: 'none',
-          sources: ['external/_template/foo.ts'],
-          dependents: [{ path: 'core/src/foo-not-in-monorepo.ts', regen: 'manual', hint: 'h' }]
-        }
-      ]
-    }
-    expect(findMissingDependentPaths(registry, process.cwd())).toEqual([])
-  })
-})
-
-describe('findMatchingEntries (pattern matching)', () => {
-  it('normalizes Windows and relative paths', () => {
-    expect(normalizeScaffoldPath('.\\packages\\core\\src\\')).toBe('packages/core/src')
-  })
-
-  it('matches exact paths', () => {
-    const reg = registryFromEntries([makeEntry('exact', ['packages/core/src/index.ts'])])
-    expect(matchedIds(reg, 'packages/core/src/index.ts')).toEqual(['exact'])
-    expect(matchedIds(reg, 'packages/core/src/other.ts')).toEqual([])
-  })
-
-  it('matches /** suffix as deep prefix', () => {
-    const reg = registryFromEntries([makeEntry('deep', ['packages/core/src/**'])])
-    expect(matchedIds(reg, 'packages/core/src/foo.ts')).toEqual(['deep'])
-    expect(matchedIds(reg, 'packages/core/src/nested/deeply/foo.ts')).toEqual(['deep'])
-    expect(matchedIds(reg, 'packages/core/package.json')).toEqual([])
-    expect(matchedIds(reg, 'packages/core/src')).toEqual([])
-  })
-
-  it('matches /* suffix as single-level prefix', () => {
-    const reg = registryFromEntries([makeEntry('shallow', ['packages/*/package.json'])])
-    expect(matchedIds(reg, 'packages/core/package.json')).toEqual(['shallow'])
-    expect(matchedIds(reg, 'packages/ui/package.json')).toEqual(['shallow'])
-    expect(matchedIds(reg, 'packages/core/nested/package.json')).toEqual([])
-  })
-
-  it('matches mixed **/*.ext patterns at direct-child and nested depths', () => {
-    const reg = registryFromEntries([makeEntry('ext', ['apps/api/src/**/*.ts'])])
-    expect(matchedIds(reg, 'apps/api/src/foo.ts')).toEqual(['ext'])
-    expect(matchedIds(reg, 'apps/api/src/nested/deeply/foo.ts')).toEqual(['ext'])
-    expect(matchedIds(reg, 'apps/api/src/foo.tsx')).toEqual([])
-  })
-
-  it('normalizes Windows backslashes to forward slashes', () => {
-    const reg = registryFromEntries([makeEntry('winpath', ['packages/core/src/**'])])
-    expect(matchedIds(reg, 'packages\\core\\src\\foo.ts')).toEqual(['winpath'])
-  })
-
-  it('matches a directory-prefix pattern (no glob characters)', () => {
-    const reg = registryFromEntries([makeEntry('dir', ['packages/core/src'])])
-    expect(matchedIds(reg, 'packages/core/src/foo.ts')).toEqual(['dir'])
-    expect(matchedIds(reg, 'packages/core/srcfoo.ts')).toEqual([])
-  })
-
-  it('returns multiple entries when several match the same file', () => {
-    const reg = registryFromEntries([makeEntry('a', ['packages/core/src/**']), makeEntry('b', ['packages/core/src'])])
-    expect(matchedIds(reg, 'packages/core/src/foo.ts').sort()).toEqual(['a', 'b'])
-  })
-
-  it('returns empty when no entries match', () => {
-    const reg = registryFromEntries([makeEntry('a', ['packages/core/src/**'])])
-    expect(matchedIds(reg, 'apps/api/src/foo.ts')).toEqual([])
-  })
-
-  it('exposes the same matcher for direct consumers', () => {
-    expect(scaffoldPathMatchesPattern('packages/core/src/foo.test.ts', 'packages/core/src/**/*.ts')).toBe(true)
-    expect(scaffoldPathMatchesPattern('packages/core/src/foo.test.ts', 'packages/ui/src/**/*.ts')).toBe(false)
-  })
-})
-
-describe('findEmptySourcePatterns', () => {
-  it('flags source patterns that do not match any file or directory', () => {
-    const root = makeTempRoot()
-    mkdirSync(path.join(root, 'packages', 'core', 'src'), { recursive: true })
-    writeFileSync(path.join(root, 'packages', 'core', 'src', 'index.ts'), 'export {}\n', 'utf8')
-
-    const registry = registryFromEntries([
-      makeEntry('ok-exact', ['packages/core/src/index.ts']),
-      makeEntry('ok-glob', ['packages/core/src/**/*.ts']),
-      makeEntry('empty', ['packages/core/src/**/*.tsx'])
-    ])
-
-    expect(findEmptySourcePatterns(registry, root)).toEqual([
-      { entryId: 'empty', pattern: 'packages/core/src/**/*.tsx' }
-    ])
-  })
-
-  it('treats exact directories as non-empty source coverage', () => {
-    const root = makeTempRoot()
-    mkdirSync(path.join(root, 'external', '_template', '.claude', 'skills'), { recursive: true })
-
-    const registry = registryFromEntries([
-      makeEntry('dir', ['external/_template/.claude/skills']),
-      makeEntry('missing-dir', ['external/_template/.claude/commands'])
-    ])
-
-    expect(findEmptySourcePatterns(registry, root)).toEqual([
-      { entryId: 'missing-dir', pattern: 'external/_template/.claude/commands' }
-    ])
-  })
-})
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import {
+  findEmptySourcePatterns,
+  findMatchingEntries,
+  findMissingDependentPaths,
+  loadScaffoldRegistryFast,
+  normalizeScaffoldPath,
+  scaffoldPathMatchesPattern
+} from '../index'
+import type { ScaffoldRegistry, ScaffoldRegistryEntry } from '../schema'
+
+function makeEntry(id: string, sources: string[]): ScaffoldRegistryEntry {
+  return {
+    id,
+    kind: 'manual-scaffold',
+    owner: 'packages/core',
+    sources,
+    dependents: [{ path: 'packages/core/package.json', regen: 'manual', hint: 'h' }]
+  }
+}
+
+function registryFromEntries(entries: ScaffoldRegistryEntry[]): ScaffoldRegistry {
+  return { version: '1', entries }
+}
+
+function matchedIds(registry: ScaffoldRegistry, filePath: string): string[] {
+  return findMatchingEntries(registry, filePath).map((e) => e.id)
+}
+
+let tempRoots: string[] = []
+
+function makeTempRoot(): string {
+  const root = mkdtempSync(path.join(tmpdir(), 'scaffold-registry-'))
+  tempRoots.push(root)
+  return root
+}
+
+afterEach(() => {
+  for (const root of tempRoots) {
+    rmSync(root, { recursive: true, force: true })
+  }
+  tempRoots = []
+})
+
+describe('loadScaffoldRegistryFast', () => {
+  it('preserves external sync metadata from the compiled registry', () => {
+    const registry = loadScaffoldRegistryFast()
+    const entry = registry.entries.find((candidate) => candidate.id === 'external-sync-managed-claude')
+
+    expect(entry).toBeDefined()
+    expect(entry).toMatchObject({
+      owner: 'template',
+      category: 'replace',
+      strategy: 'replace-all',
+      delete_policy: 'manifest-only'
+    })
+  })
+})
+
+describe('findMissingDependentPaths', () => {
+  const baseEntry = {
+    id: 'fake-entry',
+    kind: 'manual-scaffold' as const,
+    owner: 'packages/core',
+    sources: ['packages/core/src/**'],
+    dependents: [{ path: 'packages/core/this-file-does-not-exist.ts', regen: 'manual', hint: 'h' }]
+  }
+
+  it('flags dependents whose paths are missing on disk', () => {
+    const registry: ScaffoldRegistry = { version: '1', entries: [baseEntry] }
+    const missing = findMissingDependentPaths(registry, process.cwd())
+    expect(missing).toEqual([{ entryId: 'fake-entry', path: 'packages/core/this-file-does-not-exist.ts' }])
+  })
+
+  it('skips symbolic targets, globs, and (self)', () => {
+    const registry: ScaffoldRegistry = {
+      version: '1',
+      entries: [
+        {
+          ...baseEntry,
+          dependents: [
+            { path: 'docs: sync-preservation-matrix', regen: 'manual', hint: 'h' },
+            { path: 'autogen-target:foo', regen: 'manual', hint: 'h' },
+            { path: 'packages/core/src/**/*.ts', regen: 'manual', hint: 'h' },
+            { path: '(self)', regen: 'manual', hint: 'h' }
+          ]
+        }
+      ]
+    }
+    expect(findMissingDependentPaths(registry, process.cwd())).toEqual([])
+  })
+
+  it('skips sync-preservation entries (their paths target derived external projects)', () => {
+    const registry: ScaffoldRegistry = {
+      version: '1',
+      entries: [
+        {
+          id: 'sync-entry',
+          kind: 'sync-preservation',
+          owner: '@elevasis/core',
+          category: 'merge',
+          strategy: 'merge-regions',
+          delete_policy: 'none',
+          sources: ['external/_template/foo.ts'],
+          dependents: [{ path: 'core/src/foo-not-in-monorepo.ts', regen: 'manual', hint: 'h' }]
+        }
+      ]
+    }
+    expect(findMissingDependentPaths(registry, process.cwd())).toEqual([])
+  })
+})
+
+describe('findMatchingEntries (pattern matching)', () => {
+  it('normalizes Windows and relative paths', () => {
+    expect(normalizeScaffoldPath('.\\packages\\core\\src\\')).toBe('packages/core/src')
+  })
+
+  it('matches exact paths', () => {
+    const reg = registryFromEntries([makeEntry('exact', ['packages/core/src/index.ts'])])
+    expect(matchedIds(reg, 'packages/core/src/index.ts')).toEqual(['exact'])
+    expect(matchedIds(reg, 'packages/core/src/other.ts')).toEqual([])
+  })
+
+  it('matches /** suffix as deep prefix', () => {
+    const reg = registryFromEntries([makeEntry('deep', ['packages/core/src/**'])])
+    expect(matchedIds(reg, 'packages/core/src/foo.ts')).toEqual(['deep'])
+    expect(matchedIds(reg, 'packages/core/src/nested/deeply/foo.ts')).toEqual(['deep'])
+    expect(matchedIds(reg, 'packages/core/package.json')).toEqual([])
+    expect(matchedIds(reg, 'packages/core/src')).toEqual([])
+  })
+
+  it('matches /* suffix as single-level prefix', () => {
+    const reg = registryFromEntries([makeEntry('shallow', ['packages/*/package.json'])])
+    expect(matchedIds(reg, 'packages/core/package.json')).toEqual(['shallow'])
+    expect(matchedIds(reg, 'packages/ui/package.json')).toEqual(['shallow'])
+    expect(matchedIds(reg, 'packages/core/nested/package.json')).toEqual([])
+  })
+
+  it('matches mixed **/*.ext patterns at direct-child and nested depths', () => {
+    const reg = registryFromEntries([makeEntry('ext', ['apps/api/src/**/*.ts'])])
+    expect(matchedIds(reg, 'apps/api/src/foo.ts')).toEqual(['ext'])
+    expect(matchedIds(reg, 'apps/api/src/nested/deeply/foo.ts')).toEqual(['ext'])
+    expect(matchedIds(reg, 'apps/api/src/foo.tsx')).toEqual([])
+  })
+
+  it('normalizes Windows backslashes to forward slashes', () => {
+    const reg = registryFromEntries([makeEntry('winpath', ['packages/core/src/**'])])
+    expect(matchedIds(reg, 'packages\\core\\src\\foo.ts')).toEqual(['winpath'])
+  })
+
+  it('matches a directory-prefix pattern (no glob characters)', () => {
+    const reg = registryFromEntries([makeEntry('dir', ['packages/core/src'])])
+    expect(matchedIds(reg, 'packages/core/src/foo.ts')).toEqual(['dir'])
+    expect(matchedIds(reg, 'packages/core/srcfoo.ts')).toEqual([])
+  })
+
+  it('returns multiple entries when several match the same file', () => {
+    const reg = registryFromEntries([makeEntry('a', ['packages/core/src/**']), makeEntry('b', ['packages/core/src'])])
+    expect(matchedIds(reg, 'packages/core/src/foo.ts').sort()).toEqual(['a', 'b'])
+  })
+
+  it('returns empty when no entries match', () => {
+    const reg = registryFromEntries([makeEntry('a', ['packages/core/src/**'])])
+    expect(matchedIds(reg, 'apps/api/src/foo.ts')).toEqual([])
+  })
+
+  it('exposes the same matcher for direct consumers', () => {
+    expect(scaffoldPathMatchesPattern('packages/core/src/foo.test.ts', 'packages/core/src/**/*.ts')).toBe(true)
+    expect(scaffoldPathMatchesPattern('packages/core/src/foo.test.ts', 'packages/ui/src/**/*.ts')).toBe(false)
+  })
+})
+
+describe('findEmptySourcePatterns', () => {
+  it('flags source patterns that do not match any file or directory', () => {
+    const root = makeTempRoot()
+    mkdirSync(path.join(root, 'packages', 'core', 'src'), { recursive: true })
+    writeFileSync(path.join(root, 'packages', 'core', 'src', 'index.ts'), 'export {}\n', 'utf8')
+
+    const registry = registryFromEntries([
+      makeEntry('ok-exact', ['packages/core/src/index.ts']),
+      makeEntry('ok-glob', ['packages/core/src/**/*.ts']),
+      makeEntry('empty', ['packages/core/src/**/*.tsx'])
+    ])
+
+    expect(findEmptySourcePatterns(registry, root)).toEqual([
+      { entryId: 'empty', pattern: 'packages/core/src/**/*.tsx' }
+    ])
+  })
+
+  it('treats exact directories as non-empty source coverage', () => {
+    const root = makeTempRoot()
+    mkdirSync(path.join(root, 'external', '_template', '.claude', 'skills'), { recursive: true })
+
+    const registry = registryFromEntries([
+      makeEntry('dir', ['external/_template/.claude/skills']),
+      makeEntry('missing-dir', ['external/_template/.claude/commands'])
+    ])
+
+    expect(findEmptySourcePatterns(registry, root)).toEqual([
+      { entryId: 'missing-dir', pattern: 'external/_template/.claude/commands' }
+    ])
+  })
+})