@ankhorage/devtools 1.14.3 → 1.14.5

package/dist/tools/agents/index.d.ts

@@ -2,5 +2,6 @@ export declare const agentsManagedFiles: readonly [{
     readonly relativePath: "AGENTS.md";
     readonly render: typeof renderAgentsFile;
 }];
+/*** Render mandatory repository instructions from the target package identity. */
 declare function renderAgentsFile(targetDirectory: string): Promise<string>;
 export {};

package/dist/tools/agents/index.js

@@ -6,6 +6,7 @@ export const agentsManagedFiles = [
         render: renderAgentsFile,
     },
 ];
+/*** Render mandatory repository instructions from the target package identity. */
 async function renderAgentsFile(targetDirectory) {
     const manifest = await readPackageManifest(targetDirectory);
     const packageName = readNonEmptyString(manifest.name) ?? 'Package name not declared';
@@ -33,11 +34,25 @@ published public APIs and declared dependencies, never sibling source files.
 Current-runtime error handling and canonical database or infrastructure migrations remain valid
 when they support states that the current architecture can intentionally produce.
 
-## Project structure
+## Required repository instructions
 
-For directory ownership, package boundaries, architectural profiles, ports and adapters, public
-entrypoints, or cross-repository structural work, load and follow
-\`.agents/skills/ankhorage-project-structure/SKILL.md\`.
+Before changing any file, read this \`AGENTS.md\` completely and inspect \`.agents/skills/\`.
+For every change, load and follow both baseline repository skills before making changes:
+
+1. \`.agents/skills/ankhorage-coding-rules/SKILL.md\`
+2. \`.agents/skills/ankhorage-project-structure/SKILL.md\`
+
+Load and follow every additional repository-local skill relevant to the task, including skills
+required by either baseline skill. Continue to follow these instructions and skills through
+validation and delivery; do not substitute remembered, globally installed, or generic guidance for
+the repository-local versions.
+
+## Documentation
+
+\`README.md\` and the \`paradox/\` documentation tree are generated by \`@ankhorage/paradox\`.
+Never edit generated documentation directly. Update the owning Paradox \`/*** ... */\` comments in
+\`src\`, including \`@readme\` tags where the content belongs in the README, then run \`bun docs\`
+and commit the regenerated artifacts.
 
 ## Pull requests
 

package/dist/tools/skills/assets/ankhorage-coding-rules/SKILL.md

@@ -38,8 +38,10 @@ exceptions or replaced by generic preferences from this skill.
   validation pass.
 - Resolve size, complexity, and related findings around cohesive responsibilities and clear data
   flow. Do not split a function or file mechanically just to cross a threshold.
-- Prefer reusable pure transformations, immutable values, and explicit inputs and outputs. Keep
-  unavoidable mutation and external side effects at clear boundaries.
+- Use functional programming by default: declare bindings with `const`, not `let`; write pure
+  functions with explicit inputs and outputs; and use immutable data and updates. Keep side effects
+  explicit and at system boundaries. Mutation or reassignment is allowed only for a clearly
+  justified boundary or demonstrated performance-critical path, and must remain locally contained.
 - Keep one canonical implementation. Do not add compatibility aliases, dual paths, historical-state
   fallbacks, or sibling-source imports.
 

package/dist/tools/skills/assets/ankhorage-project-structure/SKILL.md

@@ -1,41 +1,45 @@
 ---
 name: ankhorage-project-structure
 description: >
-  Define, review, or implement the standard source structure of Ankhorage repositories. Use for
-  feature ownership, CLI layout, hexagonal boundaries, source-module naming, type ownership,
-  utilities, or package entrypoints.
+  Define, review, or implement the standard source structure of Ankhorage repositories. Use for feature ownership, CLI layout, hexagonal boundaries, source-module naming, Contracts ownership, type ownership, utilities, or package entrypoints.
 ---
 
 # Ankhorage Project Structure
 
-Every Ankhorage repository follows this structure. It applies now to `ankhorage/studio`,
-`ankhorage/deploy`, `ankhorage/infra`, `ankhorage/repository`, and `ankhorage/navigator`.
+## Applicability
 
-## Required skills
+This skill applies to every Ankhorage repository.
 
-Before structural work, read the repository `AGENTS.md`, inspect its source tree and public
-exports, then load both required repository skills:
+### Contracts repository profile
 
-1. `.agents/skills/ankhorage-coding-rules/SKILL.md`
-2. [Hexagonal Architecture](../hexagonal-architecture/SKILL.md)
+If the current repository is `ankhorage/contracts`, apply only this profile:
 
-If `ankhorage-coding-rules` is missing or unreadable, stop immediately and report exactly:
+- The repository may contain only portable, serializable contracts expressed as interfaces and
+  types. Every field must be serializable and reconstructable without executable behavior or
+  repository-local runtime objects. Do not add call signatures, function-valued properties,
+  functions, classes, constants, enums, mutable state, adapters, framework objects, or
+  implementation helpers.
+- A contract belongs in this repository only when it is required across multiple repositories. A
+  current or coordinated change MUST identify at least two consuming repositories. Keep
+  single-repository types with their owning repository; anticipated reuse alone is not sufficient.
+- Consumers import contracts through published public subpaths and declared dependencies, never
+  sibling source files or duplicated local declarations.
 
-```
-Cannot continue: the required repository skill `ankhorage-coding-rules` is missing or unreadable at `.agents/skills/ankhorage-coding-rules/SKILL.md`. Synchronize the repository skills from `@ankhorage/devtools` and retry.
-```
+After enforcing this profile, stop before the remaining source-layout, implementation, utility,
+and migration rules; they do not apply to `ankhorage/contracts`.
 
-If `hexagonal-architecture` is missing or unreadable, stop immediately and report exactly:
+## Required skills
 
-```
-Cannot continue: the required repository skill `hexagonal-architecture` is missing or unreadable at `.agents/skills/hexagonal-architecture/SKILL.md`. Synchronize the repository skills from `@ankhorage/devtools` and retry.
-```
+Before structural work outside `ankhorage/contracts`, read the repository `AGENTS.md`, inspect its
+source tree and public exports, then load the required Hexagonal Architecture skill from the
+repository root. Do not resolve it relative to this skill's own installation location:
+
+1. `<repo-root>/.agents/skills/hexagonal-architecture/SKILL.md`
 
-## Repository-root examples
+## Required source layout
 
-`examples/` is a generally valid repository-root folder in every repository covered by this skill.
-Use it for complete, intentional, user-facing examples that people can inspect, copy, install, and
-run independently of a monorepo or internal fixture layout.
+- `examples/`: Repository-root folder in this standalone repository;
+  Use it for complete, intentional, user-facing examples that people can inspect, copy, install, and run independently of a monorepo or internal fixture layout.
 
 Each example lives in a named subdirectory, such as `examples/basic-usage/*.ts`. Do not put example
 source files directly under `examples/`.
@@ -43,17 +47,29 @@ source files directly under `examples/`.
 Test-only fixtures remain owned by the applicable test structure. Do not relabel fixtures as public
 examples merely to bypass repository structure rules.
 
-## Required source layout
+- `src/cli/` must exist or have a concrete issue tracking the missing CLI commands;
+  CLI modules are thin inbound adapters: they parse input, invoke a feature use case, and render
+  output.
 
-Every repository provides `src/features/`. It lists the repository's actual product capabilities;
-technical categories are not features. Each feature owns its own hexagonal structure as needed,
-following the required Hexagonal Architecture skill. Do not create empty layers.
+The filesystem below `src/cli/commands/` mirrors the public command path after the package prefix:
+
+```text
+ankh <package> <segment> ... <command>
+  -> src/cli/commands/<segment>/.../<command>.ts
+```
+
+The package prefix is represented by the provider and is not repeated under `commands/`. Flags and
+positional arguments do not affect this directory tree. Each command file follows the one-export
+rule: `commands/projects/list.ts` exports `list` and owns only the command-specific input/output
+mapping.
 
-Every repository provides `src/cli/`, or has a concrete issue tracking the missing CLI commands.
-CLI modules are thin inbound adapters: they parse input, invoke a feature use case, and render
-output.
+- `src/features/`: Lists the repository's actual product capabilities;
+  Technical categories are not features. Each feature owns its own hexagonal structure as needed,
+  following the required Hexagonal Architecture skill. Do not create empty layers.
 
 ```text
+examples/
+  <example>/
 src/
   cli/
     createCliProvider.ts
@@ -73,42 +89,33 @@ src/
         inbound/
         outbound/
       composition/
+      constants/
+        <topic>.ts
       utils/
   types/
     <topic>.ts
-  constants.ts
+  constants/
+    <topic>.ts
   utils/
 ```
 
 Keep only deliberate package facades directly under `src/`. Public package subpaths must name their
 explicit module in `package.json`; generic `index.ts` barrels are not public API exceptions.
 
-The filesystem below `src/cli/commands/` mirrors the public command path after the package prefix:
-
-```text
-ankh <package> <segment> ... <command>
-  -> src/cli/commands/<segment>/.../<command>.ts
-```
-
-The package prefix is represented by the provider and is not repeated under `commands/`. Flags and
-positional arguments do not affect this directory tree. Each command file follows the one-export
-rule: `commands/projects/list.ts` exports `list` and owns only the command-specific input/output
-mapping.
-
-## Feature taxonomy
+## General Taxonomy
 
 Siblings always represent the same kind of entity. A folder cannot be an unrelated catch-all beside
-peer entities. For example, this is invalid because `otherFolder` is not a color:
+peer entities. For example, this is invalid because `other/` is not a color:
 
 ```text
 colors/
   red/
   green/
   blue/
-  otherFolder/
+  other/
 ```
 
-Resolve the ownership of `otherFolder` and move it to the appropriate taxonomy. Use domain names for
+Resolve the ownership of `other` and move it to the appropriate taxonomy. Use domain names for
 features, not framework, transport, database, or generic technical names.
 
 ## Implementation modules
@@ -121,8 +128,7 @@ convenience barrels and must not expose private implementation details.
 
 - `myFunction.ts` exports `myFunction`.
 - `myFunctionAsync.ts` exports `myFunctionAsync`.
-- A public operation that is asynchronous or returns a `Promise` uses the `Async` suffix in both its
-  filename and exported name.
+- A public operation that is asynchronous or returns a `Promise` uses the `Async` suffix in both its filename and exported name.
 
 Keep private helpers below that exported declaration when they are used only by that module.
 Decide the owner of a reused function using the utility rules below, before creating another file.
@@ -132,17 +138,9 @@ Decide the owner of a reused function using the utility rules below, before crea
 Choose type ownership by its production consumers, not by the number of textual references or
 whether a barrel happens to re-export it:
 
-1. **Used by one implementation module:** keep the type directly below the function that owns it,
-   without `export`. Its private helpers can use the same local type. A test does not justify
-   exporting an implementation-private type; test through the function boundary.
-2. **Reused within the repository:** put related types together in `src/types/<topic>.ts` and use
-   type-only imports. Name the file for a cohesive topic, not for each individual type. Such a file
-   may export multiple related types/interfaces and contains no runtime implementation. Do not mix
-   type-only files among feature functions or `utils/`, and do not create one global catch-all file.
-3. **Shared across repositories:** the canonical declaration belongs in `@ankhorage/contracts` at
-   the owning topic's public subpath. Consumers import that contract through a declared dependency,
-   not another repository's source or a duplicated local declaration. Keep framework-specific
-   adapters separate from the portable shared contract.
+1. **Used by one implementation module:** keep the type directly below the function that owns it, without `export`. Its private helpers can use the same local type. A test does not justify exporting an implementation-private type; test through the function boundary.
+2. **Reused within the repository:** put related types together in `src/types/<topic>.ts` and use type-only imports. Name the file for a cohesive topic, not for each individual type. Such a file may export multiple related types/interfaces and contains no runtime implementation. Do not mix type-only files among feature functions or `utils/`, and do not create one global catch-all file.
+3. **Shared across repositories and serializable:** when at least two repositories require the same portable data declaration, it belongs in `@ankhorage/contracts` at the owning topic's public subpath. Consumers import that contract through a declared dependency, not another repository's source or a duplicated local declaration. Keep non-serializable API types with their implementation-owning package and consume them through that package's public API. Keep framework-specific adapters separate from the portable shared contract.
 
 Inspect published API declarations and real consumer imports before privatizing or relocating a
 type. A public boundary type is not private just because only one implementation uses it locally.
@@ -161,11 +159,10 @@ Constants are static declarations, not utility implementations. Do not create on
 constant per constant-named file under `utils/`.
 
 1. **Used by one implementation module:** keep the constant private in the module that owns it.
-2. **Reused only inside a feature:** group related constants in that feature's `constants.ts`.
-3. **Shared across features in one package:** group related package metadata, static policy values,
-   and other constants in `src/constants.ts`.
+2. **Reused only inside a feature:** group related constants in that feature's `constants/<topic>.ts`.
+3. **Shared across features in one package:** group related package metadata, static policy values, and other constants in `src/constants/<topic>.ts`.
 
-A `constants.ts` module may export multiple related constants. Keep it cohesive by ownership and
+A `constants/<topic>.ts` module may export multiple related constants. Keep it cohesive by ownership and
 purpose; it is not a package-wide catch-all. Split constants when they have different owners, not
 merely to create one file per export.
 
@@ -173,27 +170,34 @@ For example, Navigator's
 [`src/utils/NAVIGATOR_PACKAGE_METADATA.ts`](https://github.com/ankhorage/navigator/blob/main/src/utils/NAVIGATOR_PACKAGE_METADATA.ts)
 and
 [`src/utils/NAVIGATOR_ROUTER_POLICY.ts`](https://github.com/ankhorage/navigator/blob/main/src/utils/NAVIGATOR_ROUTER_POLICY.ts)
-belong together in `ankhorage/navigator/src/constants.ts`.
+belong together in `ankhorage/navigator/src/constants/navigator.ts`.
 
 ## Utilities
 
 `utils/` is the only utility directory name. Do not create `shared/`, `helper/`, `helpers/`,
 `common/`, or equivalent catch-all folders. It is not a destination for every pure function or type.
 
+Apply **reuse before implementation** and **shared by default** before choosing a local owner. For
+every function that could reasonably be reused across repositories, you MUST first inspect the
+published `@ankhorage/utility` public API and its owning topic. Reuse the existing export when its
+semantics match. If the function is missing and is generic without product, manifest, or framework
+policy, implement, test, and export it from the appropriate Utility topic, then consume that public
+export through a declared dependency. Do not duplicate it locally or add a forwarding wrapper.
+`isRecord` from `@ankhorage/utility/object` is one motivating example of this general rule, not a
+special case.
+
 - Used by one module: keep the helper private below its owning function.
 - Reused only inside a feature: keep it in that feature's `utils/`.
 - Shared across features but tied to this package's capability or policy: use `src/utils/`.
   Navigator topology traversal or Expo Router-specific validation does not become a general utility
   merely because several navigator features use it.
-- Generally reusable without the owning product, manifest, or framework policy: inspect the
-  published `@ankhorage/utility` API first, reuse it where semantics match, and put missing general
-  helpers in that package's owning topic. Examples include generic string escaping or source-literal
-  serialization. Do not copy a utility locally, create a forwarding wrapper, or change semantics
-  just to reuse a similarly named function.
+- Generally reusable across repositories: it belongs in the canonical `@ankhorage/utility` topic
+  under the reuse-first rule above. Examples include generic string escaping or source-literal
+  serialization. Do not change semantics merely to reuse a similarly named function.
 
 Separate the decisions for functions and types: reusable functions belong to Utility when general;
 repo-local type groups belong to `src/types/`; repo-crossing types belong to Contracts. Respect
 release boundaries and obtain approval for additional package changes when they exceed the task.
 
 This skill defines the target architecture. Schedule repository migrations separately and in this
-order: Studio, Deploy, Infra, Repository, Navigator.
+order: Studio, Deploy, Infra, Repository, Navigator, Surface, ZORA.

package/dist/tools/skills/assets/hexagonal-architecture/SKILL.md

@@ -1,72 +1,276 @@
 ---
 name: hexagonal-architecture
-description: >
-  Organize Ankhorage features with ports and adapters so domain policy stays independent from
-  transport, frameworks, and infrastructure.
-origin: ECC, adapted for Ankhorage
-metadata:
-  github-repo: https://github.com/affaan-m/ECC
-  github-ref: refs/tags/v2.2.0
-  github-path: docs/ja-JP/skills/hexagonal-architecture
+description: ヘキサゴナルアーキテクチャ（ポート・アダプタパターン）、境界の分離、および外部依存関係の管理。
+origin: ECC
 ---
 
 # Hexagonal Architecture
 
-Hexagonal architecture keeps a feature's domain policy independent from its transport, framework,
-and infrastructure details. The application layer depends on ports; inbound and outbound adapters
-implement the edge-specific work.
+Hexagonal architecture (Ports and Adapters) keeps business logic independent from frameworks, transport, and persistence details. The core app depends on abstract ports, and adapters implement those ports at the edges.
 
-## Feature boundaries
+## When to Use
 
-Apply this structure inside the owning `src/features/<feature>/` directory. A feature may contain
-only the layers it needs:
+- Building new features where long-term maintainability and testability matter.
+- Refactoring layered or framework-heavy code where domain logic is mixed with I/O concerns.
+- Supporting multiple interfaces for the same use case (HTTP, CLI, queue workers, cron jobs).
+- Replacing infrastructure (database, external APIs, message bus) without rewriting business rules.
+
+Use this skill when the request involves boundaries, domain-centric design, refactoring tightly coupled services, or decoupling application logic from specific libraries.
+
+## Core Concepts
+
+- **Domain model**: Business rules and entities/value objects. No framework imports.
+- **Use cases (application layer)**: Orchestrate domain behavior and workflow steps.
+- **Inbound ports**: Contracts describing what the application can do (commands/queries/use-case interfaces).
+- **Outbound ports**: Contracts for dependencies the application needs (repositories, gateways, event publishers, clock, UUID, etc.).
+- **Adapters**: Infrastructure and delivery implementations of ports (HTTP controllers, DB repositories, queue consumers, SDK wrappers).
+- **Composition root**: Single wiring location where concrete adapters are bound to use cases.
+
+Outbound port interfaces usually live in the application layer (or in domain only when the abstraction is truly domain-level), while infrastructure adapters implement them.
+
+Dependency direction is always inward:
+
+- Adapters -> application/domain
+- Application -> port interfaces (inbound/outbound contracts)
+- Domain -> domain-only abstractions (no framework or infrastructure dependencies)
+- Domain -> nothing external
+
+## How It Works
+
+### Step 1: Model a use case boundary
+
+Define a single use case with a clear input and output DTO. Keep transport details (Express `req`, GraphQL `context`, job payload wrappers) outside this boundary.
+
+### Step 2: Define outbound ports first
+
+Identify every side effect as a port:
+
+- persistence (`UserRepositoryPort`)
+- external calls (`BillingGatewayPort`)
+- cross-cutting (`LoggerPort`, `ClockPort`)
+
+Ports should model capabilities, not technologies.
+
+### Step 3: Implement the use case with pure orchestration
+
+Use case class/function receives ports via constructor/arguments. It validates application-level invariants, coordinates domain rules, and returns plain data structures.
+
+### Step 4: Build adapters at the edge
+
+- Inbound adapter converts protocol input to use-case input.
+- Outbound adapter maps app contracts to concrete APIs/ORM/query builders.
+- Mapping stays in adapters, not inside use cases.
+
+### Step 5: Wire everything in a composition root
+
+Instantiate adapters, then inject them into use cases. Keep this wiring centralized to avoid hidden service-locator behavior.
+
+### Step 6: Test per boundary
+
+- Unit test use cases with fake ports.
+- Integration test adapters with real infra dependencies.
+- E2E test user-facing flows through inbound adapters.
+
+## Architecture Diagram
+
+```mermaid
+flowchart LR
+  Client["Client (HTTP/CLI/Worker)"] --> InboundAdapter["Inbound Adapter"]
+  InboundAdapter -->|"calls"| UseCase["UseCase (Application Layer)"]
+  UseCase -->|"uses"| OutboundPort["OutboundPort (Interface)"]
+  OutboundAdapter["Outbound Adapter"] -->|"implements"| OutboundPort
+  OutboundAdapter --> ExternalSystem["DB/API/Queue"]
+  UseCase --> DomainModel["DomainModel"]
+```
+
+## Suggested Module Layout
+
+Use feature-first organization with explicit boundaries:
 
 ```text
-<feature>/
-  domain/
-  application/
-    ports/
-      inbound/
-      outbound/
-    use-cases/
-  adapters/
-    inbound/
-    outbound/
-  composition/
-  utils/
+src/
+  features/
+    orders/
+      domain/
+        Order.ts
+        OrderPolicy.ts
+      application/
+        ports/
+          inbound/
+            CreateOrder.ts
+          outbound/
+            OrderRepositoryPort.ts
+            PaymentGatewayPort.ts
+        use-cases/
+          CreateOrderUseCase.ts
+      adapters/
+        inbound/
+          http/
+            createOrderRoute.ts
+        outbound/
+          postgres/
+            PostgresOrderRepository.ts
+          stripe/
+            StripePaymentGateway.ts
+      composition/
+        ordersContainer.ts
 ```
 
-- `domain/` contains entities, value objects, and business policy. It imports no framework,
-  transport, database, or SDK code.
-- `application/` defines use cases and the ports they require. It orchestrates domain behavior and
-  depends only inward.
-- `adapters/inbound/` converts CLI, HTTP, worker, or UI input to use-case input.
-- `adapters/outbound/` implements application ports for persistence, APIs, queues, clocks, and
-  other external dependencies.
-- `composition/` explicitly wires concrete adapters to use cases.
+## TypeScript Example
+
+### Port definitions
+
+```typescript
+export interface OrderRepositoryPort {
+  save(order: Order): Promise<void>;
+  findById(orderId: string): Promise<Order | null>;
+}
+
+export interface PaymentGatewayPort {
+  authorize(input: { orderId: string; amountCents: number }): Promise<{ authorizationId: string }>;
+}
+```
+
+### Use case
+
+```typescript
+type CreateOrderInput = {
+  orderId: string;
+  amountCents: number;
+};
+
+type CreateOrderOutput = {
+  orderId: string;
+  authorizationId: string;
+};
+
+export class CreateOrderUseCase {
+  constructor(
+    private readonly orderRepository: OrderRepositoryPort,
+    private readonly paymentGateway: PaymentGatewayPort,
+  ) {}
+
+  async execute(input: CreateOrderInput): Promise<CreateOrderOutput> {
+    const order = Order.create({ id: input.orderId, amountCents: input.amountCents });
+
+    const auth = await this.paymentGateway.authorize({
+      orderId: order.id,
+      amountCents: order.amountCents,
+    });
+
+    // markAuthorized returns a new Order instance; it does not mutate in place.
+    const authorizedOrder = order.markAuthorized(auth.authorizationId);
+    await this.orderRepository.save(authorizedOrder);
+
+    return {
+      orderId: order.id,
+      authorizationId: auth.authorizationId,
+    };
+  }
+}
+```
+
+### Outbound adapter
+
+```typescript
+export class PostgresOrderRepository implements OrderRepositoryPort {
+  constructor(private readonly db: SqlClient) {}
+
+  async save(order: Order): Promise<void> {
+    await this.db.query(
+      'insert into orders (id, amount_cents, status, authorization_id) values ($1, $2, $3, $4)',
+      [order.id, order.amountCents, order.status, order.authorizationId],
+    );
+  }
+
+  async findById(orderId: string): Promise<Order | null> {
+    const row = await this.db.oneOrNone('select * from orders where id = $1', [orderId]);
+    return row ? Order.rehydrate(row) : null;
+  }
+}
+```
+
+### Composition root
+
+```typescript
+export const buildCreateOrderUseCase = (deps: { db: SqlClient; stripe: StripeClient }) => {
+  const orderRepository = new PostgresOrderRepository(deps.db);
+  const paymentGateway = new StripePaymentGateway(deps.stripe);
+
+  return new CreateOrderUseCase(orderRepository, paymentGateway);
+};
+```
+
+## Multi-Language Mapping
+
+Use the same boundary rules across ecosystems; only syntax and wiring style change.
+
+- **TypeScript/JavaScript**
+  - Ports: `application/ports/*` as interfaces/types.
+  - Use cases: classes/functions with constructor/argument injection.
+  - Adapters: `adapters/inbound/*`, `adapters/outbound/*`.
+  - Composition: explicit factory/container module (no hidden globals).
+- **Java**
+  - Packages: `domain`, `application.port.in`, `application.port.out`, `application.usecase`, `adapter.in`, `adapter.out`.
+  - Ports: interfaces in `application.port.*`.
+  - Use cases: plain classes (Spring `@Service` is optional, not required).
+  - Composition: Spring config or manual wiring class; keep wiring out of domain/use-case classes.
+- **Kotlin**
+  - Modules/packages mirror the Java split (`domain`, `application.port`, `application.usecase`, `adapter`).
+  - Ports: Kotlin interfaces.
+  - Use cases: classes with constructor injection (Koin/Dagger/Spring/manual).
+  - Composition: module definitions or dedicated composition functions; avoid service locator patterns.
+- **Go**
+  - Packages: `internal/<feature>/domain`, `application`, `ports`, `adapters/inbound`, `adapters/outbound`.
+  - Ports: small interfaces owned by the consuming application package.
+  - Use cases: structs with interface fields plus explicit `New...` constructors.
+  - Composition: wire in `cmd/<app>/main.go` (or dedicated wiring package), keep constructors explicit.
+
+## Anti-Patterns to Avoid
+
+- Domain entities importing ORM models, web framework types, or SDK clients.
+- Use cases reading directly from `req`, `res`, or queue metadata.
+- Returning database rows directly from use cases without domain/application mapping.
+- Letting adapters call each other directly instead of flowing through use-case ports.
+- Spreading dependency wiring across many files with hidden global singletons.
 
-Dependency direction is always inward: adapters depend on application and domain; application
-depends on domain and ports; domain has no external dependencies. Adapters do not call each other
-to bypass a use case.
+## Migration Playbook
 
-## Ports and use cases
+1. Pick one vertical slice (single endpoint/job) with frequent change pain.
+2. Extract a use-case boundary with explicit input/output types.
+3. Introduce outbound ports around existing infrastructure calls.
+4. Move orchestration logic from controllers/services into the use case.
+5. Keep old adapters, but make them delegate to the new use case.
+6. Add tests around the new boundary (unit + adapter integration).
+7. Repeat slice-by-slice; avoid full rewrites.
 
-Define an inbound port when a feature needs a stable use-case boundary. Define an outbound port for
-each capability the application needs from persistence, an external system, or cross-cutting runtime
-services. Model ports as capabilities rather than technologies.
+### Refactoring Existing Systems
 
-Use cases accept plain inputs, enforce application invariants, coordinate domain behavior through
-ports, and return plain outputs. Keep protocol request objects, database rows, SDK clients, and
-transport error formats in adapters.
+- **Strangler approach**: keep current endpoints, route one use case at a time through new ports/adapters.
+- **No big-bang rewrites**: migrate per feature slice and preserve behavior with characterization tests.
+- **Facade first**: wrap legacy services behind outbound ports before replacing internals.
+- **Composition freeze**: centralize wiring early so new dependencies do not leak into domain/use-case layers.
+- **Slice selection rule**: prioritize high-churn, low-blast-radius flows first.
+- **Rollback path**: keep a reversible toggle or route switch per migrated slice until production behavior is verified.
 
-## Testing
+## Testing Guidance (Same Hexagonal Boundaries)
 
-Test domain rules without framework setup. Test use cases with fakes for outbound ports. Test
-adapters at their boundary with the real protocol or infrastructure they translate. Cover critical
-flows end-to-end through an inbound adapter, use case, and outbound adapter.
+- **Domain tests**: test entities/value objects as pure business rules (no mocks, no framework setup).
+- **Use-case unit tests**: test orchestration with fakes/stubs for outbound ports; assert business outcomes and port interactions.
+- **Outbound adapter contract tests**: define shared contract suites at port level and run them against each adapter implementation.
+- **Inbound adapter tests**: verify protocol mapping (HTTP/CLI/queue payload to use-case input and output/error mapping back to protocol).
+- **Adapter integration tests**: run against real infrastructure (DB/API/queue) for serialization, schema/query behavior, retries, and timeouts.
+- **End-to-end tests**: cover critical user journeys through inbound adapter -> use case -> outbound adapter.
+- **Refactor safety**: add characterization tests before extraction; keep them until new boundary behavior is stable and equivalent.
 
-## Ankhorage conventions
+## Best Practices Checklist
 
-Follow `ankhorage-project-structure` for feature naming, one-export source modules, and `utils/`
-ownership. Do not introduce legacy paths, compatibility facades, dual implementations, or rollback
-switches while applying this architecture; use the current architecture directly.
+- Domain and use-case layers import only internal types and ports.
+- Every external dependency is represented by an outbound port.
+- Validation occurs at boundaries (inbound adapter + use-case invariants).
+- Use immutable transformations (return new values/entities instead of mutating shared state).
+- Errors are translated across boundaries (infra errors -> application/domain errors).
+- Composition root is explicit and easy to audit.
+- Use cases are testable with simple in-memory fakes for ports.
+- Refactoring starts from one vertical slice with behavior-preserving tests.
+- Language/framework specifics stay in adapters, never in domain rules.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/devtools",
-  "version": "1.14.3",
+  "version": "1.14.5",
   "description": "Shared development tools and repository standards for Ankhorage",
   "license": "MIT",
   "homepage": "https://github.com/ankhorage/devtools#readme",