@devtrack-solution/codesdd 1.2.4-rc3 → 1.2.4

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

@@ -198,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.
@@ -207,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`
 

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,12 +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/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
 ```
 
-The ORM subsystem has one Nest module only: `src/infrastructure/adapters/orm/orm.module.ts`. It registers TypeORM entities, concrete `*.typeorm-repository.ts` providers, mapper dependencies when needed, and exports the repository providers/tokens required by application ports. Do **not** create per-context or per-entity modules such as `auth-orm.module.ts`, `pessoas-orm.module.ts`, `wallets-orm.module.ts`, or `sync-engine-orm.module.ts`. Do **not** create `src/infrastructure/<context>/persistence/typeorm/`.
+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)
 
@@ -275,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, the single `orm.module.ts`, 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

@@ -1,12 +1,13 @@
 # Portable Agent Contract
 
-Use this reference when adapting `devtrack-api` for Codex, Claude Code, Cursor, Gemini, Kimi, OpenCode, or any markdown/CLI coding agent.
+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 trigger surface; keep `name: devtrack-api` and a direct description of NestJS, TypeORM, DDD, Clean Architecture, CodeSDD, and Foundation-compatible API work.
+- 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`.
@@ -30,7 +31,7 @@ Use this reference when adapting `devtrack-api` for Codex, Claude Code, Cursor,
 Every agent must leave enough evidence for another agent to continue:
 
 - files changed and why;
-- selected derivation profile from `contract-pack.yaml`;
+- 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;

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,11 +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/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
 ```
 
+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:
@@ -180,7 +183,7 @@ Rules:
 - Do not leak `Repository`, `QueryRunner`, `DataSource`, or ORM entities through ports.
 - Keep transaction ownership explicit and aligned with existing repository/unit-of-work patterns.
 
-## ORM Module
+## ORM Modules
 
 Pattern:
 
@@ -203,10 +206,10 @@ import { ExampleTypeOrmRepository } from '@infrastructure/adapters/orm/repositor
   ],
   exports: [ExampleRepositoryPortSymbol],
 })
-export class OrmModule {}
+export class ExampleOrmModule {}
 ```
 
-The ORM subsystem must have one Nest module only: `src/infrastructure/adapters/orm/orm.module.ts`. Do not create `*-orm.module.ts` files per entity, context, or feature. Add every new `*.typeorm-repository.ts` provider to this module and export the repository provider and/or its application port token from this module.
+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
 
@@ -214,7 +217,8 @@ 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/orm.module.ts`
+- `src/infrastructure/adapters/orm/typeorm.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.