@devtrack-solution/codesdd 1.2.2 → 1.2.3

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

@@ -0,0 +1,295 @@
+# Foundation Layout — Canonical Ground Truth
+
+This reference is the **authoritative physical layout** of `devtrack-foundation-api`. It is the ground truth that every implementation plan, debate, ADR, and code change for the Foundation or any derived API must respect. The skill's "Canonical Paths" and "Forbidden Patterns" sections in `SKILL.md` are summaries of this document; when they conflict (they should not), this document wins.
+
+This is not a style guide. It is an inventory of what Foundation actually does, derived from `/Volumes/WORKSPACE/DEVTRACK_TOOLS/devtrack-foundation-api/src/`. When you propose a path that diverges from this layout, you are proposing to fork the contract — which requires an explicit ADR, not a guess.
+
+## How To Use This Reference
+
+- Load it before producing **any** debate, plan, or code change that introduces new files.
+- For every proposed path, perform a literal lookup in the tables below. If the pattern is not present, the path is forbidden.
+- For every new domain context, decide BO-pattern vs. entity-pattern using the rule in section 2 before drafting the plan.
+- For every ADR that introduces a deliberate divergence from this layout, record the deviation, the justification, and the migration path back to the canonical layout (if any).
+
+## 1. Top-Level Tree
+
+```text
+src/
+├── application/
+│   └── business/<context>/
+├── domain/
+│   ├── <context>/                     (per business context)
+│   └── ...
+├── infrastructure/
+│   ├── adapters/<subsystem>/          (centralized by subsystem)
+│   ├── settings/
+│   └── infrastructure.module.ts
+├── presentation/
+│   └── <transport>/<context>/         (transport before context)
+├── shared/
+│   ├── domain/
+│   ├── infrastructure/
+│   ├── presentation/
+│   └── agent/
+├── app.module.ts
+├── main.ts
+└── schema.gql
+```
+
+## 2. Domain — Two Coexisting Patterns
+
+Domain contexts use exactly one of two patterns. There is no third pattern. The choice is observable from the physical folder layout in `src/domain/<context>/`.
+
+### 2.1 BO-pattern (canonical default for new contexts)
+
+Folders allowed:
+
+```text
+src/domain/<context>/business-objects/<name>.bo.ts
+src/domain/<context>/value-objects/<name>.vo.ts          (optional, present only when context defines its own VOs)
+src/domain/<context>/types/<name>.type.ts
+src/domain/<context>/constants/<name>.const.ts           (optional)
+```
+
+Folders forbidden in BO-pattern:
+
+- `entities/` — would conflate the pattern with legacy entity-pattern.
+- `repository-ports/` — repository ports for BO-pattern live in **application** (`ports/out/`).
+- `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).
+
+Contexts currently using BO-pattern in Foundation:
+
+| Context | Path | Notes |
+|---|---|---|
+| `auth` | `src/domain/auth/` | `business-objects/auth-user.bo.ts`, `business-objects/api-keys.bo.ts`, `types/`. **No** `entities/`, **no** `repository-ports/`. |
+| `files` | `src/domain/files/` | `business-objects/`, `types/`. |
+| `integrations` | `src/domain/integrations/` | `business-objects/`, `types/`. |
+| `intelligence` | `src/domain/intelligence/` | `business-objects/`, `value-objects/`, `types/`. The only BO-pattern context with its own `value-objects/`. **Status:** the domain folder is currently a BO/VO shell — the active intelligence runtime lives in `src/application/intelligence/*` (`conversation`, `course-agents`, `report-chat`) and does not import the domain shell. Keep the shell as an expansion-ready surface; do not delete, but do not assume runtime coupling. |
+| `knowledge` | `src/domain/knowledge/` | `business-objects/`, `types/`. |
+| `notifications` | `src/domain/notifications/` | `constants/`, `types/`. No BO yet, but follows BO-pattern shape. |
+
+### 2.2 Entity-pattern (legacy — extension only)
+
+Folders allowed:
+
+```text
+src/domain/<context>/entities/<name>.entity.ts
+src/domain/<context>/repository-ports/<name>-repository.port.ts
+src/domain/<context>/validators/<name>.validator.ts
+src/domain/<context>/events/<name>-<event>.event.ts      (optional)
+src/domain/<context>/types/<name>.type.ts
+```
+
+Contexts currently using entity-pattern in Foundation:
+
+| Context | Path | Notes |
+|---|---|---|
+| `pessoas` | `src/domain/pessoas/` | Full entity-pattern: `entities/pessoa.entity.ts`, `repository-ports/pessoa-repository.port.ts`, `validators/`, `events/pessoa-created.event.ts`, `types/`. |
+| `wallets` | `src/domain/wallets/` | `entities/wallet.entity.ts`, `repository-ports/wallet-repository.port.ts`, `validators/`, `types/`. No `events/`. |
+
+The legacy set is closed. Do not add new contexts to it without an ADR.
+
+### 2.3 Application-only contexts (no domain counterpart)
+
+Foundation also ships application contexts that legitimately have **no
+`src/domain/<context>/` counterpart** because their work is composition,
+adaptation, or coordination — not new business invariants. The currently
+allowed application-only contexts are:
+
+| Application path | Reason no domain |
+|---|---|
+| `src/application/business/aws-integrations/` | Orchestrates AWS adapter wiring across infrastructure subsystems; the invariants live in the AWS adapters themselves under `src/infrastructure/adapters/aws/*`. |
+| `src/application/business/foundation/` | Composition root for Foundation-wide use-cases shared by other contexts; does not introduce its own bounded-context vocabulary. |
+
+Adding a new application-only context is **not free**: it requires an ADR
+that names the orchestration responsibility and explains why no domain
+artifacts are introduced. The validator rule covering this case is
+`DTAPI-P1-APPONLY-001` (see [contract-pack.yaml](contract-pack.yaml)).
+
+### 2.4 Decision Rule (summary)
+
+- New domain context → BO-pattern. Always.
+- Extending `pessoas` or `wallets` → entity-pattern. Match what is already there.
+- New application context without domain artifacts → forbidden unless ADR-justified per `DTAPI-P1-APPONLY-001`.
+- Anything else → forbidden until an ADR justifies the deviation.
+
+## 3. Shared Domain (Centralized Primitives)
+
+`src/shared/domain/` holds primitives reused across contexts. Never duplicate these per-context.
+
+```text
+src/shared/domain/exceptions/business-validation.exception.ts
+src/shared/domain/exceptions/entity-not-found.exception.ts
+src/shared/domain/exceptions/duplicate-entity.exception.ts
+src/shared/domain/value-objects/email.vo.ts
+src/shared/domain/value-objects/telefone.vo.ts
+src/shared/domain/validators/...
+src/shared/domain/types/...
+src/shared/domain/generic-business-object.ts
+src/shared/domain/generic.validator.ts
+```
+
+The alias `@domain/*` resolves to **both** `src/domain/*` and `src/shared/domain/*` (tsconfig `paths`). That is why `import { BusinessValidationException } from '@domain/exceptions/business-validation.exception'` works even though the file physically lives under `src/shared/domain/exceptions/`. Do not interpret this as a license to create `src/domain/<context>/exceptions/` — the resolution is convenience, not permission.
+
+**Domain exceptions are centralized in `src/shared/domain/exceptions/`. Period.** Context-specific exception names (`InvalidCredentialsException`, `TokenExpiredException`) belong nowhere in domain; if you need such precision, throw `BusinessValidationException` with a context-specific message payload, or model the failure as a return type from the use case.
+
+## 4. Application
+
+```text
+src/application/business/<context>/use-cases/<verb-noun>.use-case.ts
+src/application/business/<context>/ports/in/<verb-noun>.use-case.port.ts
+src/application/business/<context>/ports/out/<name>.port.ts
+src/application/business/<context>/ports/out/<name>-repository.port.ts        (BO-pattern only)
+src/application/business/<context>/services/<name>.service.ts
+src/application/business/<context>/handlers/<name>.handler.ts
+src/application/business/<context>/<context>.application.module.ts
+```
+
+Repository ports for BO-pattern contexts live here, not in domain. Example: `src/application/business/auth/ports/out/user-repository.port.ts`, `api-key-repository.port.ts`, `role-repository.port.ts`.
+
+Service ports (collaborator interfaces that are not repositories) also live in `ports/out/`. Example: `password-hash.service.port.ts`, `access-control.service.port.ts`, `api-key.service.port.ts`.
+
+Use case ports (entry points to the application from presentation) live in `ports/in/`. One port per use case.
+
+### 4.1 Intelligence Modules
+
+Foundation also has application-layer intelligence modules. They are canonical application modules, not an exception to the layer model.
+
+```text
+src/application/intelligence/<context>/use-cases/<verb-noun>.use-case.ts
+src/application/intelligence/<context>/ports/in/<verb-noun>.use-case.port.ts
+src/application/intelligence/<context>/ports/out/<name>.port.ts
+src/application/intelligence/<context>/services/<name>.service.ts
+src/application/intelligence/<context>/handlers/<name>.handler.ts
+src/application/intelligence/<context>/agents/<name>.agent.ts
+src/application/intelligence/<context>/tools/<name>.tool.ts
+src/application/intelligence/common/agent-runtime/<name>.ts
+```
+
+Observed intelligence contexts in Foundation: `common`, `conversation`, `course-agents`, `report-chat`.
+
+Provider-specific SDKs, credentials, retries, and transport details stay in infrastructure adapters. Intelligence application code owns provider-neutral ports, use cases, tool orchestration, and conversation semantics.
+
+## 5. Infrastructure (Centralized by Subsystem)
+
+Infrastructure is segmented by **subsystem**, never by business context. A subsystem is a category of external concern (persistence, cache, queue, AWS, LLM, etc.), independent of which business contexts use it.
+
+```text
+src/infrastructure/adapters/<subsystem>/<name>.adapter.ts
+src/infrastructure/adapters/<subsystem>/<subsystem>.module.ts
+```
+
+Observed subsystems in Foundation (closed set; new subsystems require ADR):
+
+| Subsystem | Path | Purpose |
+|---|---|---|
+| `auth` | `src/infrastructure/adapters/auth/` | JWT, password hashing, API key signing. |
+| `aws` | `src/infrastructure/adapters/aws/` | S3, Cognito, SES, SNS, SQS clients. |
+| `cache` | `src/infrastructure/adapters/cache/` | Redis cache adapters. |
+| `configuration` | `src/infrastructure/adapters/configuration/` | Settings loaders. |
+| `http` | `src/infrastructure/adapters/http/` | Outbound HTTP clients. |
+| `llm` | `src/infrastructure/adapters/llm/` | LLM provider adapters. |
+| `orm` | `src/infrastructure/adapters/orm/` | TypeORM entities, repositories, mappers, migrations. |
+| `queue` | `src/infrastructure/adapters/queue/` | Queue producers/consumers. |
+| `redis` | `src/infrastructure/adapters/redis/` | Redis raw client. |
+| `sync-engine` | `src/infrastructure/adapters/sync-engine/` | Sync orchestration adapter. |
+| `temporal` | `src/infrastructure/adapters/temporal/` | Temporal workflow adapter. |
+| `vector-store` | `src/infrastructure/adapters/vector-store/` | Vector DB adapters. |
+
+### 5.1 TypeORM (subsystem `orm`)
+
+Fixed sub-layout — no variation tolerated:
+
+```text
+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/<context>-orm.module.ts
+src/infrastructure/adapters/orm/typeorm.config.ts
+src/infrastructure/adapters/orm/typeorm-cli.datasource.ts
+src/infrastructure/adapters/orm/typeorm.module.ts
+```
+
+The `<context>-orm.module.ts` files (e.g., `auth-orm.module.ts`, `pessoas-orm.module.ts`, `wallets-orm.module.ts`, `sync-engine-orm.module.ts`) wire per-context TypeORM artifacts inside the centralized `orm/` folder. Do **not** create `src/infrastructure/<context>/persistence/typeorm/`.
+
+### 5.2 Adapter ports (shared)
+
+Ports for shared adapters live in `src/shared/infrastructure/adapter/<subsystem>/<name>.port.ts`. Example: `src/shared/infrastructure/adapter/auth/jwt.port.ts`. The alias `@infrastructure/adapter/*` resolves to both `src/shared/infrastructure/adapter/*` and `src/infrastructure/adapters/*`.
+
+## 6. Presentation (Transport Before Context)
+
+```text
+src/presentation/<transport>/<context>/controllers/<verb-noun>.controller.ts
+src/presentation/<transport>/<context>/dtos/<verb-noun>.dto.ts
+src/presentation/<transport>/<context>/presentation-validators/<verb-noun>.presentation-validator.ts
+src/presentation/<transport>/<context>/guards/<name>.guard.ts
+src/presentation/<transport>/<context>/decorators/<name>.decorator.ts
+src/presentation/<transport>/<context>/<context>.module.ts
+```
+
+Observed transports in the current Foundation tree: `rest/`, `graphql/`, `cli/`, `websocket/`. `agent/` follows the same transport-before-context shape when a derived API explicitly introduces that transport.
+
+REST `dtos/` are Foundation-compatible presentation contracts. Keep DTOs thin and transport-scoped; validation, mapping, and use case orchestration must remain in presentation validators and application.
+
+**Never** `src/presentation/<context>/` without a transport segment. Even if a context is REST-only today, the path must be `src/presentation/rest/<context>/` to preserve room for future transports.
+
+## 7. Shared Infrastructure And Presentation
+
+```text
+src/shared/infrastructure/<subsystem>/...
+src/shared/infrastructure/adapter/<subsystem>/<name>.port.ts
+src/shared/presentation/filters/<name>.filter.ts
+src/shared/presentation/interceptors/<name>.interceptor.ts
+src/shared/presentation/pipes/<name>.pipe.ts
+```
+
+## 8. TSConfig Aliases (Path Resolution)
+
+From `devtrack-foundation-api/tsconfig.json`:
+
+| Alias | Resolves to (in order) |
+|---|---|
+| `@application/business/notifications/ports/out/*` | `src/application/business/notifications/ports/out/*` |
+| `@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/presentation.module` | `src/presentation/presentation.module` |
+| `@src/application.module` | `src/application/application.module` |
+| `@src/*` | `src/*` |
+| `@tests/*` | `tests/*` |
+
+Aliases are mandatory in `src/` and tests. Same-folder relative imports are forbidden.
+
+## 9. Forbidden Patterns (Quick Reference)
+
+| Forbidden | Canonical Replacement |
+|---|---|
+| `src/domain/<context>/exceptions/` | `src/shared/domain/exceptions/` |
+| `<name>.schema.ts` (TypeORM) | `<name>.orm-entity.ts` |
+| `<name>.value-object.ts` | `<name>.vo.ts` |
+| `<name>.repository.ts` | `<name>.typeorm-repository.ts` (infrastructure) or `<name>-repository.port.ts` (port) |
+| `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/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` |
+| `events/` in BO-pattern domain context | emit from application handlers |
+| Custom domain exception class per context | `BusinessValidationException` from `shared/domain/exceptions` with payload |
+
+## 10. Compliance Verification
+
+For any debate or plan that proposes new files:
+
+1. For each proposed path, perform a literal substring lookup against the patterns in sections 2–6.
+2. If no pattern matches, the path is **non-canonical** and must either:
+   - be rewritten to match a canonical pattern, or
+   - be accompanied by an ADR justifying the deviation, the migration cost, and the planned re-alignment.
+3. If a new subsystem, transport, or domain context is proposed, list it explicitly in the debate's ADR section.
+
+The skill `devtrack-api` is the contract; this reference is the contract's evidence. Drift between this document and `devtrack-foundation-api/src/` is a defect in this document — submit a correction insight before relying on the divergent state.

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

@@ -3,13 +3,13 @@
 ## Before Editing
 
 - Read nearest `AGENTS.md` and `AGENT.md`.
-- Run `opensdd sdd onboard system`.
-- Run `opensdd sdd next`.
-- Run `opensdd sdd context <FEAT-ID>` if a feature id is available.
+- Run `codesdd sdd onboard system`.
+- Run `codesdd sdd next`.
+- Run `codesdd sdd context <FEAT-ID>` if a feature id is available.
 - Check `git status --short`.
 - Inspect nearby files before creating new patterns.
 - Identify user changes in the dirty worktree and avoid overwriting them.
-- If SDD has no ready feature and work proceeds because the user explicitly requested it, state that exception in the final handoff and create an OpenSDD insight/feature only when durable follow-up is required.
+- If SDD has no ready feature and work proceeds because the user explicitly requested it, state that exception in the final handoff and create an CodeSDD insight/feature only when durable follow-up is required.
 - Do not persist planning, backlog, workflow status, project memory, scratchpad, or handoff in external context stores.
 
 ## Task Understanding

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

@@ -23,13 +23,17 @@ Do not claim these commands passed unless they were executed successfully.
 Use aliases from `tsconfig.json`:
 
 ```text
+@application/business/notifications/ports/out/* -> src/application/business/notifications/ports/out/*
 @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/presentation.module   -> src/presentation/presentation.module
+@src/application.module    -> src/application/application.module
 @src/*                     -> src/*
+@tests/*                   -> tests/*
 ```
 
 The lint rule `no-relative-import-paths/no-relative-import-paths` forbids relative imports in `src`, with `allowSameFolder: false`.

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

@@ -133,7 +133,7 @@ When an active SDD feature exists and the task is feature completion:
 2. Declare frontend impact:
 
 ```bash
-opensdd sdd frontend-impact <FEAT-ID> ...
+codesdd sdd frontend-impact <FEAT-ID> ...
 ```
 
 3. Update affected docs when behavior or architecture changes:
@@ -149,7 +149,7 @@ AGENT.md
 4. Finalize:
 
 ```bash
-opensdd sdd finalize --ref <FEAT-ID>
+codesdd 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.

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024-2026 OpenSDD Contributors
+Copyright (c) 2024-2026 CodeSDD Contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal