@ankhorage/devtools 1.14.4 → 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,28 +1,40 @@
 ---
 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
 
 ## Applicability
 
-This skill applies to every Ankhorage repository except `ankhorage/contracts`.
+This skill applies to every Ankhorage repository.
 
-If the current repository is `ankhorage/contracts`, stop applying this skill. Contracts owns the
-portable cross-repository contract taxonomy and does not inherit this skill's required `src/cli/`,
-`src/features/`, hexagonal feature layout, type/constant/utility ownership, package facade, or
-repository migration rules.
+### Contracts repository profile
+
+If the current repository is `ankhorage/contracts`, apply only this profile:
+
+- 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.
+
+After enforcing this profile, stop before the remaining source-layout, implementation, utility,
+and migration rules; they do not apply to `ankhorage/contracts`.
 
 ## Required skills
 
-Before structural work, read the repository `AGENTS.md`, inspect its source tree and public
-exports, then load both required repository skills from the repository root. Do not resolve required
-skills relative to this skill's own installation location:
+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/ankhorage-coding-rules/SKILL.md`
-2. `<repo-root>/.agents/skills/hexagonal-architecture/SKILL.md`
+1. `<repo-root>/.agents/skills/hexagonal-architecture/SKILL.md`
 
 ## Required source layout
 
@@ -128,7 +140,7 @@ 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.
+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.
@@ -165,14 +177,23 @@ belong together in `ankhorage/navigator/src/constants/navigator.ts`.
 `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

package/package.json

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