@devtrack-solution/codesdd 1.2.2

package/.sdd/skills/curated/devtrack-api/references/imports-lint.md

@@ -0,0 +1,207 @@
+# Imports, Aliases, And Lint
+
+## Purpose
+
+Imports express architecture. Treat import and lint failures as signals that a dependency boundary, type boundary, or error handling decision may be wrong.
+
+## Commands
+
+Use these checks:
+
+```bash
+pnpm lint
+pnpm build
+pnpm exec jest <test-file-or-pattern> --runInBand
+```
+
+Run targeted tests first. Use full lint/build after cross-layer or module wiring changes.
+
+Do not claim these commands passed unless they were executed successfully.
+
+## Import Aliases
+
+Use aliases from `tsconfig.json`:
+
+```text
+@domain/*                  -> src/domain/*, src/shared/domain/*
+@application/*             -> src/application/*
+@presentation/*            -> src/presentation/*, src/shared/presentation/*
+@infrastructure/adapter/*  -> src/shared/infrastructure/adapter/*, src/infrastructure/adapters/*
+@infrastructure/*          -> src/infrastructure/*, src/shared/infrastructure/*
+@shared/*                  -> src/shared/*
+@src/*                     -> src/*
+```
+
+The lint rule `no-relative-import-paths/no-relative-import-paths` forbids relative imports in `src`, with `allowSameFolder: false`.
+
+Do not write:
+
+```ts
+import { Foo } from './foo';
+import { Bar } from '../bar';
+```
+
+Write:
+
+```ts
+import { Foo } from '@application/business/example/services/foo.service';
+import { Bar } from '@domain/example/business-objects/bar.bo';
+```
+
+Apply the same principle to tests when the lint/configuration expects aliases there.
+
+## Type-Only Imports
+
+`@typescript-eslint/consistent-type-imports` is enabled. Use `import type` when the symbol is used only as a type:
+
+```ts
+import { Injectable } from '@nestjs/common';
+import type { Repository } from 'typeorm';
+import type { Pessoa } from '@domain/pessoas/entities/pessoa.entity';
+```
+
+When a module exports both runtime and type symbols, split imports:
+
+```ts
+import { PessoaRepositoryPortSymbol } from '@domain/pessoas/repository-ports/pessoa-repository.port';
+import type { PessoaRepositoryPort } from '@domain/pessoas/repository-ports/pessoa-repository.port';
+```
+
+Rules:
+
+- Runtime decorators, symbols, classes, and values must use normal imports.
+- Interfaces, type aliases, and generic-only dependencies should use `import type`.
+- Avoid importing a whole module just to access a type.
+
+## Layer Import Matrix
+
+### Domain
+
+Allowed:
+
+- `@domain/*`
+- `@shared/domain/*`
+- TypeScript built-ins and tiny runtime utilities with no framework coupling.
+
+Forbidden:
+
+- `@nestjs/*`
+- `typeorm`
+- `class-validator`
+- `@application/*`
+- `@presentation/*`
+- `@infrastructure/*`
+- HTTP, queue, AWS, cache, ORM, LLM, vector store, Temporal, SDK, provider, prompt, or transport concepts.
+
+### Application
+
+Allowed:
+
+- `@domain/*`
+- `@application/*`
+- Nest DI decorators such as `@Injectable`, `@Inject`, `@Optional` where existing patterns use them.
+- Port interfaces from `@infrastructure/adapter/**/*.port` only when the port is a shared infrastructure contract.
+
+Forbidden:
+
+- `@presentation/*`
+- `src/infrastructure/*`
+- `@infrastructure/adapters/*` concrete adapters.
+- Provider SDKs, TypeORM entities, queue processors, HTTP controllers, or presentation validators.
+
+Prefer application-owned ports under:
+
+```text
+src/application/<context>/<module>/ports/out
+```
+
+### Presentation
+
+Allowed:
+
+- `@application/*`
+- `@presentation/*`
+- Nest controller, guard, Swagger, GraphQL, CLI, WebSocket, and class-validator APIs.
+- Shared presentation DTOs and filters through `@presentation/*`.
+
+Forbidden:
+
+- concrete infrastructure adapters,
+- TypeORM entities or repositories,
+- provider SDKs,
+- business decisions that belong in domain/application,
+- raw internal lifecycle payloads.
+
+### Infrastructure
+
+Allowed:
+
+- `@domain/*`
+- `@application/*` ports
+- `@infrastructure/*`
+- `@infrastructure/adapter/*`
+- framework SDKs, TypeORM, AWS SDK, BullMQ, Redis, Temporal, LLM providers, vector stores.
+
+Infrastructure implements contracts; it should not define business rules.
+
+## Lint Rules To Respect
+
+Important rules from `eslint.config.mjs`:
+
+- no relative imports.
+- no unused variables, except args prefixed with `_`.
+- `no-console` is a warning. Use Nest `Logger` or existing logger patterns.
+- `@typescript-eslint/no-floating-promises` is an error. Await promises or intentionally handle them.
+- `@typescript-eslint/no-explicit-any` is a warning. Prefer `unknown`, generics, or explicit DTO types.
+- `@typescript-eslint/no-unsafe-argument` is a warning. Narrow unknown values before passing them.
+- Prettier is enforced with `endOfLine: auto`.
+
+Warnings are not automatically safe to ignore. Treat them as design feedback and document any accepted warning in the handoff when it remains.
+
+## Promise Handling Pattern
+
+If a background publish must not block the main flow, handle errors explicitly:
+
+```ts
+this.publisher
+  .publish(event)
+  .catch((error) => this.logger.error('Failed to publish event', error));
+```
+
+Do not leave a floating promise.
+
+For async callbacks, queue processors, event handlers, and tool calls, either `await`, return the promise, or attach `.catch` with useful error handling.
+
+## Import Ordering
+
+Follow nearby files. A stable default is:
+
+1. Framework imports.
+2. Node or package imports.
+3. Runtime aliases.
+4. Type-only aliases.
+
+Avoid duplicate imports from the same package unless splitting runtime and type imports is required by lint.
+
+## Boundary Smells
+
+Investigate these patterns before accepting them:
+
+- Domain importing Nest, TypeORM, class-validator, SDKs, or HTTP concepts.
+- Application importing a concrete adapter instead of a port.
+- Presentation importing repositories, TypeORM entities, AWS clients, LLM clients, or queues.
+- Infrastructure returning ORM entities through a domain/application contract.
+- A mapper performing queries or business decisions.
+- A validator duplicating domain invariants.
+- A service using `any` to bypass type mismatches.
+- A lint disable without a narrow reason.
+
+## Common Fixes
+
+- If lint reports a relative import, replace it with the correct alias.
+- If lint reports a type import, split runtime and type imports.
+- If domain imports a framework, move that concern outward.
+- If application imports a concrete adapter, introduce or use a port.
+- If presentation imports infrastructure, inject an application port instead.
+- If `any` appears, prefer `unknown`, a generic, a domain/application type, or a presentation validator type.
+- If a promise floats, `await`, return it, or attach `.catch`.

package/.sdd/skills/curated/devtrack-api/references/testing-validation.md

@@ -0,0 +1,167 @@
+# Testing And Validation
+
+## Validation Mission
+
+Validation proves that the change works and that architecture boundaries still hold. Choose the smallest meaningful checks first, then broaden when the change crosses layers or wiring.
+
+Never state that a check passed unless it actually ran and exited successfully.
+
+## Package Scripts
+
+Primary commands:
+
+```bash
+pnpm lint
+pnpm build
+pnpm test
+pnpm test:e2e
+pnpm exec jest <path> --runInBand
+```
+
+Operational commands:
+
+```bash
+pnpm start:dev
+pnpm start:all
+pnpm validate:stack
+pnpm migration:show
+pnpm migration:run
+```
+
+Use `pnpm` because the repo is configured around it.
+
+Before using a script for a version-sensitive claim, confirm it exists in `package.json`.
+
+## Test Selection
+
+Choose the smallest useful validation:
+
+- Domain BO/VO/type changes: run matching `tests/unitaries/domains/**` specs.
+- Legacy domain entity/validator changes: run matching `tests/unitaries/pessoas/**` or `tests/unitaries/domains/<context>/**` specs.
+- Application use case changes: run `tests/unitaries/applications/<module>/**`.
+- Presentation REST changes: run `tests/unitaries/presentation/rest/<module>/**`.
+- GraphQL/CLI/WebSocket changes: run matching `tests/unitaries/presentation/<transport>/**`.
+- TypeORM mapper/repository changes: run `tests/unitaries/infrastructure/**` mapper/repository specs.
+- TypeORM config/entity/migration wiring: run `pnpm build`, targeted infrastructure specs, and `pnpm migration:show` when DB env is available.
+- Cross-layer feature: run targeted unit tests by layer, then `pnpm lint` and `pnpm build`; add e2e when behavior is user-facing.
+- AI/agent/tool changes: run targeted application tests for orchestration plus infrastructure adapter tests for provider mapping/mocking when available.
+- Security-sensitive changes: add negative-path tests for authorization, validation, invalid input, and sensitive-data exposure when relevant.
+
+## Test Folder Patterns
+
+Existing test roots:
+
+```text
+tests/unitaries/domains
+tests/unitaries/applications
+tests/unitaries/infrastructure
+tests/unitaries/presentation
+tests/e2e
+```
+
+Follow current naming:
+
+```text
+<name>.spec.ts
+```
+
+Examples:
+
+```text
+tests/unitaries/domains/intelligence/intelligence.bo.spec.ts
+tests/unitaries/applications/pessoas/create-pessoa.use-case.spec.ts
+tests/unitaries/infrastructure/adapters/orm/repositories/pessoa.typeorm-repository.spec.ts
+tests/unitaries/presentation/rest/pessoas/create-pessoa.controller.spec.ts
+tests/e2e/pessoas/pessoas.e2e-spec.ts
+```
+
+## Unit Test Principles
+
+- Domain tests assert invariants, normalization, cloning/immutability, and domain exceptions.
+- VO tests assert `create`, `normalize`, `isValid`, `equals`, and invalid input paths.
+- Use case tests mock ports and verify orchestration.
+- Controller tests mock application ports and verify mapping only.
+- Repository tests mock or isolate TypeORM repository behavior unless an integration DB is explicitly used.
+- Mapper tests assert domain <-> ORM conversion, including `null`, `undefined`, dates, and enum/status values.
+- Agent/tool tests should verify typed input, safe failure handling, and use-case/port boundaries without calling real providers.
+- Avoid testing framework internals.
+
+## Lint And Build Expectations
+
+`pnpm lint` validates:
+
+- no relative imports,
+- layer import restrictions,
+- type-only imports,
+- no floating promises,
+- no unused variables,
+- Prettier formatting.
+
+`pnpm build` validates:
+
+- Nest build,
+- `tsc-alias`,
+- migration tsconfig build,
+- path alias correctness after compilation.
+
+Treat failures as real until proven otherwise. Do not dismiss them as flaky without evidence.
+
+## Migration And Database Validation
+
+For TypeORM entity or migration changes:
+
+- Confirm entity decorators and migration SQL match.
+- Run `pnpm build` before migration commands because CLI points to `dist`.
+- Run `pnpm migration:show` when DB env is available.
+- Avoid running `pnpm migration:run` unless the task requires it and the target database is confirmed safe.
+- Never run destructive database operations against production-like environments unless explicitly requested and scoped.
+
+## External Integration Validation
+
+For AWS, queue, HTTP, LLM, vector store, Temporal, or cache changes:
+
+- Prefer unit tests with mocked adapters for normal, error, timeout, retry, and invalid payload paths.
+- Keep real provider calls out of automated tests unless the repo already has a controlled integration pattern.
+- Validate configuration parsing without exposing secret values.
+- Confirm failure handling does not leak sensitive payloads.
+
+## SDD Completion
+
+When an active SDD feature exists and the task is feature completion:
+
+1. Update `.sdd/active/<FEAT-ID>/5-quality.yaml` with validation evidence or a formal exception.
+2. Declare frontend impact:
+
+```bash
+opensdd sdd frontend-impact <FEAT-ID> ...
+```
+
+3. Update affected docs when behavior or architecture changes:
+
+```text
+README.md
+.sdd/AGENT.md
+.sdd/core/*.md
+AGENTS.md
+AGENT.md
+```
+
+4. Finalize:
+
+```bash
+opensdd sdd finalize --ref <FEAT-ID>
+```
+
+Do not finalize when the user asked only for a narrow code edit and feature archiving is not in scope.
+
+## Reporting Validation
+
+In the final response, state:
+
+- what changed,
+- which checks ran,
+- result of each check,
+- any checks not run and why,
+- any residual risk.
+
+Do not paste full command output unless the user asks. Include enough detail for another engineer or agent to reproduce the validation.

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

