@devtrack-solution/codesdd 1.2.2

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

@@ -0,0 +1,137 @@
+---
+name: devtrack-api
+description: Model-agnostic engineering skill for the DevTrack Foundation API and derived DevTrack APIs. Use it to implement, review, refactor, test, document, or govern NestJS TypeScript backend work using DDD, Hexagonal Architecture, Clean Architecture, TypeORM, OpenSDD, strict import boundaries, layered modules under domain, application, presentation, infrastructure, and shared, plus safe operational practices, evidence-based validation, and quality handoff.
+---
+
+# DevTrack API
+
+## Mission
+
+Use this skill as the local architecture, quality, safety, and delivery contract for `devtrack-foundation-api` and compatible derived APIs.
+
+The goal is not only to produce code. The goal is to preserve architectural integrity, avoid unsafe changes, validate outcomes with evidence, and leave a reliable handoff that any capable engineering agent can continue.
+
+## Universal Agent Contract
+
+These rules apply to any assistant, automation host, IDE agent, command-line coding agent, or model runtime using this skill:
+
+- Stay model-agnostic. Do not depend on a specific LLM, vendor, chat product, IDE, plugin, or hidden tool.
+- Prefer repository evidence over memory, assumptions, examples, or generated guesses.
+- Do not invent APIs, flags, files, package scripts, class names, module names, environment variables, database objects, or behavior.
+- Verify version-sensitive details from local files such as `package.json`, lockfiles, configs, migrations, source code, or official docs when available.
+- Keep work scoped to the user request and the active OpenSDD feature when one exists.
+- Preserve user changes in a dirty worktree. Never overwrite unrelated modifications.
+- Avoid destructive actions unless the user explicitly requested them and the scope is clear.
+- Never expose, copy, log, commit, or summarize real secrets.
+- 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.
+
+## Operating Mode
+
+Repository files are the source for implementation facts. OpenSDD is the source for operational planning, progress, dependencies, blockers, quality, and handoff.
+
+Before edits in the API repository:
+
+1. Read the nearest `AGENTS.md` and `AGENT.md`.
+2. Run `opensdd sdd onboard system`.
+3. Run `opensdd sdd next`.
+4. If SDD returns a ready or active feature id, run `opensdd sdd context <FEAT-ID>` before coding.
+5. If no feature id is available but the user explicitly requested the work, continue narrowly and state the SDD exception in the final handoff.
+6. Check `git status --short` before editing and before the final handoff.
+7. Inspect nearby implementation files before creating new patterns.
+
+When a command or local tool is unavailable, report it as unavailable, explain the effect on confidence, and use the smallest safe alternative. Do not fake command output.
+
+## Safety Baseline
+
+Treat the repository as a production-grade system:
+
+- No real secrets in commits, examples, logs, tests, prompts, fixtures, screenshots, or handoff text.
+- Update `.env.example` when variable names change. Do not copy values from `.env`.
+- Do not run destructive commands such as broad deletes, hard resets, force pushes, production migrations, table drops, queue purges, or cloud deletions unless explicitly requested and scoped.
+- Avoid changing authentication, authorization, encryption, tenancy, payment, data-retention, PII, logging, or observability behavior without targeted validation.
+- For AI/LLM integrations, keep provider-specific SDKs and credentials in infrastructure, expose capabilities through ports, and avoid leaking prompts, secrets, personal data, or internal lifecycle payloads through presentation.
+- Prefer explicit failure handling over silent fallbacks for security-sensitive behavior.
+
+## Reference Map
+
+Load only the files needed for the task, but always load governance before code changes:
+
+- Always read [architecture-governance.md](references/architecture-governance.md) before code changes.
+- 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 [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.
+- Use [implementation-checklist.md](references/implementation-checklist.md) as the final pass checklist.
+
+## Layer Order
+
+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.
+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.
+5. `src/shared`: stable cross-cutting primitives only when genuinely shared.
+
+Dependency direction is strict:
+
+- `domain` must not import `application`, `presentation`, or `infrastructure`.
+- `application` must not import `presentation` or concrete infrastructure adapters.
+- `presentation` must not import concrete infrastructure.
+- `infrastructure` implements ports defined by `domain` or `application`.
+
+## Non-Negotiable Naming
+
+- Domain types: `src/domain/<context>/types/<name>.type.ts`.
+- Business objects: `src/domain/<context>/business-objects/<name>.bo.ts`.
+- Value objects: `src/domain/<context>/value-objects/<name>.vo.ts`.
+- Domain entities, where the context already uses entities: `<name>.entity.ts`.
+- Domain repository ports: `src/domain/<context>/repository-ports/<name>-repository.port.ts`.
+- Application ports: `src/application/<context>/<module>/ports/in/*.port.ts` and `ports/out/*.port.ts`.
+- Use cases: `<verb-noun>.use-case.ts`.
+- Services: `<name>.service.ts`.
+- Handlers: `<name>.handler.ts`.
+- REST controllers: `<verb-noun>.controller.ts`, one controller class per file.
+- Presentation validators: `<verb-noun>.presentation-validator.ts`.
+- TypeORM entities: `<name>.orm-entity.ts`.
+- TypeORM repositories: `<name>.typeorm-repository.ts`.
+- TypeORM mappers: `<name>.mapper.ts`.
+- TypeORM migrations: `<timestamp>-<action>.migration.ts`.
+- Nest modules: `<module>.application.module.ts`, `<module>.module.ts`, or `<module>-orm.module.ts` by layer.
+
+## Imports And Lint First Principles
+
+- Do not use relative imports in `src` or tests. Even same-folder imports are forbidden.
+- Use aliases: `@domain/*`, `@application/*`, `@presentation/*`, `@infrastructure/*`, `@infrastructure/adapter/*`, `@shared/*`, `@src/*`.
+- Use `import type` for type-only imports.
+- Keep domain free of Nest, TypeORM, class-validator, HTTP, queue, AWS, cache, LLM, and framework concepts.
+- Treat lint warnings as design feedback, not cosmetic noise.
+
+## Implementation Standard
+
+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 orchestration in application use cases, services, or handlers.
+- It keeps transport mapping and request validation in presentation.
+- It keeps concrete integrations in infrastructure.
+- It handles promises, errors, transactions, retries, and mapping boundaries deliberately.
+- It updates wiring, tests, docs, and SDD quality records when the change requires them.
+
+## Completion Contract
+
+Before final response on API work:
+
+1. Run the smallest useful tests first, then broaden if the change crosses layers.
+2. Prefer `pnpm lint` and `pnpm build` for structural changes.
+3. Update `.sdd/active/<FEAT-ID>/5-quality.yaml` when an active feature exists and completion evidence is in scope.
+4. Declare frontend impact with `opensdd sdd frontend-impact <FEAT-ID> ...` when an active feature exists and the feature is being completed.
+5. Update affected docs required by SDD when the task changes architecture or behavior.
+6. Run `opensdd sdd finalize --ref <FEAT-ID>` only when feature completion is actually in scope.
+7. Final handoff must include changed areas, validation commands and results, skipped checks with reasons, SDD exception if any, and residual risks.
+
+Never claim validation passed unless the command actually ran successfully.

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

@@ -0,0 +1,4 @@
+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 OpenSDD, DDD/Clean Architecture, TypeORM, strict import boundaries, evidence-based validation, and safe operational constraints."

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

@@ -0,0 +1,381 @@
+# Application And Presentation
+
+## Application Layer Intent
+
+Application orchestrates use cases. It coordinates domain objects and ports.
+
+Allowed responsibilities:
+
+- Create domain objects.
+- Call repository/output ports.
+- Coordinate services and handlers.
+- Translate application input into domain calls.
+- Manage non-HTTP orchestration.
+- Use Nest DI decorators where existing modules do.
+- Handle application-level authorization or policy checks only when the repository already models them there.
+- Normalize external messages when the normalization is part of application semantics.
+
+Forbidden responsibilities:
+
+- HTTP response shaping.
+- TypeORM queries.
+- ORM entities.
+- class-validator DTOs.
+- Business invariants that belong in domain.
+- Concrete infrastructure adapters.
+- Provider SDK calls, raw credentials, or transport-specific envelopes.
+
+## Canonical Application Layout
+
+For each module:
+
+```text
+src/application/<context>/<module>/
+  ports/in
+  ports/out
+  use-cases
+  services
+  handlers
+  agents
+  tools
+  <module>.application.module.ts
+```
+
+Use `business` for standard API modules and `intelligence` for agent/conversation modules.
+
+## Application Design Rules
+
+- Keep use cases small and orchestration-focused.
+- Let domain objects validate business invariants.
+- Prefer explicit input/output application types when a use case needs a stable contract beyond a domain object.
+- Catch infrastructure-specific errors only in infrastructure, unless the error is represented by a port contract.
+- Handle non-awaited promises with `.catch` and useful logging.
+- Return domain objects or application output types, not presentation DTOs.
+- Keep transactions behind ports or infrastructure abstractions unless a local pattern already defines an application-level unit-of-work port.
+- Do not log secrets, tokens, raw provider payloads, full prompts with sensitive data, or personal data beyond what existing policy allows.
+
+## Input Ports
+
+Input ports expose use cases to presentation or other application modules.
+
+File:
+
+```text
+ports/in/<verb-noun>.use-case.port.ts
+```
+
+Pattern:
+
+```ts
+import type { Example } from '@domain/example/business-objects/example.bo';
+import type { ExampleType } from '@domain/example/types/example.type';
+
+export const CreateExampleUseCasePortSymbol = Symbol('CreateExampleUseCasePortSymbol');
+
+export interface CreateExampleUseCasePort {
+  execute(input: ExampleType.Input): Promise<Example>;
+}
+```
+
+Rules:
+
+- Export a `Symbol`.
+- Export an interface.
+- Use `execute` for use cases.
+- Use type-only imports for domain types.
+- Do not expose presentation validators, ORM entities, provider SDK types, or HTTP request/response types.
+
+## Output Ports
+
+Output ports describe external dependencies needed by application.
+
+File:
+
+```text
+ports/out/<capability>.port.ts
+```
+
+Pattern:
+
+```ts
+export const ExampleProducerPortSymbol = Symbol('ExampleProducerPortSymbol');
+
+export interface ExampleProducerPort {
+  publish(event: ExampleCreatedDomainEvent): Promise<void>;
+}
+```
+
+Rules:
+
+- Application owns the port when the dependency exists to satisfy a use case.
+- Infrastructure implements it.
+- Do not import concrete adapters.
+- Keep contracts provider-neutral unless the integration is intentionally provider-specific and isolated.
+- Represent failures in the contract when the use case needs to make a decision from them.
+
+## Use Cases
+
+File:
+
+```text
+use-cases/<verb-noun>.use-case.ts
+```
+
+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 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';
+import type { ExampleProducerPort } from '@application/business/example/ports/out/example-producer.port';
+
+@Injectable()
+export class CreateExampleUseCase implements CreateExampleUseCasePort {
+  private readonly logger = new Logger(CreateExampleUseCase.name);
+
+  constructor(
+    @Inject(ExampleRepositoryPortSymbol)
+    private readonly repository: ExampleRepositoryPort,
+    @Optional()
+    @Inject(ExampleProducerPortSymbol)
+    private readonly producer?: ExampleProducerPort,
+  ) {}
+
+  async execute(input: ExampleType.Input): Promise<Example> {
+    const example = new Example(input);
+    const saved = await this.repository.save(example);
+
+    if (this.producer) {
+      this.producer.publish(saved.toPersistenceObject()).catch((error) => {
+        this.logger.error('Failed to publish Example event', error);
+      });
+    }
+
+    return saved;
+  }
+}
+```
+
+Rules:
+
+- Keep use cases small and orchestration-focused.
+- Let domain objects validate business invariants.
+- Catch infrastructure-specific errors only in infrastructure, unless the error is represented by a port contract.
+- Handle non-awaited promises with `.catch`.
+- Return domain objects or application output types, not presentation DTOs.
+- Do not call repositories outside their port contract.
+- Do not implement retries, polling, SDK configuration, or transport acknowledgements in use cases.
+
+## Services
+
+File:
+
+```text
+services/<name>.service.ts
+```
+
+Use services for reusable application orchestration that is not a single user action. A service can depend on ports and domain objects. It must not import presentation or concrete infrastructure.
+
+## Handlers
+
+File:
+
+```text
+handlers/<name>.handler.ts
+```
+
+Use handlers for application-level event or message processing. Keep queue polling, ack, retry, and DLQ in infrastructure. Keep message normalization and use-case invocation in application when the normalization is part of application semantics.
+
+## Agents And Tools
+
+Under intelligence modules, use:
+
+```text
+agents
+tools
+```
+
+The canonical generic runtime is:
+
+```text
+src/application/intelligence/common/agent-runtime
+```
+
+Do not add new runtime ownership to `src/shared/agent` or `src/application/intelligence/agents`.
+
+Rules:
+
+- Agent orchestration belongs in application; provider calls and credentials belong in infrastructure.
+- Tool interfaces should be explicit, typed, and provider-neutral where practical.
+- Tools must enforce application/domain constraints instead of bypassing use cases.
+- Do not expose raw prompts, internal chain data, provider credentials, or internal lifecycle payloads to presentation.
+- Tool calls that mutate data or trigger external side effects must have clear input contracts and tests.
+- Log failures without leaking sensitive payloads.
+
+## Application Modules
+
+File:
+
+```text
+src/application/<context>/<module>/<module>.application.module.ts
+```
+
+Pattern:
+
+```ts
+import { Module } from '@nestjs/common';
+import { CreateExampleUseCase } from '@application/business/example/use-cases/create-example.use-case';
+import { CreateExampleUseCasePortSymbol } from '@application/business/example/ports/in/create-example.use-case.port';
+
+@Module({
+  providers: [{ provide: CreateExampleUseCasePortSymbol, useClass: CreateExampleUseCase }],
+  exports: [CreateExampleUseCasePortSymbol],
+})
+export class ExampleApplicationModule {}
+```
+
+Also wire the module in `src/application/application.module.ts` when it is part of the public application graph.
+
+## Presentation Layer Intent
+
+Presentation handles transport:
+
+- REST controllers.
+- GraphQL resolvers/types.
+- CLI commands.
+- WebSocket gateways/dtos.
+- Guards and decorators.
+- Presentation validators and Swagger docs.
+
+Presentation must be thin. It maps request input to application input and returns output.
+
+Presentation must not become a backdoor for business rules, infrastructure access, provider calls, or internal payload exposure.
+
+## REST Controllers
+
+Rules:
+
+- One controller class per file.
+- One public route method per controller, usually `handle`.
+- Inject application input port through its symbol.
+- Extend `GenericController<Port>` when matching existing REST patterns.
+- Generate transport-only values such as request UUIDs here when existing pattern does so.
+- Do not call repositories, TypeORM, AWS SDK, queues, LLM providers, vector stores, or domain validators directly.
+- Do not return raw domain internals, provider responses, internal lifecycle payloads, or sensitive data.
+- Keep error mapping aligned with existing exception filters and controller patterns.
+
+Pattern:
+
+```ts
+import { Body, Controller, Post } from '@nestjs/common';
+import { ApiCreatedResponse, ApiOperation, ApiTags } from '@nestjs/swagger';
+import { randomUUID } from 'crypto';
+import { Inject } from '@nestjs/common';
+import { CreateExampleUseCasePortSymbol } from '@application/business/example/ports/in/create-example.use-case.port';
+import type { CreateExampleUseCasePort } from '@application/business/example/ports/in/create-example.use-case.port';
+import { GenericController } from '@presentation/generic-controller';
+import { CreateExamplePresentationValidator } from '@presentation/rest/example/presentation-validators/create-example.presentation-validator';
+
+@ApiTags('Examples')
+@Controller('examples')
+export class CreateExampleController extends GenericController<CreateExampleUseCasePort> {
+  constructor(@Inject(CreateExampleUseCasePortSymbol) useCase: CreateExampleUseCasePort) {
+    super(useCase);
+  }
+
+  @Post()
+  @ApiOperation({ summary: 'Criar example' })
+  @ApiCreatedResponse({ description: 'Example criado com sucesso' })
+  async handle(@Body() validator: CreateExamplePresentationValidator) {
+    const example = await this.useCase.execute({
+      id: randomUUID(),
+      name: validator.name,
+    });
+
+    return example.value;
+  }
+}
+```
+
+## Presentation Validators
+
+File:
+
+```text
+presentation-validators/<verb-noun>.presentation-validator.ts
+```
+
+Use `class-validator` and Swagger decorators for request shape. Do not encode business-only rules here.
+
+Pattern:
+
+```ts
+import { ApiProperty } from '@nestjs/swagger';
+import { IsString, Length } from 'class-validator';
+
+export class CreateExamplePresentationValidator {
+  @ApiProperty({
+    description: 'Nome do example',
+    example: 'Example A',
+    minLength: 2,
+    maxLength: 120,
+  })
+  @IsString()
+  @Length(2, 120)
+  name!: string;
+}
+```
+
+Rules:
+
+- Validate transport shape only.
+- Keep business invariants in domain.
+- Do not import domain BOs or TypeORM entities into validators.
+- Do not expose secret defaults or internal provider configuration in Swagger examples.
+
+## REST Modules
+
+File:
+
+```text
+src/presentation/rest/<module>/<module>.module.ts
+```
+
+Pattern:
+
+```ts
+import { Module } from '@nestjs/common';
+import { ApplicationModule } from '@application/application.module';
+import { CreateExampleController } from '@presentation/rest/example/controllers/create-example.controller';
+
+@Module({
+  imports: [ApplicationModule],
+  controllers: [CreateExampleController],
+})
+export class ExampleModule {}
+```
+
+Wire into `src/presentation/rest/rest.presentation.module.ts` if the REST module is new.
+
+## GraphQL, CLI, And WebSocket
+
+Follow existing folders:
+
+```text
+src/presentation/graphql/<module>
+src/presentation/cli/<module>
+src/presentation/websocket
+```
+
+Rules:
+
+- Keep resolvers/commands/gateways thin.
+- Inject application ports.
+- Keep transport DTOs separate from domain types.
+- Guards remain presentation concerns.
+- Do not bypass application use cases to call infrastructure directly.
+- Validate and sanitize external input before mapping to application input.