@ankhorage/devtools 1.19.19 → 1.21.0

package/README.md

@@ -3,7 +3,7 @@
 
 # @ankhorage/devtools
 
-![license: MIT](././paradox/badges/license.svg) ![npm: v1.19.19](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: checked](././paradox/badges/tests.svg) ![docs: paradox](././paradox/badges/docs.svg)
+![license: MIT](././paradox/badges/license.svg) ![npm: v1.21.0](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: checked](././paradox/badges/tests.svg) ![docs: paradox](././paradox/badges/docs.svg)
 
 Shared tooling, repository automation, runtime policies, and agent standards for Ankhorage TypeScript projects
 
@@ -199,10 +199,12 @@ The canonical workflow, VS Code, and skill files are packaged with `@ankhorage/d
 
 ## Managed agent instructions
 
-`ankh devtools agents sync` owns the repository-root `AGENTS.md`. The shared instructions are intentionally small and stable. The target repository's package name and description are rendered from `package.json`; the remaining content defines the unconditional current-architecture policy, directs structural work to the managed project-structure skill, and requires the canonical build, type, lint, Knip, Changeset, and formatting commands before pull request creation.
+`ankh devtools agents sync` owns the repository-root `AGENTS.md` plus `CLAUDE.md` and `GEMINI.md` as symbolic links to that canonical file. The shared instructions are intentionally small and stable. The target repository's package name and description are rendered from `package.json`; the remaining content defines the unconditional current-architecture policy, directs structural work to the managed project-structure skill, and requires the canonical build, type, lint, Knip, Changeset, and formatting commands before pull request creation.
 
 Only the current Ankhorage architecture is supported. Managed instructions reject deprecated APIs, compatibility aliases, shims, dual old/new paths, historical-state fallbacks, and migrations whose sole purpose is obsolete state. A canonical cross-package change requires affected repositories to update to the latest released public API.
 
+Every Devtools-managed repository is standalone: its own checkout must be sufficient to install, build, test, and use it with declared dependencies and explicit configuration. Published packages are additionally consumer-agnostic and reusable outside Ankhorage. Sibling repositories/source imports, unpublished workspace/file/link coupling, hidden organization-local state, and hard assumptions about a consuming app, infrastructure, hosting provider, web server, container runtime, or deployment topology are architecture debt rather than supported exceptions.
+
 ## Managed repository skills
 
 `ankh devtools skills sync` owns the complete `.agents/skills/ankhorage-coding-rules/`, `.agents/skills/hexagonal-architecture/`, and `.agents/skills/ankhorage-project-structure/` trees from the immutable copies shipped in the Devtools release. It creates `.agents/` when missing, replaces stale files in those managed skills, and preserves every unrelated skill directory. The project-structure skill requires both the coding-rules and hexagonal-architecture skills before structural work can continue.

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

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

package/dist/tools/agents/index.js

@@ -5,6 +5,14 @@ export const agentsManagedFiles = [
         relativePath: 'AGENTS.md',
         render: renderAgentsFile,
     },
+    {
+        relativePath: 'CLAUDE.md',
+        symlinkTarget: 'AGENTS.md',
+    },
+    {
+        relativePath: 'GEMINI.md',
+        symlinkTarget: 'AGENTS.md',
+    },
 ];
 /*** Render mandatory repository instructions from the target package identity. */
 async function renderAgentsFile(targetDirectory) {
@@ -13,6 +21,7 @@ async function renderAgentsFile(targetDirectory) {
     const description = readNonEmptyString(manifest.description) ?? 'No package description is declared.';
     const sections = [
         renderCurrentArchitectureInstructions(),
+        renderStandaloneRepositoryInstructions(),
         renderRequiredRepositoryInstructions(),
         renderDocumentationInstructions(),
         renderPullRequestInstructions(),
@@ -45,6 +54,26 @@ 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.
 
+`;
+}
+/*** Render the mandatory standalone repository and package contract. */
+function renderStandaloneRepositoryInstructions() {
+    return `## Standalone contract
+
+Every repository managed by \`@ankhorage/devtools\` is standalone. It must be independently
+installable, buildable, testable, and usable from its own checkout using only declared dependencies
+and explicit configuration. It must not require sibling repositories, sibling source imports,
+\`workspace:\`, \`file:\`, or \`link:\` dependencies to unpublished packages, hidden
+organization-local state, or assumptions about a specific consuming application, infrastructure,
+hosting provider, web server, container runtime, or deployment topology.
+
+Published packages are additionally consumer-agnostic and reusable outside Ankhorage.
+Environment- or provider-specific behavior belongs behind explicit configuration and adapters,
+never in the package core.
+
+If an existing repository violates this contract, treat that as architecture debt to remove, not
+as an exception to preserve.
+
 `;
 }
 /*** Render contextual repository skill-selection requirements. */

package/dist/tools/shared/managedFiles.d.ts

@@ -5,6 +5,7 @@ export interface ManagedFileDefinition {
     readonly sourceUrl?: URL;
     readonly contents?: string;
     readonly render?: ManagedFileRenderer;
+    readonly symlinkTarget?: string;
     readonly mode?: ManagedFileMode;
     readonly isApplicable?: (targetDirectory: string) => Promise<boolean> | boolean;
 }
@@ -18,8 +19,11 @@ export interface ManagedFileSyncResult {
     readonly relativePath: string;
     readonly action: ManagedFileSyncAction;
 }
+/*** Resolve and validate the repository directory targeted by a managed-files operation. */
 export declare function resolveManagedTargetDirectory(cwd: string, requestedPath: string | undefined): Promise<string>;
+/*** Inspect managed files and symbolic links without mutating repository state. */
 export declare function inspectManagedFiles(targetDirectory: string, definitions: readonly ManagedFileDefinition[]): Promise<readonly ManagedFileStatus[]>;
+/*** Synchronize managed files and symbolic links to their canonical definitions. */
 export declare function syncManagedFiles(targetDirectory: string, definitions: readonly ManagedFileDefinition[], options: {
     readonly dryRun: boolean;
 }): Promise<readonly ManagedFileSyncResult[]>;

package/dist/tools/shared/managedFiles.js