@@ -0,0 +1,334 @@
+# TypeORM And Infrastructure
+
+## Infrastructure Intent
+
+Infrastructure owns concrete integrations:
+
+- TypeORM entities, repositories, mappers, migrations.
+- AWS adapters and modules.
+- Queue processors and adapters.
+- Redis/cache adapters.
+- HTTP clients.
+- LLM and vector store providers.
+- Temporal adapters.
+- Centralized settings.
+
+Infrastructure implements ports from domain/application. It must not become the source of business rules.
+
+## Infrastructure Safety Rules
+
+- Keep credentials, provider configuration, SDK clients, retries, rate limits, polling, ack, retry, DLQ, and transport details in infrastructure.
+- Never expose raw provider responses, credentials, internal lifecycle payloads, or infrastructure envelopes through presentation.
+- Translate provider/database errors into domain/shared/application errors at the boundary where the port contract requires it.
+- Do not add logs that reveal secrets, tokens, raw prompts, full provider responses, personal data, or connection strings.
+- Avoid destructive operations against cloud, queue, cache, or database resources unless explicitly requested and scoped.
+
+## TypeORM File Map
+
+Use:
+
+```text
+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.config.ts
+src/infrastructure/adapters/orm/typeorm-cli.datasource.ts
+src/infrastructure/adapters/orm/typeorm.module.ts
+```
+
+## ORM Entities
+
+Pattern:
+
+```ts
+import { Column, Entity, Index } from 'typeorm';
+import { DatabaseEntityBase } from '@infrastructure/adapter/orm/database-entity-base';
+
+@Entity({ name: 'examples' })
+export class ExampleOrmEntity extends DatabaseEntityBase {
+  @Column({ type: 'varchar', length: 120 })
+  @Index({ unique: true })
+  name!: string;
+
+  @Column({ type: 'varchar', length: 32, default: 'draft' })
+  status!: string;
+}
+```
+
+Rules:
+
+- Entity classes end with `OrmEntity`.
+- Files end with `.orm-entity.ts`.
+- Keep ORM decorators here only.
+- No domain methods.
+- No application services.
+- No HTTP/Swagger/class-validator decorators.
+- Prefer `DatabaseEntityBase` for id/audit fields on new entities.
+- If an existing entity redeclares base fields, preserve local pattern unless the user asks for a refactor.
+- Set explicit column names when database naming differs from property names.
+- Use nullable fields intentionally and reflect `null` in mapper/domain types.
+- Add indexes/unique constraints through decorators and migrations.
+- Do not store secrets, raw provider credentials, or sensitive prompt content unless the domain and security model explicitly require it.
+
+## Mappers
+
+Pattern:
+
+```ts
+import { Example } from '@domain/example/business-objects/example.bo';
+import type { ExampleType } from '@domain/example/types/example.type';
+import { ExampleOrmEntity } from '@infrastructure/adapters/orm/entities/example.orm-entity';
+
+export class ExampleMapper {
+  static toDomain(entity: ExampleOrmEntity): Example {
+    const props: ExampleType.Repository = {
+      id: entity.id,
+      name: entity.name,
+      status: entity.status as ExampleType.Status,
+      createdAt: entity.createdAt,
+      updatedAt: entity.updatedAt,
+    };
+
+    return new Example(props);
+  }
+
+  static toOrm(example: Example): ExampleOrmEntity {
+    const props = example.toPersistenceObject();
+    const entity = new ExampleOrmEntity();
+
+    entity.id = props.id;
+    entity.name = props.name;
+    entity.status = props.status;
+    entity.createdAt = props.createdAt;
+    if (props.updatedAt) entity.updatedAt = props.updatedAt;
+
+    return entity;
+  }
+}
+```
+
+Rules:
+
+- Mappers are stateless.
+- `toDomain` returns domain objects.
+- `toOrm` returns TypeORM entities.
+- Convert `undefined` to `null` where database columns are nullable.
+- Preserve Date values as `Date`, not strings.
+- Do not put queries in mappers.
+- Do not put business decisions in mappers.
+- Keep enum/status casts narrow and backed by domain validation.
+
+## TypeORM Repositories
+
+Pattern:
+
+```ts
+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 { Example } from '@domain/example/business-objects/example.bo';
+import { DuplicateEntityException } from '@domain/exceptions/duplicate-entity.exception';
+import { GenericRepository } from '@infrastructure/adapter/orm/generic-repository';
+import { ExampleOrmEntity } from '@infrastructure/adapters/orm/entities/example.orm-entity';
+import { ExampleMapper } from '@infrastructure/adapters/orm/mappers/example.mapper';
+
+@Injectable()
+export class ExampleTypeOrmRepository
+  extends GenericRepository<Example, ExampleOrmEntity, string>
+  implements ExampleRepositoryPort
+{
+  constructor(
+    @InjectRepository(ExampleOrmEntity)
+    repo: Repository<ExampleOrmEntity>,
+  ) {
+    super(repo);
+  }
+
+  protected toDomain(orm: ExampleOrmEntity): Example {
+    return ExampleMapper.toDomain(orm);
+  }
+
+  protected toOrm(domain: Example): ExampleOrmEntity {
+    return ExampleMapper.toOrm(domain);
+  }
+
+  async save(domain: Example): Promise<Example> {
+    try {
+      return await super.save(domain);
+    } catch (error) {
+      if (this.isUniqueConstraintViolation(error)) {
+        throw new DuplicateEntityException('Example', 'name', domain.name);
+      }
+
+      throw error;
+    }
+  }
+}
+```
+
+Rules:
+
+- Repository files end with `.typeorm-repository.ts`.
+- Repository classes end with `TypeOrmRepository`.
+- Implement domain/application port interfaces.
+- Use `GenericRepository` when CRUD patterns fit.
+- Return domain objects only.
+- Catch Postgres unique violation `23505` and translate to domain/shared exceptions.
+- Keep query-builder specifics inside infrastructure.
+- 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
+
+Pattern:
+
+```ts
+import { Global, Module } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { ExampleRepositoryPortSymbol } from '@domain/example/repository-ports/example-repository.port';
+import { ExampleOrmEntity } from '@infrastructure/adapters/orm/entities/example.orm-entity';
+import { ExampleTypeOrmRepository } from '@infrastructure/adapters/orm/repositories/example.typeorm-repository';
+
+@Global()
+@Module({
+  imports: [TypeOrmModule.forFeature([ExampleOrmEntity])],
+  providers: [
+    ExampleTypeOrmRepository,
+    {
+      provide: ExampleRepositoryPortSymbol,
+      useExisting: ExampleTypeOrmRepository,
+    },
+  ],
+  exports: [ExampleRepositoryPortSymbol],
+})
+export class ExamplesOrmModule {}
+```
+
+Wire new ORM modules into `src/infrastructure/infrastructure.module.ts` when they must be available to the app.
+
+## TypeORM Root Wiring
+
+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/infrastructure.module.ts`
+
+Do not rely on glob entity discovery for new application entities unless the repo switches to that pattern.
+
+## Migrations
+
+Migration file:
+
+```text
+src/infrastructure/adapters/orm/migrations/<timestamp>-create-examples-table.migration.ts
+```
+
+Pattern:
+
+```ts
+import type { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class CreateExamplesTable1700000000006 implements MigrationInterface {
+  name = 'CreateExamplesTable1700000000006';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      CREATE TABLE IF NOT EXISTS examples (
+        id uuid PRIMARY KEY,
+        name varchar(120) UNIQUE NOT NULL,
+        status varchar(32) NOT NULL DEFAULT 'draft',
+        is_active boolean NOT NULL DEFAULT true,
+        created_at TIMESTAMP NOT NULL DEFAULT now(),
+        updated_at TIMESTAMP NOT NULL DEFAULT now(),
+        deleted_at TIMESTAMP NULL
+      )
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query('DROP TABLE IF EXISTS examples');
+  }
+}
+```
+
+Rules:
+
+- Use idempotent `CREATE TABLE IF NOT EXISTS` when consistent with existing migrations.
+- Drop dependent tables before parent tables in `down`.
+- Name foreign key constraints explicitly.
+- Keep migration SQL aligned with entity decorators.
+- Build before running migrations because CLI points to `dist`.
+- Avoid irreversible destructive migrations unless explicitly required and documented.
+- Do not run migrations against production-like environments unless explicitly requested and the target is confirmed.
+
+Migration commands:
+
+```bash
+pnpm migration:show
+pnpm migration:run
+pnpm migration:revert
+```
+
+These run `pnpm build` first through package scripts.
+
+## Settings And Environment
+
+Settings must be centralized in infrastructure settings/configuration, not scattered through application or presentation.
+
+Use existing configuration adapters:
+
+```text
+src/infrastructure/adapters/configuration
+src/shared/infrastructure/configuration
+```
+
+When adding environment variables:
+
+- Update `.env.example`.
+- Keep `.env` and `.env.example` variable names synchronized.
+- Do not commit secret values.
+- Add tests for parsing/defaults if behavior changes.
+- Redact secret values in logs and handoff text.
+
+## AWS Adapters
+
+AWS adapters live under:
+
+```text
+src/infrastructure/adapters/aws
+```
+
+Use application ports for lifecycle orchestration. Keep public labs under `presentation/rest/aws-integrations` isolated from internal lifecycle payloads.
+
+Rules:
+
+- Keep AWS clients, credentials, regions, profiles, retry settings, and SDK error translation in infrastructure.
+- Do not expose canonical internal lifecycle envelopes through REST/GraphQL/CLI/WebSocket.
+- Avoid destructive AWS calls unless explicitly requested and scoped.
+- Mock AWS in unit tests unless a controlled integration pattern already exists.
+
+## Queue Processors
+
+Queue processors and BullMQ/SQS infrastructure live in infrastructure. Application owns message normalization when it expresses use-case semantics. Infrastructure owns polling, ack, retry, DLQ, connection, and SDK concerns.
+
+Rules:
+
+- Do not ack messages before durable application work is complete unless existing semantics require it.
+- Handle retries and DLQ consistently with existing adapter patterns.
+- Log message failures without leaking sensitive payloads.
+- Keep queue payload mapping explicit and tested.
+
+## Provider, LLM, Vector Store, And HTTP Adapters
+
+- Provider SDKs and credentials belong in infrastructure.
+- Application interacts through ports.
+- Mappers translate provider payloads into application/domain-safe shapes.
+- Prompt templates, tool schemas, embeddings, and provider responses must not leak secrets or personal data.
+- Add timeout, retry, and error translation behavior only when aligned with existing patterns or explicitly required.
+- Avoid real provider calls in unit tests.