@devtrack-solution/codesdd 1.2.3 → 1.2.4

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

@@ -1,13 +1,13 @@
 ---
 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, CodeSDD, strict import boundaries, layered modules under domain, application, presentation, infrastructure, and shared, plus safe operational practices, evidence-based validation, and quality handoff.
+description: Compatibility skill for CodeSDD API profiles derived from DevTrack Foundation API. Use the named profiles minimal-rest, rest-auth-rbac, rest-crud-typeorm, evented-api, ai-agent-api, or full-foundation-compatible for NestJS TypeScript backend work using TypeORM, Foundation boundaries, Swagger/OpenAPI, .env.example, package scripts, route guards, auth/authz planning, and evidence-based validation.
 ---
 
-# DevTrack API
+# CodeSDD API Profiles
 
 ## Mission
 
-Use this skill as the local architecture, quality, safety, and delivery contract for `devtrack-foundation-api` and compatible derived APIs.
+Use this compatibility skill as the local architecture, quality, safety, and delivery contract for CodeSDD API profiles derived from `devtrack-foundation-api`.
 
 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.
 
@@ -18,6 +18,7 @@ These rules apply to any assistant, automation host, IDE agent, command-line cod
 - 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.
+- Treat the minimum operational API baseline as an explicit requirement for API/scaffold work. Use Foundation evidence to infer OpenAPI docs, `.env.example`, package scripts, use cases, route guards, and auth/authz planning unless the user explicitly limits the work to a prototype, docs-only review, or a recorded exception profile.
 - 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 CodeSDD feature when one exists.
 - Preserve user changes in a dirty worktree. Never overwrite unrelated modifications.
@@ -26,12 +27,15 @@ 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
 
 Repository files are the source for implementation facts. CodeSDD is the source for operational planning, progress, dependencies, blockers, quality, and handoff.
 
-When CodeSDD is governing a project and the user asks for API or backend work without explicitly selecting another skill/profile, `devtrack-api` is the default API skill. Explicit Python/Flask/LangGraph API work uses the dedicated Python skill/profile instead.
+When CodeSDD is governing a project and the user asks for API or backend work without explicitly selecting another skill/profile, choose a CodeSDD API profile from the profile family below. `devtrack-api` remains the compatibility skill id and legacy alias, not the preferred public profile name for new API requests. Explicit Python/Flask/LangGraph API work uses the dedicated Python skill/profile instead.
 
 Before edits in the API repository:
 
@@ -60,37 +64,108 @@ 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.
+- Always read [contract-pack.yaml](references/contract-pack.yaml) before planning, approving, or executing a CodeSDD API profile project, debate, EPIC, or FEAT. It is the machine-readable contract pack for API profile ids, compatibility alias behavior, 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 [generated-artifact-invalidation.md](references/generated-artifact-invalidation.md) before reusing, approving, grandfathering, or citing generated previews, scaffold dry-runs, caches, artifact maps, validator results, or evidence bundles created before the active Foundation-compatible gates.
 - 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.
 - Use [implementation-checklist.md](references/implementation-checklist.md) as the final pass checklist.
 
+## CodeSDD API Profile Family
+
+New API/backend requests should name one of these public profile ids:
+
+- `minimal-rest`: smallest production-grade REST API baseline with Swagger/OpenAPI, `.env.example`, package scripts, DTOs, use cases, structured errors, health/root wiring, and route/use-case tests.
+- `rest-auth-rbac`: REST API with authentication and authorization planning, JWT strategy, route guards, permission decorators, authenticated-user request boundary, protected Swagger/OpenAPI bearer docs, and allow/deny route tests.
+- `rest-crud-typeorm`: REST CRUD API with BO-pattern domain artifact, application repository port, transactional use cases, TypeORM entity/repository/mapper in infrastructure, migration scripts, pagination/filtering, uniqueness checks, and CRUD persistence tests.
+- `evented-api`: API with application event contracts for BO-pattern contexts, application handlers, event publisher ports, queue delivery adapters, idempotency boundaries, retry/error policy, event contract docs, and event tests.
+- `ai-agent-api`: API for AI agent workflows with endpoint DTOs, application use-case ports, provider/tool/audit ports, prompt safety policy, redaction service, redacted provider configuration, audit adapters, deterministic tests, and no live credentials.
+- `full-foundation-compatible`: strict full compatibility with `devtrack-foundation-api` architecture and conventions.
+
+The legacy `devtrack-api` request/profile name is compatibility-only and resolves to `full-foundation-compatible` with a migration notice. Do not expose `devtrack-api` as the normal public identity for future API projects.
+
 ## Contract Pack And Derivation Profiles
 
-The structured contract lives in [contract-pack.yaml](references/contract-pack.yaml). Treat it as the executable policy source that future CodeSDD gates can import. The Markdown skill explains the rules; the YAML contract names the profiles, severities, rule ids, drift map, and evidence expectations.
+The structured contract lives in [contract-pack.yaml](references/contract-pack.yaml). Treat it as the executable policy source that future CodeSDD gates can import. The Markdown skill explains the rules; the YAML contract names the CodeSDD API profile ids, compatibility aliases, derivation profiles, severities, rule ids, drift map, and evidence expectations.
 
-Every `devtrack-api` plan must select exactly one profile before implementation:
+Every CodeSDD API profile plan must also select exactly one derivation governance profile before implementation:
 
 - `prototype`: exploratory only. It cannot be reported as Foundation-compatible unless a later FEAT upgrades and validates it.
 - `foundation-compatible`: default for derived DevTrack APIs. P0 drift blocks finalize; P1 drift requires remediation or formal exception.
 - `enterprise-strict`: audit-grade mode. P0 and P1 drift block finalize; P2 drift requires evidence or ADR-backed exception.
 
-For the first two or three DEBs of a new `devtrack-api` project or major API theme, CodeSDD must generate a package-structure preview and ask the human planner to approve or correct it before FEAT execution. Missing profile selection, missing preview, missing human validation, or declarative-only skill evidence are contract defects.
+For the first two or three DEBs of a new CodeSDD API profile project or major API theme, CodeSDD must generate a package-structure preview and ask the human planner to approve or correct it before FEAT execution. Missing API profile selection, missing derivation profile selection, missing preview, missing human validation, or declarative-only skill evidence are contract defects.
 
 The `codesdd-validate` field failure is mapped in the contract pack under `codesdd_validate_drift_map`. Future planning, validator, finalize, provenance, and field-validation FEATs must consume that map instead of reinterpreting the failure from memory.
 
