@devtrack-solution/codesdd 1.2.2 → 1.2.3

package/.sdd/skills/curated/devtrack-api/references/contract-pack.yaml

@@ -0,0 +1,317 @@
+schema_version: 1
+contract_id: devtrack-api-contract-pack
+skill_id: devtrack-api
+contract_version: 1
+status: active
+authority:
+  codesdd_source: .sdd/skills/curated/devtrack-api/
+  foundation_source: devtrack-foundation-api/src/
+  source_priority:
+    - devtrack-foundation-api source tree
+    - .sdd/skills/curated/devtrack-api/references/foundation-layout.md
+    - .sdd/skills/curated/devtrack-api/SKILL.md
+    - this contract pack
+  consumer_rule: Consumer copies are one-way CodeSDD materializations and must not become upstream sources of truth.
+derivation_profiles:
+  prototype:
+    default: false
+    purpose: Explore functionality quickly without claiming Foundation compatibility.
+    allowed_only_with: Explicit DEB or ADR exception before implementation.
+    enforcement:
+      path_conformance: warn
+      semantic_conformance: warn
+      finalize_blocking: false
+    required_evidence:
+      - chosen profile and reason
+      - accepted architectural risks
+      - follow-up path for foundation-compatible validation when needed
+  foundation-compatible:
+    default: true
+    purpose: Produce a derived API that follows Foundation physical layout, NestJS module boundaries, ports, TypeORM runtime, and validation expectations.
+    allowed_only_with: No exception required.
+    enforcement:
+      path_conformance: block_on_p0
+      semantic_conformance: block_on_p0
+      finalize_blocking: true
+    required_evidence:
+      - package structure preview approved by human planner
+      - policy pool generated from this skill
+      - skill provenance and sync evidence
+      - semantic architecture validation result
+  enterprise-strict:
+    default: false
+    purpose: Produce a consumer API with audit-grade evidence, no unresolved P0/P1 drift, and formal exception handling for every accepted divergence.
+    allowed_only_with: Human approval in DEB or ADR before FEAT execution.
+    enforcement:
+      path_conformance: block_on_p0_p1
+      semantic_conformance: block_on_p0_p1
+      finalize_blocking: true
+    required_evidence:
+      - all foundation-compatible evidence
+      - no open P0 or P1 drift
+      - ADR-backed exception for every accepted P2 drift
+      - field-validation packet plan
+severity_model:
+  P0:
+    meaning: Must not be finalized for foundation-compatible or enterprise-strict work.
+    required_action: Block execution or finalize unless a profile explicitly permits warning-only handling.
+  P1:
+    meaning: High-risk drift that may compromise Foundation fidelity or enterprise audit evidence.
+    required_action: Block in enterprise-strict; require formal exception or remediation in foundation-compatible.
+  P2:
+    meaning: Lower-risk drift, documentation gap, or profile-specific variance.
+    required_action: Record evidence, exception, or follow-up before closure.
+rules:
+  - id: DTAPI-P0-PROFILE-001
+    severity: P0
+    title: Derivation profile must be explicit before implementation.
+    applies_to:
+      - DEB
+      - EPIC
+      - FEAT
+    detect:
+      - missing profile among prototype, foundation-compatible, enterprise-strict
+    required_response:
+      - ask the human planner to approve the profile
+      - record profile in the debate, FEAT workspace, or policy pool
+  - id: DTAPI-P0-PREVIEW-001
+    severity: P0
+    title: Early devtrack-api planning must include package structure preview.
+    applies_to:
+      - DEB
+      - FEAT
+    detect:
+      - first two or three devtrack-api debates lack a package tree preview
+      - package tree is not explicitly human-approved
+    required_response:
+      - generate package structure preview
+      - request human approval before FEAT execution
+  - id: DTAPI-P0-PATH-001
+    severity: P0
+    title: Proposed paths must match canonical Foundation-compatible paths.
+    applies_to:
+      - DEB
+      - FEAT
+      - source
+    detect:
+      - forbidden paths from SKILL.md or foundation-layout.md
+      - new domain entities folder outside approved legacy contexts
+      - context-owned infrastructure adapters
+      - transport-less presentation context folders
+    required_response:
+      - replace with canonical path
+      - or record ADR-backed divergence before execution
+  - id: DTAPI-P0-IMPORTS-001
+    severity: P0
+    title: Source and tests must use Foundation-compatible path aliases instead of relative imports.
+    applies_to:
+      - DEB
+      - FEAT
+      - source
+      - validator
+    detect:
+      - missing tsconfig baseUrl or paths for @domain, @application, @presentation, @infrastructure, @shared, or @src
+      - relative imports inside src or tests, including same-folder relative imports
+      - import aliases diverging from devtrack-foundation-api without ADR
+    required_response:
+      - add or repair the Foundation alias map before implementation/finalize
+      - replace relative imports with canonical aliases
+      - or record ADR-backed divergence before execution
+  - id: DTAPI-P0-TYPEORM-001
+    severity: P0
+    title: TypeORM-named repositories must use real TypeORM runtime wiring.
+    applies_to:
+      - source
+      - validator
+    detect:
+      - files ending in .typeorm-repository.ts without InjectRepository or Repository usage
+      - in-memory Map persistence inside TypeORM-named repositories
+      - missing TypeOrmModule.forFeature wiring for concrete ORM repositories
+    required_response:
+      - implement real TypeORM repository wiring
+      - rename prototype adapters so they do not claim TypeORM compatibility
+      - or downgrade to prototype with explicit exception
+  - id: DTAPI-P0-COMPOSITION-001
+    severity: P0
+    title: Presentation modules must not become composition roots for application and infrastructure.
+    applies_to:
+      - source
+      - validator
+    detect:
+      - presentation imports concrete infrastructure adapters
+      - presentation module instantiates repositories, adapters, services, or use cases directly
+      - dependency injection tokens owned by presentation for application ports
+    required_response:
+      - move provider ownership to application or infrastructure modules
+      - keep presentation importing application boundaries only
+  - id: DTAPI-P0-MODULES-001
+    severity: P0
+    title: Aggregate application, infrastructure, and presentation modules are mandatory for compatible APIs.
+    applies_to:
+      - source
+      - validator
+    detect:
+      - missing src/application/application.module.ts
+      - missing src/infrastructure/infrastructure.module.ts
+      - missing src/presentation/presentation.module.ts or transport aggregate module
+      - module-named files that export constants instead of NestJS modules
+    required_response:
+      - add or correct aggregate modules before finalization
+  - id: DTAPI-P0-PORTS-001
+    severity: P0
+    title: Ports must have correct ownership and explicit symbols.
+    applies_to:
+      - source
+      - validator
+    detect:
+      - input use-case ports without exported Symbol (e.g., RegisterUseCasePort missing RegisterUseCasePortSymbol)
+      - output ports without exported Symbol
+      - multiple unrelated use-case ports grouped into one file
+      - BO-pattern repository ports placed in domain repository-ports folders
+    required_response:
+      - split ports by use case or output contract
+      - export Symbol plus interface for both input and output ports
+      - wire providers through the owning module
+  - id: DTAPI-P1-DOMAIN-001
+    severity: P1
+    title: New domain contexts must follow BO and VO contracts.
+    applies_to:
+      - source
+      - validator
+    detect:
+      - new contexts using entity-pattern without ADR
+      - BO classes missing the expected Foundation business-object shape
+      - VO classes missing normalize, isValid, getValue, toString, or equals when applicable
+    required_response:
+      - align to BO-pattern
+      - record ADR for entity-pattern divergence
+  - id: DTAPI-P1-RUNTIME-001
+    severity: P1
+    title: Persistence runtime artifacts must exist when an API claims operational TypeORM compatibility.
+    applies_to:
+      - source
+      - validator
+    detect:
+      - missing DataSource or TypeORM root config
+      - missing migrations for new persistent tables
+      - missing database indexes or uniqueness rules required by the domain contract
+    required_response:
+      - add runtime config and migrations
+      - or explicitly select prototype profile
+  - id: DTAPI-P1-APPONLY-001
+    severity: P1
+    title: Application-only contexts (no domain counterpart) require ADR justification.
+    applies_to:
+      - source
+      - validator
+      - DEB
+    detect:
+      - src/application/business/<context>/ exists without src/domain/<context>/
+      - new application-only context introduced without ADR in .sdd/core/adrs/
+      - application-only context not enumerated in foundation-layout.md §2.1.1
+    required_response:
+      - record ADR naming the orchestration responsibility and why no domain artifacts are introduced
+      - update foundation-layout.md §2.1.1 with the new entry
+      - confirm the context is composition, adaptation, or coordination only — not new business invariants
+    grandfathered:
+      - aws-integrations
+      - foundation
+  - id: DTAPI-P1-EVIDENCE-001
+    severity: P1
+    title: Skill evidence must prove semantic conformance, not only skill usage.
+    applies_to:
+      - FEAT
+      - quality
+    detect:
+      - skill_evidence only states that devtrack-api shaped the work
+      - no policy result, package preview, or semantic validation evidence is attached
+    required_response:
+      - record applied policy id, profile, validation result, and exception status
+  - id: DTAPI-P2-LANGUAGE-001
+    severity: P2
+    title: Bounded-context language and naming must be explicit.
+    applies_to:
+      - DEB
+      - FEAT
+      - source
+    detect:
+      - mixed Portuguese and English context naming without rationale
+      - new context name diverges from Foundation naming convention without decision
+    required_response:
+      - record naming rationale
+      - align context names before implementation when possible
+codesdd_validate_drift_map:
+  CVD-01:
+    observed: Functional API and passing tests did not prove Foundation fidelity.
+    mapped_rules:
+      - DTAPI-P0-PROFILE-001
+      - DTAPI-P1-EVIDENCE-001
+  CVD-02:
+    observed: Path and suffix checks were weaker than semantic checks.
+    mapped_rules:
+      - DTAPI-P0-PATH-001
+      - DTAPI-P0-IMPORTS-001
+      - DTAPI-P0-TYPEORM-001
+      - DTAPI-P0-COMPOSITION-001
+  CVD-03:
+    observed: TypeORM repository names masked in-memory Map implementations.
+    mapped_rules:
+      - DTAPI-P0-TYPEORM-001
+      - DTAPI-P1-RUNTIME-001
+  CVD-04:
+    observed: Presentation REST module acted as application and infrastructure composition root.
+    mapped_rules:
+      - DTAPI-P0-COMPOSITION-001
+      - DTAPI-P0-MODULES-001
+  CVD-05:
+    observed: Ports were grouped and lacked symbols.
+    mapped_rules:
+      - DTAPI-P0-PORTS-001
+  CVD-06:
+    observed: BO and VO classes were useful but not Foundation-compatible enough.
+    mapped_rules:
+      - DTAPI-P1-DOMAIN-001
+  CVD-07:
+    observed: Runtime persistence artifacts such as DataSource, migrations, and TypeORM module wiring were absent.
+    mapped_rules:
+      - DTAPI-P1-RUNTIME-001
+  CVD-08:
+    observed: Skill evidence was declarative, not executable.
+    mapped_rules:
+      - DTAPI-P1-EVIDENCE-001
+  CVD-09:
+    observed: Application-only contexts (e.g., aws-integrations, foundation) existed in src/application/business without domain counterparts and without explicit governance, producing false-positive drift in path validators.
+    mapped_rules:
+      - DTAPI-P1-APPONLY-001
+      - DTAPI-P0-PATH-001
+field_evidence_drift_map:
+  WCA-01:
+    observed: A derived API planned/implemented before devtrack-api became required evidence, then required a later corrective FEAT.
+    mapped_rules:
+      - DTAPI-P0-PROFILE-001
+      - DTAPI-P1-EVIDENCE-001
+  WCA-02:
+    observed: A derived API used relative imports and lacked Foundation-compatible tsconfig alias paths.
+    mapped_rules:
+      - DTAPI-P0-IMPORTS-001
+  WCA-03:
+    observed: A derived API used TypeORM repositories without the Foundation auth module idiom of TypeOrmModule.forFeature and InjectRepository where applicable.
+    mapped_rules:
+      - DTAPI-P0-TYPEORM-001
+      - DTAPI-P1-RUNTIME-001
+early_debate_gate:
+  applies_to: first two or three DEBs that plan a new devtrack-api project or major API theme
+  required_outputs:
+    - selected derivation profile
+    - package structure preview
+    - human approval or correction
+    - exception list with ADR refs when applicable
+    - policy pool seed derived from this contract pack
+future_consumers:
+  - FEAT-0233 package preview gate
+  - FEAT-0234 project-local skill policy pool
+  - FEAT-0235 active FEAT workspace policy injection
+  - FEAT-0236 semantic architecture validator
+  - FEAT-0237 finalize lifecycle gate
+  - FEAT-0238 skill provenance and applied-policy evidence
+  - FEAT-0239 future field validation protocol

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