@@ -1,5 +1,6 @@
-import { mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { lstat, mkdir, readFile, readlink, rm, stat, symlink, writeFile } from 'node:fs/promises';
 import { dirname, resolve } from 'node:path';
+/*** Resolve and validate the repository directory targeted by a managed-files operation. */
 export async function resolveManagedTargetDirectory(cwd, requestedPath) {
     const targetDirectory = resolve(cwd, requestedPath ?? '.');
     let targetStats;
@@ -14,46 +15,62 @@ export async function resolveManagedTargetDirectory(cwd, requestedPath) {
     }
     return targetDirectory;
 }
+/*** Inspect managed files and symbolic links without mutating repository state. */
 export async function inspectManagedFiles(targetDirectory, definitions) {
-    const statuses = await Promise.all(definitions.map(async (definition) => {
-        const targetPath = resolve(targetDirectory, definition.relativePath);
-        const isApplicable = await (definition.isApplicable?.(targetDirectory) ?? true);
-        try {
-            const targetContents = await readFile(targetPath, 'utf8');
-            if (!isApplicable) {
-                return { relativePath: definition.relativePath, state: 'obsolete' };
-            }
-            if ((definition.mode ?? 'replace') === 'create-only') {
-                return { relativePath: definition.relativePath, state: 'current' };
-            }
-            const canonicalContents = await readCanonicalContents(definition, targetDirectory);
-            return {
-                relativePath: definition.relativePath,
-                state: targetContents === canonicalContents ? 'current' : 'outdated',
-            };
-        }
-        catch (error) {
-            if (isMissingFileError(error)) {
-                return isApplicable
-                    ? { relativePath: definition.relativePath, state: 'missing' }
-                    : undefined;
-            }
-            throw new Error(`Failed to inspect managed file: ${targetPath}`, { cause: error });
-        }
-    }));
+    const statuses = await Promise.all(definitions.map((definition) => inspectManagedFileAsync(targetDirectory, definition)));
     return statuses.filter((status) => status !== undefined);
 }
+/*** Synchronize managed files and symbolic links to their canonical definitions. */
 export async function syncManagedFiles(targetDirectory, definitions, options) {
     const statuses = await inspectManagedFiles(targetDirectory, definitions);
     const definitionsByPath = new Map(definitions.map((definition) => [definition.relativePath, definition]));
     const results = [];
     for (const status of statuses) {
-        const result = await syncManagedFile(targetDirectory, status, definitionsByPath, options);
-        results.push(result);
+        results.push(await syncManagedFileAsync(targetDirectory, status, definitionsByPath, options));
     }
     return results;
 }
-async function syncManagedFile(targetDirectory, status, definitionsByPath, options) {
+/*** Inspect one managed artifact against its file or symbolic-link definition. */
+async function inspectManagedFileAsync(targetDirectory, definition) {
+    assertSingleContentSource(definition);
+    const targetPath = resolve(targetDirectory, definition.relativePath);
+    const isApplicable = await (definition.isApplicable?.(targetDirectory) ?? true);
+    try {
+        const targetStats = await lstat(targetPath);
+        if (!isApplicable) {
+            return { relativePath: definition.relativePath, state: 'obsolete' };
+        }
+        if ((definition.mode ?? 'replace') === 'create-only') {
+            return { relativePath: definition.relativePath, state: 'current' };
+        }
+        const current = definition.symlinkTarget === undefined
+            ? await isCurrentFileAsync(targetPath, targetStats.isSymbolicLink(), definition, targetDirectory)
+            : await isCurrentSymlinkAsync(targetPath, targetStats.isSymbolicLink(), definition.symlinkTarget);
+        return {
+            relativePath: definition.relativePath,
+            state: current ? 'current' : 'outdated',
+        };
+    }
+    catch (error) {
+        if (isMissingFileError(error)) {
+            return isApplicable ? { relativePath: definition.relativePath, state: 'missing' } : undefined;
+        }
+        throw new Error(`Failed to inspect managed file: ${targetPath}`, { cause: error });
+    }
+}
+/*** Compare one regular managed file with its canonical rendered contents. */
+async function isCurrentFileAsync(targetPath, isSymbolicLink, definition, targetDirectory) {
+    if (isSymbolicLink)
+        return false;
+    return ((await readFile(targetPath, 'utf8')) ===
+        (await readCanonicalContents(definition, targetDirectory)));
+}
+/*** Compare one managed symbolic link with its canonical relative target. */
+async function isCurrentSymlinkAsync(targetPath, isSymbolicLink, symlinkTarget) {
+    return isSymbolicLink && (await readlink(targetPath)) === symlinkTarget;
+}
+/*** Apply one managed artifact status to the target repository. */
+async function syncManagedFileAsync(targetDirectory, status, definitionsByPath, options) {
     if (status.state === 'current') {
         return { relativePath: status.relativePath, action: 'unchanged' };
     }
@@ -63,7 +80,7 @@ async function syncManagedFile(targetDirectory, status, definitionsByPath, optio
     }
     if (status.state === 'obsolete') {
         if (!options.dryRun) {
-            await rm(resolve(targetDirectory, definition.relativePath));
+            await rm(resolve(targetDirectory, definition.relativePath), { force: true, recursive: true });
         }
         return {
             relativePath: status.relativePath,
@@ -78,12 +95,41 @@ async function syncManagedFile(targetDirectory, status, definitionsByPath, optio
     }
     const targetPath = resolve(targetDirectory, definition.relativePath);
     await mkdir(dirname(targetPath), { recursive: true });
-    await writeFile(targetPath, await readCanonicalContents(definition, targetDirectory), 'utf8');
+    const canonicalContents = definition.symlinkTarget === undefined
+        ? await readCanonicalContents(definition, targetDirectory)
+        : undefined;
+    await prepareManagedTargetAsync(targetPath, definition);
+    await writeManagedArtifactAsync(targetPath, definition, canonicalContents);
     return {
         relativePath: status.relativePath,
         action: status.state === 'missing' ? 'created' : 'updated',
     };
 }
+/*** Remove an existing artifact only when writing through it would violate the target type. */
+async function prepareManagedTargetAsync(targetPath, definition) {
+    try {
+        const targetStats = await lstat(targetPath);
+        if (definition.symlinkTarget !== undefined || targetStats.isSymbolicLink()) {
+            await rm(targetPath, { force: true, recursive: true });
+        }
+    }
+    catch (error) {
+        if (!isMissingFileError(error))
+            throw error;
+    }
+}
+/*** Write either a canonical regular file or a canonical symbolic link. */
+async function writeManagedArtifactAsync(targetPath, definition, canonicalContents) {
+    if (definition.symlinkTarget !== undefined) {
+        await symlink(definition.symlinkTarget, targetPath);
+        return;
+    }
+    if (canonicalContents === undefined) {
+        throw new Error(`Missing canonical file contents for ${definition.relativePath}.`);
+    }
+    await writeFile(targetPath, canonicalContents, 'utf8');
+}
+/*** Resolve canonical contents for one regular managed file definition. */
 async function readCanonicalContents(definition, targetDirectory) {
     assertSingleContentSource(definition);
     if (definition.sourceUrl !== undefined) {
@@ -95,17 +141,25 @@ async function readCanonicalContents(definition, targetDirectory) {
     if (definition.render !== undefined) {
         return await definition.render(targetDirectory);
     }
-    throw new Error(`Managed file has no content source: ${definition.relativePath}`);
+    throw new Error(`Managed file does not contain regular-file content: ${definition.relativePath}`);
 }
+/*** Require every managed artifact to define exactly one canonical source. */
 function assertSingleContentSource(definition) {
-    const sourceCount = [definition.sourceUrl, definition.contents, definition.render].filter((value) => value !== undefined).length;
+    const sourceCount = [
+        definition.sourceUrl,
+        definition.contents,
+        definition.render,
+        definition.symlinkTarget,
+    ].filter((value) => value !== undefined).length;
     if (sourceCount !== 1) {
         throw new Error(`Managed file must define exactly one content source: ${definition.relativePath}`);
     }
 }
+/*** Check whether an unknown failure means the target path does not exist. */
 function isMissingFileError(error) {
     return isNodeError(error) && error.code === 'ENOENT';
 }
+/*** Check whether an unknown failure carries a Node.js error code. */
 function isNodeError(error) {
     return error instanceof Error && 'code' in error;
 }

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

@@ -36,71 +36,57 @@ repository root. Do not resolve it relative to this skill's own installation loc
 
 1. `<repo-root>/.agents/skills/hexagonal-architecture/SKILL.md`
 
-## Required source 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/`.
-
-Test-only fixtures remain owned by the applicable test structure. Do not relabel fixtures as public
-examples merely to bypass repository structure rules.
-
-- `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.
-
-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.
-
-- `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
-    commands/
-      <command>.ts
-      <group>/
-        <command>.ts
-  features/
-    <feature>/
-      domain/
-      application/
-        ports/
-          inbound/
-          outbound/
-        use-cases/
-      adapters/
-        inbound/
-        outbound/
-      composition/
-      constants/
-        <topic>.ts
-      utils/
-  types/
-    <topic>.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.
+## Architecture profiles and source layout
+
+Do not impose one folder tree on every repository. Select the smallest profile that matches the
+repository's real responsibility, then enforce that profile's vocabulary and dependency direction.
+Read `references/architecture-profiles.md` and `references/hexagonal-invariants.md` before
+creating or moving architectural directories.
+
+Valid profiles include:
+
+- simple/value/contracts library;
+- reusable UI or design-system library;
+- application, engine, or hybrid package;
+- provider or platform adapter package;
+- tooling package;
+- generated standalone application;
+- an explicitly documented repository-specific profile such as Studio.
+
+A package may start flat. Introduce `domain/`, `application/`, `ports/`, `adapters/`,
+`composition/`, `features/`, or `core/` only when those names communicate a real architectural
+role. Once a vocabulary is introduced, its combinations must be coherent:
+
+- `domain/` may stand alone and must remain independent from outer mechanisms;
+- `application/` coordinates use cases and may depend inward on domain policy and required ports;
+- `ports/` define capabilities required by inner policy; they do not implement provider technology;
+- `adapters/` translate or implement a port at an external edge and therefore require an inward
+  capability boundary to adapt to;
+- `composition/` is outer wiring and exists only when concrete implementations need selection;
+- `features/` is feature-first organization, not a generic bucket. Each feature owns a coherent
+  slice and may introduce only the role directories it actually needs;
+- `core/` is allowed only when the repository defines it narrowly as stable inner policy. It must
+  never become a miscellaneous dumping ground.
+
+Dependency direction is the invariant. Inner policy must not import outer mechanisms. A domain or
+core module must not depend on application orchestration, adapters, composition, CLI, host,
+platform, framework, database, or provider implementation details. Application/use-case code must
+not import concrete adapters or composition roots. Adapters may depend inward on ports/application/
+domain contracts. Composition may depend on all pieces it wires.
+
+Do not create empty layers for symmetry. A small package with no domain orchestration does not need
+hexagonal ceremony. UI libraries use component/foundation dependency direction rather than fake
+application ports. Contracts libraries remain portable and side-effect free.
+
+Repository-root `examples/` contains complete user-facing examples. Each example lives in a named
+subdirectory. Test-only fixtures remain test-owned.
+
+Package-level delivery edges such as `src/cli/`, `src/host/`, `src/app/`, or `src/platform/`
+remain thin adapters/composition boundaries. The filesystem below `src/cli/commands/` mirrors the
+public Ankh command path, and command modules parse input, invoke package behavior, and render output.
+
+Keep only deliberate public facades directly under `src/`. Public package subpaths must map to
+explicit package exports; generic barrels are not an excuse to bypass ownership.
 
 ## General Taxonomy
 

package/dist/tools/skills/assets/ankhorage-project-structure/references/architecture-profiles.md

@@ -0,0 +1,141 @@
+# Architecture Profiles
+
+Choose the profile from actual ownership and consumers. Profiles define allowed vocabulary and
+dependency direction; they are not templates that require every listed directory.
+
+## Simple, value, or contracts library
+
+Use for portable types, deterministic values, parsers, constants, algorithms, and small libraries
+without application orchestration.
+
+Typical forms:
+
+```text
+src/
+  index.ts
+  <domain-or-topic>/
+  types/
+  constants/
+  utils/
+```
+
+Do not invent ports, adapters, application, or composition layers when there is no external edge to
+abstract. Contracts packages additionally keep public declarations serializable and free of runtime
+implementation.
+
+## Reusable UI or design-system library
+
+Use semantic UI ownership and stable foundation layers rather than fake use cases:
+
+```text
+src/
+  foundation/
+  theme/
+  layout/
+  primitives/
+  components/
+  patterns/
+  registry/
+```
+
+Higher-level UI may depend on lower-level foundations; foundations must not depend upward on composed
+components or registries. Provider execution belongs outside reusable presentation components.
+
+## Application, engine, or hybrid package
+
+Use when the package owns use cases, state transitions, external systems, or several delivery edges.
+Domain-first and feature-first organization are both valid when coherent.
+
+Domain-first example:
+
+```text
+src/
+  <domain>/
+    domain/
+    application/
+    ports/
+    adapters/
+    composition/
+  cli/
+  host/
+  app/
+  platform/
+```
+
+Feature-first example:
+
+```text
+src/
+  features/
+    <feature>/
+      domain/
+      application/
+      ports/
+      adapters/
+      composition/
+  cli/
+```
+
+Only create the role directories that the capability actually needs. A pure domain feature can stop
+at `domain/`; an in-memory use case need not invent an outbound adapter.
+
+## Provider or platform adapter package
+
+Use when the package deliberately implements an external technology boundary:
+
+```text
+src/
+  contracts/
+  planning/
+  adapters/
+  composition/
+  cli/
+```
+
+Portable configuration and planning stay independent from SDK/runtime values. Concrete provider code
+stays in adapters.
+
+## Tooling package
+
+Command-centric tooling may use:
+
+```text
+src/
+  cli/
+  policy/
+  application/
+  adapters/
+  composition/
+```
+
+Policy remains deterministic. Filesystem, process, registry, network, and GitHub behavior stay at
+the edge.
+
+## Generated standalone application
+
+A generated app owns its manifest, lockfile, installation, validation, build, and deployment inputs.
+A parent tool may invoke it with the app as `cwd`, but it must not depend on a hidden parent
+workspace, sibling source, or installation state.
+
+## Repository-specific profile
+
+A repository may define a narrower profile when its domain genuinely needs one. That profile must be
+documented in the managed project-structure skill or an explicit repository reference and must still
+respect the shared standalone and dependency-direction invariants. Studio is the canonical example:
+its `features/` taxonomy is intentional and each substantial feature may layer internally.
+
+## Combination rules
+
+Folder names create obligations:
+
+- `domain/`: inner policy; no outward mechanism dependencies.
+- `application/`: use-case orchestration; no concrete adapter/composition dependency.
+- `ports/`: capability contracts required by inner policy.
+- `adapters/`: concrete edge implementations; there must be an inward capability/policy to adapt.
+- `composition/`: selects and wires concrete implementations; do not create it without pieces to wire.
+- `features/`: siblings are product capabilities, not technical categories.
+- `core/`: only a narrowly defined inner-policy layer; never a generic dumping ground.
+- `common/`, `shared/`, and `helpers/`: not architectural ownership categories.
+
+Doctor should validate these combinations and dependency directions rather than require every
+repository to match one tree.

package/dist/tools/skills/assets/ankhorage-project-structure/references/hexagonal-invariants.md

@@ -0,0 +1,80 @@
+# Hexagonal Architecture Invariants
+
+The canonical rule is isolation of inner policy from external mechanisms, not the visual shape or a
+fixed number of directories.
+
+## Research basis
+
+- Alistair Cockburn's original Ports & Adapters article defines an application on the inside
+  communicating through purposeful ports with replaceable technology-specific adapters. It
+  explicitly notes that the number of ports is not fixed:
+  https://alistair.cockburn.us/hexagonal-architecture
+- Robert C. Martin's Clean Architecture states the Dependency Rule: source dependencies point
+  inward, while outer mechanisms must not leak names or formats into inner policy:
+  https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html
+- Martin Fowler describes layering as a logical separation that can exist at different granularities
+  and notes that larger systems often modularize primarily by domain, layering inside those modules:
+  https://martinfowler.com/bliki/PresentationDomainDataLayering.html
+- DDD-oriented layered architecture keeps domain rules independent from infrastructure while the
+  application layer coordinates use cases and infrastructure implements technical details:
+  https://learn.microsoft.com/dotnet/architecture/microservices/microservice-ddd-cqrs-patterns/ddd-oriented-microservice
+
+## Invariants
+
+```text
+outer adapter/composition -> application/use case -> domain/core policy
+                                  |
+                                  v
+                           required port contract
+
+concrete adapter ----------------> required port contract
+```
+
+The exact filesystem can vary, but source dependencies must preserve this direction.
+
+### Inner policy
+
+Domain/core policy owns deterministic rules, values, invariants, and transformations. It must not
+import:
+
+- CLI, HTTP, UI, worker, or framework entrypoints;
+- filesystem/process/network/database/provider SDK implementations;
+- adapters or composition roots;
+- application orchestration that sits outside that policy.
+
+### Application/use cases
+
+Application code coordinates domain policy and required capabilities. It may define or consume port
+contracts, but it must not import concrete adapter implementations or composition roots.
+
+### Ports
+
+A port names a capability or conversation at a boundary. Create one when an external side effect,
+provider, process, platform, storage mechanism, or multiple delivery mechanisms justify substitution
+or deterministic testing. A port is not required for an ordinary pure function call.
+
+### Adapters
+
+Adapters translate at the edge. Inbound adapters map CLI/HTTP/UI/worker input into an application
+operation. Outbound adapters implement required capabilities using concrete technology.
+
+An `adapters/` directory without any identifiable inward policy/capability boundary is structurally
+suspicious: technology has become the architecture instead of adapting it.
+
+### Composition
+
+Composition selects implementations and wires dependencies. It is intentionally outermost and may
+know concrete adapters. Inner policy must never import it.
+
+## Verification strategy
+
+Doctor should validate what can be proven statically:
+
+- local dependency protocols and sibling-source coupling;
+- folder-role combinations after a vocabulary is introduced;
+- relative import direction between recognized roles;
+- generic catch-all architecture directories;
+- public-package standalone scripts and packed artifact boundaries.
+
+Semantic independence that cannot be inferred statically belongs in the package-owned
+`test:standalone` suite. Release must execute both Doctor and that owner test.

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

@@ -35,6 +35,15 @@ Dependency direction is always inward:
 - Domain -> domain-only abstractions (no framework or infrastructure dependencies)
 - Domain -> nothing external
 
+## Structural rule
+
+Hexagonal architecture does not prescribe one mandatory directory tree or a fixed number of ports.
+The enforceable contract is dependency direction and replaceability: inner policy must remain
+independent from outer technology, and adapters translate external mechanisms at explicit
+boundaries. Use the repository's managed `ankhorage-project-structure` skill to select a concrete
+profile and validate folder-role combinations. Do not create empty layers or ports merely to match
+a diagram.
+
 ## How It Works
 
 ### Step 1: Model a use case boundary

package/dist/tools/workflows/files/ci.yml

@@ -83,6 +83,19 @@ jobs:
             echo "No test script found; skipping."
           fi
 
+      - name: Run standalone contract
+        run: |
+          if node -e "const p=require('./package.json'); const required=p.private!==true&&p.publishConfig?.access==='public'; process.exit(required||p.scripts?.['test:standalone']?0:1)"; then
+            if node -e "const p=require('./package.json'); process.exit(p.scripts?.['test:standalone']?0:1)"; then
+              bun run test:standalone
+            else
+              echo "::error title=Standalone contract test required::Public packages must define test:standalone."
+              exit 1
+            fi
+          else
+            echo "No standalone owner test required; skipping."
+          fi
+
       - name: Run typecheck
         run: |
           if node -e "const p=require('./package.json'); process.exit(p.scripts?.typecheck ? 0 : 1)"; then

package/dist/tools/workflows/files/release.yml

@@ -76,6 +76,18 @@ jobs:
             echo "No build script found; skipping."
           fi
 
+      - name: Validate standalone release contract
+        run: |
+          BUN_INSTALL_CACHE_DIR="${RUNNER_TEMP}/doctor-cache" bunx @ankhorage/doctor@__ANKH_DOCTOR_VERSION__ validate .
+          if node -e "const p=require('./package.json'); const required=p.private!==true&&p.publishConfig?.access==='public'; process.exit(required||p.scripts?.['test:standalone']?0:1)"; then
+            if node -e "const p=require('./package.json'); process.exit(p.scripts?.['test:standalone']?0:1)"; then
+              bun run test:standalone
+            else
+              echo "::error title=Standalone contract test required::Public packages must define test:standalone."
+              exit 1
+            fi
+          fi
+
       - name: Version packages directly on main
         id: release
         if: hashFiles('.changeset/config.json') != ''
@@ -148,6 +160,31 @@ jobs:
             echo "release_sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
           fi
 
+      - name: Verify standalone packed install
+        if: steps.release.outputs.versioned == 'true'
+        run: |
+          set -euo pipefail
+          bun install --frozen-lockfile --ignore-scripts
+          if node -e "const p=require('./package.json'); process.exit(p.scripts?.build?0:1)"; then
+            bun run build
+          fi
+          if node -e "const p=require('./package.json'); process.exit(p.scripts?.['test:standalone']?0:1)"; then
+            bun run test:standalone
+          fi
+          pack_dir="$(mktemp -d "${RUNNER_TEMP}/standalone-pack.XXXXXX")"
+          install_dir="$(mktemp -d "${RUNNER_TEMP}/standalone-install.XXXXXX")"
+          npm pack --ignore-scripts --pack-destination "$pack_dir" >/dev/null
+          artifact="$(find "$pack_dir" -maxdepth 1 -type f -name '*.tgz' -print -quit)"
+          if [ -z "$artifact" ]; then
+            echo "::error title=Standalone pack failed::npm pack did not produce a package artifact."
+            exit 1
+          fi
+          printf '{"name":"standalone-consumer","private":true,"version":"0.0.0"}\n' > "$install_dir/package.json"
+          (
+            cd "$install_dir"
+            bun add "$artifact" --ignore-scripts
+          )
+
       - name: Publish unpublished packages
         if: hashFiles('.changeset/config.json') != ''
         run: |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/devtools",
-  "version": "1.19.19",
+  "version": "1.21.0",
   "description": "Shared tooling, repository automation, runtime policies, and agent standards for Ankhorage TypeScript projects",
   "license": "MIT",
   "homepage": "https://github.com/ankhorage/devtools#readme",
@@ -121,7 +121,8 @@
     "changeset": "bun src/cli/bin/changeset.ts",
     "changeset:status": "bun src/cli/bin/changeset.ts status --since=origin/main",
     "version-packages": "bun src/cli/bin/changeset.ts version",
-    "check-types": "bun x tsc --noEmit -p tsconfig.test.json"
+    "check-types": "bun x tsc --noEmit -p tsconfig.test.json",
+    "test:standalone": "bun test src/tools/agents/index.test.ts src/tools/shared/managedFiles.test.ts"
   },
   "dependencies": {
     "@ankhorage/apm": "^0.8.10",