+Generated previews, dry-runs, caches, artifact maps, validator results, and evidence bundles created before the EPIC-0080 gates are noncanonical by default. Use `generated-artifact-invalidation.md` to classify each as `revalidated`, `invalidated`, `grandfathered`, or `not_applicable`; do not treat legacy generated output as Foundation-compatible unless the active contract revalidates it.
+
+## CodeSDD Artifact Frontmatter Baseline
+
+When generating, filling, reviewing, or copying CodeSDD governance artifacts for API work, keep YAML frontmatter schema-compatible before handing control back to `codesdd` commands. Do not rely on the consumer project to repair malformed governance files.
+
+For DEB artifacts, `decision.mediator.accepted_risks` must be an array of objects, never an array of strings:
+
+```yaml
+decision:
+  mediator:
+    accepted_risks:
+      - risk: "Local JWT authentication requires tested hashing, refresh token rotation, and expiry policy."
+        mitigation: "Cover register, login, refresh, logout, expired token, invalid token, and inactive user cases before finalize."
+```
+
+If the source material only provides a free-text risk, preserve it as `risk` and add an explicit `mitigation` field such as the required test, follow-up FEAT, ADR exception, rollback condition, or human validation gate. A DEB that cannot pass `codesdd sdd decide <DEB-ID> --outcome epic` is not ready for EPIC promotion.
+
+## Tool-Level API Baseline
+
+When a user asks CodeSDD for an API, backend tool, scaffold, CRUD slice, or new REST capability governed by a CodeSDD API profile, the agent must infer the minimum API baseline even when the user does not spell it out. This is not arbitrary invention; it is the default tool contract derived from Foundation and must be implemented or explicitly excepted before handoff.
+
+Minimum root package baseline:
+
+- `package.json` with Foundation-compatible scripts for build, start, development start, production start, lint, unit tests, coverage, e2e tests, cleanup, cleanup:install, and migrations when persistent schema changes are present.
+- `scripts/cleanup.sh` that removes dependency installs, build outputs, caches, lockfiles, and TypeScript compilation residue unless an ADR preserves a canonical lockfile for the target project.
+- `scripts/kill-port.js` invoked by both `start` and `start:dev` before Nest starts; it must resolve the configured port from a script argument or `PORT`/`APP_PORT`, terminate the current listener, and continue bootstrap.
+- Generated scripts must work through both `npm run ...` and `pnpm run ...`; nested package-script composition uses `npm run` and `npm install` so Docker images do not need pnpm unless the target records an ADR-backed opt-in.
+- `.env.example` for every environment variable introduced by the change. Use placeholders only; never copy real `.env` values.
+- `tsconfig.json` alias map, Nest CLI configuration, lint/test configuration, and validation commands aligned to local package evidence.
+- `src/main.ts` bootstrap with global validation and OpenAPI wiring when the project exposes REST.
+
+Minimum API documentation baseline:
+
+- Install and wire `@nestjs/swagger` when missing and the selected profile is not a documented prototype exception.
+- Configure `DocumentBuilder`, `SwaggerModule.createDocument`, and `SwaggerModule.setup("docs", app, document)` at bootstrap.
+- Include local/prod Swagger server settings such as `SWAGGER_SERVER_LOCAL` and optional `SWAGGER_SERVER_PROD` through typed configuration.
+- Decorate controllers with `@ApiTags`, `@ApiOperation`, response decorators, and `@ApiBearerAuth("bearer")` when protected by bearer auth.
+- Decorate transport DTOs and presentation validators with `@ApiProperty` or `@ApiPropertyOptional`; Swagger examples must not expose secrets or internal provider payloads.
+
+Minimum application slice baseline:
+
+- Every user-facing route maps to an application input port and a use case in `src/application/business/<context>/ports/in/` and `src/application/business/<context>/use-cases/`.
+- Controllers inject the input port symbol and do transport mapping only.
+- Controllers must not call repositories, TypeORM, infrastructure adapters, domain validators, or services as a substitute for a use case.
+
+Minimum auth/authz planning baseline:
+
+- During planning, ask whether the API requires authentication and authorization.
+- Capture the expected mechanism: JWT bearer, API key, session, machine-to-machine credential, public route, role, permission, policy, tenancy, and docs visibility.
+- If the user does not answer and implementation must proceed, choose the safest local default: protect non-health, non-login, non-registration, non-public write routes with the existing guard pattern, record the assumption, and ask for confirmation in the handoff.
+- Route guards and auth decorators live in presentation transport folders such as `src/presentation/rest/<context>/guards/` and `src/presentation/rest/<context>/decorators/`. Application-layer policy checks belong in use cases or application services when the policy is business/application behavior.
+- Public routes must be explicitly marked in the plan and documentation; silence is not a public-route decision.
+
+Prototype exceptions are allowed only when the selected derivation profile permits warning-only handling. Even then, record the omitted baseline items as follow-up work and do not claim Foundation compatibility.
+
 ## 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.
+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.
@@ -125,6 +200,8 @@ src/domain/<context>/types/<name>.type.ts
 src/domain/<context>/constants/<name>.const.ts           (optional)
 ```
 
+New aggregate BO classes follow this shape: `extends GenericBusinessObject<T>` and `implements <Name>Interface, IValidator`, in that order. The observed `src/domain/auth/business-objects/api-keys.bo.ts` static utility is a named Foundation exception and must not become the model for new aggregate BO files.
+
 **Domain (entity-pattern — legacy `pessoas` and `wallets` only)**
 
 ```text