@@ -0,0 +1,95 @@
+# devtrack-api Field Validation Protocol
+
+## Scope
+
+This protocol defines the minimum field evidence required before CodeSDD treats the reformed `devtrack-api` skill as proven in a real consumer project.
+
+Field evidence belongs in the consumer project's own CodeSDD quality ledger or handoff. CodeSDD may keep the protocol, a summary, and an external reference, but it must not copy private consumer artifacts into this repository.
+
+## Minimum Validation Target
+
+A valid field-validation packet must cover:
+
+- at least one derived consumer project using the reformed `devtrack-api` skill;
+- at least two consumer `DEB-*` artifacts with detailed implementation plan tables;
+- the CodeSDD commit or release that supplied the consumer skill copy;
+- the Foundation checkout path, commit, or release used as architectural evidence when available;
+- sync evidence from [consumer-sync-policy.md](consumer-sync-policy.md);
+- selected derivation profile and applied policy evidence from [contract-pack.yaml](contract-pack.yaml);
+- a divergence matrix showing D-01 through D-08 closed for each validated debate.
+
+## Divergence Classes
+
+| Class | Field check | Closed when |
+| --- | --- | --- |
+| D-01 | New non-legacy domain contexts avoid `entities/` and use `business-objects/*.bo.ts`. | The debate maps each new BO-pattern context to `src/domain/<context>/business-objects/<name>.bo.ts`, or cites an ADR for entity-pattern divergence. |
+| D-02 | Domain exceptions are not invented per context. | The debate uses `src/shared/domain/exceptions/` or records an ADR-backed exception. |
+| D-03 | Value objects use the `.vo.ts` suffix. | The debate uses `<name>.vo.ts` and contains no `.value-object.ts` plan entries. |
+| D-04 | TypeORM persistence stays under centralized `src/infrastructure/adapters/orm/`. | Entities use `*.orm-entity.ts`, repositories use the ORM repository folder, and no `src/infrastructure/<context>/persistence/typeorm/` path remains. |
+| D-05 | Infrastructure repositories use explicit TypeORM repository names. | Concrete repositories use `<name>.typeorm-repository.ts`; ambiguous `<name>.repository.ts` entries are absent or justified by ADR. |
+| D-06 | BO-pattern repository ports live in application `ports/out/`. | New BO-pattern contexts do not add `domain/<context>/repository-ports/`; application outbound ports are listed instead. |
+| D-07 | Presentation is segmented by transport before context. | REST plans use `src/presentation/rest/<context>/...` or another explicit transport folder. |
+| D-08 | Infrastructure adapters are organized by subsystem, not business context. | Plans use `src/infrastructure/adapters/<subsystem>/...`; no `src/infrastructure/<context>/adapters/` entries remain. |
+
+## Required Consumer Evidence
+
+For each validated consumer debate, record:
+
+1. consumer project id and repository reference;
+2. debate id and title;
+3. whether the debate was created or revised after the reformed `devtrack-api` skill was synchronized;
+4. path inventory or implementation table location;
+5. D-01 through D-08 status, using only `closed`, `not_applicable`, or `accepted_exception`;
+6. ADR reference for every `accepted_exception`;
+7. validation commands and outcomes from the consumer project, including `codesdd sdd check --render`, `codesdd sdd diagnose`, and relevant backend tests/build commands;
+8. quality-ledger or handoff reference where the evidence lives.
+
+Do not mark field validation complete when any D-class is `open`, undocumented, or only verbally accepted.
+
+## Consumer Packet Template
+
+```yaml
+devtrack_api_field_validation:
+  protocol: devtrack-api-field-validation-v1
+  consumer_project: "<project-id>"
+  consumer_repo_ref: "<path-or-remote-ref>"
+  codesdd_source_ref: "<commit-or-release>"
+  foundation_source_ref: "<path-commit-or-release>"
+  sync_evidence_ref: "<consumer-quality-or-handoff-ref>"
+  debates:
+    - debate_ref: "DEB-####"
+      title: "<debate title>"
+      plan_table_ref: "<file#section-or-line>"
+      statuses:
+        D-01: closed
+        D-02: closed
+        D-03: closed
+        D-04: closed
+        D-05: closed
+        D-06: closed
+        D-07: closed
+        D-08: closed
+      accepted_exception_refs: []
+      validation_commands:
+        - command: "codesdd sdd check --render"
+          result: "pass"
+        - command: "codesdd sdd diagnose"
+          result: "pass"
+      applied_contract:
+        contract_pack_ref: "references/contract-pack.yaml"
+        profile: "foundation-compatible"
+        open_policy_findings: []
+```
+
+## CodeSDD Closure Rule
+
+CodeSDD may close the field-validation expectation only when:
+
+- the consumer packet references at least two detailed debates;
+- all D-01 through D-08 rows are `closed`, `not_applicable`, or `accepted_exception`;
+- every accepted exception has an ADR or explicit consumer SDD decision;
+- the consumer packet records sync-policy evidence;
+- the consumer packet records the selected derivation profile and applied contract-pack evidence;
+- 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.