@devtrack-solution/codesdd 1.2.3 → 1.2.4-rc3

package/.sdd/skills/curated/devtrack-api/SKILL.md

@@ -26,6 +26,9 @@ These rules apply to any assistant, automation host, IDE agent, command-line cod
 - Do not create external memory, backlog, workflow, scratchpad, context, or handoff stores.
 - Do not use BRV in this environment.
 - Never introduce Prisma. Persistence is TypeORM only.
+- Treat this skill as isolated from `devtrack-angular` and `devtrack-flutter`; share only explicit API contracts, DTO boundaries, schemas, generated clients, and documented platform contracts.
+- Treat `agents/*.yaml` files as host adapters only. `SKILL.md`, `references/contract-pack.yaml`, and the Foundation source/layout references remain canonical across Codex, Claude Code, Cursor, Gemini, Kimi, OpenCode, and equivalent markdown/CLI agents.
+- If this skill conflicts with `devtrack-foundation-api` source or Foundation layout evidence, Foundation wins unless a governed ADR or contract-pack exception explicitly records the divergence.
 
 ## Operating Mode
 
@@ -61,12 +64,13 @@ Treat the repository as a production-grade system:
 Load only the files needed for the task, but always load governance and layout before code changes:
 
 - Always read [contract-pack.yaml](references/contract-pack.yaml) before planning, approving, or executing a `devtrack-api` project, debate, EPIC, or FEAT. It is the machine-readable contract pack for derivation profiles, P0/P1/P2 severity, early package preview, human validation, and `codesdd-validate` drift remediation.
+- Read [portable-agent-contract.md](references/portable-agent-contract.md) when adapting this skill for Codex, Claude Code, Cursor, Gemini, Kimi, OpenCode, or a generic markdown/CLI agent.
 - Always read [architecture-governance.md](references/architecture-governance.md) before code changes.
 - Always read [foundation-layout.md](references/foundation-layout.md) before producing any implementation plan, debate, or code change that proposes new file paths. Foundation layout is canonical, not advisory.
 - Read [consumer-sync-policy.md](references/consumer-sync-policy.md) before copying, updating, validating, or accepting `devtrack-api` in a consumer repository.
 - Read [field-validation-protocol.md](references/field-validation-protocol.md) before declaring `devtrack-api` adoption validated in a consumer project or closing field-evidence expectations.
 - Read [imports-lint.md](references/imports-lint.md) before editing imports or fixing lint.
-- Read [domain-modeling.md](references/domain-modeling.md) for `domain/`, `.type.ts`, `.bo.ts`, `.vo.ts`, validators, events, and repository ports.
+- Read [domain-modeling.md](references/domain-modeling.md) for `domain/`, `.type.ts`, `.bo.ts`, `.vo.ts`, the closed legacy entity-pattern, validators, events, and repository-port placement.
 - Read [application-presentation.md](references/application-presentation.md) for use cases, services, handlers, ports, modules, controllers, DTO validators, GraphQL, CLI, WebSocket, agents, and tools.
 - Read [typeorm-infrastructure.md](references/typeorm-infrastructure.md) for TypeORM entities, repositories, mappers, migrations, modules, config, infrastructure adapters, settings, queues, AWS, and provider integrations.
 - Read [testing-validation.md](references/testing-validation.md) before finishing or when choosing tests.
@@ -90,7 +94,7 @@ The `codesdd-validate` field failure is mapped in the contract pack under `codes
 
 Implement from inside out unless the task is purely presentation or infrastructure:
 
-1. `src/domain`: business rules, BOs, VOs, types, validators, events, repository port contracts.
+1. `src/domain`: business rules, BOs, VOs, and types. Validators, events, entities, and domain repository ports are legacy entity-pattern only.
 2. `src/application`: orchestration, use cases, services, handlers, agents/tools, ports in/out.
 3. `src/infrastructure`: concrete adapters, TypeORM, AWS, queue, cache, HTTP, LLM, vector store, Temporal, settings.
 4. `src/presentation`: REST/GraphQL/CLI/WebSocket entrypoints and request validation.
@@ -180,11 +184,13 @@ src/infrastructure/adapters/orm/entities/<name>.orm-entity.ts
 src/infrastructure/adapters/orm/repositories/<name>.typeorm-repository.ts
 src/infrastructure/adapters/orm/mappers/<name>.mapper.ts
 src/infrastructure/adapters/orm/migrations/<timestamp>-<action>.migration.ts
-src/infrastructure/adapters/orm/<context>-orm.module.ts
+src/infrastructure/adapters/orm/orm.module.ts
 ```
 
 Known subsystems in Foundation: `auth`, `aws`, `cache`, `configuration`, `http`, `llm`, `orm`, `queue`, `redis`, `sync-engine`, `temporal`, `vector-store`. Add a new subsystem folder only when no existing subsystem covers the integration.
 
