@devtrack-solution/codesdd 1.2.3 → 1.2.4

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?
 
@@ -202,7 +198,8 @@ export class Example
 Rules:
 
 - Extend `GenericBusinessObject<T>` when the object owns invariants.
-- Implement `IValidator` when following the canonical BO pattern.
+- Implement the BO interface first and `IValidator` second: `implements <Name>Interface, IValidator`.
+- Keep the class declaration ordered as `extends GenericBusinessObject<T>` before `implements ...`.
 - Validate before transform through `GenericBusinessObject` constructor behavior.
 - Normalize data in `loadData` or `transform`.
 - Expose read-only getters; clone arrays/objects/dates to avoid external mutation.
@@ -211,6 +208,7 @@ Rules:
 - Throw domain exceptions, usually `BusinessValidationException`, not HTTP exceptions.
 - Do not inject repositories, services, loggers, config, SDKs, or framework dependencies into domain objects.
 - Do not publish events, send messages, call providers, or persist data from the domain object directly.
+- The observed `src/domain/auth/business-objects/api-keys.bo.ts` static utility is a named Foundation exception. Do not use it as the model for new aggregate BO files.
 
 ## Value Objects: `.vo.ts`
 
@@ -291,16 +289,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 +319,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/field-validation-protocol.md

@@ -93,3 +93,43 @@ CodeSDD may close the field-validation expectation only when:
 - the evidence remains in the consumer repository, with only a summary and reference retained here.
 
 If this evidence is not yet available, CodeSDD should keep a follow-up SDD item or formal exception instead of claiming field adoption is proven.
+
+## FEAT-0378 Consumer Evidence Summary
+
+FEAT-0378 records the EPIC-0080 consumer-field validation boundary without importing private consumer ledgers into this repository.
+
+Summary reference packet:
+
+```yaml
+devtrack_api_field_validation_summary:
+  protocol: devtrack-api-field-validation-v1
+  feature_ref: FEAT-0378
+  governing_decision_ref: ADR-FEAT-0378
+  profile: foundation-compatible
+  codesdd_source_ref: FEAT-0378 active workspace
+  foundation_source_ref: devtrack-foundation-api audited projection via FEAT-0373 through FEAT-0376
+  sync_evidence_ref: consumer-sync-policy.md#feat-0378-consumer-evidence-sync-rule
+  private_ledger_boundary: consumer-held evidence only; do not copy ledgers into CodeSDD
+  consumer_evidence_refs:
+    - ref: consumer-owned-devtrack-api-deb-1
+      kind: approved_owner_reference
+      ledger_location: consumer CodeSDD quality ledger or handoff
+      status: accepted_exception
+    - ref: consumer-owned-devtrack-api-deb-2
+      kind: approved_owner_reference
+      ledger_location: consumer CodeSDD quality ledger or handoff
+      status: accepted_exception
+  divergence_matrix:
+    D-01: accepted_exception
+    D-02: accepted_exception
+    D-03: accepted_exception
+    D-04: accepted_exception
+    D-05: accepted_exception
+    D-06: accepted_exception
+    D-07: accepted_exception
+    D-08: accepted_exception
+  accepted_exception_ref: ADR-FEAT-0378
+  open_policy_findings: []
+```
+
+The `accepted_exception` status above is a privacy-preserving governance closure, not a copy of consumer evidence. Operators must resolve each opaque `consumer-owned-*` reference in the consumer repository before using the packet to claim field adoption for that consumer. If either reference cannot be resolved, the consuming project remains blocked or excepted under its own CodeSDD quality ledger.

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

@@ -58,6 +58,18 @@ Folders forbidden in BO-pattern:
 - `events/` — emit domain events from application use cases, not domain artifacts, when the context is BO-pattern. Foundation emits events from application handlers.
 - `validators/` — present only in legacy entity-pattern; BO-pattern validates inside the BO (`validate()` method).
 