@@ -180,11 +257,16 @@ 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
 ```
 
 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.
 
+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`.
+
+The ORM subsystem uses `src/infrastructure/adapters/orm/typeorm.module.ts` as the root TypeORM module and `src/infrastructure/adapters/orm/<context>-orm.module.ts` for context repository providers. Context ORM modules import `TypeOrmModule.forFeature([...])`, provide concrete `*.typeorm-repository.ts` adapters, bind the owning port symbol with `useExisting`, and export the port symbols required by application/domain ports.
+
 **Presentation (segmented by transport before context)**
 
 ```text
@@ -206,7 +288,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. TypeORM root wiring is exactly `typeorm.module.ts`; context persistence modules end with `-orm.module.ts`.
 
 ## Forbidden Patterns
 
@@ -216,6 +298,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/<entity>-orm.module.ts` — context modules are allowed, entity-specific modules are not; use `<context>-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/`.
@@ -230,6 +313,9 @@ When producing an implementation plan (the "Arquivo NestJS | Ação" table insid
 1. For each proposed path, match it against Canonical Paths. If it does not match, replace it with the canonical equivalent or flag it as an explicit architectural divergence requiring ADR.
 2. For each new domain context, declare the chosen pattern (BO or entity) and justify the choice. The default is BO; declaring entity for a new context requires citing the ADR.
 3. Cross-check against [foundation-layout.md](references/foundation-layout.md). Skill compliance is verifiable: every path either exists as a pattern in Foundation or is forbidden.
+4. For each public route, name the application input port and use case that owns the action.
+5. For each route, record the auth/authz decision: guard, decorator, role/permission/policy, public exception, and Swagger security documentation.
+6. For each new API project or scaffold, include the root package baseline: `.env.example`, package scripts, OpenAPI bootstrap, validation commands, and typed runtime configuration.
 
 A plan that fails this gate corrupts the downstream FEAT execution and the discovery quality ledger. Fix the plan before merging the debate.
 
@@ -247,7 +333,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,10 @@
+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.
+  - For new API work, select minimal-rest, rest-auth-rbac, rest-crud-typeorm, evented-api, ai-agent-api, or full-foundation-compatible; devtrack-api is compatibility-only.
+  - For API scaffold or route work, apply the tool-level baseline for Swagger, .env.example, cleanup/cleanup:install, port-safe start/start:dev scripts, use cases, and auth/authz planning.

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

@@ -0,0 +1,10 @@
+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.
+  - For new API work, select minimal-rest, rest-auth-rbac, rest-crud-typeorm, evented-api, ai-agent-api, or full-foundation-compatible; devtrack-api is compatibility-only.
+  - For API scaffold or route work, apply the tool-level baseline for Swagger, .env.example, cleanup/cleanup:install, port-safe start/start:dev scripts, use cases, and auth/authz planning.

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

@@ -0,0 +1,10 @@
+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.
+  - For new API work, select minimal-rest, rest-auth-rbac, rest-crud-typeorm, evented-api, ai-agent-api, or full-foundation-compatible; devtrack-api is compatibility-only.
+  - For API scaffold or route work, apply the tool-level baseline for Swagger, .env.example, cleanup/cleanup:install, port-safe start/start:dev scripts, use cases, and auth/authz planning.

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

@@ -0,0 +1,10 @@
+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.
+  - For new API work, select minimal-rest, rest-auth-rbac, rest-crud-typeorm, evented-api, ai-agent-api, or full-foundation-compatible; devtrack-api is compatibility-only.
+  - For API scaffold or route work, apply the tool-level baseline for Swagger, .env.example, cleanup/cleanup:install, port-safe start/start:dev scripts, use cases, and auth/authz planning.

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

@@ -0,0 +1,10 @@
+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.
+  - For new API work, select minimal-rest, rest-auth-rbac, rest-crud-typeorm, evented-api, ai-agent-api, or full-foundation-compatible; devtrack-api is compatibility-only.
+  - For API scaffold or route work, apply the tool-level baseline for Swagger, .env.example, cleanup/cleanup:install, port-safe start/start:dev scripts, use cases, and auth/authz planning.

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."
+  display_name: "CodeSDD API Profiles"
+  short_description: "Governed CodeSDD API profile guidance with DevTrack Foundation fidelity."
+  default_prompt: "Use the CodeSDD API profile family to implement, review, refactor, test, or document NestJS API work. Select minimal-rest, rest-auth-rbac, rest-crud-typeorm, evented-api, ai-agent-api, or full-foundation-compatible; treat devtrack-api as a compatibility-only skill id. Preserve TypeORM, strict imports, Swagger/OpenAPI, .env.example, package scripts with cleanup/cleanup:install and port-safe start/start:dev bootstrap, application use cases, route guards, auth/authz planning, and validation evidence."
+policy:
+  allow_implicit_invocation: true

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

@@ -0,0 +1,12 @@
+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.
+  - For new API work, select minimal-rest, rest-auth-rbac, rest-crud-typeorm, evented-api, ai-agent-api, or full-foundation-compatible; devtrack-api is compatibility-only.
+  - For API scaffold or route work, apply the tool-level baseline for Swagger, .env.example, cleanup/cleanup:install, port-safe start/start:dev scripts, use cases, and auth/authz planning.

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

@@ -54,6 +54,12 @@ Use `business` for standard API modules and `intelligence` for agent/conversatio
 - 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.
 
+## Use-Case Requirement For API Slices
+
+Every REST, GraphQL, CLI, WebSocket, agent, or tool entrypoint that represents a user/system action must call an application input port backed by a use case. A route without `src/application/business/<context>/ports/in/<verb-noun>.use-case.port.ts` and `src/application/business/<context>/use-cases/<verb-noun>.use-case.ts` is incomplete for Foundation-compatible work.
+
+Controllers and other transports do transport mapping only. They must not call repositories, TypeORM, infrastructure adapters, domain validators, or application services as a shortcut around a use case. If a route is operationally read-only, health-only, or intentionally public, record that exception in the plan and still keep business behavior in application.
+
 ## Input Ports
 
 Input ports expose use cases to presentation or other application modules.
@@ -126,8 +132,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';
@@ -255,6 +261,50 @@ Presentation must be thin. It maps request input to application input and return
 
 Presentation must not become a backdoor for business rules, infrastructure access, provider calls, or internal payload exposure.
 
+## API Documentation And Auth Planning
+
+OpenAPI/Swagger is part of the minimum API baseline for REST APIs. A derived API or scaffold that exposes REST should include the root bootstrap and route-level decorators unless an explicit prototype exception records the omission.
+
+Root bootstrap requirements:
+
+```ts
+import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
+
+const docBuilder = new DocumentBuilder()
+  .setTitle('<api title>')
+  .setDescription('<api description>')
+  .setVersion('1.0')
+  .addServer(appConfig.swagger.serverLocal, 'Local Development')
+  .addBearerAuth(
+    {
+      type: 'http',
+      scheme: 'bearer',
+      bearerFormat: 'JWT',
+      name: 'JWT',
+      in: 'header',
+    },
+    'bearer',
+  );
+
+if (appConfig.swagger.serverProd) {
+  docBuilder.addServer(appConfig.swagger.serverProd, 'Production');
+}
+
+const document = SwaggerModule.createDocument(app, docBuilder.build());
+SwaggerModule.setup('docs', app, document);
+```
+
+The corresponding runtime configuration must expose documented placeholders in `.env.example`, including `SWAGGER_SERVER_LOCAL` and optional `SWAGGER_SERVER_PROD` when production docs are configured.
+
+Before implementing routes, the plan must ask or record:
+
+- Is authentication required? If yes, which mechanism: JWT bearer, API key, session, machine-to-machine credential, or another Foundation-compatible guard?
+- Is authorization required? If yes, which role, permission, policy, ownership, or tenancy rule applies?
+- Which routes are intentionally public, and how are those public exceptions documented?
+- Should Swagger show bearer security (`@ApiBearerAuth("bearer")`) or another documented security scheme?
+
+When the answer is unknown and work must continue, protect non-health, non-login, non-registration, non-public write routes with the existing guard pattern and record the assumption.
+
 ## REST Controllers
 
 Rules:
@@ -267,20 +317,25 @@ Rules:
 - 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.
+- Document every route with `@ApiTags`, `@ApiOperation`, and response decorators such as `@ApiCreatedResponse`, `@ApiOkResponse`, `@ApiBadRequestResponse`, or `@ApiUnauthorizedResponse`.
+- Use `@ApiBearerAuth("bearer")` and `@UseGuards(JwtAuthGuard)` or the applicable guard/decorator for protected routes.
+- Permission, role, tenancy, or ownership checks must be explicit through presentation guards/decorators and/or application policy use cases. Do not leave auth/authz implicit.
+- Public routes must be explicitly marked in the plan and docs.
 
 Pattern:
 
 ```ts
-import { Body, Controller, Post } from '@nestjs/common';
-import { ApiCreatedResponse, ApiOperation, ApiTags } from '@nestjs/swagger';
+import { Body, Controller, Inject, Post, UseGuards } from '@nestjs/common';
+import { ApiBearerAuth, 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 { JwtAuthGuard } from '@presentation/rest/auth/guards/jwt-auth.guard';
 import { CreateExamplePresentationValidator } from '@presentation/rest/example/presentation-validators/create-example.presentation-validator';
 
 @ApiTags('Examples')
+@ApiBearerAuth('bearer')
 @Controller('examples')
 export class CreateExampleController extends GenericController<CreateExampleUseCasePort> {
   constructor(@Inject(CreateExampleUseCasePortSymbol) useCase: CreateExampleUseCasePort) {
@@ -288,6 +343,7 @@ export class CreateExampleController extends GenericController<CreateExampleUseC
   }
 
   @Post()
+  @UseGuards(JwtAuthGuard)
   @ApiOperation({ summary: 'Criar example' })
   @ApiCreatedResponse({ description: 'Example criado com sucesso' })
   async handle(@Body() validator: CreateExamplePresentationValidator) {

package/.sdd/skills/curated/devtrack-api/references/consumer-sync-policy.md

@@ -7,8 +7,8 @@ This policy governs every copy of `.sdd/skills/curated/devtrack-api/` that CodeS
 It covers:
 
 - `SKILL.md`
-- `agents/openai.yaml`
-- all files under `references/`, including `contract-pack.yaml`
+- all files under `agents/`, including Codex, OpenAI, Claude Code, Cursor, Gemini, Kimi, OpenCode, and any generic markdown/CLI adapter materialized by the contract pack;
+- all files under `references/`, including `contract-pack.yaml`, `field-validation-protocol.md`, and `generated-artifact-invalidation.md`.
 
 It does not make CodeSDD the canonical backend implementation source. `devtrack-foundation-api` remains the backend architecture ground truth; CodeSDD owns the skill distribution and consumer materialization contract.
 
@@ -86,8 +86,20 @@ If a consumer copy needs an urgent local correction:
 
 A consumer copy is current only when:
 
-- `SKILL.md`, `agents/openai.yaml`, and every `references/*.md` file match the intended CodeSDD source commit or release;
+- `SKILL.md`, every `agents/*` adapter, and every `references/*.md` file match the intended CodeSDD source commit or release;
 - `references/contract-pack.yaml` matches the intended CodeSDD source commit or release;
 - the consumer FEAT quality or handoff records source version, update command, and diff result;
 - no durable edits exist only in the consumer copy;
 - any Foundation-driven guidance change passed the CodeSDD Foundation-layout conformance test first.
+
+## FEAT-0378 Consumer Evidence Sync Rule
+
+For FEAT-0378, CodeSDD records only summary references for consumer-owned field evidence:
+
+- consumer-held debates remain in the consumer repository quality ledger or handoff;
+- CodeSDD may store opaque references to at least two approved consumer evidence owners;
+- D-01 through D-08 closure may be represented here only as `closed`, `not_applicable`, or `accepted_exception`;
+- `accepted_exception` rows must point to `ADR-FEAT-0378` or a consumer-owned ADR/decision;
+- unresolved opaque references block consumer-local adoption claims, but do not require copying private ledgers into this repository.
+
+This keeps the distribution contract auditable while preserving the one-way materialization boundary: CodeSDD owns the reusable `devtrack-api` skill and protocol, and the consumer project owns its private implementation evidence.