+The ORM subsystem has one Nest module only: `src/infrastructure/adapters/orm/orm.module.ts`. Do not create entity/context modules such as `<context>-orm.module.ts`; wire and export all `*.typeorm-repository.ts` providers through `orm.module.ts`.
+
 **Presentation (segmented by transport before context)**
 
 ```text
@@ -206,7 +212,7 @@ Other transports follow the same shape under `graphql/`, `cli/`, `websocket/`, o
 - REST controllers end with `.controller.ts`, one class per file.
 - REST DTOs end with `.dto.ts`.
 - Presentation validators end with `.presentation-validator.ts`.
-- Nest modules end with `.application.module.ts`, `.module.ts`, or `-orm.module.ts` by layer.
+- Nest modules end with `.application.module.ts` or `.module.ts` by layer. The ORM module is exactly `orm.module.ts`.
 
 ## Forbidden Patterns
 
@@ -216,6 +222,7 @@ These layouts have been observed in derived debates and plans and **must be reje
 - `<name>.schema.ts` for TypeORM entities — use `<name>.orm-entity.ts`.
 - `<name>.value-object.ts` — use `<name>.vo.ts`.
 - `<name>.repository.ts` (ambiguous) — use `<name>.typeorm-repository.ts` in infrastructure, `<name>-repository.port.ts` in port.
+- `src/infrastructure/adapters/orm/*-orm.module.ts` — use the single `src/infrastructure/adapters/orm/orm.module.ts`.
 - `src/infrastructure/<context>/persistence/typeorm/` — use `src/infrastructure/adapters/orm/`.
 - `src/infrastructure/<context>/adapters/` — use `src/infrastructure/adapters/<subsystem>/`.
 - `src/infrastructure/<context>/repositories/` — use `src/infrastructure/adapters/orm/repositories/`.
@@ -247,7 +254,7 @@ A plan that fails this gate corrupts the downstream FEAT execution and the disco
 A valid change must satisfy all relevant checks:
 
 - It matches the current repository patterns unless the user explicitly requested a better pattern and the migration cost is justified.
-- It keeps business invariants in domain objects, value objects, or domain validators.
+- It keeps BO-pattern business invariants in domain business objects and value objects; domain validators apply only to existing entity-pattern contexts.
 - It keeps orchestration in application use cases, services, or handlers.
 - It keeps transport mapping and request validation in presentation.
 - It keeps concrete integrations in infrastructure.

package/.sdd/skills/curated/devtrack-api/agents/claude-code.yaml

@@ -0,0 +1,8 @@
+agent_id: claude
+display_name: Claude Code
+skill_id: devtrack-api
+adapter_type: markdown-skill
+canonical_skill: ../SKILL.md
+notes:
+  - Treat this adapter as a host mapping only; SKILL.md and references remain canonical.
+  - Preserve dirty worktrees and report unavailable commands honestly.

package/.sdd/skills/curated/devtrack-api/agents/codex.yaml

@@ -0,0 +1,8 @@
+agent_id: codex
+display_name: Codex
+skill_id: devtrack-api
+adapter_type: markdown-skill
+canonical_skill: ../SKILL.md
+notes:
+  - Read CodeSDD policy and FEAT context before edits.
+  - Load contract-pack.yaml and Foundation layout before backend/API changes.

package/.sdd/skills/curated/devtrack-api/agents/cursor.yaml

@@ -0,0 +1,8 @@
+agent_id: cursor
+display_name: Cursor
+skill_id: devtrack-api
+adapter_type: markdown-skill
+canonical_skill: ../SKILL.md
+notes:
+  - Keep Cursor edits scoped to CodeSDD FEAT context.
+  - Do not bypass Foundation layout or TypeORM constraints.

package/.sdd/skills/curated/devtrack-api/agents/gemini.yaml

@@ -0,0 +1,8 @@
+agent_id: gemini
+display_name: Gemini
+skill_id: devtrack-api
+adapter_type: markdown-skill
+canonical_skill: ../SKILL.md
+notes:
+  - Verify version-sensitive NestJS and TypeORM details before asserting APIs.
+  - Use contract-pack rule ids in validation notes.

package/.sdd/skills/curated/devtrack-api/agents/kimi.yaml

@@ -0,0 +1,8 @@
+agent_id: kimi
+display_name: Kimi
+skill_id: devtrack-api
+adapter_type: markdown-skill
+canonical_skill: ../SKILL.md
+notes:
+  - Use the markdown skill and references as the complete contract.
+  - Produce compact, evidence-backed changes and handoff notes.

package/.sdd/skills/curated/devtrack-api/agents/openai.yaml

@@ -1,4 +1,6 @@
 interface:
   display_name: "DevTrack API"
-  short_description: "Portable DevTrack API engineering governance, architecture, safety, validation, and quality skill."
-  default_prompt: "Use $devtrack-api to implement, review, refactor, test, or document DevTrack API work with CodeSDD, DDD/Clean Architecture, TypeORM, strict import boundaries, evidence-based validation, and safe operational constraints."
+  short_description: "Governed DevTrack API architecture and Foundation fidelity."
+  default_prompt: "Use $devtrack-api to implement, review, refactor, test, or document DevTrack API work with CodeSDD, Foundation-compatible NestJS, TypeORM, strict imports, and validation evidence."
+policy:
+  allow_implicit_invocation: true

package/.sdd/skills/curated/devtrack-api/agents/opencode.yaml

@@ -0,0 +1,10 @@
+agent_id: opencode
+display_name: OpenCode
+skill_id: devtrack-api
+adapter_type: markdown-skill
+canonical_skill: ../SKILL.md
+aliases:
+  - open-code
+notes:
+  - Use opencode for local skill sync targets.
+  - Use open-code only when an MCP provider manifest requires that provider id.

package/.sdd/skills/curated/devtrack-api/references/application-presentation.md

@@ -126,8 +126,8 @@ Pattern:
 ```ts
 import { Inject, Injectable, Logger, Optional } from '@nestjs/common';
 import { Example } from '@domain/example/business-objects/example.bo';
-import { ExampleRepositoryPortSymbol } from '@domain/example/repository-ports/example-repository.port';
-import type { ExampleRepositoryPort } from '@domain/example/repository-ports/example-repository.port';
+import { ExampleRepositoryPortSymbol } from '@application/business/example/ports/out/example-repository.port';
+import type { ExampleRepositoryPort } from '@application/business/example/ports/out/example-repository.port';
 import type { ExampleType } from '@domain/example/types/example.type';
 import type { CreateExampleUseCasePort } from '@application/business/example/ports/in/create-example.use-case.port';
 import { ExampleProducerPortSymbol } from '@application/business/example/ports/out/example-producer.port';

package/.sdd/skills/curated/devtrack-api/references/contract-pack.yaml

@@ -12,6 +12,44 @@ authority:
     - .sdd/skills/curated/devtrack-api/SKILL.md
     - this contract pack
   consumer_rule: Consumer copies are one-way CodeSDD materializations and must not become upstream sources of truth.
+  foundation_wins_rule: If devtrack-api guidance conflicts with devtrack-foundation-api source or Foundation layout evidence, Foundation wins unless a governed ADR or contract-pack exception records the divergence.
+  isolation_rule: devtrack-api governs backend/API work only; devtrack-angular remains the isolated Angular Admin/backoffice skill and devtrack-flutter remains the isolated Flutter/Dart skill.
+portable_agents:
+  canonical_targets:
+    - openai
+    - codex
+    - claude
+    - cursor
+    - gemini
+    - kimi
+    - opencode
+    - generic-markdown-cli
+  aliases:
+    claude-code: claude
+    kimmy-code: kimi
+    kilo-code: generic-markdown-cli
+    open-code: opencode
+    OpenCode: opencode
+    Kimi: kimi
+  artifact_map:
+    openai: agents/openai.yaml
+    codex: agents/codex.yaml
+    claude: agents/claude-code.yaml
+    cursor: agents/cursor.yaml
+    gemini: agents/gemini.yaml
+    kimi: agents/kimi.yaml
+    opencode: agents/opencode.yaml
+    generic-markdown-cli: SKILL.md
+  required_artifacts:
+    - SKILL.md
+    - agents/openai.yaml
+    - agents/codex.yaml
+    - agents/claude-code.yaml
+    - agents/cursor.yaml
+    - agents/gemini.yaml
+    - agents/kimi.yaml
+    - agents/opencode.yaml
+    - references/portable-agent-contract.md
 derivation_profiles:
   prototype:
     default: false
@@ -62,6 +100,21 @@ severity_model:
     meaning: Lower-risk drift, documentation gap, or profile-specific variance.
     required_action: Record evidence, exception, or follow-up before closure.
 rules:
+  - id: DTAPI-P0-FOUNDATION-001
+    severity: P0
+    title: Foundation evidence wins over generated or adapter-specific guidance.
+    applies_to:
+      - DEB
+      - EPIC
+      - FEAT
+      - source
+      - validator
+    detect:
+      - plan, code, or agent adapter diverges from devtrack-foundation-api source without ADR
+      - generated path, module, import, or TypeORM rule conflicts with foundation-layout.md
+    required_response:
+      - align with devtrack-foundation-api source or foundation-layout.md
+      - or record an ADR-backed and profile-compatible exception before execution or finalize
   - id: DTAPI-P0-PROFILE-001
     severity: P0
     title: Derivation profile must be explicit before implementation.
@@ -97,6 +150,7 @@ rules:
       - forbidden paths from SKILL.md or foundation-layout.md
       - new domain entities folder outside approved legacy contexts
       - context-owned infrastructure adapters
+      - per-context or per-entity TypeORM modules under src/infrastructure/adapters/orm
       - transport-less presentation context folders
     required_response:
       - replace with canonical path
@@ -127,6 +181,7 @@ rules:
       - files ending in .typeorm-repository.ts without InjectRepository or Repository usage
       - in-memory Map persistence inside TypeORM-named repositories
       - missing TypeOrmModule.forFeature wiring for concrete ORM repositories
+      - concrete ORM repositories not provided and exported through src/infrastructure/adapters/orm/orm.module.ts
     required_response:
       - implement real TypeORM repository wiring
       - rename prototype adapters so they do not claim TypeORM compatibility

package/.sdd/skills/curated/devtrack-api/references/domain-modeling.md

@@ -2,7 +2,7 @@
 
 ## Domain Intent
 
-Domain code expresses business language, invariants, state transitions, and persistence contracts for aggregates. It must remain framework-free and portable.
+Domain code expresses business language, invariants, and state transitions. It must remain framework-free and portable.
 
 Domain is the last place where business truth should be guessed. When a rule is unclear, inspect existing domain objects, tests, use cases, and SDD context before adding a new invariant.
 
@@ -14,14 +14,10 @@ Use these folders by intent:
 src/domain/<context>/types
 src/domain/<context>/business-objects
 src/domain/<context>/value-objects
-src/domain/<context>/entities
-src/domain/<context>/validators
-src/domain/<context>/events
-src/domain/<context>/repository-ports
 src/domain/<context>/constants
 ```
 
-Use `business-objects/` and `value-objects/` for new canonical aggregate work, especially intelligence. Use `entities/` when extending a context that already uses domain entities, such as `pessoas` or `wallets`.
+Use `business-objects/` and `value-objects/` for new canonical aggregate work. Use `entities/`, `validators/`, `events/`, and `repository-ports/` only when extending a context that already uses the legacy entity-pattern, currently `pessoas` or `wallets`.
 
 Do not create domain folders for transport, database, provider, prompt, SDK, queue, cache, HTTP, or UI concerns.
 
@@ -31,7 +27,7 @@ Before adding a domain artifact, decide:
 
 - Is this a durable business concept or just transport/persistence shape?
 - Does it own invariants or only type information?
-- Is it an aggregate/business object, value object, legacy entity, validator, event, constant, or repository port?
+- Is it a business object, value object, type, constant, or an ADR-backed extension to a legacy entity-pattern context?
 - Does existing domain language already cover it?
 - Which tests should prove normalization, invalid paths, and immutability?
 
@@ -291,16 +287,18 @@ export class PessoaValidator {
 }
 ```
 
-Presentation validators must not replace domain validators. Presentation validates request shape; domain validates business invariants.
+Presentation validators must not replace domain invariants. Presentation validates request shape; BO-pattern contexts validate inside BOs and VOs. Domain validators are limited to existing entity-pattern contexts.
 
 ## Repository Ports
 
-Repository ports belong in domain when they represent domain aggregate persistence:
+For BO-pattern contexts, repository ports belong in application `ports/out`:
 
 ```text
-src/domain/<context>/repository-ports/<name>-repository.port.ts
+src/application/business/<context>/ports/out/<name>-repository.port.ts
 ```
 
+Domain `repository-ports/` exists only when extending the closed legacy entity-pattern contexts already present in Foundation (`pessoas`, `wallets`).
+
 Pattern:
 
 ```ts
@@ -319,17 +317,19 @@ Rules:
 - Export a `Symbol` and an interface.
 - Return domain objects, not ORM entities.
 - Keep persistence technology out of the port name, except implementation names in infrastructure.
-- Application ports can also describe repositories when the persistence need is application-specific rather than aggregate-owned. Follow existing module patterns.
-- Do not expose query builders, transactions, connection objects, ORM entities, or provider SDK types through domain ports.
+- For BO-pattern contexts, this port is an application outbound port even when it returns a domain BO.
+- Do not expose query builders, transactions, connection objects, ORM entities, or provider SDK types through ports.
 
 ## Domain Events
 
-Use domain events for business facts:
+Use domain events for business facts only when extending an existing entity-pattern context:
 
 ```text
 src/domain/<context>/events/<name>-created.event.ts
 ```
 
+For BO-pattern contexts, emit integration or domain-like events from application handlers unless an ADR deliberately extends the pattern.
+
 Keep events serializable and framework-free:
 
 ```ts

package/.sdd/skills/curated/devtrack-api/references/foundation-layout.md

@@ -206,13 +206,12 @@ src/infrastructure/adapters/orm/entities/<name>.orm-entity.ts
 src/infrastructure/adapters/orm/repositories/<name>.typeorm-repository.ts
 src/infrastructure/adapters/orm/mappers/<name>.mapper.ts
 src/infrastructure/adapters/orm/migrations/<timestamp>-<action>.migration.ts
-src/infrastructure/adapters/orm/<context>-orm.module.ts
+src/infrastructure/adapters/orm/orm.module.ts
 src/infrastructure/adapters/orm/typeorm.config.ts
 src/infrastructure/adapters/orm/typeorm-cli.datasource.ts
-src/infrastructure/adapters/orm/typeorm.module.ts
 ```
 
-The `<context>-orm.module.ts` files (e.g., `auth-orm.module.ts`, `pessoas-orm.module.ts`, `wallets-orm.module.ts`, `sync-engine-orm.module.ts`) wire per-context TypeORM artifacts inside the centralized `orm/` folder. Do **not** create `src/infrastructure/<context>/persistence/typeorm/`.
+The ORM subsystem has one Nest module only: `src/infrastructure/adapters/orm/orm.module.ts`. It registers TypeORM entities, concrete `*.typeorm-repository.ts` providers, mapper dependencies when needed, and exports the repository providers/tokens required by application ports. Do **not** create per-context or per-entity modules such as `auth-orm.module.ts`, `pessoas-orm.module.ts`, `wallets-orm.module.ts`, or `sync-engine-orm.module.ts`. Do **not** create `src/infrastructure/<context>/persistence/typeorm/`.
 
 ### 5.2 Adapter ports (shared)
 

package/.sdd/skills/curated/devtrack-api/references/implementation-checklist.md

@@ -78,7 +78,7 @@
 - Mapper ends with `.mapper.ts`.
 - Repository implements a port.
 - Mapper is stateless and maps domain <-> ORM only.
-- New entity is added to TypeORM config, CLI datasource, root module, ORM feature module, and infrastructure module as needed.
+- New entity is added to TypeORM config, CLI datasource, the single `orm.module.ts`, and infrastructure module as needed.
 - Migration SQL matches entity decorators.
 - Unique violations are translated to domain/shared exceptions.
 - No Prisma artifacts.

package/.sdd/skills/curated/devtrack-api/references/portable-agent-contract.md

@@ -0,0 +1,41 @@
+# Portable Agent Contract
+
+Use this reference when adapting `devtrack-api` for Codex, Claude Code, Cursor, Gemini, Kimi, OpenCode, or any markdown/CLI coding agent.
+
+## Common Rules
+
+- The `SKILL.md` frontmatter is the trigger surface; keep `name: devtrack-api` and a direct description of NestJS, TypeORM, DDD, Clean Architecture, CodeSDD, and Foundation-compatible API work.
+- The body is the runtime contract; detailed Foundation rules live in `references/`.
+- Agent-specific files in `agents/` are adapters, not separate sources of truth.
+- CodeSDD state remains canonical for planning, quality, and finalize evidence.
+- `devtrack-foundation-api` source and the Foundation layout reference win over generated assumptions.
+- Do not persist hidden memory or parallel backlog outside `.sdd`.
+- If the host cannot read `agents/*.yaml`, it must still be able to follow `SKILL.md` and this reference.
+
+## Agent Matrix
+
+| Agent | Canonical id | Adapter file | Expected behavior |
+| --- | --- | --- | --- |
+| OpenAI host adapter | `openai` | `agents/openai.yaml` | Provide interface metadata for OpenAI/Codex-compatible skill hosts; not a separate planning source. |
+| Codex | `codex` | `agents/codex.yaml` | Read CodeSDD policy first, load FEAT context, use repository evidence, and preserve user changes. |
+| Claude Code | `claude` | `agents/claude-code.yaml` | Read AGENTS/CLAUDE files, keep changes scoped, and report unavailable tools honestly. |
+| Cursor | `cursor` | `agents/cursor.yaml` | Use repository-local context and avoid detached plans that bypass CodeSDD. |
+| Gemini | `gemini` | `agents/gemini.yaml` | Prefer explicit references and validation commands over inferred NestJS or TypeORM APIs. |
+| Kimi | `kimi` | `agents/kimi.yaml` | Treat markdown skill text as authoritative and produce compact, evidence-backed edits. |
+| OpenCode | `opencode` | `agents/opencode.yaml` | Use `opencode` for local skill sync and `open-code` only when an MCP provider contract requires it. |
+| Generic | `generic-markdown-cli` | none required | Read `SKILL.md`, then relevant references, then report evidence in CodeSDD quality artifacts. |
+
+## Evidence Expectations
+
+Every agent must leave enough evidence for another agent to continue:
+
+- files changed and why;
+- selected derivation profile from `contract-pack.yaml`;
+- Foundation source/layout evidence used;
+- relevant DTAPI rule ids checked;
+- validation commands run, skipped, or unavailable;
+- residual drift, exception status, and ADR or follow-up FEAT references.
+
+## Isolation
+
+`devtrack-api` governs backend/API layout and Foundation fidelity. It may publish API contracts or DTO expectations to frontend or mobile consumers, but it does not govern Angular page structure, UI-kit adapters, Formly schemas, NGXS state, Flutter widget layout, Flutter routing, Flutter localization, or frontend/mobile accessibility gates. Angular Admin belongs to `devtrack-angular`; Flutter/Dart app work belongs to `devtrack-flutter`.

package/.sdd/skills/curated/devtrack-api/references/typeorm-infrastructure.md

@@ -32,10 +32,9 @@ src/infrastructure/adapters/orm/entities/<name>.orm-entity.ts
 src/infrastructure/adapters/orm/mappers/<name>.mapper.ts
 src/infrastructure/adapters/orm/repositories/<name>.typeorm-repository.ts
 src/infrastructure/adapters/orm/migrations/<timestamp>-<action>.migration.ts
-src/infrastructure/adapters/orm/<module>-orm.module.ts
+src/infrastructure/adapters/orm/orm.module.ts
 src/infrastructure/adapters/orm/typeorm.config.ts
 src/infrastructure/adapters/orm/typeorm-cli.datasource.ts
-src/infrastructure/adapters/orm/typeorm.module.ts
 ```
 
 ## ORM Entities
@@ -128,7 +127,7 @@ Pattern:
 import { Injectable } from '@nestjs/common';
 import { InjectRepository } from '@nestjs/typeorm';
 import type { Repository } from 'typeorm';
-import type { ExampleRepositoryPort } from '@domain/example/repository-ports/example-repository.port';
+import type { ExampleRepositoryPort } from '@application/business/example/ports/out/example-repository.port';
 import type { Example } from '@domain/example/business-objects/example.bo';
 import { DuplicateEntityException } from '@domain/exceptions/duplicate-entity.exception';
 import { GenericRepository } from '@infrastructure/adapter/orm/generic-repository';
@@ -181,14 +180,14 @@ Rules:
 - Do not leak `Repository`, `QueryRunner`, `DataSource`, or ORM entities through ports.
 - Keep transaction ownership explicit and aligned with existing repository/unit-of-work patterns.
 
-## ORM Modules
+## ORM Module
 
 Pattern:
 
 ```ts
 import { Global, Module } from '@nestjs/common';
 import { TypeOrmModule } from '@nestjs/typeorm';
-import { ExampleRepositoryPortSymbol } from '@domain/example/repository-ports/example-repository.port';
+import { ExampleRepositoryPortSymbol } from '@application/business/example/ports/out/example-repository.port';
 import { ExampleOrmEntity } from '@infrastructure/adapters/orm/entities/example.orm-entity';
 import { ExampleTypeOrmRepository } from '@infrastructure/adapters/orm/repositories/example.typeorm-repository';
 
@@ -204,10 +203,10 @@ import { ExampleTypeOrmRepository } from '@infrastructure/adapters/orm/repositor
   ],
   exports: [ExampleRepositoryPortSymbol],
 })
-export class ExamplesOrmModule {}
+export class OrmModule {}
 ```
 
-Wire new ORM modules into `src/infrastructure/infrastructure.module.ts` when they must be available to the app.
+The ORM subsystem must have one Nest module only: `src/infrastructure/adapters/orm/orm.module.ts`. Do not create `*-orm.module.ts` files per entity, context, or feature. Add every new `*.typeorm-repository.ts` provider to this module and export the repository provider and/or its application port token from this module.
 
 ## TypeORM Root Wiring
 
@@ -215,8 +214,7 @@ When adding a new ORM entity, update all relevant places:
 
 - `src/infrastructure/adapters/orm/typeorm.config.ts`
 - `src/infrastructure/adapters/orm/typeorm-cli.datasource.ts`
-- `src/infrastructure/adapters/orm/typeorm.module.ts`
-- new or existing `*-orm.module.ts`
+- `src/infrastructure/adapters/orm/orm.module.ts`
 - `src/infrastructure/infrastructure.module.ts`
 
 Do not rely on glob entity discovery for new application entities unless the repo switches to that pattern.