+Canonical BO class shape for new aggregate/business objects:
+
+```text
+export class <Name>
+  extends GenericBusinessObject<<Name>Type.Output>
+  implements <Name>Interface, IValidator
+```
+
+Order matters: `extends GenericBusinessObject<T>` first, then `implements <Name>Interface, IValidator`. The BO interface declares read-only getters, behavior methods, and `toPersistenceObject()`. The class validates through `public validate(...)`, normalizes through `protected transform(...)` or `static loadData(...)`, exposes read-only getters, and returns domain persistence data from `toPersistenceObject()`.
+
+Observed exception in the current Foundation tree: `src/domain/auth/business-objects/api-keys.bo.ts` is a static domain utility named `ApiKeysDomain`; do not use it as the template for new aggregate BOs.
+
 Contexts currently using BO-pattern in Foundation:
 
 | Context | Path | Notes |
@@ -206,13 +218,17 @@ 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/typeorm.module.ts
 src/infrastructure/adapters/orm/<context>-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/`.
+Observed ORM modules in Foundation: `auth-orm.module.ts`, `pessoas-orm.module.ts`, `sync-engine-orm.module.ts`, `typeorm.module.ts`, `wallets-orm.module.ts`.
+
+`typeorm.module.ts` is the root TypeORM module. It calls `TypeOrmModule.forRootAsync`, references `typeorm.config.ts`, and registers base entities through `TypeOrmModule.forFeature`.
+
+`<context>-orm.module.ts` files are context-level provider modules. They import `TypeOrmModule.forFeature([...])`, register concrete `*.typeorm-repository.ts` adapters, bind the owning repository/service port symbols with `useExisting`, and export those port symbols. Do **not** create entity-specific modules such as `category-entity-orm.module.ts` or any `src/infrastructure/<context>/persistence/typeorm/` tree.
 
 ### 5.2 Adapter ports (shared)
 
@@ -276,6 +292,7 @@ Aliases are mandatory in `src/` and tests. Same-folder relative imports are forb
 | `src/infrastructure/<context>/persistence/typeorm/` | `src/infrastructure/adapters/orm/` |
 | `src/infrastructure/<context>/adapters/` | `src/infrastructure/adapters/<subsystem>/` |
 | `src/infrastructure/<context>/repositories/` | `src/infrastructure/adapters/orm/repositories/` |
+| `src/infrastructure/adapters/orm/<entity>-orm.module.ts` | `src/infrastructure/adapters/orm/<context>-orm.module.ts` |
 | `src/presentation/<context>/` (no transport) | `src/presentation/rest/<context>/` (or other transport) |
 | `entities/` in new domain context | `business-objects/` |
 | `repository-ports/` in new domain context | application `ports/out/<name>-repository.port.ts` |

package/.sdd/skills/curated/devtrack-api/references/generated-artifact-invalidation.md

@@ -0,0 +1,97 @@
+# devtrack-api Generated Artifact Invalidation
+
+## Scope
+
+This policy governs generated `devtrack-api` previews, scaffold dry-runs, caches, artifact maps, validation manifests, and evidence bundles created before the EPIC-0080 Foundation-compatible gates became active.
+
+It applies to artifacts produced or consumed by:
+
+- `codesdd sdd plugin devtrack-api scaffold-dry-run`;
+- package-structure previews and `human_validation_gate` payloads;
+- Foundation artifact maps and semantic validator results;
+- generated evidence stored in `.sdd/plugin-evidence/`, `.sdd/active/`, `.sdd/archived/`, `outputs/`, or disposable `~/.codesdd/cache` entries.
+
+## Default Rule
+
+Pre-charter generated artifacts are noncanonical by default. They are evidence only until revalidated against the active `foundation-compatible` contract.
+
+An artifact must not be treated as Foundation-compatible when it lacks any of the following:
+
+- selected derivation profile;
+- artifact-map validation result;
+- package preview material signature;
+- `human_validation_gate.status` using only `approved`, `corrected`, `pending`, or `rejected`;
+- semantic validator profile outcome for `foundation-compatible`;
+- sync evidence for the `devtrack-api` skill copy when the artifact came from a consumer repository;
+- D-01 through D-08 field-validation summary or formal exception when the artifact claims consumer adoption.
+
+## Classification
+
+Use exactly one classification per generated artifact:
+
+| Classification | Meaning | Required action |
+| --- | --- | --- |
+| `revalidated` | The artifact was regenerated or checked against the active contract and passed the applicable profile gates. | Record command, profile, validator output, material signature, and approval state in the owning FEAT quality ledger. |
+| `invalidated` | The artifact predates active gates, fails P0 validation, has stale approval, or cannot be traced to current sources. | Mark noncanonical, exclude from Foundation-compatible claims, and regenerate before use. |
+| `grandfathered` | The artifact remains useful as historical evidence but is not used as an executable or compatibility claim. | Record owner, scope, reason, review deadline, rollback trigger, and governing ADR/FEAT quality entry. |
+| `not_applicable` | The artifact is unrelated to `devtrack-api` generated output or is disposable cache without governance value. | Keep disposable or ignore; do not promote to CodeSDD state. |
+
+## Revalidation Procedure
+
+Before reusing a legacy generated artifact:
+
+1. Identify the artifact owner, path, generator command, source commit or release, selected profile, and creation time when available.
+2. Re-run the active non-mutating generator or validator for the same intent.
+3. Compare the current artifact map and preview material signature with the legacy artifact.
+4. Run semantic validation for the selected profile.
+5. Reset any prior `approved` or `corrected` `human_validation_gate.status` to `pending` when source material, profile, exception refs, artifact map, preview structure, or validator scope changed.
+6. Record the classification in the owning FEAT quality ledger.
+
+Minimum validation commands:
+
+```bash
+codesdd sdd plugin devtrack-api scaffold-dry-run
+codesdd sdd check --render
+codesdd sdd diagnose --json
+```
+
+When source code or TypeScript validator contracts changed, also run the targeted validator tests:
+
+```bash
+pnpm exec vitest run test/core/sdd/devtrack-api-appliance.test.ts test/core/sdd/foundation-artifact-map-validator.test.ts test/core/sdd/package-structure-gate.test.ts test/core/sdd/devtrack-api-architecture.test.ts
+```
+
+## Invalidation Triggers
+
+Invalidate or reset approval for a generated artifact when any trigger applies:
+
+- artifact predates `ADR-FEAT-0373`;
+- artifact predates artifact-map gate evidence from `ADR-FEAT-0374`;
+- package preview lacks the FEAT-0375 material signature or Foundation `tests/` projection;
+- semantic validator output lacks FEAT-0376 drift classes or profile outcomes;
+- consumer field-validation references changed after `ADR-FEAT-0378`;
+- artifact uses plural CodeSDD roots as `devtrack-api` output;
+- artifact uses forbidden Foundation alias shapes or omits `@tests/*`;
+- artifact lacks provenance for source refs, decision refs, profile, or exception refs;
+- disposable cache cannot be tied to the current project fingerprint.
+
+## Grandfathering Rule
+
+Grandfathering never means compatible. It means the artifact remains useful for history, comparison, or rollback only.
+
+A grandfathered artifact must record:
+
+- owner;
+- artifact path or opaque reference;
+- reason;
+- accepted risk;
+- compensating control;
+- review deadline;
+- rollback trigger;
+- governing ADR, DEB, or FEAT quality entry.
+
+## Closure Rule
+
+EPIC-0080 closure may cite legacy generated artifacts only when every cited artifact is `revalidated`, `invalidated`, `grandfathered`, or `not_applicable`.
+
+Any uncategorized legacy artifact blocks the compatibility claim it supports. Disposable cache may be ignored only when it is not referenced by a FEAT quality ledger, ADR, preview, artifact map, validator result, or consumer evidence summary.

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

@@ -20,6 +20,22 @@
 - Keep the scope narrow; do not repair unrelated architecture unless it blocks the requested work.
 - Prefer local patterns over generic best practices when both are valid.
 
+## Tool-Level API Baseline Pass
+
+- For API, backend, scaffold, CRUD, or route work, infer the minimum operational API baseline unless the user explicitly selected a prototype/docs-only exception.
+- The plan asks whether authentication is required and which mechanism applies: JWT bearer, API key, session, machine-to-machine credential, or public route.
+- The plan asks whether authorization is required and which role, permission, policy, ownership, or tenancy rule applies.
+- Public routes are explicitly named; lack of auth/authz discussion is not treated as public by default.
+- New API projects/scaffolds include `package.json`, `.env.example`, `tsconfig.json`, Nest CLI config, lint/test config, and validation commands.
+- Root scripts include build, start, development start, production start, lint, unit tests, coverage, e2e tests, and migrations when persistent schema changes exist.
+- Root scripts include `cleanup` and `cleanup:install`; cleanup removes dependency installs, build output, caches, lockfiles, and TypeScript compilation residue unless an ADR preserves a canonical lockfile.
+- `start` and `start:dev` invoke `node scripts/kill-port.js` before Nest starts and continue after terminating any process bound to the configured port.
+- Scripts can be invoked with `npm run` and `pnpm run`; nested package-script calls use `npm run` and `npm install` so Docker builds do not need pnpm by default.
+- `.env.example` uses placeholders for new variables and includes Swagger server settings when OpenAPI is configured.
+- REST APIs include root Swagger/OpenAPI bootstrap with `DocumentBuilder`, `SwaggerModule.createDocument`, and `SwaggerModule.setup("docs", app, document)`.
+- Each user-facing route has an application input port plus use case before controller wiring is considered complete.
+- Protected routes include route guards/decorators and Swagger security documentation.
+
 ## Design Slice
 
 - Identify touched layers.
@@ -29,6 +45,7 @@
 - Decide whether persistence needs a domain repository port or an application output port.
 - Decide whether a public endpoint is appropriate. Internal AWS lifecycle work should not get public endpoints.
 - Decide whether the change affects API contracts, migrations, environment variables, queues, LLM tools, prompts, or security-sensitive behavior.
+- For each route, name the input port, use case, controller/transport, request DTO/presentation validator, response DTO when applicable, guard/decorator, and Swagger operation/response docs.
 
 ## Domain Pass
 
@@ -78,7 +95,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, `typeorm.module.ts`, the owning `<context>-orm.module.ts`, and infrastructure module as needed.
 - Migration SQL matches entity decorators.
 - Unique violations are translated to domain/shared exceptions.
 - No Prisma artifacts.
@@ -98,12 +115,24 @@
 - No unhandled promises.
 - No broad lint disables without a narrow reason.
 
+## Root Package And Runtime Pass
+
+- `package.json` contains scripts needed to build, run, lint, test, collect coverage, run e2e, cleanup, cleanup:install, and execute migrations when applicable.
+- `scripts/cleanup.sh` removes dependency installs, build outputs, caches, lockfiles, and compilation residue unless a FEAT/ADR records a narrower cleanup contract.
+- `scripts/kill-port.js` supports explicit script arguments and `PORT`/`APP_PORT`, covers Unix and Windows termination paths, and is wired before `start` and `start:dev`.
+- Script composition uses `npm run` and `npm install` internally so `npm` and `pnpm` entrypoints remain valid without requiring pnpm in Docker.
+- `package.json` includes `@nestjs/swagger` for REST APIs with OpenAPI docs.
+- `.env.example` exists and documents every new runtime variable with safe placeholder values.
+- `src/main.ts` wires global validation and Swagger/OpenAPI when REST is present.
+- Runtime configuration reads Swagger server settings through typed config instead of hard-coded secrets or deployment URLs.
+
 ## Security And Data Pass
 
 - No secrets, tokens, private keys, cookies, credentials, or connection strings are added to code, tests, docs, logs, prompts, or handoff.
 - `.env.example` is updated when variable names change; `.env` real values are not copied.
 - Logs avoid sensitive payloads, raw prompts, full provider responses, and personal data unless existing policy allows it.
 - Auth, authorization, tenancy, encryption, PII, retention, and audit behavior are unchanged unless the task requires it.
+- Auth/authz planning decisions are not left pending for new routes; protected routes have guards/decorators and public routes have explicit exceptions.
 - Destructive operations are not executed unless explicitly requested and scoped.
 - Public endpoints do not expose internal lifecycle envelopes or infrastructure payloads.
 

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

@@ -0,0 +1,42 @@
+# Portable Agent Contract
+
+Use this reference when adapting the CodeSDD API profile family through the `devtrack-api` compatibility skill for Codex, Claude Code, Cursor, Gemini, Kimi, OpenCode, or any markdown/CLI coding agent.
+
+## Common Rules
+
+- The `SKILL.md` frontmatter is the compatibility trigger surface; keep `name: devtrack-api`, but public API work should name one of `minimal-rest`, `rest-auth-rbac`, `rest-crud-typeorm`, `evented-api`, `ai-agent-api`, or `full-foundation-compatible`.
+- The body is the runtime contract; detailed Foundation rules live in `references/`.
+- Agent-specific files in `agents/` are adapters, not separate sources of truth.
+- `devtrack-api` is a compatibility-only alias and must not be presented as the normal public profile for new API projects.
+- 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 CodeSDD API profile id and selected derivation governance 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/testing-validation.md

@@ -28,10 +28,31 @@ pnpm migration:show
 pnpm migration:run
 ```
 
-Use `pnpm` because the repo is configured around it.
+Use `pnpm` for this CodeSDD repository because the repo is configured around it.
 
 Before using a script for a version-sensitive claim, confirm it exists in `package.json`.
 
+For generated or linked DevTrack API projects, package scripts must also be
+valid through `npm run`. When runtime scripts are touched, validate or inspect
+both entrypoints:
+
+```bash
+npm run build
+npm run start -- --help
+npm run start:dev -- --help
+npm run cleanup
+npm run cleanup:install
+pnpm run build
+pnpm run start:dev -- --help
+```
+
+Generated package-script composition must use `npm run` and `npm install`
+internally so Docker images do not require pnpm by default. `start` and
+`start:dev` must run `node scripts/kill-port.js` before Nest starts, and
+`cleanup` must remove dependency installs, build outputs, caches, lockfiles,
+and TypeScript compilation residue unless a FEAT/ADR records a narrower
+cleanup contract.
+
 ## Test Selection
 
 Choose the smallest useful validation:

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

@@ -32,12 +32,14 @@ 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/typeorm.module.ts
+src/infrastructure/adapters/orm/<context>-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
 ```
 
+Observed ORM modules in Foundation: `auth-orm.module.ts`, `pessoas-orm.module.ts`, `sync-engine-orm.module.ts`, `typeorm.module.ts`, `wallets-orm.module.ts`.
+
 ## ORM Entities
 
 Pattern:
@@ -128,7 +130,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';
@@ -188,7 +190,7 @@ 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 +206,10 @@ import { ExampleTypeOrmRepository } from '@infrastructure/adapters/orm/repositor
   ],
   exports: [ExampleRepositoryPortSymbol],
 })
-export class ExamplesOrmModule {}
+export class ExampleOrmModule {}
 ```
 
-Wire new ORM modules into `src/infrastructure/infrastructure.module.ts` when they must be available to the app.
+Foundation uses `src/infrastructure/adapters/orm/typeorm.module.ts` for root TypeORM configuration and `src/infrastructure/adapters/orm/<context>-orm.module.ts` for repository provider modules. Add a new context module when a new persisted context introduces repositories. Do not create per-entity modules; module ownership is by context.
 
 ## TypeORM Root Wiring
 
@@ -216,7 +218,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/<context>-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.